Skip to content

Area: Developers

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.

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.

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 of 500s 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.

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.

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.

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 POSTs 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.

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.

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.

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.

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.