Provider APIs
Introduction
Provider APIs represent a different data flow from the rest of the APIs - a data flow that involves BigCommerce making API requests to your own application to retrieve data on behalf of a store in a specific context. This means that these are not, strictly speaking, implemented APIs but rather specifications for APIs that your own applications must implement.
BigCommerce connects to your provider API endpoints in the context of a single-click app that is installed from a merchant store control panel. Therefore, a prerequisite for developing your provider application is to implement a single-click app OAuth workflow and register the app in the BigCommerce Developer Portal. We’ll discuss more details of single-click apps in a later section.
Shipping Provider API
An app will implement Shipping Provider API endpoints when it supplies shipping rate quotes to merchants and shoppers at checkout or during order creation.
You might develop a shipping provider app if you are partnering with a custom carrier to provide an integration via the BigCommerce app marketplace, or if you simply need to provide custom drop-shipping or table rates with an unlisted app for a single merchant.
To get started with the Shipping Provider API, you must register a single-click app and then contact BigCommerce with the details of your app, its service endpoints, and any applicable carrier configuration (see below). Once you’ve completed this process and received a carrier ID, any store that installs your app via the control panel can enable the shipping option to receive shipping quotes.
Authentication and Carrier Configuration
When you request your carrier ID from BigCommerce, you can also provide a carrier configuration schema. This defines settings that will be available to merchants when configuring the shipping provider in the control panel or via API. Examples of common carrier configuration settings are merchant authentication keys, settings to select available shipping methods, or flags to identify a “sandbox” mode.
How a store is authenticated in requests to your API endpoints is up to your own implementation and can be done utilizing the unique carrier configuration settings you choose to include. When BigCommerce makes requests to your app, it will include the store’s configuration settings in its payload.
Endpoints
The Shipping Provider API endpoints your app must or may implement include:
- Request shipping rates: A request to this endpoint will include details of a shipping origin and destination, as well as order/cart items. The payload will also include the merchant’s “connection options” matching your carrier configuration schema. This endpoint should then return carrier information, available methods, and rates.
- Validate connection options: A request will be made to this endpoint when the shipping carrier is first connected and configured, giving your app the opportunity to inspect and validate the connection options.
BigCommerce caches shipping rates provided in your responses and will reuse these for identical shipping estimate requests.
Learn more about the Shipping Provider API in the developer guide and API reference.
Tax Provider API
An app will implement Tax Provider API endpoints to provide sales tax estimates to shoppers on the storefront or to merchants in the control panel.
To get started with the Tax Provider API, you must register a single-click app and then contact BigCommerce with the details of your app and its service endpoints. Once you’ve completed this process and received a provider ID, any store that installs your app can enable the tax provider in the control panel tax settings.
Authentication
Your app should use the Tax Provider Connection API to establish a connection for the store when the tax provider app is installed and the merchant’s account or credentials are verified. You can provide whatever authentication workflow or additional settings are appropriate for your service within the app interface that displays within the Apps section of the store control panel.
When you use the Tax Provider Connection API to update the store’s connection, you’ll supply a username and password, which BigCommerce will then provide in HTTP Basic Authentication headers when making requests to your endpoints, in order to identify the store.
Endpoints
The Tax Provider API endpoints your app must or may implement include:
- Estimate taxes: Requests to this endpoint will contain details of the quote request, including transaction date, customer information, and the billing, shipping and item details of each consignment. The response should include tax totals and amounts broken down by tax rate.
- Commit tax quote: This optional endpoint is used if a merchant enables “Submit Order Data” in their tax configuration, for persisting tax document submission.
- Adjust tax quote: This optional endpoint is intended to replace a committed tax quote with a new quote.
- Void tax quote: This optional endpoint is intended to invalidate a committed tax quote.
Learn more about the Tax Provider API in the developer guide and API reference.
