How the Partner API works
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.
If you are a merchant integrating your own shop, you do not need any of this: start with How Releva connects to your shop.
Partner, account, domain
Section titled “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
Section titled “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.
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 of500s 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 exactly as a merchant would.
The name is the key
Section titled “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/domainswithname.
Internal or external billing
Section titled “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
Section titled “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/subscriptionslists 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
pendingConfirmationuntil you confirm it, thenactive; an uninstall parks it asinactive. Selection ids are whatsubscriptions/confirmtakes. - A billing period is a dated window on the account (
start,end,trialDays) that usage is counted in. You create and move it withsubscriptions/confirm.
The confirmation loop, step by step:
- The merchant chooses a plan in the Releva admin (or you send them to the plan page with a sign-on link).
- Releva creates the selections as
pendingConfirmationandPOSTs them to your subscription change link URL, authenticated with the shop’s secret key:{"subscriptions": [{"id": 12, "appliedValues": {...}}]}.appliedValuesholds the plan with the tier that matches the shop’s current usage. - You create the subscription in your billing system and answer
{"confirmationUrl": "https://..."}. Releva sends the merchant there to approve the charge. - When the merchant approves, you call
subscriptions/confirmwithsubscriptionIds: [12], the billing period and the trial days (asktrialDaysfor the days left if the merchant already had a period). Releva activates the selection, removes the superseded ones and sets the shoprunning. - On every renewal or plan change, repeat step 4. A confirm with the same
startas the current period updates it in place and never shortens the trial, so redelivered webhooks are harmless; a laterstartcloses 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 throughPUT /partners/domainsor 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
Section titled “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 POSTs every charge that you have not yet confirmed to your usage webhook:
{ "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
Section titled “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 | 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.
Signing merchants into the admin
Section titled “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
Section titled “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.