Facebook

Cancellation and Refund API - Commerce Platform - Documentation - Meta for Developers

Cancellation and Refund API

Use the cancellation and refund API to initiate cancellations or refunds on a given order.

Cancel Order

You can only cancel an order or items (unshipped) fully or partially.

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.

Graph API Explorer

 curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{order-id}/cancellations

 POST /{order-id}/cancellations HTTP/1.1
Host: graph.facebook.com

 /* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{order-id}/cancellations',
    array (),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

 /* make the API call */
FB.api(
    "/{order-id}/cancellations",
    "POST",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Request

Attribute Description

Attribute	Description
`cancel_reason` Type: `cancel_reason`	Optional Why the seller is canceling the order; for example, out of stock.
`restock_items` Type: boolean	Optional By default, the value is `false` . A seller can set this value to `true` to be added back to the inventory.
`items` Type: array of `items`	Optional Array of items being canceled.
`idempotency_key` Type: string	Required Unique key per request.

cancel_reason

Type: cancel_reason

Optional

Why the seller is canceling the order; for example, out of stock.

restock_items

Type: boolean

Optional

By default, the value is false . A seller can set this value to true to be added back to the inventory.

items

Type: array of items

Optional

Array of items being canceled.

idempotency_key

Type: string

Required

Unique key per request.

`cancel_reason` object

Attribute Description

Attribute	Description
`reason_code` Type: `reason_code`	Optional Reason for the cancellation.
`reason_description` Type: string	Optional Reason for the cancellation, this message may be presented to the user.

reason_code

Type: reason_code

Optional

Reason for the cancellation.

reason_description

Type: string

Optional

Reason for the cancellation, this message may be presented to the user.

`items`

Attribute Description

Attribute	Description
`retailer_id` Type: string	Required if `item_id` is not provided. 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` Type: string	Required if `retailer_id` is not provided. A Meta-generated ID representing the line item on the order. This value is readable as the `id` field of the `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` Type: number	Required Number of items canceled.

retailer_id

Type: string

Required if item_id is not provided.

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

Type: string

Required if retailer_id is not provided.

A Meta-generated ID representing the line item on the order. This value is readable as the id field of the 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

Type: number

Required

Number of items canceled.

`reason_code` enum

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

You can only refund an order or items (shipped), fully or partially (by quantity or price).

Graph API Explorer

 curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{order-id}/refunds

 POST /{order-id}/refunds HTTP/1.1
Host: graph.facebook.com

 /* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{order-id}/refunds',
    array (),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

 /* make the API call */
FB.api(
    "/{order-id}/refunds",
    "POST",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Request

Attribute Description

Attribute	Description
`items` Type: array of `refund_item`	Optional For partial refund, specify the item-level breakdown. Not required for a full refund.
`reason_code` Type: `refund_reason_code`	Required Reason for the refund.
`reason_text` Type: string	Optional Reason for the refund. This message is presented to the user.
`idempotency_key` Type: string	Required Unique key per request.
`shipping` Type: `shipping_refund` object	Optional Amount to be refunded for shipping.
`deductions` Type: array of `deductions` object	Optional Amount to be deducted off of the refund. Commonly used for a return label fee for order returns.
`return_id` Type: string	Optional ID representing the return to which the refund is associated. See Returns API

items

Type: array of refund_item

Optional

For partial refund, specify the item-level breakdown. Not required for a full refund.

reason_code

Type: refund_reason_code

Required

Reason for the refund.

reason_text

Type: string

Optional

Reason for the refund. This message is presented to the user.

idempotency_key

Type: string

Required

Unique key per request.

shipping

Type: shipping_refund object

Optional

Amount to be refunded for shipping.

deductions

Type: array of deductions object

Optional

Amount to be deducted off of the refund. Commonly used for a return label fee for order returns.

return_id

Type: string

Optional

ID representing the return to which the refund is associated. See Returns API

`deductions` object

Attribute Description

Attribute	Description
`deduction_type` Type: string	Required Currently `RETURN_SHIPPING` is the only allowed type.
`deduction_amount` Type: `currency_amount`	Required Amount to be deducted for shipping. See `currency_amount` .

deduction_type

Type: string

Required

Currently RETURN_SHIPPING is the only allowed type.

deduction_amount

Type: currency_amount

Required

Amount to be deducted for shipping. See currency_amount .

`shipping_refund` object

Attribute Description

Attribute	Description
`shipping_refund` Type: `currency_amount`	Required Amount to be refunded for shipping. See `currency_amount` .

shipping_refund

Type: currency_amount

Required

Amount to be refunded for shipping. See currency_amount .

`refund_item` object

Attribute Description

Attribute	Description
`retailer_id` Type: string	Required if `item_id` is not provided. 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` Type: string	Required if `retailer_id` is not provided. A Meta-generated ID representing the line item on the order. This value is readable as the `id` field of the `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` Type: `currency_amount`	Required if `item_refund_quantity` is not provided. Amount to refund, before any tax. Can be any value up to the full value of the item. See `currency_amount` .
`item_refund_quantity` Type: number	Required if `item_refund_amount` is not provided. Number of items to be refunded fully.

retailer_id

Type: string

Required if item_id is not provided.

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

Type: string

Required if retailer_id is not provided.

item_refund_amount

Type: currency_amount

Required if item_refund_quantity is not provided.

Amount to refund, before any tax. Can be any value up to the full value of the item. See currency_amount .

item_refund_quantity

Type: number

Required if item_refund_amount is not provided.

Number of items to be refunded fully.

`currency_amount` object

Attribute Description

Attribute	Description
`amount` Type: string	Required Amount in decimal format. Example: `5.5`
`currency` Type: string	Required Three digit ISO-4217-3 code for the purchase. Format the currency as a number, followed by the 3-digit ISO currency code (ISO 4217 standards) , with a space between cost and currency. Example: `30 USD`

amount

Type: string

Required

Amount in decimal format. Example: 5.5

currency

Type: string

Required

Three digit ISO-4217-3 code for the purchase. Format the currency as a number, followed by the 3-digit ISO currency code (ISO 4217 standards) , with a space between cost and currency.

Example: 30 USD

`refund_reason_code` enum

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)

