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

AttributeDescription

cancel_reason

Type: cancel_reason

Required

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

AttributeDescription

reason_code

Type: reason_code

Required

Reason for the cancellation.

reason_description

Type: string

Optional

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

items

AttributeDescription

retailer_id

Type: string

Required

ID representing the product in the seller's catalog.

quantity

Type: number

Required

Number of items canceled.

reason_code enum

ValueDescription

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

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

AttributeDescription

items

Type: array of refund_item

Optional

For partial refund, specify the item level breakdown. Not required for 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 return label fee for order returns.

deductions object

AttributeDescription

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

AttributeDescription

shipping_refund

Type: currency_amount

Required

Amount to be refunded for shipping. See currency_amount.

refund_item object

AttributeDescription

retailer_id

Type: string

Required

Retailer identifier for the product.

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

AttributeDescription

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

ValueDescription

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 will be 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

data

Type: array of refund_item_object

refund_item_object

AttributeDescriptionDefault 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

data

Type: array of item

item object

AttributeDescription

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

AttributeDescriptionDefault 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

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