---
title: "Call a catalog service, paid with subscription credits"
method: POST
path: "/router/subscription/route"
tags: ["Router"]
---

# Call a catalog service, paid with subscription credits

`POST /router/subscription/route`

## Request

- Base URL: `https://api.sandbox.nevermined.app/api/v1`
- URL: `https://api.sandbox.nevermined.app/api/v1/router/subscription/route`
- Auth: HTTP bearer

Call a catalog service and pay it with your Nevermined Subscription credits (mode B). Like `POST /router/route`, but Nevermined pays the merchant from its treasury and your subscription is charged the endpoint's rate in credits. There is no Delegation, no wallet to fund and no routing fee.

- **A slug, never a URL.** Address the service by `slug` (+ `path`, `search`, `method`, `headers`, `body`). A `url` or a `delegationId` is refused (`BCK.SUBSCRIPTION_ROUTER.0005`), not ignored.
- **`requestId` is required** (idempotency): a retry with the same id is never paid twice.
- **Only a merchant `2xx` keeps the credits.** They are reserved before the merchant is called and kept (`Committed`) only on a `2xx`; anything else marks them for refund and they are returned (`Refunded`). Every refusal below happens before anything is reserved, signed or charged — except a 502, which can follow a payment.
- **Rails:** x402 `exact` and MPP `tempo` merchants only.

For large or streamed responses, the streaming form is `ALL /api/v1/router/subscription/svc/{slug}/{path}` with an `X-Router-Request-Id` header; it answers with `X-Router-Credits-Charged` and `X-Router-Credits-Status` beside the `X-Router-Payment-*` headers, and refuses `X-Router-Target-Url`, `X-Router-Target-Slug` and `X-Router-Delegation-Id`.

Personal API keys only: the Nevermined Subscription belongs to a personal account, so call with a key that carries no organization tag and without `X-Current-Org-Id`. An OAuth-minted credential is refused (`BCK.OAUTH.0030`). Where the subscription is not available — on this deployment or to this account — it answers 404 `BCK.SUBSCRIPTION_ACCESS.0001`.

## Request body

- SubscriptionRouteRequestDto
  - `slug` string, required: Catalog slug of the service to call. Subscription credits pay catalog services only, addressed by slug; the Router resolves it to the merchant server-side.
  - `path` string: Subpath of the endpoint, appended to the resolved merchant URL (path segments only — `//`, `..`, a backslash or an embedded absolute URL is refused).
  - `search` string: Query string without the leading `?`, attached to the resolved merchant URL.
  - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE': HTTP method to use for the upstream request.
  - `headers` object: Headers to forward to the merchant (e.g. its own auth). Optional.
  - `body` unknown
  - `credentialHeader` string: Header the payment credential rides in on the paid hop, when the merchant needs its own `Authorization` too (a separate `Payment` header is the common one). Do not set it by default.
  - `protocol` 'x402' | 'mpp': Advisory: the Router detects the protocol from the merchant's 402.
  - `requestId` string, required: Idempotency key — REQUIRED. At most one payment per (caller, requestId): a retry is never paid twice.

## Response `201`

The merchant's response (`status`, and `body` only when it delivered) plus the `payment` Nevermined made and the credits it cost.

