Subscriptions

Search your store's subscriptions, get one subscription with its lines and billing history, and list billing attempts with the Subrise API.

These endpoints read subscriptions. To change one, see Change a subscription. They need a key with Read permission. See Developer API for the base URL and authentication.

Search subscriptions

text

POST /subscription-contracts/search

Returns a page of subscriptions from Subrise's records, newest first unless you sort.

Query parameters

Name	Type	Description
`page`	integer	Page number, starting at `1`. Default `1`.
`limit`	integer	Subscriptions per page. Default `600`. Send a smaller number, such as `50`.

Body

Field	Type	Description
`filters`	object	Required. Send `{}` for no filters.
`searchOrder`	object	Optional. `{ "field": "<field name>", "direction": 1 }` sorts ascending, `-1` descending. For example `nextBillingDate` or `createdAt`.

Filters you can combine:

Filter	Type	Matches
`status`	string	`ACTIVE`, `PAUSED`, `CANCELLED` or `EXPIRED`. `ALL` matches active and paused. `ANY-STATUS` matches every status. `FAILED` matches active and paused subscriptions with at least one failed charge.
`customerId`	string	A customer's numeric Shopify ID, such as `"7727997518103"`.
`id`	string	One subscription's numeric ID.
`email`, `firstName`, `lastName`	string	The customer field contains this text, ignoring case. When you send more than one, any of them can match.
`searchQuery`	string	Free text across the subscription ID, customer name and email, and product and variant titles and IDs.
`nextBillingDateStart`, `nextBillingDateEnd`	string	Next order date on or after, and on or before, these ISO dates.
`productId`	string	A product's Shopify global ID on any line.
`sellingPlanId`	string	A plan's Shopify global ID on any line.
`minPrice`, `maxPrice`	number	The subscription total is at least, or at most, this amount.
`isPrepaid`	boolean	`true` for prepaid subscriptions only.
`includeBillingAttempts`	boolean	`true` adds `BillingAttempts`, `lastSuccessfulOrder` and `lastFailedCharge` to each subscription.

Draft subscriptions are never returned.

Example

bash

curl -X POST "https://backend-production.subrise.app/api/subscription-contracts/search?page=1&limit=50" \
  -H "x-api-key: $SUBRISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": { "status": "ACTIVE", "nextBillingDateEnd": "2026-11-30T23:59:59Z" },
    "searchOrder": { "field": "nextBillingDate", "direction": 1 }
  }'

json

{
  "data": [
    {
      "id": "12704383255",
      "status": "ACTIVE",
      "nextBillingDate": "2026-11-05T14:00:00Z",
      "createdAt": "2026-03-05T15:50:09Z",
      "currencyCode": "USD",
      "subscriptionTotal": 8.99,
      "deliveryPrice": 4.9,
      "billingInterval": "MONTH",
      "billingIntervalCount": 1,
      "deliveryInterval": "MONTH",
      "deliveryIntervalCount": 1,
      "isPrepaid": false,
      "maxCycles": null,
      "minCycles": null,
      "failedBillingCount": 0,
      "customerId": "7727997518103",
      "customer": {
        "id": "7727997518103",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com",
        "phone": null
      },
      "lines": [
        {
          "id": "gid://shopify/SubscriptionLine/8380c059-ca4f-4fb6-b2f2-89158b66b754",
          "title": "Clay Plant Pot",
          "variantTitle": "Regular",
          "productId": "gid://shopify/Product/8107112661271",
          "variantId": "gid://shopify/ProductVariant/44406306701591",
          "sellingPlanId": "gid://shopify/SellingPlan/689892688151",
          "sellingPlanName": "Subscribe & Save",
          "quantity": 1,
          "currentPrice": { "amount": "8.99", "currencyCode": "USD" }
        }
      ],
      "addons": [],
      "paymentMethodId": "6fddc78b26624ee3ac6c1774ed278560",
      "paymentLastDigits": "4242",
      "shippingAddressInformation": {
        "firstName": "John",
        "lastName": "Doe",
        "shippingAddressOne": "1234 Test Street",
        "shippingAddressTwo": null,
        "shippingCity": "Providence",
        "shippingState": "Rhode Island",
        "shippingZipCode": "02907",
        "shippingCountry": "United States",
        "shippingProvinceCode": "RI"
      },
      "pauseAfterBillings": null,
      "scheduledPauseCycles": null
    }
  ],
  "totalCount": 132,
  "pageCount": 3
}

