Customer state

Read one buyer's subscriptions and purchases by your account reference or by email: fields, statuses and limits.

GET /api/v1/customers/state returns the subscriptions and purchases of one of your buyers: what the partner sees in the cabinet's subscribers and order lists, for one person and machine-readable. It answers 200 always; for an unknown (or foreign) buyer both lists are empty.

The server API is for a partner whose application knows its own user: a payment is created from your server, with no button or panel on a page, and the user's state (subscriptions and purchases) is read by your own account reference. The key is the same as for the access check (API key tab in the cabinet), sent as Authorization: Bearer; the partner is identified by the key, there is no partner parameter. Rate limits are the same as for the access check: per your server's address and per key. Responses are JSON only and never cached. You can ask only about your own products and buyers: a foreign product or buyer and a non-existent one answer alike.

Request

http

GET https://app.norelio.eu/api/v1/customers/state?clientReference={reference}
GET https://app.norelio.eu/api/v1/customers/state?email={email}
Authorization: Bearer {api key}

Exactly one query parameter: clientReference (your account reference, same format) or email (the buyer's email, lower-cased as in the cabinet). Both or neither is a 400 error. By account reference, the orders carrying it are found together with the subscriptions those orders started, including their renewals.

Example by client reference

curl -s "https://app.norelio.eu/api/v1/customers/state?clientReference=acc_10294" \
  -H "Authorization: Bearer $NORELIO_API_KEY"

{"subscriptions":[{"id":"sub_4d5e6f","productId":"prod_1a2b3c","status":"active","validUntil":"2026-04-14T09:26:53.000Z","currentPeriodEnd":"2026-04-14T09:26:53.000Z","cancelAtPeriodEnd":false,"clientReference":"acc_10294"}],"purchases":[{"orderId":"ord_7k3m2p","productId":"prod_1a2b3c","paidAt":"2026-03-14T09:26:53.000Z","amount":1990,"currency":"EUR","status":"paid","clientReference":"acc_10294","refunded":false},{"orderId":"ord_9z8y7x","productId":"prod_4d5e6f","paidAt":"2026-02-01T18:03:11.000Z","amount":990,"currency":"EUR","status":"refunded","clientReference":"acc_10294","refunded":true}]}

Example by email

curl -s "https://app.norelio.eu/api/v1/customers/state?email=buyer%40example.com" \
  -H "Authorization: Bearer $NORELIO_API_KEY"

Response

200 OK with two lists. Each subscription:

Field	Description
`id`	The subscription id at Norelio.
`productId`	The product id.
`status`	The subscription state as in the buyer's account: active — charges are running; past_due — the last charge failed and the provider is retrying; canceled — charges stopped, the paid period runs out; ended — the subscription is over.
`validUntil`	Until when access is paid (ISO 8601): the same date the access check returns, without grace; null when there is no access. It is the access date, not the next charge: a refund or a closed access shortens it.
`currentPeriodEnd`	End of the current paid period as the provider reports it, i.e. the next charge; null when unknown.
`cancelAtPeriodEnd`	true when charges have been stopped and the subscription runs out its period.
`clientReference`	The account reference of the order the subscription started with, or null.

Each purchase:

Field	Description
`orderId`	The order id — the same paymentId as in the webhooks.
`productId`	The product id; null for a payment without a product.
`paidAt`	When the payment was confirmed (ISO 8601); null while it is not.
`amount`	The price shown to the buyer, in the smallest currency unit (cents), without VAT — like amount in the webhook.
`currency`	The currency of that price, three-letter code.
`status`	paid, refunded (in full) or disputed.
`clientReference`	The account reference by the client reference rule: for a subscription renewal, the one of the order the subscription started with; null when none was passed.
`refunded`	true when money went back to the buyer, in full or in part.
`credits`	For a top-up purchase, the number of credits bought (from the order's snapshot); null for any other purchase.
`creditsUnit`	For a top-up purchase, the unit name; null for any other purchase.

Each list holds up to 50 rows, newest first. Purchases include only orders on which money actually moved: paid, refunded and disputed ones; unpaid and cancelled attempts are not shown.

Example response

{
  "subscriptions": [
    {
      "id": "sub_4d5e6f",
      "productId": "prod_1a2b3c",
      "status": "active",
      "validUntil": "2026-04-14T09:26:53.000Z",
      "currentPeriodEnd": "2026-04-14T09:26:53.000Z",
      "cancelAtPeriodEnd": false,
      "clientReference": "acc_10294"
    }
  ],
  "purchases": [
    {
      "orderId": "ord_7k3m2p",
      "productId": "prod_1a2b3c",
      "paidAt": "2026-03-14T09:26:53.000Z",
      "amount": 1990,
      "currency": "EUR",
      "status": "paid",
      "clientReference": "acc_10294",
      "refunded": false
    },
    {
      "orderId": "ord_9z8y7x",
      "productId": "prod_4d5e6f",
      "paidAt": "2026-02-01T18:03:11.000Z",
      "amount": 990,
      "currency": "EUR",
      "status": "refunded",
      "clientReference": "acc_10294",
      "refunded": true
    }
  ]
}

Unknown buyer

{
  "subscriptions": [],
  "purchases": []
}

Errors

An error from any API endpoint is JSON of one shape: an error object with code (one of the codes below) and message (a short English sentence). A 429 response carries a Retry-After header. The access check keeps its own, older error shape.

Status	Code	When
`429`	`rate_limited`	too many requests in a row, from your address or with your key
`401`	`invalid_api_key`	the key is missing or does not match
`400`	`invalid_request`	the body or the query is malformed; message says what exactly
`403`	`direct_checkout_not_enabled`	creating payments from your server is not yet enabled for your account: the platform first reviews your purchase terms (the same review as for direct checkout)
`404`	`product_not_found`	no product with this id belongs to your account, or it cannot be bought right now
`502`	`checkout_failed`	the payment provider could not start the payment; retry later
`404`	`not_found`	no such endpoint
`405`	`method_not_allowed`	the endpoint does not accept that method
`403`	`test_key_required`	the endpoint works only with the test API key (it starts with nrl_test_), and the request came with the live key
`404`	`test_order_not_found`	no test order with this id belongs to your account, or it has already been deleted: test orders live for 30 days
`409`	`test_action_not_allowed`	the action is not possible in the test order's current state, such as a refund of an order not yet paid or a renewal of a canceled subscription; message names the reason

Example error

{
  "error": {
    "code": "direct_checkout_not_enabled",
    "message": "Creating payments from your server is enabled after the platform has reviewed your purchase terms. Ask support from the cabinet's Messages section."
  }
}