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.

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, it will be in a pending status, and a checkoutUrl will be included in the response. The URL 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.

To create a checkout, run the createCheckout mutation:

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 {
                    entityId
                    type
                    productLevel
                  }
                  scope {
                    entityId
                    type
                  }
                  pricingPlan {
                    interval
                    price {
                      value
                      currencyCode
                    }
                    trialDays
                  }
                  redirectUrl
                  description
                }
              }
            }
          }
        }
      }
    }

Fetch a checkout

To fetch an existing checkout, copy and run the following query:

Replace the checkoutId with the following variable:

{
  "checkoutId": "bc/account/checkout/ab0a8354-3caf-423b-a3be-42a59c97fcf5"
}

Example query: Fetch a checkout

query Account($checkoutId: ID!) {
  account {
    checkout(id: $checkoutId) {
      id
      accountId
      checkoutUrl
      status
      items {
        edges {
          node {
            description
            status
            product {
              entityId
              productLevel
              type
            }
            scope {
              entityId11
              type
            }
            pricingPlan {
              price {
                value
                currencyCode
              }
              interval
              trialDays
            }
            subscriptionId
            redirectUrl
          }
        }
      }
    }
  }
}

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.

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
              }
            }
          }
        }
      }
    }
  }

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).

Example Query: Cancel a subscription

  mutation ($subscription: CancelSubscriptionInput!) {
    subscription {
      cancelSubscription(input: $subscription) {
        subscriptionId
        cancelledAt
      }
    }
  }

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.

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
        }
      }
    }
  }
}

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.

"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

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
updatedAfter
status
ids

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
          }
        }
      }
    }
  }

Did you find what you were looking for?

Overview Postman collection