Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 28 ยท Checkout and Commerce Services

Payment, Shipping and Tax Providers

See how BigCommerce calls out to payment gateways, shipping rate providers and tax providers, what contracts they follow, and how to handle timeouts safely.

Most of checkout is not calculated by BigCommerce alone. When a shopper picks a destination, the platform may call a shipping provider for live rates. When the cart is priced, it may call a tax provider for exact taxes. When the shopper pays, a payment provider authorizes the charge. These providers are other people's services, and BigCommerce talks to them over HTTP using agreed formats. If you build one of them, your service becomes part of every sale on every store that connects to it, and its speed and correctness directly affect checkout.

Provider integrations are partner-level work: real ones need accounts, certification and review, and they run against live stores, so everything about the real contracts in this lesson is read-only and kept conservative. Check the current developer documentation for exact field names, endpoints and limits. The runnable part is a Node.js shipping rate service on your own machine, called with a timeout and a fallback, plus a small contract checker. Both are our own stand-ins that teach the engineering patterns; they are not BigCommerce's code. Background reading: How Online Payments Work, Authorize, Capture and Refund, Shipping Methods and Rates and Sales Tax, VAT and GST.

The shape of a provider integration

Every provider follows the same pattern:

  1. A merchant connects your provider to their store, usually by installing your app (see App Types and the OAuth Flow). The app stores the store hash and any settings, such as the merchant's carrier account.
  2. At a certain moment in checkout, BigCommerce sends your service a request describing what it needs: a destination and items, a cart to tax, a payment to authorize.
  3. Your service responds within a time limit with a result in the required format.
  4. If you are slow, down or wrong, BigCommerce behaves according to its failure rules, and the shopper sees a degraded checkout (fewer shipping choices, a tax fallback, a payment error).
sequenceDiagram
    participant U as Shopper
    participant B as BigCommerce checkout
    participant P as Your provider service
    U->>B: enters address
    B->>P: request (destination, items)
    alt answers in time
        P-->>B: quotes
        B-->>U: shows your options
    else timeout or error
        B-->>U: shows other options or an error
    end

Your service is on the critical path of checkout, so speed and reliability are features.

Because the platform calls you, your endpoint is public. Verify that requests come from the platform using whatever signing or authentication the provider API specifies, and apply the same rules as for webhooks: see Webhooks and Webhooks and Signatures.

Shipping providers

A shipping provider (often a carrier integration) supplies live rate quotes. When the shopper's address and cart are known, BigCommerce sends a rate request to the connection URL you registered. A request describes the origin, the destination, the items with their weights and dimensions, and a few cart details; your response lists quotes, each with a code, a display name, a cost and often an estimated delivery time (read-only; the exact schema is in the Shipping Provider API reference):

JSON
{
  "quote_id": "q-1001",
  "messages": [],
  "carrier_quote": {
    "code": "acme",
    "display_name": "Acme Parcels",
    "quotes": [
      {
        "code": "acme-standard",
        "display_name": "Standard (3-5 days)",
        "cost": { "currency": "USD", "amount": 4.99 }
      }
    ]
  }
}

The response is subject to a short time limit, measured in seconds; check the current limit and design for much less. If your carrier's own API is slow, call it with a smaller timeout than the platform's, and return a cached or table-based estimate instead of nothing. A fast approximate rate is usually better for the sale than a slow exact one that arrives too late.

Good shipping providers share these habits:

  • Validate the request. Missing weights, unknown countries or zero items should return a clear error response, not a crash.
  • Compute money in integer cents and convert at the edge (see Money as Integers).
  • Cache quotes for identical requests for a short time.
  • Never return an empty list silently; return messages the merchant can act on.
  • Log the request id and timing so you can explain a slow checkout later.

A shipping rate service you can run

The code below starts a small HTTP server on a random local port and calls it the way the platform would. The /rates route validates input and prices parcels by weight, with free standard shipping over a threshold and an international surcharge. A /slow-rates route imitates a slow carrier. The calling code (our stand-in for the platform) uses an abort signal for the time limit and falls back to a flat rate. Everything is deterministic, and no network beyond your own machine is used.

Node.js A shipping rate service with timeout and fallback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Compare the results with the rules. The small order weighs 800 g, so standard shipping is $4.99 and express adds $8.00. The heavy order weighs 2,400 g and its subtotal is $80, which makes standard free; express is still priced from the underlying standard rate of $7.99, so it costs $15.99. The German order pays the international rate, an invalid request gets a 422 with readable messages, and the slow route times out after 150 ms so the caller shows a flat rate instead of nothing.

Tax providers

A tax provider replaces or supplements the store's built-in tax tables. Instead of fixed rates, BigCommerce asks your service to estimate the tax for a set of items, a ship-to address and sometimes a customer type, and your service answers with the tax per line and per shipping or handling item. For finalized orders the contract also has operations to record, change or cancel the tax transaction (commit, adjust and void are the usual names), so that your tax system matches the store's orders; confirm which operations your connection must support in the current Tax Provider API documentation.

