> ## Documentation Index
> Fetch the complete documentation index at: https://developer.usetyms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Partners and Register business

> How referral partners onboard businesses, cover Plus and AI costs from partner credit, and use the partner API surface.

Tyms works with **referral business partners** (distributors): organizations or individuals who introduce small and medium-sized businesses in service, consulting, retail, and manufacturing to the platform. Partners may earn **commissions** or work on **prepaid** commercial terms on behalf of those businesses—commercial terms are agreed during **partner onboarding** with Tyms, not via this public API.

This page explains the **integration story**. Request and response fields for each partner route are in **API reference** → **Partners**.

## Becoming a partner

1. **Apply and onboard** through Tyms’s partner program (sales or partner operations). Tyms registers you as a referral business partner and issues **partner API credentials** (partner secret key, often prefixed like `adam_partner_sk_...`).
2. **Agree commercial terms** (revenue share, prepaid wallets, support expectations, branding, etc.). Those details are **not** exposed on the Developer API; they are contractual.
3. **Top up partner credit** in the partner portal when you plan to grant Plus seats or transfer AI credits to referred businesses (see [Covering costs](#covering-costs-for-referred-businesses)).
4. **Integrate** using your partner key for partner routes (register, list, billing, grants), then each business’s **`tyms_sk_...`** for day-to-day bookkeeping API calls.

<Warning>
  Partner routes expect a **partner** credential (`adam_partner_sk_...`), not a business `tyms_sk_` key. Send the partner secret in `X-API-Key` (or `api-key` / `sk`).
</Warning>

## Why Register business exists

Partners often need to:

* **Create** the Tyms business and owner account in one step.
* Optionally become an **admin** on that business so they can finish setup or support the owner.
* Optionally receive that business’s **Developer API keys** in the response so they can automate bookkeeping **on behalf of** the business they referred.

Only businesses created through this **partner** flow are attributed to you as referrer in Tyms’s systems. You receive **`api_secret_key`** in the success payload **only** when registration succeeds **and** you requested `grant_access: admin` (see reference).

## Covering costs for referred businesses

After Tyms onboards you, you purchase **partner credit** into your holding balance (partner portal — not this API). That balance is what seat grants and credit transfers draw from. You resell or bundle access to businesses you referred however your commercial terms allow.

When registering a business, `credit_from_referral_partner` (default `false`) controls who pays for **ongoing AI usage**:

| Registration flag | What it means |
| - | - |
| `false` | The business has its own credit ledger. You **grant** Plus seats and/or transfer credits from your holding when you want to cover their costs. |
| `true` | Tyms bills that business’s AI usage to **your** partner holding automatically. **Seat and credit grant endpoints are blocked** for that business — you are already managing usage centrally. |

If `credit_from_referral_partner` is `false`, you have two ways to put value on a referred business from your holding:

### Plus seats (recommended)

Use [Add seats](/api-reference/partners/add-referred-business-seats) to activate **Tyms Plus** for a period and license a seat count. Tyms debits your holding at **150 credits × seats × months** (150 AI credits per seat per month by default). The business receives matching AI credits on their ledger.

* **First call** — starts Plus for the requested `months` (default 1) and sets seat count.
* **Later calls** while that partner grant is still active — add seats for the **remaining** period only; holding cost and AI credits are **prorated**.

This is the approach we recommend: fixed seats, a clear subscription window, and predictable spend. The business can still cancel Plus from their own billing page; partner holding is not refunded.

### Transaction credits (pay as you go)

Use [Add credits](/api-reference/partners/add-referred-business-credits) to move AI credits from your holding to the business at **1:1** (100 holding credits → 100 usable AI credits). No Plus subscription required. Handy when plan-included credits run out, or when you prefer topping up usage instead of licensing seats.

Transferred credits expire **12 months** after the grant.

<Note>
  Seat grants and credit transfers only work for businesses **you referred** with `credit_from_referral_partner: false`. Check [Billing status](/api-reference/partners/get-referred-business-billing-status) before granting, and [List referred businesses](/api-reference/partners/list-referred-businesses) to reconcile your portal.
</Note>

## End-to-end integration flow

<Steps>
  <Step title="Partner authentication">
    Obtain your **partner secret** from Tyms after partner onboarding. Use it for all routes under **API reference** → **Partners** (`adam_partner_sk_...` in `X-API-Key`, `api-key`, or `sk`).
  </Step>

  <Step title="Register the business">
    [Register business](/api-reference/partners/register-business) — owner profile, `business_name`, `password` (at least 8 characters, including a letter, a number, and a special character such as `!@#$%^&*`), optional locale fields, `credit_from_referral_partner`, and `grant_access` (`admin` | `editor` | `viewer`). On success you receive `business_uuid`; with `grant_access: admin` you also receive `api_public_key` and `api_secret_key`.
  </Step>

  <Step title="Grant Plus or credits (optional)">
    When `credit_from_referral_partner` is `false`, use [Add seats](/api-reference/partners/add-referred-business-seats) to subscribe the business to Plus from your holding, or [Add credits](/api-reference/partners/add-referred-business-credits) for a pay-as-you-go top-up. [Billing status](/api-reference/partners/get-referred-business-billing-status) shows seats, plan, and credit balance before and after.
  </Step>

  <Step title="Integrate as the business">
    Call **`GET /auth/validate`**, **`POST /invoices`**, **`GET /reports/income-statement`**, etc., with **`X-API-Key: tyms_sk_...`** from the registration response — **not** the partner key.
  </Step>
</Steps>

## API surface

All partner routes live on the same **`v1/adam`** base URL as the rest of the Developer API:

| Route | Purpose |
| - | - |
| `POST /register-business` | Create a referred business and optional admin API keys |
| `GET /referred-businesses` | Paginated list of businesses you referred |
| `GET /referred-businesses/{business_uuid}/billing-status` | Subscription, seats, and credit snapshot for one business |
| `POST /referred-businesses/{business_uuid}/add-seats` | Grant or extend Plus seats from partner holding |
| `POST /referred-businesses/{business_uuid}/add-credits` | Transfer AI credits from partner holding (1:1) |

## Sandbox testing

Partners can exercise partner routes and subsequent business-scoped calls against the [sandbox environment](/introduction#environments) (`https://staging-api.usetyms.com/v1/adam`) before production. Email [developer@usetyms.com](mailto:developer@usetyms.com) for sandbox partner and business credentials — staging keys are separate from production partner secrets.

## Support

* **API support:** [developer@usetyms.com](mailto:developer@usetyms.com)
* **Partner program enrollment:** contact your Tyms partner representative or [developer@usetyms.com](mailto:developer@usetyms.com) if you do not yet have partner credentials.
* **Sandbox access:** [developer@usetyms.com](mailto:developer@usetyms.com) for pre-production account setup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.