Plans

The Plans API lets a merchant read the configuration of its own subscription plans. Its main use case is subscription upselling: plans carry a free-form metaData object that you can use to link related plans together (for example, which plan is the natural upsell of another), and this API is how you read that linkage programmatically.

Authentication

All requests are authenticated with your merchant API key, sent in the x-api-key header. You only ever see the plans of your own merchant; the key defines the identity.

NAME	DESCRIPTION	REQUIRED
`x-api-key`	Merchant API key for the target environment (sandbox or live).	YES

The base URL depends on the environment provided with your API keys. In the examples below it is shown as https://{BASE_URL}.

Both merchantId and planId are UUIDs. A malformed UUID is rejected with 400.

Get plan

METHOD	URL
GET	`/merchant/{merchantId}/plan/{planId}`
EXAMPLE	`https://{BASE_URL}/merchant/{merchantId}/plan/{planId}`

Endpoint to get a single plan by its ID.

Request example - Get plan

curl --location 'https://{BASE_URL}/merchant/{merchantId}/plan/{planId}' \
--header 'x-api-key: {X_API_KEY}'

Success responses - Get plan

HTTP CODE	DESCRIPTION
200	Plan information is provided in the body in JSON format.

Success response example - Get plan

{
  "planId": "4aa7c1e4-cf8c-4d1c-a6ad-451dd07411ee",
  "description": "Premium membership",
  "accountId": "f1b2c3d4-1234-4a5b-8c9d-0123456789ab",
  "merchantId": "74d52e64-e807-4d77-bfe2-76f5274febf1",
  "basicSettings": {
    "cycle": { "time": 28, "unit": "DAY" },
    "chargingTimeMode": "CUSTOM",
    "initialChargingTime": "17:00:00.000",
    "endingChargingTime": "17:59:59.999"
  },
  "amountSettings": {
    "base": "EUR",
    "currencies": {
      "EUR": { "type": "FIXED", "amount": 29.95 }
    }
  },
  "trialSettings": {
    "amountSettings": {
      "EUR": { "type": "FIXED", "amount": 1.95 }
    },
    "period": { "time": 7, "unit": "DAY" }
  },
  "retrySettings": {
    "enabled": true,
    "paymentSpacing": { "time": 1, "unit": "DAY" },
    "sequence": [
      { "type": "RENEWAL", "delay": { "time": 1, "unit": "DAY" } },
      { "type": "MAINTENANCE", "delay": { "time": 3, "unit": "DAY" } }
    ]
  },
  "cancellationSettings": {
    "chargeback": {
      "afterReceiving": { "enabled": true, "amount": 1 }
    }
  },
  "metaData": {
    "upsellGroup": "weight-loss",
    "upsellRole": "upsell-1"
  },
  "created": "2026-08-17T08:13:03.681Z",
  "modified": "2026-09-20T10:31:22.695Z"
}

Error response example - Get plan

A plan that does not exist (or that does not belong to your merchant) returns 404:

{
  "message": "Plan 4aa7c1e4-cf8c-4d1c-a6ad-451dd07411ee not found.",
  "error": "Not Found",
  "statusCode": 404
}

List plans

METHOD	URL
GET	`/merchant/{merchantId}/plan`
EXAMPLE	`https://{BASE_URL}/merchant/{merchantId}/plan`

Endpoint to list your plans, with pagination and filters.

Request example - List plans

curl --location --get 'https://{BASE_URL}/merchant/{merchantId}/plan' \
--header 'x-api-key: {X_API_KEY}' \
--data-urlencode 'page=1' \
--data-urlencode 'limit=20' \
--data-urlencode 'order={"modifiedDate":"DESC"}'

Query parameters - List plans

NAME	DESCRIPTION	REQUIRED	DEFAULT
`page`	Page number to retrieve.	NO	1
`limit`	Page size.	NO	20
`search`	Free-text search over the plan `description` and `planId`.	NO	—
`modifiedDateFrom`	Only plans modified from this instant (ISO 8601). If `modifiedDateTo` is omitted, the filter covers the whole day of `modifiedDateFrom`.	NO	—
`modifiedDateTo`	Only plans modified up to this instant (ISO 8601). Must not be earlier than `modifiedDateFrom`.	NO	—
`order`	Sort order as a JSON object. Only supported key: `modifiedDate`; value: `ASC` or `DESC`. Example: `{"modifiedDate":"DESC"}`.	NO	—

Success responses - List plans

HTTP CODE	DESCRIPTION
200	A page of plans is provided in the body in JSON format.

The response is a pagination envelope: count is the number of items in this page, items the plans, and total the total number of matching plans.

Success response example - List plans