The money is the hard part: tax must be computed per line, rounded in a consistent way, and add up exactly to the total. Read Sales Tax, VAT and GST for how tax systems differ; this lesson focuses on the integration:

  • The estimate runs on every cart change, so it must be fast. Cache by the full request, and use a local rate table as a fallback when your upstream tax engine is slow.
  • Be deterministic: the same request must give the same answer, or customers see totals jump.
  • Be careful with edge cases such as tax-exempt customers, tax-inclusive pricing, gift cards, shipping tax and zero-rated products.
  • Every line in the response must correspond to a line in the request. A mismatch can break checkout.

The next stand-in is a contract checker, the kind of function every provider should run against its own responses in tests. It verifies that a tax response covers exactly the requested lines, uses integer cents, has no negative taxes and that the totals add up.

JS Check a tax response against its request

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The good response passes. The bad one lists six problems together: lines b and ship are missing, line c is unexpected, the first tax is not an integer, the unexpected line has a negative tax and the total does not match the sum. Running such a check on every response in your test suite (see Testing Apps and Themes) catches contract bugs before a merchant does.

Payment providers

Payments are the most regulated part. There are two different things people call "a payment integration":

  • Using a payment gateway in a store. Most merchants enable an existing gateway (Stripe, PayPal, Adyen and others) in the control panel. No code is needed, and the checkout shows that method.
  • Building or connecting a payment provider. BigCommerce has a payments provider program for companies that process payments, with its own contract, review and security requirements. These integrations are certified and handle sensitive flows such as authorization, capture, refund, voiding, 3-D Secure and webhooks from the gateway. They are not a weekend project, and you should not attempt one without the program's documentation, certification and a PCI-compliant design.

For an app or custom checkout, the practical tool is the Payments API. After an order exists, your server requests a short-lived payment access token using its API credentials, and then submits a payment to the payments endpoint with the payment method and the instrument (a stored token, or card data collected by a PCI-compliant hosted form, never by your own server unless you are certified). The flow, read-only and simplified:

Terminal
# 1) Ask for a payment access token for an order (server-side, with your API token)
curl -X POST "$BC_API_BASE/v3/payments/access_tokens" \
  -H "X-Auth-Token: $BC_ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{ "order": { "id": 1001 } }'

# 2) Submit the payment with that token to the payments endpoint
#    (the endpoint and fields are in the Payments API reference)

Keep these rules in mind:

  • Do not store, log or transmit raw card data unless you are PCI certified. Use hosted fields or tokens; see PCI and 3-D Secure.
  • Treat every payment request as retriable and make it idempotent in your own system, so a retry after a timeout cannot charge twice. See Idempotency.
  • Handle every outcome, including declines, pending states and 3-D Secure challenges, and show a message the shopper can act on.
  • Reconcile: compare the platform's order totals and payment records against your records regularly.

Timeouts, fallbacks and monitoring

The patterns repeat across all three provider types:

  • Budget your time. Give your upstream calls (carrier API, tax engine) less time than the platform gives you, and decide in advance what you return when they miss it.
  • Degrade, don't die. A flat shipping rate, a local tax table or a cached answer is better than an error that stops a sale.
  • Cache with care. Cache by the complete request, keep entries short-lived, and never cache anything that includes personal data longer than needed.
  • Observe. Record latency, error rate and fallback rate per store. A rising fallback rate is an early warning that your upstream is struggling.
  • Be safe on retries. The platform may call you again with the same request. Handlers should be idempotent.
  • Protect the endpoint. Authenticate requests, rate limit, and never trust values in the body without validation.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should a shipping provider use a shorter timeout for its carrier API than the platform gives it?

    If the upstream call uses the entire time budget, there is no time left to answer. A smaller upstream timeout leaves room for a cached or table-based quote.
  2. 2. What must a tax estimate response contain for each requested line?

    Responses must correspond line for line to the request, with exact integer amounts that add up to the total.
  3. 3. How should an app collect card numbers for a payment?

    Raw card data must stay inside PCI-compliant systems. Apps work with tokens and results.
  4. 4. What should a shipping service do with an invalid request such as an empty item list?

    Clear errors let the platform and the merchant see what is wrong. Silent empty answers are hard to debug.

Summary

  • Providers are external services that BigCommerce calls for shipping rates, taxes and payments; they sit on the critical path of checkout.
  • Shipping providers return quotes within a short time limit; validate input, use integer cents and fall back to cached or table-based rates.
  • Tax providers estimate tax per line (and, for finalized orders, record changes); responses must match the request line for line and add up exactly.
  • Payment provider integrations are certified partner work; for apps use the Payments API with tokens and never touch raw card data.
  • Make handlers idempotent, authenticate requests, cache carefully and monitor latency and fallback rates.
  • The rate service and the contract checker are stand-ins; the exact contracts, limits and failure rules come from the current BigCommerce documentation.

Next: Headless Storefronts