> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tyms.io/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`).

## 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](https://developer.tyms.io/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](https://developer.tyms.io/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](https://developer.tyms.io/api-reference/partners/get-referred-business-billing-status) before granting, and [List referred businesses](https://developer.tyms.io/api-reference/partners/list-referred-businesses.md) to reconcile your portal.

## End-to-end integration flow

**1. 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`).

**2. Register the business**

[Register business](https://developer.tyms.io/api-reference/partners/register-business.md) — 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`.

**3. Grant Plus or credits (optional)**

When `credit_from_referral_partner` is `false`, use [Add seats](https://developer.tyms.io/api-reference/partners/add-referred-business-seats) to subscribe the business to Plus from your holding, or [Add credits](https://developer.tyms.io/api-reference/partners/add-referred-business-credits) for a pay-as-you-go top-up. [Billing status](https://developer.tyms.io/api-reference/partners/get-referred-business-billing-status) shows seats, plan, and credit balance before and after.

**4. 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.

## 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](https://developer.tyms.io/introduction.md#environments) (`https://staging-api.tyms.io/v1/adam`) before production. Email [developer@tyms.io](mailto:developer@tyms.io) for sandbox partner and business credentials — staging keys are separate from production partner secrets.

## Support

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


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