Unified Billing Overview

GraphQL Account API

Unified Billing allows merchants to buy apps through the BigCommerce App Marketplace and have the charges included on their BigCommerce invoice.

Requirements and limitations

To implement Unified Billing, you need to use the GraphQL API, as well as a partner portal account (opens in a new tab) for reconciling charges with your other systems.

The following are required to get started:

1. A Partner Portal Account with approved Partner status.
2. A non-trial store for testing. This store can be a partner sandbox store.
3. An installable app in the Developer Portal (opens in a new tab). It can be in Draft or Published status.

For an overview, requirements, limitations, and how to opt-in, see our Help Center article Unified Billing for Partners (opens in a new tab).

Prerequisites

To begin, please complete the following steps:

1. Set up Authentication
2. Ensure your app is setup for Unified Billing
3. Gather Required Information
4. Begin Integrating with Unified Billing

Authentication

The Unified Billing GraphQL API uses Account-Level API tokens for authentication. The account used to create your application must match the account used to create the token in order to correctly authenticate with Unified Billing. If you have multiple applications, make sure you are using the token from the account that the application belongs to. The following scopes pertain directly to Unified Billing. For a complete list of the available Account-Level OAuth scopes, see the Guide to API Accounts (opens in a new tab).

UI Name	Scopes	Parameter	Description	Resources
Subscriptions	cancel	account_subscriptions_cancel	View or cancel account-level subscriptions	GraphQL Account API
Subscriptions	read	account_subscriptions_read	View account-level subscriptions	GraphQL Account API
Checkouts	modify	account_checkouts_create	Create account-level checkouts	GraphQL Account API
Checkouts	read	account_checkouts_read	View account-level checkouts	GraphQL Account API

Required App Setup

For more information on creating an app, see our quick start guide (opens in a new tab).

In order for your app to connect to Unified Billing, you must ensure it is set up correctly. This requires that your application is installable (Draft or Published) and that it includes your Partner ID and the required scope. Your app must have the required scope set so that after installation it can access the merchant's account UUID via the Store Information API.

1. Go to the Developer Portal (opens in a new tab)
2. Edit your application
3. Under App Information, take note of the Account UUID. This must match the account creating your Account-Level API token.
4. Under Scopes, ensure the following are selected:
   • Information and Settings: Modify
5. Under Listing Information, enter your Partner ID in the designated field
6. Save the changes

Gathering Information

To integrate with the Unified Billing API, you'll need the following information which can be acquired following the steps below:

Value	Description
Authentication headers	To authenticate API requests, visit the account center (opens in a new tab) and generate a new Account-Level API token. Note the X-Auth-Token property because you must include it in the request headers. You can't reaccess the credentials from this page, so save them somewhere safe. Use the above list of OAuth scopes to inform the scopes you select for the API token. Note that the account used to create your application must match the account used to create the token in order to correctly authenticate with Unified Billing. If you have multiple applications, make sure you are using the token from the account that the application belongs to.
Partner ID	To retrieve the partner ID, sign in to the partner portal (Impartner) (opens in a new tab) and go to your account profile.
Partner Account UUID	Visible when creating the Account-Level API token as well as in the App Information section of your app.
Application ID	Create your app in the developer portal (opens in a new tab) and record your application ID found in the app's details URL.
Merchant Account UUID	To retrieve the merchant account UUID, send a request to the Get Store Information endpoint and record the merchant's account_uuid from the response.

Begin Integrating with Unified Billing

You can now begin integrating with the Unified Billing API. See the example queries and mutations (opens in a new tab) for more information.

Test Unified Billing with your app:

If your app is already published to production (i.e. visibility status = Public):

• Connect your app to Unified Billing
• Test using $0 checkouts, so that you don’t get charged real money.
• After you create a checkout, you can test completing of the checkout by creating and logging into a sandbox store as the Store Owner, and completing the checkout as a merchant would do.

If your app is NOT yet published to production (i.e visibility status = Draft, Under Review):

• Build your app and review the App Marketplace Approval Requirements
• Connect your app to Unified Billing
• Checkouts are limited to $0, so that you don't get charged real money.
• After you create a checkout, you can test completing of the checkout by creating and logging into a sandbox store as the Store Owner, and completing the checkout as a merchant would do.
• Submit your app for review and approval!

App Partner Responsibilities

• Trial Abuse Prevention

  • App Partners are responsible for detecting and preventing abuse of the trial system. Such as merchants creating multiple subscriptions to repeatedly access free trials. To help with this, App Partners can use the Subscriptions Query with a given scope to check for previous subscriptions before creating a new checkout.

• Enforcement and Rules:

  • Each App Partner should define its own trial eligibility rules and implement safeguards to enforce them, as this logic is not managed by the platform.