totalCount is the number of matching subscriptions. pageCount is the number of pages at your limit.

Tip

To list one customer's subscriptions, filter on customerId and set status to ANY-STATUS.

Get a subscription

text

GET /subscription-contracts/{contractId}

Returns one subscription, read live from Shopify, with every line, its billing attempts and its scheduled pause.

Path parameter	Type	Description
`contractId`	string	The subscription's numeric ID.

bash

curl https://backend-production.subrise.app/api/subscription-contracts/12704383255 \
  -H "x-api-key: $SUBRISE_API_KEY"

The response uses Shopify's field names and global IDs.

json

{
  "data": {
    "subscriptionContract": {
      "id": "gid://shopify/SubscriptionContract/12704383255",
      "status": "ACTIVE",
      "currencyCode": "USD",
      "nextBillingDate": "2026-11-05T14:00:00Z",
      "lastPaymentStatus": "SUCCEEDED",
      "createdAt": "2026-03-05T15:50:09Z",
      "updatedAt": "2026-10-05T14:02:11Z",
      "note": null,
      "customer": {
        "id": "gid://shopify/Customer/7727997518103",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john@example.com"
      },
      "billingPolicy": { "interval": "MONTH", "intervalCount": 1, "minCycles": null, "maxCycles": null, "anchors": [] },
      "lines": [
        {
          "id": "gid://shopify/SubscriptionLine/8380c059-ca4f-4fb6-b2f2-89158b66b754",
          "title": "Clay Plant Pot",
          "variantTitle": "Regular",
          "quantity": 1,
          "productId": "gid://shopify/Product/8107112661271",
          "variantId": "gid://shopify/ProductVariant/44406306701591",
          "sellingPlanId": "gid://shopify/SellingPlan/689892688151",
          "currentPrice": { "amount": "8.99", "currencyCode": "USD" }
        }
      ],
      "addons": [],
      "customerPortalLink": "https://your-store.myshopify.com/pages/subscriptions?secret=...",
      "billingAttempts": [],
      "pauseAfterBillings": null,
      "scheduledPauseCycles": null,
      "shouldUnpause": false,
      "prePauseNextBillingDate": null
    }
  }
}

lines are the products that renew. addons are one-time products added to the next order.
customerPortalLink is the link to this customer's portal. When your portal is a storefront page, the link carries a secret that lets anyone who opens it manage the subscription, so share it only with the customer.
billingAttempts lists every charge Subrise has recorded for this subscription, newest first. See List billing attempts for the fields.
pauseAfterBillings and scheduledPauseCycles describe a scheduled pause, if one is set.

A subscription that doesn't exist on your store returns 404:

json

{ "error": "Subscription contract not found" }

List billing attempts

text

GET /billing/attempts

Returns the charges Subrise has recorded for your store, newest first.

Query parameter	Type	Description
`customerId`	string	Optional. Only this customer's attempts. Numeric ID or Shopify global ID.

bash

curl "https://backend-production.subrise.app/api/billing/attempts?customerId=7727997518103" \
  -H "x-api-key: $SUBRISE_API_KEY"

json

{
  "data": [
    {
      "id": "gid://shopify/SubscriptionBillingAttempt/98234756",
      "subscription_contract_id": "gid://shopify/SubscriptionContract/12704383255",
      "customer_id": "gid://shopify/Customer/7727997518103",
      "email": "john@example.com",
      "customer_name": "John Doe",
      "created_at": "2026-10-05T14:00:03Z",
      "completed_at": "2026-10-05T14:00:09Z",
      "origin_time": "2026-10-05T14:00:00Z",
      "error_code": null,
      "error_message": null,
      "order_id": "gid://shopify/Order/5784026972439",
      "order_name": "#1840",
      "order_total": "13.89",
      "line_items": []
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 200,
  "pageCount": 1
}

A failed charge has an error_code and error_message and no order_id.

This endpoint returns at most 200 attempts and has no paging. Filter by customerId to narrow it, or read one subscription's attempts from Get a subscription.