Order Refunds

Order V3 exposes endpoints for creating refunds against orders with settled payments. These endpoints are useful when building order management or payment integrations as they make embedding refund functionality directly into the application possible without requiring merchants to return to their BigCommerce control panel.

This article provides an overview of Order's V3 refund capabilities and includes a step-by-step example for creating a single order refund.

Single order refund example

Refunding an order consists of two API requests.

Request	Operation	Endpoint	Description
1	`POST`	`/v3/orders/{id}/payment_actions/refund_quotes`	Calculate amounts and get payment methods
2	`POST`	`/v3/orders/{id}/payment_actions/refund`	Create the refund

The example requests in this article use an order with the following properties:

Products: Single product priced at $10.00
Tax: $0.83
Shipping: $10.00

The refunded amount will include the shipping, tax, and product cost (a total of $20.83). We will create a refund quote. Then, we will create a refund using the information contained in the create refund quote response.

Creating refund quotes

A refund quote provides the tax amount, total refund amount, and a list of available payment methods for order refunds.

To create a refund quote, send a POST request to /v3/orders/{order_id}/payment_actions/refund_quotes.

Example request: Create a refund quote

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/orders/{order_id}/payment_actions/refund_quotes
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "items": [
    {
      "item_type": "PRODUCT",  // Refund a product
      "item_id": 8,            // Order product ID
      "quantity": 1,           // Quantity to refund
    },
    {
      "item_type": "SHIPPING", // Refund shipping
      "item_id": 9,            // Order address ID
      "amount": 10,            // Amount to refund
    },
    {
      "item_type": "ORDER",    // Tax-exempt order level refund
      "item_id": 9,            // Order ID
      "amount": 1,             // Amount to refund
    },
    {
      "item_type": "FEE",     // Refund a fee
      "item_id": 11,          // Fee ID
      "amount": 1,            // Amount to refund
    }
  ]
}

To get an item_id, make a GET request to v2/orders/{order_id}/products. The returned id value is the item_id needed to create a PRODUCT refund quote. The returned order_address_id value is the item_id needed to create a SHIPPING refund quote. To read more about using the v2/orders/{order_id}/products endpoint, visit List Order Products.
To get a list of orders and their ids, make a request to get all orders.

Creating a refund

Use the provider_id, the amount, and items from the refund quote to create a refund.

Example request: Create a refund

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/orders/{order_id}/payment_actions/refunds
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "items": [
    {
      "item_type": "PRODUCT",  // Refund a product
      "item_id": 8,            // Order product ID
      "quantity": 1            // Quantity to refund
    },
    {
      "item_type": "SHIPPING", // Refund shipping
      "item_id": 9,            // Order address ID
      "amount": 10             // Amount to refund
    },
    {
      "item_type": "ORDER",   // Tax-exempt order level refund
      "item_id": 123,         // Order ID
      "amount": 1,            // Amount to refund
    },
    {
      "item_type": "FEE",     // Refund a fee
      "item_id": 11,          // Fee ID
      "amount": 1,            // Amount to refund
    }
  ],
  "payments": [
    {
      "provider_id": "braintree",
      "amount": 21.83,
      "offline": false
    }
  ]
}

Creating order level refunds

To refund a tax-exempt custom amount at the order level, set item_type to ORDER and specify the amount to refund.

Example request: Create a refund

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/orders/{order_id}/payment_actions/refunds
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "order_id": 1234,
  "items": [
    {
      "item_type": "ORDER", // Refund a tax-exempt custom amount
      "item_id": 1234,      // Order ID
      "amount": 1,          // Amount to refund
    }
  ],
  "payments": [...]
}

Refunding shipping and handling

To refund shipping or handling, set item_type to SHIPPING or HANDLING and specify the amount to refund.

Example request: Create a refund

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/orders/{order_id}/payment_actions/refunds
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "order_id": 1234,
  "items": [
    {
      "item_type": "SHIPPING", // Refund shipping
      "item_id": 456,          // Order address ID
      "amount": 1,             // Amount to refund
    }
  ],
  "payments": [...]
}

Refunding products and gift wrapping

To refund a product or gift wrapping, set item_type to PRODUCT or GIFT_WRAPPING and specify the quantity to refund.

Example request: Create a refund

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/orders/{order_id}/payment_actions/refunds
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "order_id": 1234,
  "items": [
    {
      "item_type": "PRODUCT",       // Refund a product
      "item_id": 1234,              // Order product ID
      "quantity": 1,                // Quantity to refund
    },
    {
      "item_type": "GIFT_WRAPPING", // Refund gift wrapping
      "item_id": 1234,              // Order product ID
      "quantity": 1,                // Quantity to refund
    }
  ],
  "payments": [...]
}

Offline order refunds

Payments collected outside of BigCommerce can be marked as offline when creating a refund. Marking payments as offline is a way to keep track of which portions of an order you refunded. However, no funds were collected. If you did not receive payment using BigCommerce, then the funds can not be refunded directly to the payment source using BigCommerce's refund endpoints.

FAQ

Is it possible to create a refund without using an item from the order?

Yes. Set item_type to ORDER and specify an amount to refund. For more information, see create order level refunds.

Can I just skip creating the quote and go straight to processing a refund?

It is possible to process a refund without creating a quote first. Quotes serve to make sure you are refunding to the correct payment provider in the correct amount.

Where do I find the item_id?

Use the V2 Orders Endpoint to get the required ID:

PRODUCT -- Order Product ID
GIFT_WRAPPING -- Order Product ID
SHIPPING -- Order Address ID
HANDLING -- Order Address ID
ORDER -- Order ID

Will this trigger an email to the shopper?

Yes, if you configure the store to send an email when an order status changes to Refunded or Partially Refunded.

How do I get a list of provider_ids?

The POST Refund Quote exposes provider_ids.

Will a refunded item be returned to inventory?

No, you cannot return items to inventory that you refunded via API. You can either update the inventory directly on the product's page or use the Control Panel (opens in a new tab) to change the inventory.

Troubleshooting

You must receive payment of the order before you can issue a refund.
If you use a payment gateway, it must support refunds. For a list of payment gateways that support refunds through BigCommerce, see the Supported Payment Gateways section in Processing Refunds (opens in a new tab).
If you use a payment gateway, you must settle payments. Some gateways require a certain amount of time to pass before you can process refunds.

Order Refunds

Single order refund example

Creating refund quotes

Creating a refund

Creating order level refunds

Refunding shipping and handling

Refunding products and gift wrapping

Offline order refunds

FAQ

Troubleshooting

Related resources

Articles

Endpoints