# Cancellation and Refund API
Use the cancellation and refund API to initiate cancellations or refunds on a given order.
## Cancel Order {#cancel_order}
You can only cancel an order or items (unshipped) fully or partially.
**Warning:** Orders can be canceled after they are moved out of the `FB_PROCESSING` state, with an exception of orders in the `FB_PROCESSING` state for more than 24 hours. An order can be in the `FB_PROCESSING` state for that long due to: 1) the inability to complete the buyer risk check or 2) a sanction on the buyer's account.
```html
curl -X POST \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<ORDER_ID>/cancellations
```
### Request
| Attribute | Description |
| --- | --- |
| `cancel_reason`<br><br>Type: [`cancel_reason`](#cancel_reason) | **Optional**<br><br>Why the seller is canceling the order; for example, out of stock. |
| `restock_items`<br><br>Type: boolean | **Optional**<br><br>By default, the value is `false`. A seller can set this value to `true` to be added back to the inventory. |
| `items`<br><br>Type: array of [`items`](#cancel_item) | **Optional**<br><br>Array of items being canceled. |
| `idempotency_key`<br><br>Type: string | **Required**<br><br>Unique key per request. |
### `cancel_reason` object {#cancel_reason}
| Attribute | Description |
| --- | --- |
| `reason_code`<br><br>Type: [`reason_code`](#reason_code) | **Optional**<br><br>Reason for the cancellation. |
| `reason_description `<br><br>Type: string | **Optional**<br><br>Reason for the cancellation, this message may be presented to the user. |
### `items` {#cancel_item}
| Attribute | Description |
| --- | --- |
| `retailer_id`<br><br>Type: string | **Required if `item_id` is not provided**.<br><br>ID representing the product in the seller's catalog. You must provide `retailer_id` or `item_id`, but not both. If `item_id` is provided, `retailer_id` must not be provided. |
| `item_id`<br><br>Type: string | **Required if `retailer_id` is not provided**.<br><br>A Meta-generated ID representing the line item on the order. This value is readable as the `id` field of the [`item`](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/order-api#item) response. You must provide `retailer_id` or `item_id`, but not both. If `retailer_id` is provided, `item_id` must not be provided. |
| `quantity`<br><br>Type: number | **Required**<br><br>Number of items canceled. |
### `reason_code` enum {#reason_code}
| Value | Description |
| --- | --- |
| `CUSTOMER_REQUESTED` | Cancellation requested by the buyer. |
| `OUT_OF_STOCK` | Product is out of stock at fulfillment. |
| `INVALID_ADDRESS` | Unable to ship to address provided by the buyer. |
| `SUSPICIOUS_ORDER` | Order is suspicious/possible fraud. |
| `CANCEL_REASON_OTHER` | Other cancellation reason. |
#### Sample Request (Full Order) {#cancel_full_order}
```json
{
"cancel_reason": {
"reason_code": "CUSTOMER_REQUESTED",
"reason_description": "Buyer did not need it anymore"
},
"restock_items": true,
"idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}
```
#### Sample Request (Partial Order) {#cancel_partial_order}
```json
{
"cancel_reason": {
"reason_code": "OUT_OF_STOCK",
"reason_description": "Ran out of item"
},
"restock_items": false,
"items": [
{
"retailer_id": "FB_product_1234",
"quantity": 1
}
],
"idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}
```
#### Sample Response
If successful:
```
{
"success": true
}
```
Otherwise, a relevant error message is returned.
## Refund Order {#refund_order}
You can only refund an order or items (shipped), fully or partially (by quantity or price).
```html
curl -X POST \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<ORDER_ID>/refunds
```
### Request
| Attribute | Description |
| --- | --- |
| `items`<br><br>Type: array of [`refund_item`](#refund_item) | **Optional**<br><br>For partial refund, specify the item-level breakdown. Not required for a full refund. |
| `reason_code`<br><br>Type: [`refund_reason_code`](#refund_reason_code) | **Required**<br><br>Reason for the refund. |
| `reason_text`<br><br>Type: string | **Optional**<br><br>Reason for the refund. This message is presented to the user. |
| `idempotency_key`<br><br>Type: string | **Required**<br><br>Unique key per request. |
| `shipping`<br><br>Type: [`shipping_refund`](#shipping_refund) object | **Optional**<br><br>Amount to be refunded for shipping. |
| `deductions`<br><br>Type: array of [`deductions`](#deductions) object | **Optional**<br><br>Amount to be deducted off of the refund. Commonly used for a return label fee for order returns. |
| `return_id`<br><br>Type: string | **Optional**<br><br>ID representing the return to which the refund is associated. See [Returns API](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/returns-api) |
### `deductions` object {#deductions}
| Attribute | Description |
| --- | --- |
| `deduction_type`<br><br>Type: string | **Required**<br><br>Currently `RETURN_SHIPPING` is the only allowed type. |
| `deduction_amount`<br><br>Type: [`currency_amount`](#currency_amount) | **Required**<br><br>Amount to be deducted for shipping. See [`currency_amount`](#currency_amount). |
### `shipping_refund` object {#shipping_refund}
| Attribute | Description |
| --- | --- |
| `shipping_refund`<br><br>Type: [`currency_amount`](#currency_amount) | **Required**<br><br>Amount to be refunded for shipping. See [`currency_amount`](#currency_amount). |
### `refund_item` object {#refund_item}
| Attribute | Description |
| --- | --- |
| `retailer_id`<br><br>Type: string | **Required if `item_id` is not provided**.<br><br>ID representing the product in the seller's catalog. You must provide `retailer_id` or `item_id`, but not both. If `item_id` is provided, `retailer_id` must not be provided. |
| `item_id`<br><br>Type: string | **Required if `retailer_id` is not provided**.<br><br>A Meta-generated ID representing the line item on the order. This value is readable as the `id` field of the [`item`](https://developers.facebook.com/documentation/ads-commerce/commerce-platform/order-management/order-api#item) response. You must provide `retailer_id` or `item_id`, but not both. If `retailer_id` is provided, `item_id` must not be provided. |
| `item_refund_amount`<br><br>Type: [`currency_amount`](#currency_amount) | **Required if `item_refund_quantity` is not provided**. <br><br>Amount to refund, before any tax. Can be any value up to the full value of the item. See [`currency_amount`](#currency_amount). |
| `item_refund_quantity`<br><br>Type: number | **Required if `item_refund_amount` is not provided**.<br><br>Number of items to be refunded fully. |
### `currency_amount` object {#currency_amount}
| Attribute | Description |
| --- | --- |
| `amount`<br><br>Type: string | **Required**<br><br>Amount in decimal format. Example: `5.5` |
| `currency`<br><br>Type: string | **Required**<br><br>[Three digit ISO-4217-3 code](https://developers.facebook.com/documentation/ads-commerce/marketing-api/currencies) for the purchase. Format the currency as a number, followed by the 3-digit ISO currency code [(ISO 4217 standards)](https://en.wikipedia.org/wiki/ISO_4217), with a space between cost and currency.<br><br>Example: `30 USD` |
### `refund_reason_code` enum {#refund_reason_code}
| Value | Description |
| --- | --- |
| `BUYERS_REMORSE` | Refunded by buyers remorse. |
| `DAMAGED_GOODS` | Refunded as goods were delivered damaged. |
| `NOT_AS_DESCRIBED` | Product not as described. |
| `QUALITY_ISSUE` | Product had quality issues. |
| `REFUND_REASON_OTHER` | Other refund reason. |
| `WRONG_ITEM` | Wrong product delivered. |
| `FACEBOOK_INITIATED` | Refund issued by the Facebook support team, usually in response of a dispute with the buyer. |
#### Sample Request (Full Order)
```json
{
"reason_code": "WRONG_ITEM",
"idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}
```
#### Sample Request (Partial Order)
```json
{
"items": [
{
"retailer_id": "1234",
"item_refund_quantity": 1
},
{
"retailer_id": "38383838",
"item_refund_amount": {
"amount": "2.5",
"currency": "USD"
}
}
],
"shipping": {
"shipping_refund": {
"amount": "2.4",
"currency": "USD"
}
},
"deductions": [
{
"deduction_type": "RETURN_SHIPPING",
"deduction_amount": {
"amount": "5.5",
"currency": "USD"
}
}
],
"reason_code": "WRONG_ITEM",
"idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}
```
#### Response
If successful:
```json
{
"success": true
}
```
Otherwise, a relevant error message is returned.
If you received an error that this order couldn't be refunded until the customer's payment method had been charged, validate if [the payment was captured](https://developers.facebook.com/docs/commerce-platform/reporting/payments-and-promotions#transaction_detail_object).
## List Cancellations {#get_cancellations}
```html
curl -X GET -G \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<ORDER_ID>/cancellations
```
### Response
If successful:
```json
{
"data": [
{
"id": "412737486183265",
"items": {
"data": [
{
"id": "32121321312",
"product_id": "2082596341811586",
"retailer_id": "FB_product_1234",
"quantity": 1
}
]
},
"cancel_reason": {
"reason_code": "CUSTOMER_REQUESTED",
"reason_description": "Buyer did not need it anymore"
}
}
]
}
```
## List Refunds {#get_refunds}
```html
curl -X GET -G \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<ORDER_ID>/refunds
```
### Response
| Attribute and Type |
| --- |
| `data`<br><br>Type: array of [`refund_item_object`](#refund_item_object) |
### `refund_item_object` {#refund_item_object}
| Attribute | Description | Default Display |
| --- | --- | --- |
| `id`<br><br>Type: string | Refund unique ID. | Yes |
| `items`<br><br>Type: [`items`](#items) | Array of refunded items. | Yes |
| `refund_amount`<br><br>Type: [`refund_amount`](#refund_amount) | Total refund amount. See [`refund_subtotal` object](#refund_subtotal). | Yes |
| `refund_reason`<br><br>Type: number | Reason for the refund. See [`refund_reason_code` enum](#refund_reason_code). | Yes |
### `items` object {#items}
| Attribute and Type |
| --- |
| `data`<br><br>Type: array of [`item`](#item) |
### `item` object {#item}
| Attribute | Description |
| --- | --- |
| `id`<br><br>Type: string | Unique ID for order item. |
| `product_id `<br><br>Type: string | Unique product ID. |
| `retailer_id `<br><br>Type: string | Unique product ID set by seller. |
| `refund_subtotal `<br><br>Type: object | Subtotal of refund. |
| `quantity`<br><br>Type: number | **Optional**<br><br>Item refund quantity, only present when refunding an order with [`item_refund_quantity`](#refund_item). |
### `refund_subtotal` object {#refund_subtotal}
| Attribute | Description | Default Display |
| --- | --- | --- |
| `amount`<br><br>Type: string | Amount in decimal format. Example: `1.64` | Yes |
| `currency`<br><br>Type: string | [Three digit ISO-4217-3 code](https://developers.facebook.com/documentation/ads-commerce/marketing-api/currencies) for the purchase.<br><br>Format the currency as a number, followed by the 3-digit ISO currency code [(ISO 4217 standards)](https://en.wikipedia.org/wiki/ISO_4217), with a space between cost and currency.<br><br>Example: `30 USD` | Yes |
### `refund_amount` object {#refund_amount}
| Attribute | Description | Default Display |
| --- | --- | --- |
| `amount`<br><br>Type: string | Amount in decimal format. Example: `1.64` | Yes |
| `currency`<br><br>Type: string | [Three digit ISO-4217-3 code](https://developers.facebook.com/documentation/ads-commerce/marketing-api/currencies) for the purchase.<br><br>Format the currency as a number, followed by the 3-digit ISO currency code [(ISO 4217 standards)](https://en.wikipedia.org/wiki/ISO_4217), with a space between cost and currency.<br><br>Example: `30 USD` | Yes |
| `tax`<br><br>Type: string | Amount in decimal format with negative sign. Example: `-0.14` | No |
| `shipping`<br><br>Type: string | Amount in decimal format with negative sign. Example: `-0.14` | No |
| `subtotal `<br><br>Type: string | Amount in decimal format. Example: `0.50` | No |
| `total`<br><br>Type: string | Amount in decimal format. Example: `1.64` | No |
#### Sample Request with All Fields
```html
curl GET \
-d 'fields=id,items{product_id,retailer_id,refund_subtotal,quantity},refund_reason,refund_amount{subtotal,tax,total,amount,currency}' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<ORDER_ID>/refunds
```
#### Sample Response
If successful:
```json
{
"data": [
{
"id": "498980194169539",
"items": {
"data": [
{
"id": "486602442073981",
"product_id": "2452389501475182",
"retailer_id": "FB_shirt_1234",
"refund_subtotal": {
"amount": "1.00",
"currency": "USD"
},
"quantity": 1
}
]
},
"refund_reason": {
"reason_code": "BUYERS_REMORSE"
},
"refund_amount": {
"subtotal": "1.00",
"shipping": "10.00",
"tax": "-1.02",
"total": "12.02",
"amount": "12.02",
"currency": "USD"
},
}
],
"paging": {
"cursors": {
"before": "QVFIUkdCNjRRQ2tpZAloxbFlZAMnZABN3pYcnB5TzZALYlAzTVo2eF8wM3BraFRRRWNLZAnJwczAtanA0VUE4WnB4dVZAQYUE3OTRZASTBMZAjBWYWxOZAGJJdm9vODRn",
"after": "QVFIUkdCNjRRQ2tpZAloxbFlZAMnZABN3pYcnB5TzZALYlAzTVo2eF8wM3BraFRRRWNLZAnJwczAtanA0VUE4WnB4dVZAQYUE3OTRZASTBMZAjBWYWxOZAGJJdm9vODRn"
}
}
}
```