> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # GraphQL Account API: Unified Billing Below are examples of queries and mutations. They demonstrate how to use the Unified Billing features available through the BigCommerce GraphQL Account API. Use the API by submitting POST requests to `https://api.bigcommerce.com/accounts/{{your_partner_account_uuid}}/graphql`. We have prepared a Postman collection you can import into your Postman workspace to interact with the Unified Billing API. It includes example requests for common operations such as creating checkouts, querying checkouts, querying subscriptions, and canceling subscriptions: [Unified Billing Postman Collection](/developer/docs/integrations/apps/unified-billing/postman-collection) ## Possible Implementation Strategies Using the information gathered from the [prerequisites section](/developer/docs/integrations/apps/unified-billing), you can begin integrating with the Unified Billing API. The following examples are meant to be a helpful guide for implementation. When considering how to utilize the API, keep in mind the specific needs of your app. ### Creating Subscriptions When a merchant wants to purchase a subscription after installing your app, use the Create Checkout Mutation to generate a checkout URL for them to complete the purchase. **Implementation Options:** **Option A: Polling Checkout Status** * Cache the checkout URL for each merchant store * Periodically poll the [Checkout Query](/developer/docs/integrations/apps/unified-billing/example-queries-and-mutations) until the status changes to `COMPLETE` * Once complete, retrieve the `subscriptionId` from the checkout response **Option B: Polling Subscription Status (Recommended)** * Instead of monitoring individual checkouts, gate access to premium features until the [Subscriptions Query](/developer/docs/integrations/apps/unified-billing/example-queries-and-mutations) returns an active subscription * This approach is more efficient and provides better reliability for verifying completed purchases ### Managing Access Control Use the [Subscriptions Query](/developer/docs/integrations/apps/unified-billing/example-queries-and-mutations) to verify which merchants have active subscriptions. Filter by `scopeId` (store hash) to find the subscription for a specific merchant. **Caching Strategy:** * Cache subscription results to reduce API calls * Invalidate the cache when processing cancellations or when subscriptions expire * Consider periodic cache refresh to handle external subscription changes ### Handling Subscription Cancellations When merchants request to cancel their subscription, use the [CancelSubscription Mutation](/developer/docs/integrations/apps/unified-billing/example-queries-and-mutations). The response includes a `cancelledAt` date indicating when access ends: * **Regular subscriptions**: Access continues until the end of the current billing cycle * **Trial subscriptions**: Cancellation takes effect immediately **Implementation Note:** Invalidate any cached subscription data immediately after processing a cancellation to ensure accurate access control. ### Updating Subscription Plans To handle plan changes (upgrades, downgrades, or billing frequency modifications), create a new checkout using the [UpdateSubscription Mutation](/developer/docs/integrations/apps/unified-billing/example-queries-and-mutations). This allows you to modify subscription details while preserving the merchant's billing relationship. **Use Cases:** * Plan tier changes (Basic → Premium) * Billing frequency updates (Monthly → Annual) * Price adjustments for existing subscribers ## Example queries and mutations ### Create a checkout The first step in charging a merchant for a product is to create a checkout. After creating a checkout through the API, the checkout will be in a pending `status`, and a `checkoutUrl` will be included in the response. The `checkoutUrl` routes to the BigCommerce checkout UI where a merchant must complete the checkout in their store's control panel. After checkout completion, a subscription is created and billed to the merchant, and the checkout status moves to complete. When the merchant exits the BigCommerce checkout UI, they will be redirected to the `redirectUrl` provided in the request. Use this field to route the merchant back to your app. When creating a checkout with a product that has a trial period, set the `trialDays` field to the number of days the trial should last. The merchant will not be charged during this period. A subscription only generates an invoice once the trial period ends. No charges are made during the trial. Checkout links are valid for 24 hours and expire automatically to prevent misuse. #### Field Descriptions | Field | Description | | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accountId | The account UUID of the merchant you want to create a checkout for. | | id (product) | The id of your app. | | type (product) | The type of product. In the case for creating an app checkout, this will be `"APPLICATION"` | | productLevel (product) | The level of your product. This will help differentiate which plan the subscription is for in case your app supports different plan levels (like "Standard", "Plus", "Pro", "Silver", "Gold", "Premium", etc). | | id (scope) | Since the type of scope used here will be `STORE`, the scope id will be the store hash of the merchant you are sending the checkout to. | | type (scope) | The type of scope. In this case for creating an app checkout, this will be `"STORE"`. | | interval (pricingPlan) | The interval at which the merchant should be billed. This can be `"ANNUAL"`, `"MONTH"`, `"ONCE"`, `"QUARTER"`, or `"SEMIANNUAL"`. | | value (price) | The amount the merchant will be charged at each interval | | currencyCode (price) | The currency in which the merchant will be charged. Currently, only `USD` is supported. | | trialDays (pricingPlan) | The number of trial days granted to the merchant. The merchant will not be charged until the trial days are over. | | description | A brief description for your app | | redirectUrl | The URL the merchant will be redirected to after completing the checkout. | To create a checkout, run the `createCheckout` mutation: #### Request **`Example Query: Create a checkout`** ```graphql title="Example Query: Create a checkout" mutation ($checkout: CreateCheckoutInput!) { checkout { createCheckout(input: $checkout) { checkout { id accountId status checkoutUrl items(first: 1) { edges { node { subscriptionId status product { id type productLevel } scope { id type } pricingPlan { interval price { value currencyCode } trialDays } redirectUrl description } } } } } } } ``` #### Sample variables Here are sample variables for this mutation: **`Sample variables`** ```json title="Sample variables" { "checkout": { "accountId": "bc/account/account/61db983a-cd07-4d6b-8b59-a5ffe285ca6a", // This should be the merchant's account UUID "items": [ { "product": { "id": "bc/account/product/1234", "type": "APPLICATION", "productLevel": "Standard" }, "scope": { "id": "bc/account/scope/f0qyczpkb2", // This should be the merchant's store hash "type": "STORE" }, "pricingPlan": { "interval": "MONTH", "price": { "value": 29.99, "currencyCode": "USD" }, "trialDays": 0 }, "description": "App Subscription - Standard", "redirectUrl": "https://store-f0qyczpkb2.mybigcommerce.com/manage/app/1234/upgrade_success" } ] } } ``` #### Response **`Query response: Create a checkout`** ```json title="Query response: Create a checkout" { "data": { "checkout": { "createCheckout": { "checkout": { "id": "bc/account/checkout/bf09f4d3-3250-4103-8735-e390c3a49aff", "accountId": "bc/account/account/61db983a-cd07-4d6b-8b59-a5ffe285ca6a", "status": "PENDING", "checkoutUrl": "https://store-f0qyczpkb2.my-bigcommerce.com/manage/merchant-checkout?checkoutId=bf09f4d3-3250-4103-8735-e390c3a49aff", "items": { "edges": [ { "node": { "subscriptionId": null, "status": "PENDING", "product": { "id": "bc/account/product/1234", "type": "APPLICATION", "productLevel": "Standard" }, "scope": { "id": "bc/account/scope/f0qyczpkb2", "type": "STORE" }, "pricingPlan": { "interval": "MONTH", "price": { "value": 29.99, "currencyCode": "USD" }, "trialDays": 0 }, "redirectUrl": "https://store-f0qyczpkb2.mybigcommerce.com/manage/app/1234/upgrade_success", "description": "App Subscription - Standard" } } ] } } } } } } ``` Some common errors returned when creating a checkout: * `Product is not supported for your account.` - The application being purchased [is not owned by the partner account](/developer/docs/integrations/apps/unified-billing) (in the request URL) making the request. * `Scope does not belong to account.` - The store hash provided does not belong to the merchant account provided. * `You do not have permission to do this operation.` - This failure has multiple possible causes: * The account-level API token being used does not have the [required auth scope](/developer/docs/integrations/apps/unified-billing) for the given operation. * The account-level API token does not match the account UUID being used in the request URL. ### Fetch a checkout Once the checkout is created, you can periodically poll the status of the checkout by calling this endpoint. To fetch an existing checkout, copy and run the following query: #### Request Replace the `checkoutId` with the following variable: ```json showLineNumbers={false} { "checkoutId": "bc/account/checkout/ab0a8354-3caf-423b-a3be-42a59c97fcf5" } ``` **`Example query: Fetch a checkout`** ```graphql title="Example query: Fetch a checkout" query Account($checkoutId: ID!) { account { checkout(id: $checkoutId) { id accountId checkoutUrl status items { edges { node { description status product { id productLevel type } scope { id type } pricingPlan { price { value currencyCode } interval trialDays } subscriptionId redirectUrl } } } } } } ``` #### Response (Pending Checkout) In this example, the checkout returned is a pending checkout, which means the checkout exists, but the merchant still needs to accept the charges and complete the checkout flow. At this point, a subscription has not been created, so the `subscriptionId` field returns `null`. **`Example response: Fetch a checkout`** ```json title="Example response: Fetch a checkout" { "data": { "account": { "checkout": { "id": "bc/account/checkout/ab0a8354-3caf-423b-a3be-42a59c97fcf5", "accountId": "bc/account/account/dbf77034-5440-4365-9aca-385ab27fe4bc", "checkoutUrl": "https://store-fsm6cvyxbj.my-bigcommerce.com/manage/merchant-checkout?checkoutId=ab0a8354-3caf-423b-a3be-42a59c97fcf5", "status": "PENDING", "items": { "edges": [ { "node": { "description": "Silver Tier Monthly Plan", "status": "PENDING", "product": { "id": "bc/account/product/5", "productLevel": null, "type": "APPLICATION" }, "scope": { "id": "bc/account/scope/fsm6cvyxbj", "type": "STORE" }, "pricingPlan": { "price": { "value": 50, "currencyCode": "USD" }, "interval": "MONTH", "trialDays": 0 }, "subscriptionId": null, "redirectUrl": "https://store-fsm6cvyxbj.my-bigcommerce.com/manage/app/5" } } ] } } } } } ``` #### Response (Completed Checkout) In this example, the checkout returned is a completed checkout. The merchant has completed the checkout flow, and there is a `subscriptionId` returned. **`Query response: Checkout complete`** ```json title="Query response: Checkout complete" { "data": { "account": { "checkout": { "id": "bc/account/checkout/6e3f0de4-5bb3-451e-8c1b-3f14c6798891", "accountId": "bc/account/account/dbf77034-5440-4365-9aca-385ab27fe4bc", "checkoutUrl": "https://store-q6sxaezcnf.my-bigcommerce.com/manage/merchant-checkout?checkoutId=6e3f0de4-5bb3-451e-8c1b-3f14c6798891", "status": "COMPLETE", "items": { "edges": [ { "node": { "description": "Gold Tier Annual Plan", "status": "COMPLETE", "product": { "id": "bc/account/product/5", "productLevel": null, "type": "APPLICATION" }, "scope": { "id": "bc/account/scope/fsm6cvyxbj", "type": "STORE" }, "pricingPlan": { "price": { "value": 499.99, "currencyCode": "USD" }, "interval": "ANNUAL", "trialDays": 10 }, "subscriptionId": "bc/account/subscription/9bbe8843-27eb-4f78-b34b-c692d1016382", "redirectUrl": "https://store-q6sxaezcnf.my-bigcommerce.com/manage/app/5" } } ] } } } } } ``` ### Update a subscription The `createCheckout` mutation can also be used to update an existing subscription's pricing plan information and product level. A `subscriptionId` must be passed in the request for this to be processed as an update. #### Field Descriptions | Field | Description | | | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | accountId | The account UUID of the merchant you want to create a checkout for. | | | productLevel (product) | The level of your product. This will help differentiate which plan the subscription is for in case your app supports different plan levels (like "Standard", "Plus", "Pro", "Silver", "Gold", "Premium", etc). | | | interval (pricingPlan) | The interval at which the merchant should be billed. This can be `"ANNUAL"`, `"MONTH"`, `"ONCE"`, `"QUARTER"`, or `"SEMIANNUAL"`. | | | value (price) | The amount the merchant will be charged at each interval | | | currencyCode (price) | The currency in which the merchant will be charged. Currently, only `USD` is supported. | | | description | A brief description for your app | | | redirectUrl | The URL the merchant will be redirected to after completing the checkout. | | | subscriptionId | The id of the subscription that was returned after a fetch of a completed checkout | | #### Request **`Example Query: Update a subscription`** ```graphql title="Example Query: Update a subscription" mutation ($checkout: CreateCheckoutInput!) { checkout { createCheckout(input: $checkout) { checkout { accountId status checkoutUrl items(first: 1) { edges { node { subscriptionId status product { id type productLevel } scope { id type } pricingPlan { interval price { value currencyCode } trialDays } redirectUrl description } } } } } } } ``` #### Sample variables Here are sample variables for this mutation: **`Sample variables`** ```json title="Sample variables" { "checkout": { "accountId": "bc/account/account/2a159c53-1caa-4ce8-af4f-6b00da294e2a", "items": [ { "product": { "productLevel": "Premium" }, "pricingPlan": { "interval": "ANNUAL", "price": { "value": 129.99, "currencyCode": "USD" } }, "redirectUrl": "bigcommerce.com/checkout_success", "description": "test application", "subscriptionId": "bc/account/subscription/9cf1f949-8a74-4938-bd13-64d9741a9685" } ] } } ``` Fields for checkout input above: * `checkout` (required) * `accountId` (required) * `items` (required) * `product` (optional) * `productLevel` (optional) * `pricingPlan` (required) * `interval` (required) * `price` (required) * `value` (required) * `currencyCode` (required) * `redirectUrl` (required) * `description` (required) * `subscriptionId` (required) #### Response **`Query response: Update a subscription`** ```json title="Query response: Update a subscription" { "data": { "checkout": { "createCheckout": { "checkout": { "accountId": "bc/account/account/2a159c53-1caa-4ce8-af4f-6b00da294e2a", "status": "PENDING", "checkoutUrl": "https://store-hqjwlmtf9q.mybigcommerce.com/manage/merchant-checkout?checkoutId=6869d437-5eb9-4ad9-8c4a-086e448bb6f6", "items": { "edges": [ { "node": { "subscriptionId": "bc/account/subscription/9cf1f949-8a74-4938-bd13-64d9741a9685", "status": "PENDING", "product": { "id": "bc/account/product/16267", "type": "APPLICATION", "productLevel": "Premium" }, "scope": { "id": "bc/account/scope/hqjwlmtf9q", "type": "STORE" }, "pricingPlan": { "interval": "ANNUAL", "price": { "value": 129.99, "currencyCode": "USD" }, "trialDays": 0 }, "redirectUrl": "bigcommerce.com/checkout_success", "description": "test application" } } ] } } } } } } ``` Possible Errors: * Scope updates are not allowed for an existing subscription. * Product updates are not allowed for an existing subscription. * Trial days cannot be added to existing subscriptions. * Checkouts are not available for existing trial subscriptions. * Scope does not belong to account. * Could not find active subscription. If updates are needed for scope, product, or trial days, cancel the existing subscription and create a new checkout to create a new subscription. ### Cancel a subscription This mutation cancels the subscription at the end of the merchant's current billing cycle. The `cancelledAt` value will be the last day of the merchant's billing cycle (i.e., the day through which they have already paid). For trials and subscriptions that have not yet been invoiced, the cancellation takes effect immediately and the `cancelledAt` value will reflect this immediate time. #### Request **`Example Query: Cancel a subscription`** ```graphql title="Example Query: Cancel a subscription" mutation ($subscription: CancelSubscriptionInput!) { subscription { cancelSubscription(input: $subscription) { subscriptionId cancelledAt } } } ``` #### Sample variables Variables for this mutation should look like so: **`Sample variables`** ```json title="Sample variables" { "subscription": { "id": "bc/account/subscription/9bbe8843-27eb-4f78-b34b-c692d1016382" } } ``` #### Response **`Example response: Cancelled subscription`** ```json title="Example response: Cancelled subscription" { "data": { "subscription": { "cancelSubscription": { "subscriptionId": "bc/account/subscription/9bbe8843-27eb-4f78-b34b-c692d1016382", "cancelledAt": "2023-11-09T00:00:00.000Z" } } } } ``` #### How Cancellations Work During a Free Trial * No Billing During Trial * A subscription only generates an invoice once the trial period ends. No charges are made during the trial. * Immediate Cancellation During Trial * If a subscription is canceled while it's still in the trial period, the cancellation takes effect immediately. The trial ends, and no invoice is ever generated. * Post Trial Cancellation Behavior * Once the trial ends, the subscription begins billing. * Any cancellation initiated before the next billing cycle date will be prorated for the period from trial end until cancellation date. * Charges for prorated fees will appear on the merchant's next invoice. ### Query subscriptions Subscriptions can be queried using the `subscriptions` query endpoint. Fields that can be retrieved are: * `id` - subscription id * `accountId` - account id belonging to the merchant * `activationDate` - date billing began * `billingInterval` - billing frequency * `createdAt` - date and time the subscription was created * `currentPeriodEnd` - date of the end of the current billing period * `updatedAt` - date and time the subscription was last updated * `pricePerInterval` - amount being billed with the following fields: * `value` - the scalar amount * `currencyCode` - the currency of the amount * `product` - product object with the following fields * `productLevel` - the level of the product if it was provided * `id` - product id * `type` - product type * `status` - subscription status * `scope` - scope object with the following fields * `type` - scope type * `id` - scope id In this example, no filters are passed, so the response will include all subscriptions of the partner. The default number of subscriptions returned per page is 10. #### Request **`Example Query: Query subscriptions`** ```graphql title="Example Query: Query subscriptions" query { account { subscriptions { pageInfo { hasNextPage hasPreviousPage startCursor endCursor } edges { cursor node { id accountId activationDate pricePerInterval { value currencyCode } billingInterval status scope { type id } product { productLevel id type } createdAt currentPeriodEnd updatedAt } } } } } ``` #### Response **`Example response: Subscriptions`** ```json title="Example response: Subscriptions" { "data": { "account": { "subscriptions": { "pageInfo": { "hasNextPage": true, "hasPreviousPage": false, "startCursor": "WzE3MjQ0MzgzODk0MzY0NzYsODhd", "endCursor": "WzE3MTk3NDYxNzUyNjg2NDUsNzdd" }, "edges": [ { "cursor": "WzE3MjQ0MzgzODk0MzY0NzYsODhd", "node": { "id": "bc/account/subscription/d7762d54-1aab-4243-938b-294b846222b5", "accountId": "bc/account/account/0b2d26c8-e4e2-4635-9c99-8bf3cfd93153", "activationDate": "2024-08-23T00:00:00Z", "pricePerInterval": { "value": 14.99, "currencyCode": "USD" }, "billingInterval": "ONCE", "status": "ACTIVE", "scope": { "type": "STORE", "id": "bc/account/scope/9godyw034y" }, "product": { "productLevel": "", "id": "bc/account/product/16267", "type": "APPLICATION" }, "createdAt": "2024-08-23T18:39:48Z", "currentPeriodEnd": "2024-08-24T00:00:00Z", "updatedAt": "2024-08-23T18:39:48Z" } }, { "cursor": "WzE3MjQzNDQ1Njc2ODkwMjMsODdd", "node": { "id": "bc/account/subscription/f34807ed-493a-4d17-90f1-11b2c3283cfd", "accountId": "bc/account/account/6c3efb7e-10cf-48a3-af71-e64df983579f", "activationDate": "2024-08-22T00:00:00Z", "pricePerInterval": { "value": 14.99, "currencyCode": "USD" }, "billingInterval": "ONCE", "status": "ACTIVE", "scope": { "type": "STORE", "id": "bc/account/scope/ptjktkt6tj" }, "product": { "productLevel": "", "id": "bc/account/product/16267", "type": "APPLICATION" }, "createdAt": "2024-08-22T16:36:06Z", "currentPeriodEnd": "2024-08-23T00:00:00Z", "updatedAt": "2024-08-22T16:36:06Z" } }, { "cursor": "WzE3MjQzMzk2NjcyOTMyMjQsODZd", "node": { "id": "bc/account/subscription/803d7fea-defd-41d9-83c4-33d63b7ab22a", "accountId": "bc/account/account/209dcf7b-79d8-45fb-9990-8685e464d3fa", "activationDate": "2024-08-22T00:00:00Z", "pricePerInterval": { "value": 14.99, "currencyCode": "USD" }, "billingInterval": "ONCE", "status": "ACTIVE", "scope": { "type": "STORE", "id": "bc/account/scope/akpitaw5xe" }, "product": { "productLevel": "", "id": "bc/account/product/16267", "type": "APPLICATION" }, "createdAt": "2024-08-22T15:14:25Z", "currentPeriodEnd": "2024-08-23T00:00:00Z", "updatedAt": "2024-08-22T15:14:25Z" } }, { "cursor": "WzE3MjQzMzgyNjIwMTEzMjMsODVd", "node": { "id": "bc/account/subscription/586989f3-8f3a-40c2-bb51-23b54a2b1563", "accountId": "bc/account/account/3df4828d-eb17-4076-b516-6c1b7c44d65b", "activationDate": "2024-08-22T00:00:00Z", "pricePerInterval": { "value": 14.99, "currencyCode": "USD" }, "billingInterval": "ONCE", "status": "ACTIVE", "scope": { "type": "STORE", "id": "bc/account/scope/m8gmsdvhrz" }, "product": { "productLevel": "", "id": "bc/account/product/16267", "type": "APPLICATION" }, "createdAt": "2024-08-22T14:51:00Z", "currentPeriodEnd": "2024-08-23T00:00:00Z", "updatedAt": "2024-08-22T14:51:00Z" } }, { "cursor": "WzE3MjQyNjA0ODI2MzYyMTQsODRd", "node": { "id": "bc/account/subscription/e19d08e7-621e-4f30-90ad-6608e34ff7b0", "accountId": "bc/account/account/e9d261ee-a46a-4d03-a850-12bc56358a05", "activationDate": "2024-08-21T00:00:00Z", "pricePerInterval": { "value": 14.99, "currencyCode": "USD" }, "billingInterval": "ONCE", "status": "ACTIVE", "scope": { "type": "STORE", "id": "bc/account/scope/ixsnyuymca" }, "product": { "productLevel": "", "id": "bc/account/product/16267", "type": "APPLICATION" }, "createdAt": "2024-08-21T17:14:41Z", "currentPeriodEnd": "2024-08-22T00:00:00Z", "updatedAt": "2024-08-21T17:14:41Z" } }, { "cursor": "WzE3MjQwODQ4MTAxMzA1ODQsODNd", "node": { "id": "bc/account/subscription/4391144f-4ef1-4d44-9e39-88c92f74413d", "accountId": "bc/account/account/e6472f2c-4fda-4ac6-85bf-06ed6a3dcc3e", "activationDate": "2024-08-29T00:00:00Z", "pricePerInterval": { "value": 39.99, "currencyCode": "USD" }, "billingInterval": "ANNUAL", "status": "ACTIVE", "scope": { "type": "STORE", "id": "bc/account/scope/qithb7k8wh" }, "product": { "productLevel": "", "id": "bc/account/product/16267", "type": "APPLICATION" }, "createdAt": "2024-08-19T16:34:45Z", "currentPeriodEnd": "2025-08-19T00:00:00Z", "updatedAt": "2024-08-19T16:34:45Z" } }, { "cursor": "WzE3MjM0NzU1MDQ3MzEzMTUsODJd", "node": { "id": "bc/account/subscription/462beb00-10b6-4eeb-a314-d6cddd91bf43", "accountId": "bc/account/account/fd0809ce-2f3e-4236-8d1a-d85cc9fe723a", "activationDate": "2024-08-22T00:00:00Z", "pricePerInterval": { "value": 12.1, "currencyCode": "USD" }, "billingInterval": "MONTH", "status": "ACTIVE", "scope": { "type": "STORE", "id": "bc/account/scope/hfwvcccsmx" }, "product": { "productLevel": "", "id": "bc/account/product/16267", "type": "APPLICATION" }, "createdAt": "2024-08-23T16:55:05Z", "currentPeriodEnd": "2024-08-22T00:00:00Z", "updatedAt": "2024-08-23T16:55:05Z" } }, { "cursor": "WzE3MjMwMjkzNzgyMTM3ODgsODBd", "node": { "id": "bc/account/subscription/69f56ca2-2eac-463c-981e-40f0df48037a", "accountId": "bc/account/account/b347426e-dbce-4fa9-9b4c-f38e48e1fe83", "activationDate": "2024-07-21T00:00:00Z", "pricePerInterval": { "value": 12.1, "currencyCode": "USD" }, "billingInterval": "MONTH", "status": "SUSPENDED", "scope": { "type": "STORE", "id": "bc/account/scope/nflzugwhtu" }, "product": { "productLevel": "", "id": "bc/account/product/16267", "type": "APPLICATION" }, "createdAt": "2024-08-07T11:16:13Z", "currentPeriodEnd": "2024-08-11T00:00:00Z", "updatedAt": "2024-08-07T11:16:13Z" } }, { "cursor": "WzE3MjI4OTA0MDEzMjA3ODksODFd", "node": { "id": "bc/account/subscription/40ff5c2c-4e30-44a7-8eba-666606ceac9c", "accountId": "bc/account/account/e3a45b63-9255-42d9-b980-4345d6becf70", "activationDate": "2024-08-05T00:00:00Z", "pricePerInterval": { "value": 12.1, "currencyCode": "USD" }, "billingInterval": "MONTH", "status": "ACTIVE", "scope": { "type": "STORE", "id": "bc/account/scope/mkjajoayfu" }, "product": { "productLevel": "", "id": "bc/account/product/16267", "type": "APPLICATION" }, "createdAt": "2024-08-05T20:40:00Z", "currentPeriodEnd": "2024-09-05T00:00:00Z", "updatedAt": "2024-08-05T20:40:00Z" } }, { "cursor": "WzE3MTk3NDYxNzUyNjg2NDUsNzdd", "node": { "id": "bc/account/subscription/2cab6d7e-f575-441f-9290-1e164991ea08", "accountId": "bc/account/account/48c32212-61cc-4a87-a061-cb0affc71067", "activationDate": "2024-09-11T00:00:00Z", "pricePerInterval": { "value": 12.1, "currencyCode": "USD" }, "billingInterval": "MONTH", "status": "SUSPENDED", "scope": { "type": "STORE", "id": "bc/account/scope/gwbeti9gpi" }, "product": { "productLevel": "", "id": "bc/account/product/16267", "type": "APPLICATION" }, "createdAt": "2024-06-30T11:16:11Z", "currentPeriodEnd": "2024-10-03T00:00:00Z", "updatedAt": "2024-09-10T00:00:00Z" } } ] } } } } ``` Pagination info is returned with cursors on every subscription node. The `pageInfo` provides information on the next page along with the cursors to use in traversing the graph. ```json showLineNumbers={false} "pageInfo": { "hasNextPage": true, "hasPreviousPage": false, "startCursor": "WzE3MjQ0MzgzODk0MzY0NzYsODhd", "endCursor": "WzE3MTk3NDYxNzUyNjg2NDUsNzdd" } ``` Use the `endCursor` to begin the next query. `first` can be used to limit how many subscriptions are returned. The max limit is 50 subscriptions at a time. **`Example Query: Query subscriptions`** ```graphql title="Example Query: Query subscriptions" showLineNumbers={false} query { account { subscriptions(first: 10, after: "WzE3MTk3NDYxNzUyNjg2NDUsNzdd") { pageInfo { hasNextPage hasPreviousPage startCursor endCursor } edges { cursor node { id accountId activationDate pricePerInterval { value currencyCode } billingInterval status scope { type id } product { productLevel id type } createdAt currentPeriodEnd updatedAt } } } } } ``` Filters can also be used to query subscriptions. The supported filters are * `productId` * `productType` * `scopeId` * `scopeType` * `updatedAfter` * `status` * `ids` #### Request **`Example Query: Query subscriptions with filters`** ```graphql title="Example Query: Query subscriptions with filters" query ($filters: SubscriptionFiltersInput) { account { subscriptions(filters: $filters) { pageInfo { hasNextPage hasPreviousPage startCursor endCursor } edges { cursor node { id accountId activationDate pricePerInterval { value currencyCode } billingInterval status scope { type id } product { productLevel id type } createdAt currentPeriodEnd updatedAt } } } } } ``` #### Sample variables Variables for this query should look like so: **`Sample variables`** ```json title="Sample variables" { "filters": { "productId": "bc/account/product/16267", "productType": "APPLICATION", "updatedAfter": "2024-05-01T00:00:00Z", "status": "ACTIVE" } } ``` The `ids` filter can be used to retrieve specific subscriptions: **`IDs filter`** ```json title="IDs filter" { "filters": { "ids": ["bc/account/subscription/d7762d54-1aab-4243-938b-294b846222b5", "bc/account/subscription/f34807ed-493a-4d17-90f1-11b2c3283cfd"] } } ``` Use `scopeId` and `scopeType` filters together to retrieve specific subscriptions for a given scope: **`Scope filters`** ```json title="Scope filters" { "filters": { "scopeId": "bc/account/scope/9godyw034y", "scopeType": "STORE" } } ```