Skip to content

Area: Developers

Partner API overview

Used byShopify, MerchantPro, Partner platforms

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

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.

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

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

    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.

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):

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:

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.

  • 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:
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.

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."}
  • 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.

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.

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

# 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:

{
"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 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.

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.

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

# 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

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.

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.

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.

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

Response 200:

{ "trialDays": 30 }

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.
# 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:

{
"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!

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.

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

Response 200:

{ "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.

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

Releva sends usage charges to your usage webhook (see 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.
# 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

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

# 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 /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.

# 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'.

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

All partner endpoints are under /api/v0 (the sign-on link under /api/admin). Changes are listed in the API changelog. 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.