Subscriptions

List Subscriptions

Search and filter Subscriptions with pagination. Results are sorted by creation date (newest first) by default.

Authorization

Public key
x-fngs-public-key<token>

In: header

Query Parameters

status?string

Filter Subscriptions by their status:

  • active: Currently active Subscription
  • past_due: Payment failed but will retry
  • canceled: Subscription has been canceled
  • incomplete: Initial payment failed
  • incomplete_expired: Initial payment failed and expired
  • trialing: In trial period
  • unpaid: Payment failed and won't retry

Value in

  • "all"
  • "active"
  • "canceled"
  • "incomplete"
  • "incomplete_expired"
  • "past_due"
  • "trialing"
  • "paused"
  • "unpaid"
userId?string

Return only Subscriptions belonging to this User UUID.

Formatuuid
createdFrom?|

Filter Subscriptions created on or after this timestamp. Accepts Unix timestamp in seconds or milliseconds. Must not be later than createdTo.

Formatint64
Range0 <= value <= 9007199254740991
createdTo?|

Filter Subscriptions created on or before this timestamp. Accepts Unix timestamp in seconds or milliseconds. Must not be earlier than createdFrom.

Formatint64
Range0 <= value <= 9007199254740991
cursor?string

Cursor returned with the previous page. Send it to fetch the next one.

take?integer

Number of Subscriptions per page. Defaults to 10, maximum 100.

Formatint64
Range1 <= value <= 100
Default10

Response Body

application/json

application/json

GET
/v0/subscriptions/list
curl -X GET "https://example.com/v0/subscriptions/list"
{  "status": "success",  "data": {    "subscriptions": [      {        "object": "subscription",        "id": "string",        "status": "all",        "createdAt": 0,        "currentIntervalEnd": 0,        "currentIntervalStart": 0,        "cancelAtIntervalEnd": false,        "canceledAt": null,        "userId": null,        "user": null,        "orderId": "b3e1eced-f2bd-4d8c-9765-fbc9d1d222d5",        "orderNumber": "string",        "order": {          "object": "order",          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "number": "string",          "status": "PENDING"        },        "lastPaymentId": null,        "lastPaymentNumber": null,        "lastPayment": null      }    ],    "count": -1.7976931348623157e+308,    "cursor": "string",    "hasMore": false  }}

Archive a plan PATCH

Archive (soft delete) a plan by its ID. Existing subscriptions on this plan continue. This action is reversible.

Create Subscription POST

Create a new Subscription for a User. User must have a valid customer ID of Payment Provider set. Requires billing details with at least a country code and postal code if country is one of US, CA, UA, IN. Multiple items (up to 20) can be billed on a single Subscription — for example a base plan plus add-ons — and each line is preserved on the invoice and outbound webhooks. Because one Subscription maps to a single billing arrangement, every item must be on the same cadence: - Currency: all items must resolve to the same currency (from the item or its Offer). - Billing period: all Offers must share the same recurring interval and interval count (e.g. all monthly); mixing intervals (monthly + yearly) returns a 400. - Every item must reference a recurring Offer via offerId. - Trial: a trial (trialEnd / the Offer trial) is only applied to single-item Subscriptions. Multi-item Subscriptions start billing immediately (no trial). - Discount codes are not supported for multi-item Subscriptions. Note: User must have a valid customer ID of Payment Provider set and this customer must have a valid default payment method set (Payment Provider dashboard).