Order Refund API: Automate Refunds in BigCommerce
We are excited to announce the public availability of the Order Refund API, enabling developers to build applications that can process refunds against BigCommerce orders. These endpoints have the potential to save merchants time and reduce errors when processing refunds. They enable BigCommerce Partners to build solutions that embed refund functionality directly into their applications. Merchants will no longer need to process refunds manually via the BigCommerce Control Panel.
Developers can use the Order Refund API to:
- Export a list of past refunds to external systems
- Submit refunds via an order management system or ERP
- Extend the functionality of refunds-related third-party solutions (e.g. returns solutions)
We launched the Order Refund API to provide BigCommerce merchants, and the developers who empower them, the ability to programmatically and conveniently perform refunds.
Order Refund API endpoints
The Order Refund API consists of four endpoints. The first two endpoints unlock the ability to process refunds on a single order. The remaining two endpoints enable applications to get a list of past refunds.
- /orders/{id}/payment_actions/refund_quotes, POST — Create refund quote for order ID {id}
- /orders/{id}/payment_actions/refunds, POST Create a refund for order ID {id}
- /orders/{id}/payment_actions/refunds, GET — Returns the refunds for order ID {id}
- /orders/payment_actions/refunds, GET — Returns a list of refunds ordered by refund ID
What types of refunds are supported?
The Order Refund API supports two types of refund:
- Line-item refunds
- Order-level refunds
Line-item refunds
Line-item refunds enable applications to request refunds for specific quantities of items in a single order (demonstrated in the example further down). Because the quantity of items being refunded can be lower than the total quantity of items in the order, it’s possible to submit several line-item refunds for a single order.
In addition, when a line-item refund is processed, tax will be recalculated to ensure the most up-to-date tax rates are used for the refund.
Order-level refunds
Order-level refunds enable applications to refund an arbitrary amount from the total refundable order amount.
This type of refund is useful when refunding items by whole quantities is insufficient. For example, you can use an order-level refund when refunding the value of an item minus any return shipping or cleaning costs.
In this scenario, tax is not re-calculated during the refund quote as the refund occurs against the total refundable order amount, not any one particular line item.
What are the supported refund methods?
When it comes to providing refunds, the Order Refund API supports the following three refund methods.
Refunds via supported payment providers
BigCommerce will pass a refund request to the corresponding payment provider for processing if provider_id in the refund request payload matches a provider_id returned in the refund quote.
Refund to BigCommerce store-credit
If “storecredit” is specified as the provider_id, BigCommerce will apply a BigCommerce store-credit for the amount specified against the customer account associated with the order.
Offline refunds
Payments collected outside BigCommerce can be marked as offline when creating a refund via the Order Refund API. This ensures the order data within BigCommerce is up-to-date with the refunds that have been performed externally.
How refunds work and an example
Performing a refund on an order consists of two POST requests:
- /orders/{id}/refund_quotes, to calculate amounts and get available payment methods
- /orders/{id}/refunds, to create the refund
This refund example uses 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.
To refund the cost, we will create a refund quote. Then, we will create a refund using information from the quote.
It’s worth mentioning, if you have multiple refunds to process for the same order, the refunds need to occur in a sequential manner. In other words, start by creating a refund quote / refund for the first refund before moving on to perform the same actions for the second refund.
Get Refund Quote
A refund quote provides the tax amount, total refund amount, and a list of available payment methods for order refunds.
Request
{“items”: [{“item_type”: “PRODUCT”,“item_id”: 8,“quantity”: 1,“reason”: “Testing the Refund API!”},{“item_type”: “SHIPPING”,“item_id”: 9,“amount”: 10,“reason”: “Testing the Refund API!”}]}
The item_id used in the request is the Order Product id obtained by sending a GET request to the List Order Products endpoint.
Response
{“data”: {“total_refund_amount”: 20.83,“total_refund_tax_amount”: 0.83,“rounding”: 0,“adjustment”: 0,“is_tax_included”: true,“order_level_refund_amount”: 0,“refund_methods”: [[{“provider_id”: “braintree”,“provider_description”: “Braintree”,“amount”: 20.83,“offline”: false,“offline_provider”: false,“offline_reason”: “”}]},“meta”: {}}
Create the Refund
Use the provider_id, the amount and items from the refund quote, to create the refund:
Request
{“items”: [{“item_id”: 8,“item_type”: “PRODUCT”,“quantity”: 1},{“item_id”: 9,“item_type”: “SHIPPING”,“amount”: 10}],“payments”: [{“provider_id”: “braintree”,“amount”: 20.83,“offline”: false}]}
Response
{“data”: {“id”: 1,“order_id”: 21,“user_id”: 0,“created”: “”,“reason”: “”,“total_amount”: 20.83,“total_tax”: 0.83,“items”: [{“item_type”: “PRODUCT”,“item_id”: 8,“reason”: “”,“quantity”: 1,“requested_amount”: 10},{“item_type”: “SHIPPING”,“item_id”: 9,“reason”: “”,“requested_amount”: 10}],“payments”: [{“id”: 1,“provider_id”: “braintree”,“amount”: 20.83,“offline”: false,“is_declined”: false,“declined_message”: “”}]},“meta”: {}}
Conclusion
We’re constantly striving to provide merchants with efficient solutions that increase convenience, save time, and reduce errors. When it comes to processing refunds, the Order Refund API is closely aligned with these goals. We’ve been very pleased with adoption to date, and we’re excited to see how the developer community incorporates this new API into the solutions they build for BigCommerce merchants going forward.
Thank you to all the merchants and partners that helped us to test and enhance the Order Refund API during the beta.
Visit our Payment Actions developer documentation for an in-depth overview and let us know how you plan to use the Order Refund API by commenting below.