{
    "reason_code": "WRONG_ITEM",
    "idempotency_key": "cb090e84-e75a-9a34-45d3-5153bec88b65"
}

Sample Request (Partial Order)

{
  "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:

{
  "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 .

List Cancellations

Graph API Explorer

 curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{order-id}/cancellations

 GET /{order-id}/cancellations HTTP/1.1
Host: graph.facebook.com

 /* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{order-id}/cancellations',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

 /* make the API call */
FB.api(
    "/{order-id}/cancellations",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Response

If successful:

{
  "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

Graph API Explorer

 curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{order-id}/refunds

 GET /{order-id}/refunds HTTP/1.1
Host: graph.facebook.com

 /* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{order-id}/refunds',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

 /* make the API call */
FB.api(
    "/{order-id}/refunds",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Response

Attribute and Type

Attribute and Type
`data` Type: array of `refund_item_object`

data

Type: array of refund_item_object

`refund_item_object`

Attribute	Description	Default Display
`id` Type: string	Refund unique ID.	Yes
`items` Type: `items`	Array of refunded items.	Yes
`refund_amount` Type: `refund_amount`	Total refund amount. See `refund_subtotal` object .	Yes
`refund_reason` Type: number	Reason for the refund. See `refund_reason_code` enum .	Yes

`items` object

Attribute and Type

Attribute and Type
`data` Type: array of `item`

data

Type: array of item

`item` object

Attribute	Description
`id` Type: string	Unique ID for order item.
`product_id` Type: string	Unique product ID.
`retailer_id` Type: string	Unique product ID set by seller.
`refund_subtotal` Type: object	Subtotal of refund.
`quantity` Type: number	Optional Item refund quantity, only present if informed when refunding an order with `item_refund_quantity` .

`refund_subtotal` object

Attribute Description Default Display

amount

Type: string

Amount in decimal format. Example: 1.64

Yes

currency

Type: string

Three digit ISO-4217-3 code for the purchase.

Format the currency as a number, followed by the 3-digit ISO currency code (ISO 4217 standards) , with a space between cost and currency.

Example: 30 USD

Yes

`refund_amount` object

Attribute	Description	Default Display
`amount` Type: string	Amount in decimal format. Example: `1.64`	Yes
`currency` Type: string	Three digit ISO-4217-3 code for the purchase. Format the currency as a number, followed by the 3-digit ISO currency code (ISO 4217 standards) , with a space between cost and currency. Example: `30 USD`	Yes
`tax` Type: string	Amount in decimal format with negative sign. Example: `-0.14`	No
`shipping` Type: string	Amount in decimal format with negative sign. Example: `-0.14`	No
`subtotal` Type: string	Amount in decimal format. Example: `0.50`	No
`total` Type: string	Amount in decimal format. Example: `1.64`	No

Sample Request with All Fields

Graph API Explorer

 curl -X GET -G \
  -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/{order-id}/refunds

 GET /{order-id}/refunds?fields=id%2Citems%7Bproduct_id%2Cretailer_id%2Crefund_subtotal%2Cquantity%7D%2Crefund_reason%2Crefund_amount%7Bsubtotal%2Ctax%2Ctotal%2Camount%2Ccurrency%7D HTTP/1.1
Host: graph.facebook.com

 /* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{order-id}/refunds?fields=id%2Citems%7Bproduct_id%2Cretailer_id%2Crefund_subtotal%2Cquantity%7D%2Crefund_reason%2Crefund_amount%7Bsubtotal%2Ctax%2Ctotal%2Camount%2Ccurrency%7D',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

 /* make the API call */
FB.api(
    "/{order-id}/refunds",
    {
        "fields": "id,items{product_id,retailer_id,refund_subtotal,quantity},refund_reason,refund_amount{subtotal,tax,total,amount,currency}"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Sample Response

If successful:

{
  "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"
    }
  }
}

Design a Mobile Website

View Site in Mobile | Classic

Cancellation and Refund API

Cancel Order

Request

cancel_reason object

items

reason_code enum

Sample Request (Full Order)

Sample Request (Partial Order)

Sample Response

Refund Order

Request

deductions object

shipping_refund object

refund_item object

currency_amount object

refund_reason_code enum

Sample Request (Full Order)

Sample Request (Partial Order)

Response

List Cancellations

Response

List Refunds

Response

refund_item_object

items object

item object

refund_subtotal object

refund_amount object

Sample Request with All Fields

Sample Response

`cancel_reason` object

`items`

`reason_code` enum

`deductions` object

`shipping_refund` object

`refund_item` object

`currency_amount` object

`refund_reason_code` enum

`refund_item_object`

`items` object

`item` object

`refund_subtotal` object

`refund_amount` object