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.

In order to use Unified Billing, you must sign the Unified Billing addendum within your partner portal account.

For the full list of requirements and limitations, see our Help Center article Unified Billing for Partners (opens in a new tab).

OAuth scopes

The following scopes pertain directly to Unified Partner Billing. For a complete list of generally available account-level OAuth scopes, see the Guide to API Accounts.

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-only	account_checkouts_read	View account-level checkouts	GraphQL Account API

Gathering Information

Collect the following values to use later.

Value	Description
Authentication headers	To authenticate API requests, visit the account center (opens in a new tab) and generate a new account-level API account. 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 following list of OAuth scopes to inform the scopes you select for the API account. 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	To retrieve your partner account UUID, sign in to the Developer portal (opens in a new tab) and copy the Account UUID from the top nav bar.
Application ID	Create your app in the staging developer portal (opens in a new tab) and record your application ID. Make sure to also input your partner information associated with the app, especially the partner ID from the partner portal (Impartner) (opens in a new tab).
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.

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.