Payments and Promotions

These endpoints can be used to obtain additional financial details for a specific order:

Get Order Payments

An order can have multiple shipments. Currently each shipment will correspond to one payment. In future we may have one payment for multiple shipments.

Fetch all payment details for a given order.

Graph API Explorer
curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{order-id}/payments
GET /{order-id}/payments 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}/payments',
    '{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}/payments",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Request

AttributeTypeDescription

fields

id, subtotal, tax, tax_remitted, total_amount, shipments, transaction_details

Returns specified fields

Response

AttributeTypeDescription

data

array of payment_details

payment_details object

AttributeTypeDescription

data

array of payment_info

payment_info object

AttributeTypeDescription

id

string

ID of the payment for the order

subtotal

subtotal

Subtotal amounts on the order

tax

currency_amount

Tax amount charged on the order

tax_remitted

boolean

true if taxes are collected by Facebook

total_amount

currency_amount

Total amount charged in this payment

shipments

shipments

Shipment associated with this payment

transaction_details

transaction_details

Optional. Details of successful transactions associated with this payment. This field is missing in the case of failed payment capture, and orders without this field cannot be refunded.

subtotal object

AttributeTypeDescription

items

currency_amount

Amount of the item associated with this payment.

shipping

currency_amount

We prorate shipping based on the shipping profile. Let’s say merchant ships 1 item, then the 2nd item.


Example 1 - shipping is $5 base cost, then $1 per additional item. We will charge $5 shipping on first shipment, $1 on second shipment


Example 2 - shipping is $6 flat cost. We will charge $6 shipping on first shipment, $0 on second shipment

shipments object

AttributeTypeDescription

data

array of shipment_info

Each shipment will correspond to one payment so today this is an array with one element only. In future we may add multiple shipments to one payment.

shipment_info object

AttributeTypeDescription

id

string

Facebook shipment ID

external_shipment_id

string

ID representing the shipment in your database. This ID can be used to perform updates on tracking info set on a shipment. Optional but recommended.

transaction_details object

AttributeTypeDescription

data

array of transaction_detail

transaction_detail object

AttributeTypeDescription

transaction_type

string

Type of transaction. Allowed values are: SALE or REFUND.

transaction_date

string

Order's latest update datetime in ISO 8601 format.

transfer_id

string

processing_fee

currency_amount

Processing fee

net_payment_amount

currency_amount

Net payment amount

tax_rate

string

Percentage tax rate

tax_details

array of tax_details

Tax details object

payout_reference_id

string

The bank reference ID associated with the payout in which this transaction is included.


Note: only available for payouts processed after 5/15/19.

tax_details object

AttributeTypeDescription

data

array of tax_detail

tax_detail object

AttributeTypeDescription

tax_category

string

jurisdiction

string

imposition

string

item_tax_rate

string

item_tax_amount

currency_amount

currency_amount object

AttributeTypeDescription

amount

string

Amount in decimal format, eg. "5.5".

currency

string

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

Sample Response

{
  "data": [
    {
      "id": "2381232183",
      "subtotal": {
        "items": {
          "amount": "40.00",
          "currency": "USD"
        },
        "shipping": {
          "amount": "0.00",
          "currency": "USD"
        }
      },
      "tax": {
        "amount": "0.06",
        "currency": "USD"
      },
      "tax_remitted": true,
      "total_amount": {
        "amount": "44.06",
        "currency": "USD"
      },
      "shipments": {
        "data": [
          {
            "id": "2121312213",
            "external_shipment_id": "shopify-shipment-1"
          },
          {
            "id": "2121312213",
            "external_shipment_id": "shopify-shipment-2"
          }
        ]
      },
      "transaction_details": {
        "data": [
          {
            "transaction_type": "SALE",
            "transaction_date": "2019-01-03T09:16:21+00:00",
            "transfer_id": "po_1DqSkwFN7vzsfPbcs4aFsknN",
            "processing_fee": {
              "amount": "-0.33",
              "currency": "USD"
            },
            "net_payment_amount": {
              "amount": "0.67",
              "currency": "USD"
            }
          },
          {
            "transaction_type": "REFUND",
            "transaction_date": "2019-01-09T06:18:50+00:00",
            "processing_fee": {
              "amount": "0.33",
              "currency": "USD"
            },
            "net_payment_amount": {
              "amount": "-0.67",
              "currency": "USD"
            },
            "tax_rate": "8.25%",
            "tax_details": {
              "data": [
                {
                  "tax_category": "FBMP_OTHER_TAXABLE",
                  "jurisdiction": "CALIFORNIA",
                  "imposition": "Sales and Use Tax",
                  "item_tax_rate": "6%",
                  "item_tax_amount": {
                    "amount": "0.06",
                    "currency": "USD"
                  }
                },
                {
                  "tax_category": "FBMP_OTHER_TAXABLE",
                  "jurisdiction": "ALAMEDA",
                  "imposition": "Local Sales and Use Tax",
                  "item_tax_rate": "1.25%",
                  "item_tax_amount": {
                    "amount": "0.01",
                    "currency": "USD"
                  }
                }, // and more
              ]
            }
          }
        ]
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "--sanitized_key--",
      "after": "--sanitized_key--"
    }
  }
}

Get Order Promotions

Get details of all promotions applied on an order. Example: reimbursements.

Reimbursement payout id details are not yet available. Use the Commerce Manager reimbursement report to pull information about reimbursements.

Graph API Explorer
curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{order-id}/promotions
GET /{order-id}/promotions 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}/promotions',
    '{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}/promotions",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Request

AttributeTypeDescription

fields

id, name, reimbursement

Returns specified fields

Response

AttributeTypeDescription

data

array of promotion_details

promotion_details object

AttributeTypeDescription

id

string

ID of the promotion

name

string

Name of the promotion

reimbursement

array of reimbursement_details

Reimbursement details for the promotion

reimbursement_details object

AttributeTypeDescription

net_payout

currency_amount

Net payout

Sample Response

{
  "data": [
    {
      "id": "2131312312",
      "name": "FIRST_TIME_BUYER",
      "reimbursement": {
        "net_payout": {
          "amount": "10.00",
          "currency": "USD"
        }
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "--sanitized_key--",
      "after": "--sanitized_key--"
    }
  }
}