{
  "count": 2,
  "total": 2,
  "items": [
    {
      "planId": "4aa7c1e4-cf8c-4d1c-a6ad-451dd07411ee",
      "description": "Premium membership",
      "accountId": "f1b2c3d4-1234-4a5b-8c9d-0123456789ab",
      "merchantId": "74d52e64-e807-4d77-bfe2-76f5274febf1",
      "basicSettings": {
        "cycle": { "time": 28, "unit": "DAY" },
        "chargingTimeMode": "CUSTOM",
        "initialChargingTime": "17:00:00.000",
        "endingChargingTime": "17:59:59.999"
      },
      "amountSettings": {
        "base": "EUR",
        "currencies": { "EUR": { "type": "FIXED", "amount": 29.95 } }
      },
      "trialSettings": {
        "amountSettings": { "EUR": { "type": "FIXED", "amount": 1.95 } },
        "period": { "time": 7, "unit": "DAY" }
      },
      "retrySettings": {
        "enabled": true,
        "paymentSpacing": { "time": 1, "unit": "DAY" },
        "sequence": [
          { "type": "RENEWAL", "delay": { "time": 1, "unit": "DAY" } }
        ]
      },
      "cancellationSettings": {
        "chargeback": { "afterReceiving": { "enabled": true, "amount": 1 } }
      },
      "metaData": {
        "upsellGroup": "weight-loss",
        "upsellRole": "base"
      },
      "created": "2026-08-17T08:13:03.681Z",
      "modified": "2026-08-17T08:13:03.681Z"
    },
    {
      "planId": "22f71498-d518-49e4-aae4-2585e0800e8e",
      "description": "Premium membership - upsell bundle",
      "accountId": "f1b2c3d4-1234-4a5b-8c9d-0123456789ab",
      "merchantId": "74d52e64-e807-4d77-bfe2-76f5274febf1",
      "basicSettings": {
        "cycle": { "time": 28, "unit": "DAY" },
        "chargingTimeMode": "FIRST_PAYMENT_TIME"
      },
      "amountSettings": {
        "base": "EUR",
        "currencies": { "EUR": { "type": "FIXED", "amount": 39.95 } }
      },
      "retrySettings": { "enabled": false, "paymentSpacing": { "time": 1, "unit": "DAY" }, "sequence": [] },
      "cancellationSettings": {
        "chargeback": { "afterReceiving": { "enabled": true, "amount": 1 } }
      },
      "metaData": {
        "upsellGroup": "weight-loss",
        "upsellRole": "upsell-1"
      },
      "created": "2026-08-18T09:00:00.000Z",
      "modified": "2026-08-18T09:00:00.000Z"
    }
  ]
}

Field reference - Plan

FIELD	TYPE	DESCRIPTION
`planId`	UUID	Unique identifier of the plan. This is the value you send as `planId` when creating subscriptions.
`description`	string	Human-readable plan name/description, as configured in the Backoffice.
`accountId`	UUID	Internal account that owns the merchant.
`merchantId`	UUID	Your merchant identifier.
`basicSettings.cycle.time` / `.unit`	number / enum	Billing cycle length. `unit` is one of `DAY`, `MONTH`, `YEAR`.
`basicSettings.chargingTimeMode`	enum	`CUSTOM` (charge inside the `initialChargingTime`–`endingChargingTime` window) or `FIRST_PAYMENT_TIME` (charge at the time of day of the first payment).
`basicSettings.initialChargingTime` / `endingChargingTime`	string (time)	Charging window, format `HH:mm:ss.SSS`. Only present with `CUSTOM` mode.
`amountSettings.base`	string (ISO 4217) / null	Base currency for dynamic pricing.
`amountSettings.currencies`	object	Map of currency code → `{ type, amount }`. `type` is `FIXED` (exact amount) or `DYNAMIC` (derived from the base currency; `amount` is `null`).
`trialSettings`	object	Optional trial configuration: `amountSettings` per currency and `period` (`time` + `unit`).
`retrySettings.enabled`	boolean	Whether failed renewals are retried.
`retrySettings.paymentSpacing`	object	Minimum spacing between retry attempts (`time` + `unit`).
`retrySettings.sequence`	array	Ordered retry steps. `type` is `RENEWAL` or `MAINTENANCE`, each with a `delay` (`time` + `unit`).
`cancellationSettings.chargeback.afterReceiving`	object	Automatic cancellation policy after a chargeback: `enabled` and `amount` threshold.
`metaData`	object	Free-form key/value map configured in the Backoffice (keys are strings, values are strings or numbers). This is the field used to link plans for upselling.
`created` / `modified`	string (ISO 8601)	Creation and last-modification timestamps (UTC).

Using metadata to link plans for upselling

metaData has no fixed schema: you define the keys that make sense for your catalogue when you create or edit the plan in the Backoffice. A common convention is:

upsellGroup: identifies the product family — all plans sharing the same group are connected.
upsellRole: identifies the role of the plan inside the group (for example base, upsell-1, upsell-2).

Typical flow:

Call GET /merchant/{merchantId}/plan and group the returned plans by your metaData keys.
For a customer with an active subscription on the base plan, pick the target plan from the same group.
Create the upsell subscription with POST /subscriptions using that planId (see Create subscription).

info

These are only suggested key names — the platform stores and returns metaData verbatim and does not enforce any particular convention.

Error responses - Plans

HTTP CODE	DESCRIPTION	WHAT TO DO
400	A path parameter is not a valid UUID, or query parameters fail validation (bad date range, malformed `order` JSON, unsupported sort key, etc.).	Fix the request; the error message names the offending field.
401 / 403	Missing or invalid `x-api-key`, or the key has no access to the endpoint.	Check that you are using the key for the right environment and that the endpoint is enabled for your merchant.
404	The plan does not exist or does not belong to your merchant.	Verify `planId` with GET `/merchant/{merchantId}/plan`.
500	Unexpected internal error.	Retry with backoff; contact support if it persists.

Authentication​

Get plan​

Request example - Get plan​

Success responses - Get plan​

Success response example - Get plan​

Error response example - Get plan​

List plans​

Request example - List plans​

Query parameters - List plans​

Success responses - List plans​

Success response example - List plans​

Field reference - Plan​

Using metadata to link plans for upselling​

Error responses - Plans​