Cancellation and Refund API Reference

Use this API to initiate cancellations or refunds on a given order. In this section:

Cancel Order

Cancel an order fully or partially. You can only cancel un-shipped orders or items.

POST https://graph.facebook.com/vX.X/{order-id}/cancellations?access_token={PAGE_ACCESS_TOKEN}

Request

AttributeTypeRequiredDescription

cancel_reason

cancel_reason

Required

restock_items

boolean

Optional

By default, value is false. Merchant can set this value to true so it can be added back to inventory.

items

array of items

Optional

idempotency_key

string

Required

A unique key per request.

cancel_reason object

AttributeTypeRequiredDescription

reason_code

reason_code

Required

reason_description

string

Optional

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

items

AttributeTypeRequiredDescription

retailer_id

string

Required

ID representing the product in the merchant's catalog.

quantity

Number

Required

Number of items canceled.

reason_code enum

ValueDescription

CUSTOMER_REQUESTED

OUT_OF_STOCK

INVALID_ADDRESS

SUSPICIOUS_ORDER

CANCEL_REASON_OTHER

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

Refund Order

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

POST https://graph.facebook.com/vX.X/{order-id}/refunds?access_token={PAGE_ACCESS_TOKEN}

Request

AttributeTypeRequiredDescription

items

array of refund_item

Optional

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

reason_code

refund_reason_code

Required

reason_text

string

Optional

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

idempotency_key

string

Required

A unique key per request.

shipping

shipping_refund object

Optional

Amount to be refunded for shipping.

deductions

array of deductions object

Optional

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

deductions object

AttributeTypeRequiredDescription

deduction_type

string

Required

Currently RETURN_SHIPPING is the only allowed type. Will add more in the future.

deduction_amount

currency_amount

Required

Amount to be refunded for shipping.

shipping_refund object

AttributeTypeRequiredDescription

shipping_refund

currency_amount

Required

Amount to be refunded for shipping.

refund_item object

AttributeTypeRequiredDescription

retailer_id

string

Required

Retailer identifier for the product.

item_refund_amount

currency_amount

See notes

Amount to refund, before any tax. Required if item_refund_quantity is not provided. Can be any value up to the full value of the item.

item_refund_quantity

Number

See notes

Number of items to be refunded fully. Required if item_refund_amount is not provided.

currency_amount object

AttributeTypeDescription

amount

string

Amount in decimal format, e.g. "5.5".

currency

string

Three digit ISO-4217-3 code for the purchase, e.g. USD.

refund_reason_code enum

ValueDescription

BUYERS_REMORSE

DAMAGED_GOODS

NOT_AS_DESCRIBED

QUALITY_ISSUE

REFUND_REASON_OTHER

WRONG_ITEM

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.

List Cancellations

GET https://graph.facebook.com/vX.X/{order-id}/cancellations?access_token={PAGE_ACCESS_TOKEN}

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

GET https://graph.facebook.com/vX.X/{order-id}/refunds?access_token={PAGE_ACCESS_TOKEN}

Response

AttributeType

data

array of refund_item_object

refund_item_object

AttributeTypeDefault Display

id

string

Yes

items

items

Yes

refund_amount

refund_amount

Yes (See object)

refund_reason

Number

See notes

items object

AttributeType

data

array of item

item object

AttributeType

id

string

product_id

string

retailer_id

string

refund_subtotal

object

refund_subtotal object

AttributeTypeDescriptionDefault Display

amount

string

Amount in decimal format, e.g. "1.64".

Yes

currency

string

Three digit ISO-4217-3 code for the purchase, e.g. USD.

Yes

refund_amount object

AttributeTypeDescriptionDefault Display

amount

string

Amount in decimal format, e.g. "1.64".

Yes

currency

string

Three digit ISO-4217-3 code for the purchase, e.g. USD.

Yes

tax

string

Amount in decimal format with negative sign, e.g. "-0.14".

No

shipping

string

Amount in decimal format with negative sign, e.g. "-0.14".

No

subtotal

string

Amount in decimal format, e.g. "0.50".

No

total

string

Amount in decimal format, e.g. "1.64".

No

Sample Request With All fields

GET https://graph.facebook.com/vX.X/{order-id}/refunds?fields= id,items,refund_reason,refund_amount{subtotal,tax,total,amount,currency}&access_token={PAGE_ACCESS_TOKEN}

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