canonical: https://jentic.com/apis/bigcommerce.com/bigcommerce-orders-api

# Bigcommerce Orders V3

The BigCommerce Orders API handles the money and settings side of an order: it captures and voids authorized payments, reads an order's transactions, and creates refund quotes and refunds against a paid order. It also manages global and per-channel order settings and stores order metafields of structured data. It is the post-purchase payment and configuration surface for orders already placed in a store.

## For AI agents

Capture and void order payments, read order transactions, create refund quotes and refunds, manage global and channel order settings, and store order metafields.

## Scope

Does not create orders, manage products, or edit customer records. Use for order payment actions, refunds, transactions, and order settings only.

## Capabilities

- Capture an authorized payment on an order
- Void an authorized order payment before capture
- Read the transactions recorded against an order
- Create a refund quote and issue a refund on an order
- Set global and per-channel order settings
- Store metafields of structured data on an order

## Use cases

### Agent-driven payment capture and refunds

An AI agent manages the money on orders as they move through fulfillment: it captures the authorized payment when an order ships, voids it when an order is cancelled before capture, and issues refunds against returns. Because the API exposes refund quotes before the refund itself, the agent can confirm the exact amount and tax split before committing the refund.

Example prompt: Create a refund quote for an order, then issue the refund for the quoted amount and confirm the transaction

### Returns and refund reconciliation

Support teams need refunds that match the original transaction exactly. The Orders API reads an order's transactions and generates a refund quote before the refund, so an agent can reconcile what was charged against what is being returned and issue a precise partial or full refund without overpaying.

Example prompt: Read an order's transactions, create a refund quote for one line item, and issue the partial refund

### Order settings and metadata automation

Multi-channel stores need order behavior configured per channel and extra data attached to orders. The API manages global and per-channel order settings and stores order metafields, so an agent can apply a channel's settings and tag orders with structured attributes that downstream systems read.

Example prompt: Update the order settings for a sales channel and attach a fulfillment-priority metafield to an order

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/orders/{order_id}/payment_actions/capture` | Capture an order payment |
| POST | `/orders/{order_id}/payment_actions/void` | Void an order payment |
| GET | `/orders/{order_id}/transactions` | Get an order's transactions |
| POST | `/orders/{order_id}/payment_actions/refund_quotes` | Create a refund quote |
| POST | `/orders/{order_id}/payment_actions/refunds` | Create a refund |
| GET | `/orders/{order_id}/payment_actions/refunds` | Get refunds for an order |
| GET | `/orders/settings` | Get global order settings |
| POST | `/orders/{order_id}/metafields` | Create order metafields |

## Key resources

- **Payment actions** — Capture and void authorized payments on an order
- **Refunds** — Refund quotes and refunds against an order
- **Transactions** — Payment transactions recorded against an order
- **Order settings** — Global and per-channel order settings
- **Order metafields** — Structured extra data stored against orders

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 67 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 68 / 100
  - Developer Experience & Jentic Compatibility: 67 / 100
  - AI-Readiness & Agent Experience: 60 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 69 / 100
- **View full report:** https://jentic.com/apis/bigcommerce.com/bigcommerce-orders-api/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the BigCommerce Orders API by hand means creating a store API account, scoping its X-Auth-Token to transaction permissions, and substituting your store hash into every request path. Through Jentic you install once, import it from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The order id travels in the URL path (`/orders/{order_id}/...`), so a rule can pin your agent to one order, or allow a chosen set of operations. You choose the operations it may call, so payment capture and refunds are not included unless you add them.
- **Credential handling:** Your BigCommerce store token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'capture an order payment' or 'issue a refund', and Jentic returns the matching Orders operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **Cratejoy** — Cratejoy manages subscription-box orders and their lifecycle rather than BigCommerce orders.
- **Lightspeed** — Lightspeed handles retail and POS orders for Lightspeed-run stores.
- **Stripe** — Stripe is the payment processor behind the captures and refunds this API triggers.

## FAQ

### What authentication does the BigCommerce Orders API use?

The BigCommerce Orders API authenticates with a store API account token sent in the X-Auth-Token header, as declared in its OpenAPI spec, scoped by the transaction and order permissions granted to that token. Through Jentic the token is stored encrypted by your own Jentic One instance and injected when a call runs, so it never reaches the agent's prompt or logs.

### Can I issue a partial refund with this API?

Yes. The Orders API creates a refund quote that breaks down the refundable amount, then issues a refund against the order for the quoted figure, so an agent can refund a single line item rather than the whole order.

### What are the rate limits for the BigCommerce Orders API?

The OpenAPI spec does not state rate limits. BigCommerce enforces per-plan API quotas documented on its developer portal at developer.bigcommerce.com, so check there before processing captures or refunds in bulk.

### Is there a BigCommerce Orders MCP server?

You do not need an MCP server to give your agent the BigCommerce Orders API. Jentic connects it directly from the API Directory: import it, store your store token once, and your agent captures payments and issues refunds on demand.

### Can I limit what my agent is allowed to do with the BigCommerce Orders API?

Yes. The order id travels in the URL path, so a rule can pin the agent to one order, or you can allow only the read operations so the agent can inspect transactions and refunds but cannot capture payments or issue refunds, with every call logged.

### How do I issue a refund with this API through Jentic?

Search Jentic for an intent like 'refund a BigCommerce order' and it returns the matching operation with its input schema, then your agent calls it with the store token Jentic injects at runtime. To run it on your own infrastructure, install Jentic One from its GitHub repo.