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.
Refunding an order consists of two API requests.
The example requests in this article use an order with the following properties:
$10.00$0.83$10.00The 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.
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.
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.ids, make a request to get all orders.Use the provider_id, the amount, and items from the refund quote to create a refund.
To refund a tax-exempt custom amount at the order level, set item_type to ORDER and specify the amount to refund.
To refund shipping or handling, set item_type to SHIPPING or HANDLING and specify the amount to refund.
To refund a product or gift wrapping, set item_type to PRODUCT or GIFT_WRAPPING and specify the quantity to refund.
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.
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 to change the inventory.