# How the Partner API works

> Who the Partner API is for, the two credentials every call carries, how a merchant's shop is identified, what internal and external billing mean, how plans, billing periods and usage charges flow between you and Releva, which webhooks Releva calls on your side, and the life cycle of a partner shop from install to uninstall.

Releva partners are platforms, apps and agencies that create Releva accounts for their merchants and run them on the merchants’ behalf. The Shopify connector is one; a custom-platform connector or an agency script can be another. This page explains the model behind the endpoints. The endpoint-by-endpoint reference, with every request and error, is the [Partner API overview](https://releva.ai/documentation/reference/partners/overview/).

If you are a merchant integrating your own shop, you do not need any of this: start with [How Releva connects to your shop](https://releva.ai/documentation/learn/shop-settings/how-releva-connects-to-your-shop/).

## Partner, account, domain

Releva’s data model has three levels:

| Object      | What it is                                                                                                                                      | Who creates it                                  |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| **Partner** | You. Holds your public key, your partner token, your billing mode and the URLs of the webhooks you implement.                                   | Releva, by hand, when you send your public key. |
| **Account** | A merchant. Owns billing periods and plan selections, and is where users get access. Identified by its **name**, which is unique across Releva. | You, with `POST /partners/domains`.             |
| **Domain**  | A shop. Holds the API keys, the settings and all the data. Identified by its URL, within the account.                                           | You, with the same call.                        |

A partner can own many accounts; an account normally has one domain when it comes from a partner. The Partner API addresses a shop by its host (`shop: "demo-partner-shop.example.com"`) and only finds shops in accounts you own. Two partners never see each other’s merchants.

## Two credentials on every call

**The partner token** identifies you. It is a UUID that Releva issues once and that you send in the `x-rlv-partner-token` header. Treat it like a password: with it alone someone can list plans, and with your private key as well they can act as you.

**The signed payload** proves the request is yours and carries the data. Instead of a plain JSON body, you send `{"payload": "<JWT>"}`: a JSON Web Token whose claims are the request fields, signed with your RSA private key. Releva verifies it with the public key you registered and then reads the claims as the request. Nothing in the body is trusted unless it is inside the signature.

```plaintext
claims  { "shop": "demo-partner-shop.example.com", "running": false }
   │  sign with partner.key (RS512, expires in 1 h)
   ▼
body    { "payload": "eyJhbGciOiJSUzUxMiIs..." }
```

Two consequences:

* Your private key stays on your server. Releva only ever has the public half, so a leak on Releva’s side cannot be used to forge your requests.
* An expired, tampered or wrongly signed payload is rejected before the request is read. Today that rejection is a `500 An internal error occurred.`, so a sudden run of `500`s usually means a key or clock problem on your side.

The one exception is `GET /partners/subscriptions`, which lists public plan information and needs only the token.

The Partner API never asks for a shop’s own keys. It **gives** them to you: `POST /partners/domains` returns the shop’s `accessToken`, `secretKey` and page tokens, which you then use for the [standard integration](https://releva.ai/documentation/learn/shop-settings/how-releva-connects-to-your-shop/) exactly as a merchant would.

## The name is the key

When you provision a shop, Releva looks for an account with the `name` you sent **and** your partner id. If none exists it creates one, then looks for the domain by URL inside that account. This makes the call repeatable (sending the same data twice answers `200` and changes nothing), but it also means the account name is an identifier, not a label:

* Account names are unique across all of Releva. If a non-partner account or another partner’s account already uses the name, you get a `422`. Include the shop host in the name (`Demo Partner Shop (demo-partner-shop.example.com)`) and the collision cannot happen.
* Sending a **different** name for a shop you already provisioned creates a second account with a second domain for the same URL. It does not rename anything. Store the name you used and resend it unchanged; to change the display name of the shop, use `PUT /partners/domains` with `name`.

## Internal or external billing

Your partner account is configured in one of two billing modes. It decides which endpoints you may call and which webhooks you must implement.

|                           | Internal billing                                                    | External billing                                                                                                                 |
| ------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Who invoices the merchant | Releva                                                              | You (for example through Shopify’s app billing)                                                                                  |
| Endpoints you use         | Provision, update, pause, profiles, sign-on                         | All of those, plus `trialDays`, `subscriptions/confirm`, `uninstall`, `usageRecords/confirm`                                     |
| Webhooks you implement    | Optional: subscribe and unsubscribe                                 | Usage charges, subscription change link, spending limit, delivery suspended, plus the optional ones                              |
| Plan selection            | The merchant picks a plan in the Releva admin; it is active at once | The merchant picks a plan in the Releva admin; Releva asks you for a confirmation link; the plan is pending until you confirm it |

Calling a billing endpoint from an internally billed partner answers `400` with a message that names your partner and billing mode.

## Plans, selections and billing periods

Three objects are involved in external billing, and their ids are easy to mix up.

* A **plan** (subscription) is one of Releva’s products with its tiered and usage-based prices. `GET /partners/subscriptions` lists them. Plan ids are global.
* A **selection** (domain subscription) is “this shop is on that plan”, with the prices that applied when it was chosen. Releva creates it when the merchant picks a plan; its status is `pendingConfirmation` until you confirm it, then `active`; an uninstall parks it as `inactive`. **Selection ids are what `subscriptions/confirm` takes.**
* A **billing period** is a dated window on the account (`start`, `end`, `trialDays`) that usage is counted in. You create and move it with `subscriptions/confirm`.

The confirmation loop, step by step:

1. The merchant chooses a plan in the Releva admin (or you send them to the plan page with a sign-on link).
2. Releva creates the selections as `pendingConfirmation` and `POST`s them to your **subscription change link** URL, authenticated with the shop’s secret key: `{"subscriptions": [{"id": 12, "appliedValues": {...}}]}`. `appliedValues` holds the plan with the tier that matches the shop’s current usage.
3. You create the subscription in your billing system and answer `{"confirmationUrl": "https://..."}`. Releva sends the merchant there to approve the charge.
4. When the merchant approves, you call `subscriptions/confirm` with `subscriptionIds: [12]`, the billing period and the trial days (ask `trialDays` for the days left if the merchant already had a period). Releva activates the selection, removes the superseded ones and sets the shop `running`.
5. On every renewal or plan change, repeat step 4. A confirm with the same `start` as the current period updates it in place and never shortens the trial, so redelivered webhooks are harmless; a later `start` closes the current period a second earlier and opens the new one.

Two optional numbers travel with the confirm and are stored on the shop:

* `dynamicPriceCapUSD`: the most usage-based spend the merchant has approved per period (Shopify calls this the capped amount). Releva tracks usage against it. When the cap is reached, Releva calls your **spending limit** webhook (`{"type": "dynamicPricing"}`) so you can ask the merchant for a higher limit. Data collection continues, but if the shop stays over the cap for a grace period (7 days by default), Releva pauses value delivery (recommendations, messages) and calls your **delivery suspended** webhook (`{"reason": "usageOverLimit"}`). As soon as a higher cap arrives through `PUT /partners/domains` or a new confirm and the period is under it, delivery resumes.
* `fixedPriceAmountUSD`: the fixed amount the merchant pays for the tiered part of the plan. When the shop’s usage grows into a higher tier than that amount covers, Releva asks you for a subscription change link again so the merchant can upgrade.

## Usage charges

For externally billed shops, Releva does not invoice usage; it tells you what to charge. A nightly job computes each shop’s usage for the day, works out what is owed per usage-based price component and mints **usage charges**: ledger rows with an id, an amount, a currency and an idempotency key. It then `POST`s every charge that you have not yet confirmed to your **usage webhook**:

```plaintext
{
  "usageCharges": [
    {
      "chargeId": "123",
      "billingPeriodId": 4,
      "subscriptionDynamicPricingId": 7,
      "reference": "Mail & Push - subscribers",
      "preaggregated": true,
      "day": "2026-10-20",
      "idempotencyKey": "4/16/7/basis-0",
      "amount": "1.20",
      "currency": "USD"
    }
  ]
}
```

The request carries `authorization: Bearer <shop secret key>`, so you know which shop it is for, and times out after 10 seconds. Your job is to collect each charge (for Shopify, create an app usage record with the `idempotencyKey`) and then call `usageRecords/confirm` with the `chargeId` and the amount that landed. Until you confirm, Releva keeps sending the charge every night; a charge pending for more than a week is flagged on Releva’s side. Because every charge is confirmed before the next delta is computed, you are never asked for the same money twice, and growth that happened before a confirm is simply charged as a later delta.

Two kinds of components appear:

* `preaggregated: true` (subscribers, monthly active users, seats): the charge is the **difference** between what the period’s current total should be and what you have already confirmed. One charge at a time per component.
* `preaggregated: false` (page views, messages): one charge per day with that day’s amount.

Either way, invoice what Releva sends, confirm it, and let Releva do the arithmetic. This replaces the older model in which the partner received raw usage records and summed them itself.

## Webhooks Releva calls

All webhooks are `POST` requests with `content-type: application/json`. The billing ones carry `authorization: Bearer <shop secret key>`; look the shop up by that key. Releva gives up after 10 seconds (5 seconds for subscribe and unsubscribe) and retries failures as described.

| Webhook (configured on your partner account)          | When                                                               | Body                                                                                                           | Your answer                                   | Retries                                                                                       |
| ----------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Usage charges                                         | Nightly, for every shop with unconfirmed charges                   | `{"usageCharges": [...]}`                                                                                      | `2xx`, then `usageRecords/confirm` per charge | Every night until confirmed                                                                   |
| Subscription change link                              | The merchant picks a plan, or usage outgrows `fixedPriceAmountUSD` | `{"subscriptions": [{"id", "appliedValues"}]}`                                                                 | `{"confirmationUrl": "https://..."}`          | Not retried; the merchant can pick the plan again                                             |
| Spending limit                                        | `dynamicPriceCapUSD` reached                                       | `{"type": "dynamicPricing"}`                                                                                   | `2xx`                                         | Nightly until one succeeds, while delivery is still active                                    |
| Delivery suspended                                    | Delivery paused after the grace period over the cap                | `{"reason": "usageOverLimit"}`                                                                                 | `2xx`                                         | Nightly until one succeeds                                                                    |
| Subscribe / unsubscribe                               | A profile of the shop subscribes or unsubscribes in Releva         | `{"payload": "<JWT signed by Releva>"}` with claims `email`, `shop` and, on subscribe, `firstName`/`lastName`  | Any; failures are logged and ignored          | None                                                                                          |
| Coupon codes (create, update, delete, search, status) | A dynamic coupon list is generated or used                         | See [How dynamic coupons work](https://releva.ai/documentation/learn/dynamic-coupons/how-dynamic-coupons-work/#shopify-coupons) | JSON                                          | None; a `409` with `code: AUTHORIZATION_REQUIRED` tells the merchant to re-authorise your app |

The subscribe and unsubscribe webhooks are the mirror image of your calls: they are signed by **Releva** (RS512, one hour) with Releva’s own key pair, so ask Releva for the matching public key to verify them. They let you write marketing consent back into the shop. For what subscribing means in Releva, read [How consent works in Releva](https://releva.ai/documentation/learn/consent/how-consent-works-in-releva/).

## Signing merchants into the admin

Merchants manage their Releva setup in the Releva admin. Rather than giving them a separate password, you generate a **single sign-on link**: `https://releva.ai/api/admin/users/partnerSignin/<partner token>/<JWT>` with the shop and the user’s e-mail and name in the claims. Opening it creates the user if needed (they get a welcome e-mail to set a password for direct logins later), grants them access to the shop’s account, signs the browser in and lands them in the shop’s admin.

Where they land depends on the claims and the shop: the plan confirmation page when you pass `subscriptionsToConfirm`, the activation wizard for a Shopify shop whose app embed is not on and that is not live yet, otherwise **Analytics**. The link works for as long as the JWT is valid and for anyone who has it, so generate it when the merchant clicks, give it a few minutes of validity and never store or e-mail it.

## Life cycle of a partner shop

| Event on your side                                | Call to Releva                                                                           | Shop state afterwards                                                                                                  |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Merchant installs your app or signs up            | `POST /partners/domains`                                                                 | Account and domain exist; `running: true`; email and SMS sending disabled until Releva enables them; you hold the keys |
| You finish the storefront and catalog integration | `PUT /partners/domains` with `integrationActive: true` (and `appEmbedActive` on Shopify) | Live and billable                                                                                                      |
| Merchant approves a plan (external billing)       | `subscriptions/confirm`                                                                  | Selection active, billing period open, caps stored                                                                     |
| Merchant pauses the service, or stops paying      | `PUT /partners/domains` with `running: false`                                            | Tracking, personalization and messaging stop; no usage accrues                                                         |
| Merchant resumes                                  | `PUT` with `running: true`                                                               | Running again; suspension reason cleared                                                                               |
| Merchant uninstalls your app (external billing)   | `uninstall`                                                                              | Paused with reason `appUninstalled`, not live, all selections inactive                                                 |
| Merchant reinstalls                               | `PUT` with `running: true, integrationActive: true`, then `subscriptions/confirm`        | Running; old selections removed by the confirm                                                                         |
| Customers change in the shop                      | `POST` / `DELETE /partners/domains/profiles`                                             | Profiles synced                                                                                                        |
| Merchant wants to open the admin                  | Sign-on link                                                                             | User signed in                                                                                                         |

Pausing with `running: false` and the uninstall both stop usage, but only the uninstall touches plan selections. Use the pause for temporary stops and the uninstall for the real thing.

## Next steps

* [Partner API overview](https://releva.ai/documentation/reference/partners/overview/): Find every partner endpoint with a working request, its errors and its limits.
* [How Releva connects to your shop](https://releva.ai/documentation/learn/shop-settings/how-releva-connects-to-your-shop/): Learn what the keys and page tokens of a shop you provision are for.
* [How profiles work](https://releva.ai/documentation/learn/profiles/how-profiles-work/): See how Releva identifies a person and stores the consent and fields the partner profile endpoints write.
* [Turn on the Shopify app embed](https://releva.ai/documentation/guides/shop-settings/turn-on-the-shopify-app-embed/): See the step a Shopify merchant takes so their storefront starts sending data.