- SubscriptionRouteResultDto
  - `status` number, required: The merchant's HTTP status.
  - `body` unknown, required
  - `bodyEncoding` 'json' | 'text' | 'base64': How `body` is represented. Absent when `body` is withheld.
  - `contentType` string, nullable: The merchant's response media type, when `body` is relayed.
  - `paid` boolean, required: Whether a payment was made (false when the service answered free).
  - `payment` SubscriptionRoutePaymentDto
    - `paymentId` string, required: The Router payment id.
    - `status` 'Issued' | 'Settled' | 'Failed', required: The merchant leg, which Nevermined paid on your behalf.
    - `txHash` string, nullable, required: On-chain settlement reference of the merchant leg, when the merchant returned one.
    - `creditsCharged` integer: Credits this call cost (the endpoint's rate). Absent only when the ledger could not be read at answer time; `GET /router/payments` has it.
    - `creditsStatus` 'Reserved' | 'Committed' | 'Refunded': `Committed` — the merchant delivered (2xx) and the credits stay spent. `Reserved` — the call did not deliver and its credits are marked for refund, or its outcome is still being decided. `Refunded` — returned. Absent only when the ledger could not be read at answer time.
    - `failureReason` string, nullable, required: Why the call did not complete cleanly, when it did not.
    - `correlationId` string, nullable, required: The request correlation id.
    - `resultUrl` string: Where this result stays readable for 24 h.

## Other responses

- `202`: API version 1.48 or later: the paid call outlived the synchronous wait. Poll `GET /api/v1/router/payments/{id}/result` (also the `Location` header); the credits stay `Reserved` until the call ends. A retry with the same `requestId` returns this same answer, then the result.
- `400`: Invalid request; a field a subscription call does not accept (BCK.SUBSCRIPTION_ROUTER.0005, `params.field`); the merchant asked for a rail credits do not pay (BCK.SUBSCRIPTION_ROUTER.0003, `params.rail`); or the payment credential would overwrite a header you forward, with no `credentialHeader` naming where the service wants it (BCK.ROUTER.0021).
- `401`: Missing/invalid Nevermined API key.
- `402`: No subscription that can spend right now, including a call made in an organization you are an active member of (`X-Current-Org-Id`, or that organization's API key), which never falls back to your personal subscription (BCK.SUBSCRIPTION_ROUTER.0002); or not enough credits for this call (BCK.SUBSCRIPTION_ROUTER.0009, `params.credits`).
- `403`: This endpoint cannot be paid with subscription credits (BCK.SUBSCRIPTION_ROUTER.0001, `params.reason`); the treasury cannot pay this merchant (BCK.SUBSCRIPTION_TREASURY.0008); or an OAuth-minted credential (BCK.OAUTH.0030).
- `404`: Not available to the caller (BCK.SUBSCRIPTION_ACCESS.0001), or no listed catalog service has that `slug` (BCK.CATALOG.0001).
- `409`: The merchant's live price is outside the rate's bound, in another asset or network, or could not be read as a price, or — for a service paid over an MPP session — it asked to be paid at an address Nevermined has not seen it use on this endpoint (BCK.SUBSCRIPTION_ROUTER.0004, `params.reason`, e.g. `payee_unobserved`); the MPP session payment channel with this service, shared by every subscriber, is closing (BCK.ROUTER.0042, retry later with the same requestId); or the `requestId` was already used (BCK.ROUTER.0002 — from API 1.48, a retry of a finished call is answered from its retained result instead).
- `413`: The request body is larger than this endpoint accepts (BCK.ROUTER.0027, its `maxRequestBytes`) or than the Router accepts (BCK.ROUTER.0024). Refused before the service is contacted; nothing was charged.
- `422`: The merchant asked to be paid in an asset Nevermined's treasury does not pay in (BCK.SUBSCRIPTION_TREASURY.0002), or the endpoint is known to outlast the Router's paid-call limit (BCK.ROUTER.0036). Nothing was charged; pay this endpoint from a delegation, or pick another.
- `429`: The per-slug throttle or the per-user concurrency limit. A subscription has no spending limit beyond its credits.
- `500`: Nevermined-side error, nothing charged: the payment could not be prepared consistently (BCK.SUBSCRIPTION_ROUTER.0006, retryable with a new requestId), the subscription does not resolve to its credits (0011), the rate is unusable (0013), or a treasury configuration or ledger error (BCK.SUBSCRIPTION_TREASURY.0011–0013).
- `502`: The paid call got no response from the service (BCK.ROUTER.0034), or its reply was too large to deliver (BCK.ROUTER.0025): the merchant may have been paid, and the call's credits are marked for refund. Do not retry with a new `requestId`; read the outcome from `GET /api/v1/router/payments?requestId=…` (`creditsStatus`). An unpaid probe the service failed to answer (BCK.ROUTER.0020) paid nothing.
- `503`: Temporarily unable to pay, nothing charged: the reservation timed out (BCK.SUBSCRIPTION_ROUTER.0014, retry with the same requestId), an MPP session step did not answer in time (BCK.ROUTER.0043, `params.stage`, retry with the same requestId), the subscription lookup failed (0012), the deployment cannot run subscription calls (0010), or the treasury refused (a `BCK.SUBSCRIPTION_TREASURY.*` code, e.g. 0003 when its float cannot cover the payment). `retryable` says whether retrying can help.

---

[API](https://skmtc.dev/nevermined/apis/nevermined-api.md) · [All operations](https://skmtc.dev/nevermined/apis/nevermined-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nevermined/apis/nevermined-api/revisions/cabbe618c80b?raw)