Manage a subscription

POST /api/v1/subscriptions/{id}/manage-link returns a link to the page where the buyer manages ONE of your subscriptions: the same page the renewal and failed-charge emails lead to — the period, the next charge, cancelling at the end of the period. Put a "Manage subscription" button in your application and open the link when the user presses it. The subscription is named by its id from the customer state (subscriptions[].id); the body is optional.

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

POST https://app.norelio.eu/api/v1/subscriptions/{id}/manage-link
Authorization: Bearer {api key}
Content-Type: application/json

curl -s -X POST "https://app.norelio.eu/api/v1/subscriptions/sub_4d5e6f/manage-link" \
  -H "Authorization: Bearer $NORELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"returnUrl":"https://pawclaw.com/account"}'

The return address follows the rules of Return URL. A returnUrl that fails the check does not stop the link: it is created without the return button, and warnings carries return_url_rejected ("returnUrl was ignored: it is not an https address on one of the return sites allowed for your account. The link was created without the button that returns the buyer to your app.").

Response

201 Created with these fields:

{
  "subscriptionId": "sub_4d5e6f",
  "url": "https://pay.lis-system.eu/subscription/eyJpZCI6InN1Yl80ZDVlNmYiLCJleHAiOjE3NzM0ODQ0MTN9.Qm9ndXNTaWduYXR1cmVFeGFtcGxl",
  "expiresAt": "2026-03-14T10:26:53.000Z",
  "warnings": [],
  "test": false
}

What the buyer sees

The page shows the subscription to whoever opens the link, without signing in, and lets them cancel it at the end of the period. Links in the emails Norelio sends the buyer keep working as before and do not expire; a link from the API lives 60 minutes and carries your return button. The return address is checked again every time the page is shown: remove the site from your allowed return sites, and the button disappears from links already issued.

The whole flow

A "Manage subscription" button in your application:

1. Your server reads the customer state by the user's account reference and takes the id of the subscription from subscriptions[].
2. When the user presses the button, your server calls the manage-link endpoint with that id and, optionally, returnUrl — the page of your application to come back to.
3. Send the user to url as a normal browser navigation. They see the subscription on Norelio's page and can cancel it; "Return to the app" brings them back to returnUrl.
4. A cancellation by the buyer arrives as subscription.canceled for a product delivered by webhook, and as customer.state_changed for any product when it is on; the access check and the customer state show it at once.

The subscription id comes from Customer state; the cancellation arrives as described in Webhooks.

Test mode

With the test key, pass the id of a test subscription (it starts with test_): the link leads to the test subscription page on Norelio's payment domain (/test-checkout/subscription/…), marked as test mode, with a Cancel subscription button. Cancelling there sends subscription.canceled with test: true to your endpoint, as the cancel action of a test order does. The live key does not find test subscriptions, and the test key does not find live ones. See Test mode.

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 or 503 response carries a Retry-After header. The access check keeps its own, older error shape.

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