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.

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<ORDER_ID>/cancellations

Request

cancel_reason object

items

reason_code enum

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).

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<ORDER_ID>/refunds

Request

deductions object

shipping_refund object

refund_item object

currency_amount object

refund_reason_code enum

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

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<ORDER_ID>/cancellations

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

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<ORDER_ID>/refunds

Response

refund_item_object

items object

item object

refund_subtotal object

refund_amount object

Sample Request with All Fields

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/v24.0/<ORDER_ID>/refunds

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