Subscriptions

Recurring purchases: terms, documents, invoices, cost-center splits, cancellation, card replacement and limit increases.

📄️List subscriptions

Retrieve a paginated list of subscriptions with filtering and search capabilities. Filters AND together on top of the role scope and the my_subscriptions toggle. Every filter is whole-list SQL, so pagination.total always describes the filtered list, not the page. Multi-select params are repeated (suppliers=1&suppliers=2); the [] alias is accepted, CSV is not. An unparseable value is a 400.

📄️Get subscription statistics

Retrieve aggregated statistics about subscriptions. Accepts the same scope and filter params as GET /subscriptions and applies the same SQL predicates, so the counts describe the filtered list.

📄️Soft-delete a subscription

Marks the subscription as deleted so it no longer appears in normal listings. Does not change the active/canceled state; to cancel a subscription use POST /subscriptions/{code}/cancel.

📄️Get subscription details

Retrieve detailed information about a specific subscription.

📄️List pending approval tasks for a subscription

Returns only PENDING approval tasks for the subscription (e.g. limit increase approvals). Approved/rejected tasks are omitted.

📄️Cancel a subscription

Performs the cancel state transition: deactivates the credit card and marks the subscription inactive. Distinct from soft-deletion, which only hides the resource from listings.

📄️Update a subscription's cost-center split

Replace the cost-center allocation on the subscription's originating.

📄️Get subscription documents

Retrieves all subscription-specific documents, optionally filtered by document type.

📄️Upload a document for a subscription

Uploads a file document for a subscription with a document type (offer, contract, cancellation, others). The file must be a PDF; its content is validated, not just its name.

📄️Delete a subscription document

Deletes a specific subscription document by ID.

📄️Get a specific subscription document

Retrieves a specific subscription document by ID.

📄️Get subscription invoices

Retrieve all invoices associated with a subscription.

📄️Upload an invoice for a subscription

Uploads an invoice file for a subscription. The file must be a PDF, an image (PNG, JPEG, TIFF, WebP) or an e-invoice XML; its content is validated, not just its name. Returns the created invoice. Returns 409 Conflict if a file with the same content already exists for the subscription's purchase order, or if that order's workflow status does not accept an invoice upload.

📄️List limit increase requests for a subscription

Retrieve all limit increase requests for a subscription.

📄️Request a subscription limit increase

Request a credit card limit increase for a subscription.

📄️Get a specific limit increase request

Retrieve details of a specific limit increase request.

📄️Replace credit card for subscription

Generate a replacement credit card for a subscription's purchase order. Within 28 days of the current card's expiry this is the ordinary follow-up card, sized for the next subscription period, and the request body may be omitted. Earlier than that it is an early replacement (for a compromised or wrongly locked card): a reason is required, and the new card inherits only the replaced card's remaining limit rather than opening a new period. Returns the new card's code and masked details so the client can reveal it once via the Payrails display SDK. Pass replaces_credit_card_code (the card the client currently shows) to make the call safe to retry: if that card has already been replaced, its successor is returned instead of a second card being issued.

📄️Update subscription terms

Update the subscription terms (billing interval, renewal mode, contract duration, cancellation period).