> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Create Refund POST https://api.bigcommerce.com/stores/{store_hash}/v3/orders/{order_id}/payment_actions/refunds Content-Type: application/json Creates a refund. When there are no payment method validation issues, the refund process is successful and the refund payment request is scheduled. The payment request itself occurs asynchronously. Requires at least one of the following scopes: * `store_v2_orders` * `store_v2_transactions` **Note:** Order refunds should be processed sequentially. Processing multiple concurrent refunds on the same order are not yet supported. Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/order-operations/payment-actions/create-order-refund ## Authentication - `X-Auth-Token` header (required) — ### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Order Transactions | read and modify `transactions` and `payment_methods` | `store_v2_transactions` | | Order Transactions | read `transactions` and `payment_methods` | `store_v2_transactions_read_only` | | Orders | read and modify `payment_methods` |`store_v2_orders`| | Orders | read `payment_methods` |`store_v2_orders_read_only`| ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes). ## Request ### Path parameters - `order_id` (integer, required) — The ID of the `Order` to which the transactions belong. - `store_hash` (string, required) — Permanent ID of the BigCommerce store. ### Query parameters - `transaction_id` (string, optional) — Filters by refund payment using the BigCommerce `transaction_id`. ### Headers - `Accept` (string, required, default: application/json) — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body. ### Body (application/json) This endpoint expects a RefundRequest_Post. - `RefundRequest_Post` ## Response ### 200 The requested refund. - `data` (Refund, optional) - `meta` (metaEmpty_Full, optional) — Response metadata. ## Errors ### 422 Unprocessable Entity Error Unable to process a guest refund with store credit. - `data` (list of ErrorResponse, optional) ### 503 Service Unavailable Error Service Unavailable - `data` (list of FailedQuoteError, optional) - `meta` (Meta, optional) ## Types ### RefundRequest_Post_Items - `items` (list of ItemsRefund, required) - `payments` (list of PaymentRequest, required) - `merchant_calculated_override` (MerchantOverride, optional) — Merchant explicitly provided override based on their own calculation. This override gives merchants the flexibility to - bypass any tax correction due to tax rate/providers changes between when a customer places an order and a merchant initiates a refund - use explicit values calculated by external systems (e.g., merchants' own Extended Producer Responsibility or Order Management System) When using this when submitting refunds, please update the amount in payments section of the request payload to match the override value. Note: when using the override, BC internal tax based refund calculation is skipped and therefore order/taxes records are not updated. ### RefundRequest_Post_TaxAdjustmentAmount - `tax_adjustment_amount` (float, required) — Amount to be used when tax may have been overcharged for an order, such as when the value for a partial refund is overridden. This amount should be equal to the calculated overcharged value, or should be used with `merchant_calculated_override` to override the value. If not, this will result in a `422` error. - `merchant_calculated_override` (MerchantOverride, optional) — Merchant explicitly provided override based on their own calculation. This override gives merchants the flexibility to - bypass any tax correction due to tax rate/providers changes between when a customer places an order and a merchant initiates a refund - use explicit values calculated by external systems (e.g., merchants' own Extended Producer Responsibility or Order Management System) When using this when submitting refunds, please update the amount in payments section of the request payload to match the override value. Note: when using the override, BC internal tax based refund calculation is skipped and therefore order/taxes records are not updated. ### Refund - `id` (integer, optional) — Refund resource ID. - `order_id` (integer, optional) — Reference to order ID. - `user_id` (integer, optional) — Reference to the userʼs ID who create this refund. This is automatically populated by BigCommerce. - `created` (datetime, optional) — Timestamp of when this refund was created. - `reason` (string, optional) — Reason for refund. - `total_amount` (float, optional) — A non-negative 2 decimal place rounded value that represents the amount that can be charged/refunded with payment providers. When creating refunds and refund quotes, this field becomes irrelevant when you select PRODUCT or GIFT_WRAPPING for `item_type`. - `total_tax` (double, optional) — Total tax amount refunded back to the shopper. Note: `order_level_amount` does not affect tax liability. This can be a negative amount indicating we have collected tax by refunding less to the customer. - `uses_merchant_override_values` (boolean, optional) — Whether refund amount and tax are provided explicitly by merchant override. - `items` (list of RefundItem, optional) — Array of items refunded. In cases when `tax_refund_adjustment` was used to create the refund, this array will be empty. - `payments` (list of RefundPayment, optional) — An array of refund payments made to payment providers. ### metaEmpty_Full Response metadata. ### ErrorResponse - `errors` (ErrorResponseErrors, optional) - `status` (integer, optional) — The HTTP status code. - `title` (string, optional) — The error title describing the particular error. - `type` (string, optional) ### FailedQuoteError Failed quote response. - `order_id` (integer, optional) - `status` (integer, optional) — HTTP status code. - `error` (string, optional) — Details why the request failed. ### Meta - `meta` (MetaMeta, optional) — Data about the response, including pagination and collection totals. ### ItemsRefund ### PaymentRequest - `provider_id` (string, optional) — Reference to payment provider. - `amount` (double, optional) — Amount refunded with this provider. - `offline` (boolean, optional) — Whether the payment was marked as offline or performed through an online payment service. ### MerchantOverride Merchant explicitly provided override based on their own calculation. This override gives merchants the flexibility to - bypass any tax correction due to tax rate/providers changes between when a customer places an order and a merchant initiates a refund - use explicit values calculated by external systems (e.g., merchants' own Extended Producer Responsibility or Order Management System) When using this when submitting refunds, please update the amount in payments section of the request payload to match the override value. Note: when using the override, BC internal tax based refund calculation is skipped and therefore order/taxes records are not updated. - `total_amount` (float, required) — A non-negative 2 decimal place rounded value that represents the amount that to be used as override for the refund. - `total_tax` (double, required) — Total tax amount refunded back to the shopper. Use 0 value if there is no tax liability change for the refund or tax does not need to be recorded on the refund and would be handled externally. ### RefundItem - `item_type` (enum, optional) — Type of item that was refunded. - Allowed values: `PRODUCT`, `GIFT_WRAPPING`, `SHIPPING`, `HANDLING`, `ORDER`, `FEE` - `item_id` (integer, optional) — order_product.id corresponding to the item_types of PRODUCT, GIFT_WRAPPING. order_address.id corresponding to the item_types of SHIPPING, HANDLING. order.id corresponding to the item_type of ORDER. - `reason` (string, optional) — Reason for refunding an item. - `quantity` (integer, optional) — Quantity of item refunded. Note: this will only be populated for item_type PRODUCT - `adjustments` (list of RefundItemAdjustment, optional) — Adjustments to apply to the refunded amount for an item. Only supported for item_type PRODUCT - `requested_amount` (float, optional) — A non-negative 2 decimal place rounded value that represents the amount that can be charged/refunded with payment providers. When creating refunds and refund quotes, this field becomes irrelevant when you select PRODUCT or GIFT_WRAPPING for `item_type`. ### RefundPayment - `id` (integer, optional) — Reference to refund payment ID. - `provider_id` (string, optional) — Reference to payment provider. - `amount` (float, optional) — A non-negative 2 decimal place rounded value that represents the amount that can be charged/refunded with payment providers. When creating refunds and refund quotes, this field becomes irrelevant when you select PRODUCT or GIFT_WRAPPING for `item_type`. - `offline` (boolean, optional) — Indicate whether payment was offline. - `is_declined` (boolean, optional) — Indicate if this payment has been declined by payment provider. - `declined_message` (string, optional) — Message indicate why payment was declined. - `transaction_id` (string, optional) — The BigCommerce `transaction_id`. ### ErrorResponseErrors ### MetaMeta Data about the response, including pagination and collection totals. - `total` (integer, optional) — Total number of items in the result set. - `count` (integer, optional) — Total number of items in the collection response. - `per_page` (integer, optional) — The amount of items returned in the collection per page, controlled by the limit parameter. - `current_page` (integer, optional) — The page you are currently on within the collection. - `total_pages` (integer, optional) — The total number of pages in the collection. - `links` (MetaMetaLinks, optional) — Pagination links for the previous and next parts of the whole collection. ### QuantityBoundItem Quantity Bound Item Type of refund item that capture refunding of items in the order that are of type quantity. * `PRODUCT` * `GIFT_WRAPPING` - `item_type` (enum, required) — Type of refund. - Allowed values: `PRODUCT`, `GIFT_WRAPPING` - `item_id` (integer, required) — Order Product ID. - `quantity` (integer, required) - `adjustments` (list of RefundItemAdjustment, optional) — Array of product refund deductions - `reason` (string, optional) — Reason for refund. ### AmountBoundItem Amount Bound Item Type of refund item that capture refunding of items in the order that are of type amount. * `ORDER` * `SHIPPING` * `HANDLING` * `TAX` * `FEE` - `item_type` (enum, required) — Type of refund. - Allowed values: `ORDER`, `SHIPPING`, `HANDLING`, `TAX`, `FEE` - `item_id` (integer, required) — Order address ID. - `amount` (float, required) — A non-negative 2 decimal place rounded value that represents the amount that can be charged/refunded with payment providers. When creating refunds and refund quotes, this field becomes irrelevant when you select PRODUCT or GIFT_WRAPPING for `item_type`. - `reason` (string, optional) — Explanation of refund. ### TaxExemptItem Use this to refund a custom value at the order level. When `item_type` is set to `ORDER`, tax is not re-calculated. - `item_type` (enum, optional) — The type of refund. When `item_type` is set to `ORDER`, tax is not re-calculated. - Allowed values: `ORDER` - `item_id` (double, optional) — Numeric ID of the product in the order. - `amount` (float, optional) — A non-negative 2 decimal place rounded value that represents the amount that can be charged/refunded with payment providers. When creating refunds and refund quotes, this field becomes irrelevant when you select PRODUCT or GIFT_WRAPPING for `item_type`. - `reason` (string, optional) — Reason for the refund. ### FeeItem Use this field to refund a custom fee at the order level. - `item_type` (enum, optional) — The type of refund. - Allowed values: `FEE` - `item_id` (double, optional) — Numeric ID of the fee in the order. - `amount` (float, optional) — A non-negative 2 decimal place rounded value that represents the amount that can be charged/refunded with payment providers. When creating refunds and refund quotes, this field becomes irrelevant when you select PRODUCT or GIFT_WRAPPING for `item_type`. - `reason` (string, optional) — Reason for the refund. ### RefundItemAdjustment Use to reduce the amount refunded for an item. - `amount` (float, optional) — A negative 2 decimal place rounded value to deduct from the amount refunded. - `description` (string, optional) — Description of reason for the adjustment. ### MetaMetaLinks Pagination links for the previous and next parts of the whole collection. - `previous` (string, optional) — Link to the previous page returned in the response. - `current` (string, optional) — Link to the current page returned in the response. - `next` (string, optional) — Link to the next page returned in the response. ## Examples **Request** ```json { "tax_adjustment_amount": 1.99 } ``` **Response** ```json { "data": { "id": 1, "order_id": 1, "user_id": 1, "created": "2024-01-15T09:30:00Z", "reason": "string", "total_amount": 1.99, "total_tax": 1.1, "uses_merchant_override_values": true, "items": [ { "item_type": "PRODUCT", "item_id": 1, "reason": "string", "quantity": 1, "adjustments": [ { "amount": -10.2, "description": "Service fee" } ], "requested_amount": 1.99 } ], "payments": [ { "id": 1, "provider_id": "storecredit", "amount": 1.99, "offline": true, "is_declined": true, "declined_message": "string", "transaction_id": "1234" } ] }, "meta": {} } ``` **SDK Code** ```python import requests url = "https://api.bigcommerce.com/stores/store_hash/v3/orders/1/payment_actions/refunds" payload = { "tax_adjustment_amount": 1.99 } headers = { "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.bigcommerce.com/stores/store_hash/v3/orders/1/payment_actions/refunds'; const options = { method: 'POST', headers: { Accept: 'application/json', 'X-Auth-Token': '', 'Content-Type': 'application/json' }, body: '{"tax_adjustment_amount":1.99}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.bigcommerce.com/stores/store_hash/v3/orders/1/payment_actions/refunds" payload := strings.NewReader("{\n \"tax_adjustment_amount\": 1.99\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Accept", "application/json") req.Header.Add("X-Auth-Token", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/stores/store_hash/v3/orders/1/payment_actions/refunds") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Accept"] = 'application/json' request["X-Auth-Token"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"tax_adjustment_amount\": 1.99\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.bigcommerce.com/stores/store_hash/v3/orders/1/payment_actions/refunds") .header("Accept", "application/json") .header("X-Auth-Token", "") .header("Content-Type", "application/json") .body("{\n \"tax_adjustment_amount\": 1.99\n}") .asString(); ``` ```php request('POST', 'https://api.bigcommerce.com/stores/store_hash/v3/orders/1/payment_actions/refunds', [ 'body' => '{ "tax_adjustment_amount": 1.99 }', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/orders/1/payment_actions/refunds"); var request = new RestRequest(Method.POST); request.AddHeader("Accept", "application/json"); request.AddHeader("X-Auth-Token", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"tax_adjustment_amount\": 1.99\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" ] let parameters = ["tax_adjustment_amount": 1.99] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/orders/1/payment_actions/refunds")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```