Reading subscriptions: Subscriptions docs

Find the customer first, then list their subscriptions and read the one you need. Every read needs a key that can read customers, products and subscriptions (workspace:read).

Find a customer

GET /customers?query= matches an email, phone, order number or customer ID exactly, and a name by the start of the first, last or full name. It returns up to 15 customers, with has_more when more match; search with more of the name or an exact identifier to narrow it. No match is an empty list, not an error.

GET /customers

curl -G "https://api.chargezen.com/v1/customers" \
  --data-urlencode "query=#1042" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET"

Each result has customer_ref, name, email, phone and the stored address. The address can be blank or out of date; use it to tell two customers apart. Use customer_ref.id as customer_id.

List a customer's active subscriptions

GET /customers/{customer_id}/subscriptions

curl "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET"

{
  "active_subscriptions": [
    {
      "subscription_ref": { "type": "customer_subscription_contract", "id": "48213" },
      "status": "active",
      "items": [
        { "line_id": "gid://shopify/SubscriptionLine/77104", "product_title": "Morning Coffee", "variant_title": "Whole bean", "quantity": 2, "unit_price": "18.0" }
      ],
      "recurring_total": "36.0",
      "currency_code": "USD",
      "next_charge_at": "2026-12-02T00:00:00Z",
      "billing_interval": "MONTH",
      "billing_interval_count": 1,
      "delivery_interval": "MONTH",
      "delivery_interval_count": 1,
      "created_at": "2026-08-26T20:05:42Z",
      "updated_at": "2026-11-02T09:14:03Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "observed_at": "2026-11-09T16:20:11.402911Z"
}

When has_more is true, ask for the next page with ?after= and the next_cursor you got. The list holds active subscriptions only. Keep a subscription's id to read it after it's paused or cancelled.

Read one subscription

GET /customers/{customer_id}/subscriptions/{id}

curl "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions/48213" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET"

The answer is { "subscription": { … } } with the list fields plus its schedule changes, address and card. It works in any status.

Field	What it holds
`subscription_ref`	type and id. The id goes in the subscription's paths.
`status`	Stored Shopify status in lower case: active, paused, cancelled, expired, failed or stale.
`items[]`	line_id, product_title, variant_title, quantity, unit_price. line_id is what item changes take.
`recurring_total, currency_code`	What each order charges.
`next_charge_at`	The next charge. skip_next takes this value.
`billing_interval, billing_interval_count`	How often it bills, such as MONTH and 1.
`delivery_interval, delivery_interval_count`	How often it ships.
`paused_at, resumes_at`	When it was paused, and when it resumes by itself. null when not paused or no resume is set.
`pause_at, cancel_at`	A scheduled pause or cancellation date. null when none is scheduled.
`cancelled_at`	When it was cancelled. null unless it is cancelled.
`delivery_address`	Where orders ship, as Shopify stores it. null for pickup or when no address is stored.
`payment_method`	kind, brand, last_digits, expiry_month, expiry_year, expires_soon, revoked. Never the full number.
`created_at, updated_at`	When Chargezen stored and last updated it.

Reads come from Chargezen's stored copy

A read shows Chargezen's stored copy of the Shopify subscription. Right after a change it can lag by a few seconds, so use the change's own response for what just changed.

Read upcoming orders

Every order not yet billed within the next year, earliest first, with what it will contain, plus the orders that were skipped. Needs a teammate who can manage subscriptions.

GET .../upcoming_orders

curl "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions/48213/upcoming_orders" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET"

{
  "subscription_ref": { "type": "customer_subscription_contract", "id": "48213" },
  "currency_code": "USD",
  "orders": [
    {
      "scheduled_at": "2026-12-02T00:00:00Z",
      "charge_on": "2026-12-02",
      "cycle_index": 4,
      "next_order": true,
      "items": [
        { "line_id": "gid://shopify/SubscriptionLine/77104", "product_title": "Morning Coffee", "variant_title": "Whole bean", "quantity": 2, "unit_price": "18.0", "this_order_only": false, "every_order_quantity": null }
      ]
    }
  ],
  "skipped_orders": [
    { "scheduled_at": "2027-01-02T00:00:00Z", "cycle_index": 5 }
  ]
}

cycle_index and scheduled_at name an order for order now and next-order changes.
charge_on is the day it charges: the date to tell the customer.
this_order_only marks a one-time item. every_order_quantity shows the usual quantity when this order's differs.
Send a skipped order's scheduled_at to restore_skipped_order to bring it back.

List swap options

Each item with the replacements you offer for it, each with the recurring unit price and quantity the swap would keep, the variant's options and stock as last synced. Out-of-stock replacements are listed with available_for_sale false. An item with no replacements can't be swapped. Needs a teammate who can manage subscriptions.

GET .../swap_options

curl "https://api.chargezen.com/v1/customers/8f14e45f-ceea-467f-a0e6-0e1c2f4b9d3a/subscriptions/48213/swap_options" \
  -H "X-Chargezen-Key-Id: $CHARGEZEN_KEY_ID" \
  -H "Authorization: Bearer $CHARGEZEN_SECRET"

{
  "subscription_ref": { "type": "customer_subscription_contract", "id": "48213" },
  "lines": [
    {
      "line_id": "gid://shopify/SubscriptionLine/77104",
      "product_title": "Morning Coffee",
      "variant_title": "Whole bean",
      "quantity": 2,
      "unit_price": "18.0",
      "replacements": [
        { "product_id": "8812", "variant_id": "44120", "title": "Decaf Coffee", "variant_title": "Whole bean", "unit_price": "18.0", "currency": "USD", "quantity": 2, "available_for_sale": true, "…": "…" }
      ]
    }
  ]
}

Reading subscriptions

Find a customer

List a customer's active subscriptions

Read one subscription

Read upcoming orders

List swap options

Related Articles

Changing subscriptions

Order now