# Partner API overview

> The endpoints a platform or agency uses to provision and manage Releva accounts for its merchants: partner token and signed payload authentication, shop lookup, provisioning, pausing, plans, billing periods, uninstall, usage charges, profiles, the single sign-on link, errors and limits, with a working request for each.

The Partner API is for platforms and agencies that create and run Releva accounts on behalf of their merchants. With it you provision a shop, receive its API keys, pause and resume it, bill it (if you own the billing relationship), sync its customers and sign its staff into the Releva admin. Merchants integrating their own shop do not need it: they use the [shop keys](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/) and the regular `/api/v0` endpoints.

For the concepts behind these endpoints (the two credentials, the signed payload, billing modes and the webhooks Releva sends you), read [How the Partner API works](https://releva.ai/documentation/learn/partners/how-the-partner-api-works/).

| Endpoint                                               | Purpose                                                          | Billing mode  |
| ------------------------------------------------------ | ---------------------------------------------------------------- | ------------- |
| `POST /partners/domains`                               | Provision a shop: create its account and domain, or update them  | any           |
| `PUT /partners/domains`                                | Update, pause or resume a shop                                   | any           |
| `GET /partners/subscriptions`                          | List Releva plans and prices                                     | any           |
| `POST /partners/domains/trialDays`                     | Remaining trial days of a shop                                   | external only |
| `POST /partners/domains/subscriptions/confirm`         | Activate the chosen plan and record the billing period           | external only |
| `POST /partners/domains/uninstall`                     | The merchant removed your app: pause the shop and stop its plans | external only |
| `POST /partners/domains/usageRecords/confirm`          | Confirm that a usage charge Releva sent you was collected        | external only |
| `POST /partners/domains/profiles`                      | Create or update customer profiles of a shop                     | any           |
| `DELETE /partners/domains/profiles`                    | Delete a customer profile of a shop                              | any           |
| `GET /api/admin/users/partnerSignin/{token}/{payload}` | Single sign-on link into the Releva admin                        | any           |

Base URL: `https://releva.ai/api/v0`, except the sign-on link, which lives under `https://releva.ai/api/admin`.

## When to use it

* You are a **platform or app** (for example a Shopify or custom-platform connector) and want merchants to get a Releva account without talking to Releva first.
* You are an **agency** that sets up and manages Releva for several clients and wants to script it.
* You handle the merchant’s **billing** yourself. Then you also implement the plan, billing period, uninstall and usage charge endpoints, and the webhooks Releva calls on your side.

Releva registers your partner account by hand: there is no self-service sign-up. See [Before your first call](https://releva.ai/documentation/reference/partners/overview/#before-your-first-call).

## Before your first call

1. Generate an RSA key pair. Any RSA key works; 4096 bits is what the Releva connectors use:

   ```plaintext
   openssl genrsa -out partner.key 4096
   openssl rsa -in partner.key -pubout -outform PEM -out partner.key.pub
   ```

   Keep `partner.key` private. It never leaves your server.

2. Send `partner.key.pub` to Releva (<support@releva.ai> or your Releva contact), together with your billing mode (`internal`: Releva bills the merchant; `external`: you bill the merchant) and, for external billing, the URLs of the webhooks you implement.

3. Releva registers the key and sends you a **partner token** (a UUID). Store it as `$RELEVA_PARTNER_TOKEN`.

## Authentication

Every request carries two things.

**1. The partner token**, in the `x-rlv-partner-token` header (for the sign-on link, in the first path segment):

```plaintext
x-rlv-partner-token: $RELEVA_PARTNER_TOKEN
```

| Problem        | Status | Message                              |
| -------------- | ------ | ------------------------------------ |
| Header missing | `400`  | `Partner identification is missing!` |
| Token unknown  | `400`  | `Partner identification is invalid!` |

**2. A signed payload.** Except for `GET /partners/subscriptions`, the request body is always `{"payload": "<JWT>"}`. The JWT’s claims are the actual request fields; Releva verifies the signature with your public key and then treats the claims as the body. Sign with your RSA private key:

```plaintext
const jwt = require('jsonwebtoken');
const fs = require('fs');


const claims = { shop: 'demo-partner-shop.example.com', running: false };
const payload = jwt.sign(claims, fs.readFileSync('partner.key'), { algorithm: 'RS512', expiresIn: '1h' });
// send {"payload": payload}
```

* Use `RS512` with a one-hour expiry, like the Releva connectors. `RS256`, `RS384` and `PS256`/`PS384`/`PS512` are also accepted.
* Releva honours `exp` when it is present. It does not require it, but always set one, especially on sign-on links, which anyone holding the URL can open until the token expires.
* A payload that cannot be verified (missing, not a JWT, signed with another key, or expired) answers **`500 {"message":"An internal error occurred."}`**, not a `4xx`. If you get a `500` on every call, check your key and clock first.

**3. The shop.** Every endpoint that acts on one shop takes a `shop` claim: the shop’s host as you provisioned it. `https://`, `http://` and a trailing slash are ignored, so `demo-partner-shop.example.com` and `https://demo-partner-shop.example.com/` are the same shop. The shop must belong to an account **you** provisioned:

| Problem                                                               | Status | Message                                                                                                                                                        |
| --------------------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Shop unknown, provisioned by another partner, or `shop` claim missing | `400`  | `Domain with url demo-partner-internal.example.com cannot be found or you don't have access to it.` (with the `shop` you sent; `undefined` when you sent none) |

The Partner API never uses a shop’s secret key or access token. It **returns** them, so you can run the standard integration for the shop.

## Request format

* HTTPS only. Plain HTTP answers `400 {"message":"We do not support non-HTTPS requests."}`.
* Send `content-type: application/json`. The body is `{"payload": "<JWT>"}`; the JWT carries the fields.
* Bodies are limited to **800 KB**. Larger bodies answer `413`.
* Every curl on this page has the same shape; only the method, the path and the signed claims change:

```plaintext
curl -X POST 'https://releva.ai/api/v0/partners/domains' \
  -H 'content-type: application/json' \
  -H "x-rlv-partner-token: $RELEVA_PARTNER_TOKEN" \
  -d "{\"payload\":\"$PAYLOAD\"}"
```

`$PAYLOAD` is the signed JWT of the claims shown with each endpoint.

## Responses

Errors have one shape, `{"message": "..."}`, with no error code. When several fields fail validation the messages are joined with a space.

| Status | When                                                                                                        |
| ------ | ----------------------------------------------------------------------------------------------------------- |
| `200`  | Done; the body is described per endpoint                                                                    |
| `201`  | `POST /partners/domains` created a new account and domain                                                   |
| `202`  | A profile write or delete was accepted and is processed asynchronously; body `{}`                           |
| `302`  | The sign-on link signed the user in and redirects to the admin                                              |
| `400`  | Partner token, shop lookup, billing mode or validation error                                                |
| `404`  | `usageRecords/confirm` for a charge that is not this shop’s                                                 |
| `413`  | Body larger than 800 KB                                                                                     |
| `422`  | The account name belongs to someone else, or a value failed model validation (`Validation error! ...`)      |
| `500`  | The payload could not be verified, or an unexpected error; body `{"message":"An internal error occurred."}` |

## Limits

* No rate limit on any partner endpoint. The connectors call them on install, on settings changes and on webhooks, not in loops.
* Body size 800 KB per request. For profile syncs, send batches of a few hundred profiles.
* Billing endpoints (`trialDays`, `subscriptions/confirm`, `uninstall`, `usageRecords/confirm`) answer `400` unless your partner account is configured for external billing: `Partner Demo Partner Internal Billing it not allowed to use this API because it is not configured for external billing management. Actual value: internal` (the double space and “it not” are in the message).
* Account names are unique across Releva. Include the shop host in the `name` you provision (`Demo Partner Shop (demo-partner-shop.example.com)`), so two merchants with the same shop name cannot collide.

## Endpoints

### Provision a shop

`POST /api/v0/partners/domains`

Creates the merchant’s account and domain and answers `201`, or answers `200` with the current state when you already provisioned the same `name` and `url`. Call it when a merchant installs your app or signs up through you.

Claims:

| Claim                                       | Type   | Required  | Description                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `url`                                       | string | yes       | Shop host, for example `demo-partner-shop.example.com`. Protocol and trailing slash are removed; Releva stores `https://<host>`.                                                                                                                                                                                               |
| `name`                                      | string | yes       | Account name. **It is the key that identifies the account**: unique across Releva, and the account is found by `name` + your partner on every later call. Include the shop host.                                                                                                                                               |
| `platform`                                  | string | yes       | One of `magento1`, `magento2`, `opencart`, `cloudcart`, `woocommerce`, `shopify`, `cscart`, `merchantpro`, `gombashop`, `prestashop`, `valival`, `custom`, `shopiko`, `gomag`, `xxsale`. Use `custom` when yours is not listed.                                                                                                |
| `currencyCode`                              | string | on create | Primary currency, ISO 4217 (`EUR`). Becomes the shop’s `currency`.                                                                                                                                                                                                                                                             |
| `contactEmail`                              | string | on create | Primary contact. Becomes the shop’s sender and reply-to address. Not changed on later calls.                                                                                                                                                                                                                                   |
| `timezoneOffset`                            | string | on create | UTC offset as `+HHMM` or `-HHMM` (`+0300`). Sets the shop’s quiet hours to 22:00–09:00 local time. Not changed on later calls.                                                                                                                                                                                                 |
| `locale`                                    | string | on create | Primary language, ISO 639-1 (`en`). Also picks the template the new shop’s pages and campaigns are copied from.                                                                                                                                                                                                                |
| `productSyncType`                           | string | no        | `api` (default), `fbCsvFeed` or `fbXmlFeed`.                                                                                                                                                                                                                                                                                   |
| `productSyncApiUrl`, `subscriberSyncApiUrl` | string | no        | Pull URLs for the catalog and subscriber syncs. For `custom` shops they default to `https://<host>/api/releva/products` and `https://<host>/api/releva/subscribers`; the other platforms have fixed defaults. See [Default sync URLs](https://releva.ai/documentation/learn/shop-settings/how-releva-connects-to-your-shop/#default-sync-urls). |

“On create” fields are not checked by the endpoint, but the database requires them when the domain is created. Always send all seven.

```plaintext
# claims to sign
{
  "url": "demo-partner-shop.example.com",
  "name": "Demo Partner Shop (demo-partner-shop.example.com)",
  "platform": "custom",
  "currencyCode": "EUR",
  "contactEmail": "owner@demo-partner-shop.example.com",
  "timezoneOffset": "+0300",
  "locale": "en"
}


curl -X POST 'https://releva.ai/api/v0/partners/domains' \
  -H 'content-type: application/json' \
  -H "x-rlv-partner-token: $RELEVA_PARTNER_TOKEN" \
  -d "{\"payload\":\"$PAYLOAD\"}"
```

Response `201` (new) or `200` (existing). The body is the full domain record (about 105 fields) with its pages. The fields you need:

```plaintext
{
  "domain": {
    "id": 16,
    "accountId": 5,
    "name": "Demo Partner Shop (demo-partner-shop.example.com)",
    "url": "https://demo-partner-shop.example.com",
    "accessToken": "<uuid>",
    "secretKey": "<uuid>",
    "platform": "custom",
    "currency": "EUR",
    "locale": "en",
    "running": true,
    "integrationActive": null,
    "disabledServices": ["email", "textMessage"],
    "senderName": "Demo Partner Shop (demo-partner-shop.example.com)",
    "senderEmail": "owner@demo-partner-shop.example.com",
    "quietHoursStart": "22:00:00.000+0300",
    "quietHoursEnd": "09:00:00.000+0300",
    "productSyncType": "api",
    "pages": [
      { "name": "<page name>", "token": "<uuid>" }
    ]
  }
}
```

Store `domain.accessToken` (for the storefront and the SDKs), `domain.secretKey` (for server-to-server calls, keep it on your server) and each `pages[].token` by `pages[].name`. They are what the shop’s [standard integration](https://releva.ai/documentation/learn/shop-settings/how-releva-connects-to-your-shop/) needs. The `pages` array comes from Releva’s template for the platform and locale.

What a new shop looks like: `running: true`; email and SMS sending are off (`disabledServices`) until Releva enables them; subscription management is `internal`; the sender name is the `name` you sent and the sender e-mail is `contactEmail`. Releva also starts generating the shop’s brand identity and notifies its CRM.

On the `200` path only `name`, `currency`, `locale`, `platform` and the sync fields are updated, and `subscriptionManagement` and `subscriptionRequestBehavior` are reset to `internal` and `subscribe`; sender, quiet hours and `contactEmail` stay as they were. Fields you leave out are not changed.

> **Caution**
>
> The account is found by `name`. If you send a different `name` for a shop you already provisioned, Releva does not rename it: it creates a **second** account and a second domain with the same URL. Store the exact `name` you used first and resend it on every call.

| Cause                                                   | Status | Message                                                                                                                                                                                                        |
| ------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url` missing or empty after normalization (`https://`) | `400`  | `url is required`                                                                                                                                                                                              |
| `name` missing                                          | `400`  | `name is required`                                                                                                                                                                                             |
| `platform` missing                                      | `400`  | `platform is required`                                                                                                                                                                                         |
| Unknown platform                                        | `400`  | `Unsupported platform "bigcommerce". Supported platforms: magento1, magento2, opencart, cloudcart, woocommerce, shopify, cscart, merchantpro, gombashop, prestashop, valival, custom, shopiko, gomag, xxsale.` |
| `name` already used by an account that is not yours     | `422`  | `An account named "Demo Partner Internal Shop (demo-partner-internal.example.com)" already exists. Account names are unique across Releva - send a name that includes the shop domain.`                        |

### Update, pause or resume a shop

`PUT /api/v0/partners/domains`

Changes settings of a shop you provisioned. Claims: `shop` plus any of the fields below. Fields you leave out keep their value; unknown fields are ignored.

| Claim                                                                                                                | Type    | Description                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `running`                                                                                                            | boolean | `false` pauses the shop: tracking, personalization and messaging stop, so no usage accrues. `true` resumes it and clears the suspension reason.                                                 |
| `name`                                                                                                               | string  | Domain display name.                                                                                                                                                                            |
| `url`                                                                                                                | string  | New shop URL, stored as sent.                                                                                                                                                                   |
| `senderName`, `senderEmail`, `replyToEmail`                                                                          | string  | E-mail sender settings.                                                                                                                                                                         |
| `unsubscribeLink`                                                                                                    | string  | The shop’s newsletter settings page. Must be an `http(s)` URL; validated only when it changes.                                                                                                  |
| `maxEmailsPerDay`                                                                                                    | integer | 1 to 10.                                                                                                                                                                                        |
| `quietHoursStart`, `quietHoursEnd`                                                                                   | string  | For example `22:00:00.000+0300`.                                                                                                                                                                |
| `locale`, `currency`                                                                                                 | string  | ISO 639-1 and ISO 4217.                                                                                                                                                                         |
| `productSyncType`, `productSyncApiUrl`, `subscriberSyncApiUrl`, `productSyncSchedule`                                | string  | Sync type (`api`, `fbCsvFeed`, `fbXmlFeed`), pull URLs and a cron schedule.                                                                                                                     |
| `defaultProductImageUrl`                                                                                             | string  | Image for products without one.                                                                                                                                                                 |
| `integrationActive`                                                                                                  | boolean | The shop is live and billable. Set it to `true` when you reinstall after an uninstall.                                                                                                          |
| `appEmbedActive`                                                                                                     | boolean | Shopify only: the theme app embed is on. Releva stamps `appEmbedCheckedAt` with the server time.                                                                                                |
| `dynamicPriceCapUSD`, `fixedPriceAmountUSD`                                                                          | number  | The price caps; see [Confirm a plan](https://releva.ai/documentation/reference/partners/overview/#confirm-a-plan-and-billing-period). Raising `dynamicPriceCapUSD` lifts a usage-limit suspension immediately when the current period is under the new cap. |
| `subscriptionManagement`, `subscriptionRequestBehavior`, `onboardingSessionScheduledAt`, SMS and Viber sender fields |         | Accepted; change them only in agreement with Releva.                                                                                                                                            |

Leave `controlGroupFraction` out: it is a legacy domain-level setting in basis points, and a decimal value answers `500`.

```plaintext
# claims to sign
{ "shop": "demo-partner-shop.example.com", "running": false }


curl -X PUT 'https://releva.ai/api/v0/partners/domains' \
  -H 'content-type: application/json' \
  -H "x-rlv-partner-token: $RELEVA_PARTNER_TOKEN" \
  -d "{\"payload\":\"$PAYLOAD\"}"
```

Response `200 {"domain": {...}}`: the full domain record, now with an `account` object (`id`, `name`, `partnerId`, invoice fields). To resume, send `running: true`.

| Cause                                                                | Status | Message                                                                                    |
| -------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------ |
| Unknown shop                                                         | `400`  | `Domain with url unknown-shop.example.com cannot be found or you don't have access to it.` |
| `unsubscribeLink` is not an http(s) URL                              | `400`  | `unsubscribeLink must be a valid URL`                                                      |
| Value outside the allowed list, for example `productSyncType: "csv"` | `422`  | `Validation error! Validation is In on product Sync Type failed`                           |

### List Releva plans

`GET /api/v0/partners/subscriptions`

Lists every Releva plan with its prices, so you can show them to a merchant. This is the only endpoint without a payload: send the partner token and nothing else.

```plaintext
curl 'https://releva.ai/api/v0/partners/subscriptions' \
  -H 'content-type: application/json' \
  -H "x-rlv-partner-token: $RELEVA_PARTNER_TOKEN"
```

Response `200 {"subscriptions": [...]}`, ordered by `position`. Each plan has `id`, `name`, `type` (`flagship` or `modular`), `description`, `currency`, `allowedActions` (the admin features the plan unlocks), `hidden`, `position`, `subscriptionTieredPricings[]` (`id`, `name`, `treshold` (spelled like that), `price`, `unit: "subscribers"`) and `subscriptionDynamicPricings[]` (`id`, `unitPrice`, `unit`: one of `monthlyActiveUsers`, `subscribers`, `seats`, `pageViews`, `emailsSent`, `viberTextMessages`, `viberMultimediaMessages`, `textMessages`). `price` and `unitPrice` are decimals (expect them as strings). Plans with `hidden: true` are included; filter them out before showing the list.

The plan `id` values are **not** what you send to `subscriptions/confirm`; see the next section.

### Get remaining trial days

`POST /api/v0/partners/domains/trialDays` (external billing only)

Returns how many trial days the shop has left in its current billing period, counted in whole days from the period’s start. A shop without a billing period gets the default, `30`. Use it to set the trial on the merchant’s subscription in your own billing system.

```plaintext
# claims to sign
{ "shop": "demo-partner-shop.example.com" }
```

Response `200`:

```plaintext
{ "trialDays": 30 }
```

### Confirm a plan and billing period

`POST /api/v0/partners/domains/subscriptions/confirm` (external billing only)

Tells Releva which of the shop’s plan selections the merchant accepted and paid for, and when the billing period runs. Call it when the merchant approves the subscription in your system (for Shopify, when the app subscription becomes active) and again on every plan change or renewal.

| Claim                 | Type      | Required | Description                                                                                                                                                                                                                                                                                                                                             |
| --------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shop`                | string    | yes      |                                                                                                                                                                                                                                                                                                                                                         |
| `subscriptionIds`     | number\[] | yes      | Ids of the shop’s **domain subscriptions**: the pending selections Releva sent to your subscription change link, or the ids in the sign-on link’s `subscriptionsToConfirm`. Not the plan ids from `GET /partners/subscriptions`. The listed ones become active; every other active or inactive selection of the shop is removed. `[]` removes them all. |
| `start`, `end`        | string    | yes      | Billing period, ISO 8601 with time and offset, for example `2026-10-21T00:00:00.000Z`.                                                                                                                                                                                                                                                                  |
| `trialDays`           | number    | yes      | Trial days counted from `start`.                                                                                                                                                                                                                                                                                                                        |
| `dynamicPriceCapUSD`  | number    | no       | Maximum usage-based charge per billing period. When the shop is over it, Releva pauses delivery and asks you (through your webhooks) to let the merchant raise it.                                                                                                                                                                                      |
| `fixedPriceAmountUSD` | number    | no       | The fixed (tiered) amount the merchant pays per period. When the tiered price for the shop’s actual usage exceeds it, Releva asks you for a plan change link.                                                                                                                                                                                           |

```plaintext
# claims to sign
{
  "shop": "demo-partner-shop.example.com",
  "subscriptionIds": [12],
  "start": "2026-10-21T00:00:00.000Z",
  "end": "2026-11-20T23:59:59.000Z",
  "trialDays": 14,
  "dynamicPriceCapUSD": 100,
  "fixedPriceAmountUSD": 50
}
```

Response `200`:

```plaintext
{
  "billingPeriod": {
    "id": 4,
    "start": "2026-10-21T00:00:00.000Z",
    "end": "2026-11-20T23:59:59.000Z",
    "trialDays": 14,
    "accountId": 5,
    "createdAt": "2026-10-21T19:21:39.747Z",
    "updatedAt": "2026-10-21T19:21:39.747Z"
  }
}
```

Besides the plan selections, the call sets `running: true` and stores the two caps on the shop. It does not touch `integrationActive`.

How billing periods are reconciled:

| Your `start` compared with the shop’s current period           | Result                                                                                                                                                                                |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No period overlaps                                             | A new period is created.                                                                                                                                                              |
| Same `start` as the current period                             | That period is kept: `end` is updated and `trialDays` becomes the larger of the old and new value (it never shrinks). This makes redelivered webhooks and same-day plan changes safe. |
| Later than the current period’s start (plan change mid-period) | The current period ends one second before your `start`; a new period begins.                                                                                                          |
| Earlier than the current period’s start                        | `400`. Billing periods cannot be moved backwards.                                                                                                                                     |

| Cause                                       | Status | Message                                                                                                                                                                                                                      |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Required fields missing                     | `400`  | `The 'subscriptionIds' field is required. The 'start' field is required. The 'end' field is required. The 'trialDays' field is required.`                                                                                    |
| Date without time, for example `2026-11-01` | `400`  | `start must be a valid ISO-8601 date including seconds and timezone offset with optional milliseconds such as 2020-01-01T23:59:59.999Z or 2020-01-01T23:59:59.999-0500 or 2020-01-01T23:59:59-0500. Got 2026-11-01 instead.` |
| Id that is not a number                     | `400`  | `The 'subscriptionIds[0]' field must be a number.`                                                                                                                                                                           |
| `start` before the current period’s start   | `400`  | `The start date of this subscription needs to be later than the start date of the last billing period. This is not supported!`                                                                                               |

### Report that the app was uninstalled

`POST /api/v0/partners/domains/uninstall` (external billing only)

Call it when the merchant removes your app (for Shopify, from the `app/uninstalled` webhook). In one step Releva pauses the shop (`running: false`, `runningSuspendedReason: "appUninstalled"`), marks it not live (`integrationActive: false`) and sets every active and pending plan selection to inactive, so billing stops. Safe to repeat: a second call changes nothing and still answers `200`.

```plaintext
# claims to sign
{ "shop": "demo-partner-shop.example.com" }
```

Response `200`:

```plaintext
{ "domain": { "running": false, "runningSuspendedReason": "appUninstalled", "integrationActive": false }, "deactivatedSubscriptions": 1 }
```

(`domain` is the full record with its `account`; `deactivatedSubscriptions` is the number of selections that were still active or pending.)

When the merchant reinstalls, send `PUT /partners/domains` with `running: true` and `integrationActive: true`, and confirm the new plan with `subscriptions/confirm`. The inactive selections are removed by that confirm.

### Confirm a usage charge

`POST /api/v0/partners/domains/usageRecords/confirm` (external billing only)

Releva sends usage charges to your usage webhook (see [Webhooks Releva calls](https://releva.ai/documentation/learn/partners/how-the-partner-api-works/#webhooks-releva-calls)). After you collect a charge, confirm it so Releva stops resending it and counts it as paid.

| Claim                     | Type             | Required | Description                                                                                                                                                                                               |
| ------------------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `shop`                    | string           | yes      |                                                                                                                                                                                                           |
| `chargeId`                | string           | yes      | The `chargeId` from the webhook (a digit string).                                                                                                                                                         |
| `acceptedAmount`          | string or number | no       | What you actually collected, in the charge’s currency. Defaults to the full amount; a higher value is capped at the charged amount. Zero or negative leaves the charge pending, so Releva sends it again. |
| `shopifyAppUsageRecordId` | string           | no       | Your own record id, stored for support.                                                                                                                                                                   |

```plaintext
# claims to sign
{ "shop": "demo-partner-shop.example.com", "chargeId": "123", "acceptedAmount": "1.20" }
```

Response `200 {"confirmed": true}` when the charge is accepted (now or already), `{"confirmed": false}` when it stays pending. Repeating a confirm is a no-op; the first accepted amount wins.

| Cause                                                                   | Status | Message                                |
| ----------------------------------------------------------------------- | ------ | -------------------------------------- |
| Unknown, missing or non-numeric `chargeId`, or a charge of another shop | `404`  | `Unknown usage charge for this domain` |

### Create or update profiles

`POST /api/v0/partners/domains/profiles`

Writes customer profiles into a shop you provisioned, with the same semantics as the shop’s own [`POST /profiles`](https://releva.ai/documentation/reference/profiles/overview/#create-or-update-profiles). Use it to sync the merchant’s customers and their marketing consent.

Claims: `shop` and `profiles`, an array (at least 1) of `{ "profile": {...} }`. Each `profile` needs at least one of `id`, `email` or `phoneNumber` and may contain `firstName`, `lastName`, `registeredAt` and `subscribedAt` (ISO 8601 with time; omit `subscribedAt` unless the user subscribed, and do not send `null`), `addTags`, `removeTags`, `subscriptions` (replaces the list), `unsubscribeLink` (URL or empty string), `birthday` (`YYYY-MM-DD`), `custom`, `addCustom`, `location` (`{lon, lat}`) and `consent`. No other key is allowed. Next to `profile`, each entry takes `subscribedAtChanged`: send `true` whenever you send `subscribedAt`. Entries with none of the three identifiers are dropped; the request fails only when nothing is left.

```plaintext
# claims to sign
{
  "shop": "demo-partner-shop.example.com",
  "profiles": [
    {
      "profile": {
        "id": "DEMO-PARTNER-CUSTOMER-1001",
        "email": "maria@example.com",
        "firstName": "Maria",
        "lastName": "Example",
        "registeredAt": "2026-10-01T09:00:00.000Z",
        "subscribedAt": "2026-10-01T09:00:00.000Z",
        "addTags": ["demo"]
      },
      "subscribedAtChanged": true
    }
  ]
}
```

Response `202 {}`. The profiles are written asynchronously.

| Cause                                       | Status | Message                                                                     |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------- |
| `profiles` missing                          | `400`  | `The 'profiles' field is required.`                                         |
| Empty array                                 | `400`  | `The 'profiles' field must contain at least 1 items.`                       |
| No entry has `id`, `email` or `phoneNumber` | `400`  | `profiles[0].profile: at least one of (id, email, phoneNumber) is required` |
| Unknown key                                 | `400`  | `The object 'profiles[0].profile' contains forbidden keys: 'nickname'.`     |
| Invalid e-mail                              | `400`  | `The 'profiles[0].profile.email' field must be a valid e-mail.`             |

### Delete a profile

`DELETE /api/v0/partners/domains/profiles?email=maria@example.com`

Deletes the profile matching the identifier, together with the anonymous profiles linked to it. The identifier goes in the **query string** (`profileId`, `email` or `phoneNumber`); the body still carries the signed payload with `shop`.

```plaintext
# claims to sign
{ "shop": "demo-partner-shop.example.com" }


curl -X DELETE 'https://releva.ai/api/v0/partners/domains/profiles?email=maria@example.com' \
  -H 'content-type: application/json' \
  -H "x-rlv-partner-token: $RELEVA_PARTNER_TOKEN" \
  -d "{\"payload\":\"$PAYLOAD\"}"
```

Response `202 {}`, also when nothing matches or no identifier is given.

| Cause                   | Status | Message                                            |
| ----------------------- | ------ | -------------------------------------------------- |
| Unknown query parameter | `400`  | `The object '' contains forbidden keys: 'userId'.` |

### Single sign-on link

`GET https://releva.ai/api/admin/users/partnerSignin/{token}/{payload}`

A URL you generate and open in the merchant’s browser (for example from a button in your app). `{token}` is your partner token and `{payload}` a JWT with these claims:

| Claim                             | Required    | Description                                                                         |
| --------------------------------- | ----------- | ----------------------------------------------------------------------------------- |
| `shop`                            | yes         | The shop.                                                                           |
| `user.email`                      | yes         | The person signing in.                                                              |
| `user.firstName`, `user.lastName` | recommended | Used when the user is created.                                                      |
| `role`                            | no          | Role on the shop’s account, used only when the user gets access for the first time. |
| `subscriptionsToConfirm`          | no          | Domain subscription ids to show on the plan confirmation page.                      |

```plaintext
const payload = jwt.sign(
  { shop: 'demo-partner-shop.example.com', user: { firstName: 'Maria', lastName: 'Example', email: 'maria@example.com' } },
  fs.readFileSync('partner.key'),
  { algorithm: 'RS512', expiresIn: '5m' }
);
const link = `https://releva.ai/api/admin/users/partnerSignin/${process.env.RELEVA_PARTNER_TOKEN}/${payload}`;
```

Opening the link:

1. Creates the user if the e-mail is new, and sends a “Welcome to Releva!” e-mail with a **Confirm your account** button to set a password.
2. Gives the user access to the shop’s account if it has none.
3. Signs the browser in and redirects (`302`) to the shop’s admin: the plan confirmation page when `subscriptionsToConfirm` is set, the activation wizard for a Shopify shop whose app embed is not on and that is not live yet (`integrationActive` false or unset), otherwise **Analytics**.

The link is valid as long as the JWT is. Generate it on demand with a short expiry and never cache or e-mail it.

| Cause                       | Status | Message                                                                                    |
| --------------------------- | ------ | ------------------------------------------------------------------------------------------ |
| Unknown partner token       | `400`  | `Partner identification is invalid!`                                                       |
| Shop not provisioned by you | `400`  | `Domain with url unknown-shop.example.com cannot be found or you don't have access to it.` |
| Payload not verifiable      | `500`  | `An internal error occurred.`                                                              |

## Versioning

All partner endpoints are under `/api/v0` (the sign-on link under `/api/admin`). Changes are listed in the [API changelog](https://releva.ai/documentation/changelog/api/). Compared with the previous version of this page: the plan list is a `GET` with the token only and returns `{"subscriptions": [...]}`; the confirm field is `fixedPriceAmountUSD` and `trialDays` is required; the usage webhook sends `usageCharges` that you confirm with `usageRecords/confirm`.

## Next steps

* [How the Partner API works](https://releva.ai/documentation/learn/partners/how-the-partner-api-works/): Understand the credentials, billing modes, webhooks and life cycle of a partner shop.
* [How Releva connects to your shop](https://releva.ai/documentation/learn/shop-settings/how-releva-connects-to-your-shop/): Learn what to do with the keys and page tokens you receive for a shop.
* [Profiles API overview](https://releva.ai/documentation/reference/profiles/overview/): Check the profile fields and subscriber sync rules the partner profile endpoints share.
* [Turn on the Shopify app embed](https://releva.ai/documentation/guides/shop-settings/turn-on-the-shopify-app-embed/): See the merchant step that the app embed status in the shop response reports on.