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

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