--- title: "Reading subscriptions: Subscriptions docs | Chargezen" description: "Find a customer, list their active subscriptions, read one subscription with its address and card, and read its upcoming orders and swap options." url: "https://chargezen.com/docs/subscriptions/api/reading-subscriptions" lang: "en" updated: "2026-11-09" --- Canonical URL: https://chargezen.com/docs/subscriptions/api/reading-subscriptions # Reading subscriptions Find a customer, list their active subscriptions, read one subscription with its address and card, and read its upcoming orders and swap options. Last updated: 2026-11-09 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 ```bash 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 ```bash 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} ```bash 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 ```bash 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 ```bash 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, "…": "…" } ] } ] } ``` ### Related Articles [ #### Changing subscriptions Use what you read to make a change ](https://chargezen.com/docs/subscriptions/api/changing-subscriptions)[ #### Order now Place the next order early ](https://chargezen.com/docs/subscriptions/api/order-now) Was this page helpful? Need more help? [Contact support](https://chargezen.com/docs/checkoutos/troubleshooting/support)