From e53c9cc341f48ea1a163c992fcc37eba1b6ed4be Mon Sep 17 00:00:00 2001 From: mikelopez100 Date: Mon, 22 Sep 2025 15:14:40 -0500 Subject: [PATCH 1/4] BRP-17798 Improve UB docs --- .../apps/unified-billing/example-queries.mdx | 64 +++++++++++++++++-- 1 file changed, 59 insertions(+), 5 deletions(-) diff --git a/docs/integrations/apps/unified-billing/example-queries.mdx b/docs/integrations/apps/unified-billing/example-queries.mdx index bef0875c0..3b363c727 100644 --- a/docs/integrations/apps/unified-billing/example-queries.mdx +++ b/docs/integrations/apps/unified-billing/example-queries.mdx @@ -1,9 +1,57 @@ -# GraphQL Account API: Unified billing +# GraphQL Account API: Unified Billing -The following examples of queries and mutations use the Unified Billing features of the BigCommerce GraphQL Account API. Use the API by submitting POST requests to `https://api.bigcommerce.com/accounts/{{partner_account_uuid}}/graphql`. +The following examples of queries and mutations use the Unified Billing features of 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](https://developer.bigcommerce.com/docs/integrations/apps/unified-billing/postman-collection) +## Possible Implementation Strategies + +Using the information gathered from the [prerequisites section](https://developer.bigcommerce.com/docs/integrations/apps/unified-billing#prerequisites), 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](https://developer.bigcommerce.com/docs/integrations/apps/unified-billing/example-queries#fetch-a-checkout) 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](https://developer.bigcommerce.com/docs/integrations/apps/unified-billing/example-queries#query-subscriptions) returns an active subscription +- This approach is more efficient and provides better reliability for verifying completed purchases + +### Managing Access Control + +Use the [Subscriptions Query](https://developer.bigcommerce.com/docs/integrations/apps/unified-billing/example-queries#query-subscriptions) to verify which merchants have active subscriptions. Filter by `scopeId` (store hash) to check if a specific merchant has access to premium features. + +**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](https://developer.bigcommerce.com/docs/integrations/apps/unified-billing/example-queries#cancel-a-subscription). 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](https://developer.bigcommerce.com/docs/integrations/apps/unified-billing/example-queries#update-a-subscription). 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 @@ -71,7 +119,7 @@ To create a checkout, run the `createCheckout` mutation: ```json filename="Sample variables" showLineNumbers copy { "checkout": { - "accountId": "bc/account/account/61db983a-cd07-4d6b-8b59-a5ffe285ca6a", + "accountId": "bc/account/account/61db983a-cd07-4d6b-8b59-a5ffe285ca6a", // This should be the merchant's account UUID "items": [ { "product": { @@ -80,7 +128,7 @@ To create a checkout, run the `createCheckout` mutation: "productLevel": "Standard" }, "scope": { - "id": "bc/account/scope/f0qyczpkb2", + "id": "bc/account/scope/f0qyczpkb2", // This should be the merchant's store hash "type": "STORE" }, "pricingPlan": { @@ -150,6 +198,12 @@ To create a checkout, run the `createCheckout` mutation: +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 (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 scope for the given operation. + * The account-level API token does not match the account UUID being used in the request URL. ### Fetch a checkout @@ -461,7 +515,7 @@ The `createCheckout` mutation can also be used to update an existing subscriptio ### 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). +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. From fd7a2724c03cbab09db97c33f944d8e0961a620f Mon Sep 17 00:00:00 2001 From: mikelopez100 Date: Tue, 23 Sep 2025 14:33:42 -0500 Subject: [PATCH 2/4] chanch --- docs/integrations/apps/unified-billing/example-queries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/integrations/apps/unified-billing/example-queries.mdx b/docs/integrations/apps/unified-billing/example-queries.mdx index 3b363c727..0af023b9b 100644 --- a/docs/integrations/apps/unified-billing/example-queries.mdx +++ b/docs/integrations/apps/unified-billing/example-queries.mdx @@ -1,6 +1,6 @@ # GraphQL Account API: Unified Billing -The following examples of queries and mutations use the Unified Billing features of the BigCommerce GraphQL Account API. +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`. From 29fba13210d9b92f559e9c6bdbd02d289bc74553 Mon Sep 17 00:00:00 2001 From: mikelopez100 Date: Tue, 23 Sep 2025 15:24:46 -0500 Subject: [PATCH 3/4] cath --- docs/integrations/apps/unified-billing/example-queries.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/integrations/apps/unified-billing/example-queries.mdx b/docs/integrations/apps/unified-billing/example-queries.mdx index 0af023b9b..fe2a8c4e9 100644 --- a/docs/integrations/apps/unified-billing/example-queries.mdx +++ b/docs/integrations/apps/unified-billing/example-queries.mdx @@ -27,7 +27,7 @@ When a merchant wants to purchase a subscription after installing your app, use ### Managing Access Control -Use the [Subscriptions Query](https://developer.bigcommerce.com/docs/integrations/apps/unified-billing/example-queries#query-subscriptions) to verify which merchants have active subscriptions. Filter by `scopeId` (store hash) to check if a specific merchant has access to premium features. +Use the [Subscriptions Query](https://developer.bigcommerce.com/docs/integrations/apps/unified-billing/example-queries#query-subscriptions) 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 @@ -202,7 +202,7 @@ 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 (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 scope for the given operation. + * The account-level API token being used does not have the [required auth scope](https://developer.bigcommerce.com/docs/integrations/apps/unified-billing#authentication) for the given operation. * The account-level API token does not match the account UUID being used in the request URL. ### Fetch a checkout From 348a8339c6cbb13f9897a1b9d9a2f19b3675c97e Mon Sep 17 00:00:00 2001 From: mikelopez100 Date: Tue, 23 Sep 2025 15:26:22 -0500 Subject: [PATCH 4/4] cath --- docs/integrations/apps/unified-billing/example-queries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/integrations/apps/unified-billing/example-queries.mdx b/docs/integrations/apps/unified-billing/example-queries.mdx index fe2a8c4e9..dd1ef8500 100644 --- a/docs/integrations/apps/unified-billing/example-queries.mdx +++ b/docs/integrations/apps/unified-billing/example-queries.mdx @@ -199,7 +199,7 @@ To create a checkout, run the `createCheckout` mutation: 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 (in the request URL) making the request. +* `Product is not supported for your account.` - The application being purchased [is not owned by the partner account](https://developer.bigcommerce.com/docs/integrations/apps/unified-billing#required-app-setup) (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](https://developer.bigcommerce.com/docs/integrations/apps/unified-billing#authentication) for the given operation.