> 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 Quote

POST https://api.bigcommerce.com/stores/{store_hash}/v3/orders/{order_id}/payment_actions/refund_quotes
Content-Type: application/json

Calculate the tax amount, total refund amount and get available payment options for an order refund by providing items and costs or quantities to refund.

Requires at least one of the following scopes:
* `store_v2_orders`
* `store_v2_transactions`   

**Notes:**
* Create a refund quote before performing a refund request to best avoid a `422` error. Check the refund quote's response body for the `refund_methods` array. The `amount` given in the array must match the `amount` used in the refund request body.
* Order refunds should be processed sequentially. Processing multiple concurrent refunds on the same order is not yet supported.

Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/order-operations/payment-actions/create-order-refund-quotes

## 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.

### 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 RefundQuote_Post.

- `RefundQuote_Post`

## Response

### 200

The requested refund quote.

- `data` (RefundQuote_Full, optional)
- `meta` (metaEmpty_Full, optional) — Response metadata.

## Errors

### 422 Unprocessable Entity Error

This occurs when missing or unacceptable data is passed for one or more fields. Please correct the values for the fields listed in the errors object.

- `errors` (ErrorResponseErrors, optional)
- `status` (integer, optional) — The HTTP status code.
- `title` (string, optional) — The error title describing the particular error.
- `type` (string, optional)

## Types

### RefundQuote_ItemsRefund

- `items` (list of ItemsRefund, required)

### RefundQuote_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.

### RefundQuote_Full

- `order_id` (integer, optional) — ID of the order to be refunded.
- `total_refund_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_refund_tax_amount` (double, optional)
- `order_level_refund_amount` (double, optional)
- `rounding` (double, optional) — Indicates rounding value to bring `refund_total` to an amount refundable with payment providers (in this case to 2 decimal places).
- `adjustment` (float, optional) — A negative or positive 2 decimal place rounded value that represents the difference between the refund amount requested in the refund quote and the actual amount that is refundable on the order. This value is negative when the refund amount requested in the refund quote is more than the total refundable amount. This value is positive when the total refundable amount has increased, e.g. as a result of rounding.
- `tax_inclusive` (boolean, optional) — Indicate if `total_refund_amount` includes tax amount.
- `refund_methods` (list of list of PaymentOption, optional) — An array of available refund methods. Note that `refund_methods` is an array of refund methods, with each refund method being an array of payment options. For example, if the order was placed by a combination of store credit and bank deposit the refund methods would be: ```json { "refund_methods": [ [ { "provider_id": "storecredit", "provider_description": "Store Credit", "amount": 119.35, "offline": false, "offline_provider": false, "offline_reason": "" } ], [ { "provider_id": "custom", "provider_description": "Custom", "amount": 119.35, "offline": true, "offline_provider": true, "offline_reason": "This is an offline payment provider." } ], [ { "provider_id": "bankdeposit", "provider_description": "Bank Deposit", "amount": 80.35, "offline": true, "offline_provider": true, "offline_reason": "This is an offline payment provider." }, { "provider_id": "storecredit", "provider_description": "Store Credit", "amount": 39, "offline": false, "offline_provider": false, "offline_reason": "" } ] ] } ``` In this case there are three refund methods available to the merchant: 1. Refund up to the entire order amount to store credit. 2. Mark an amount up to the full order amount as refunded externally, through a provider or means not represented directly in BC ("custom"). 3. Refund the amount paid by store credit to store credit, and the amount paid by bank deposit with a manual refund, which will be recorded as being refunded against the bank deposit.

### metaEmpty_Full

Response metadata.

### ErrorResponseErrors

### ItemsRefund

### PaymentOption

- `provider_id` (string, optional) — Name of the payment method.
- `provider_description` (string, optional) — Description for payment provider.
- `amount` (double, optional) — Amount to be refunded with this payment provider.
- `offline` (boolean, optional) — Indicates the payment must be done offline due to constraints of the payment provider, such as partial refunds not being supported, or it being offline only such as cash on delivery of bank deposit.
- `offline_provider` (boolean, optional) — Indicates if the payment provider is a strictly offline provider, such as cash on delivery or bank deposit.
- `offline_reason` (string, optional) — Reason the payment option is offline only, if applicable.

### 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.

## Examples

**Request**

```json
{
  "tax_adjustment_amount": 1.99
}
```

**Response**

```json
{
  "data": {
    "order_id": 1,
    "total_refund_amount": 1.99,
    "total_refund_tax_amount": 1.95,
    "order_level_refund_amount": 1.99,
    "rounding": 1.1,
    "adjustment": -10.2,
    "tax_inclusive": true,
    "refund_methods": [
      [
        {
          "provider_id": "checkout_paypalexpress",
          "provider_description": "Paypal Express",
          "amount": 9.99,
          "offline": true,
          "offline_provider": true,
          "offline_reason": "Multiple online refunds are not available"
        }
      ]
    ]
  },
  "meta": {}
}
```

**SDK Code**

```python
import requests

url = "https://api.bigcommerce.com/stores/store_hash/v3/orders/1/payment_actions/refund_quotes"

payload = { "tax_adjustment_amount": 1.99 }
headers = {
    "Accept": "application/json",
    "X-Auth-Token": "<apiKey>",
    "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/refund_quotes';
const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'X-Auth-Token': '<apiKey>',
    '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/refund_quotes"

	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", "<apiKey>")
	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/refund_quotes")

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"] = '<apiKey>'
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<String> response = Unirest.post("https://api.bigcommerce.com/stores/store_hash/v3/orders/1/payment_actions/refund_quotes")
  .header("Accept", "application/json")
  .header("X-Auth-Token", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tax_adjustment_amount\": 1.99\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.bigcommerce.com/stores/store_hash/v3/orders/1/payment_actions/refund_quotes', [
  'body' => '{
  "tax_adjustment_amount": 1.99
}',
  'headers' => [
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
    'X-Auth-Token' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/orders/1/payment_actions/refund_quotes");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "application/json");
request.AddHeader("X-Auth-Token", "<apiKey>");
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": "<apiKey>",
  "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/refund_quotes")! 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()
```