Order

You can use the order object to interact with orders created by the application using Facebook Payments to view and update orders as needed.

You can also access all orders for a user or an application by accessing the /payments connection on the user or application objects.

Note: You must use real orders when calling the Graph API. Transactions from the users listed in the 'Payments Testers' section of your app settings are not be processed and will not appear in the Order API

Properties

The properties associated with the order object.

Name	Description	Permissions	Returns
`id`	id for the order	app `access_token`	`name` and `id` of the user
`from`	userid associated with the order unless the user has uninstalled, in which case we return a third_party_id	app `access_token`	`string`
`amount`	amount for the order	app `access_token`	`integer`
`status`	status the order	app `access_token`	`string` - possible values are `placed`, `settled`, `disputed`, `refunded`, `cancelled`
`application`	application associated with the order	app `access_token`	`name` and `id` of the application
`country`	country associated with the order	app `access_token`	String containing `ISO 3166 alpha 2` code representing the country
`refund_reason_code`	refund reason code if the order was refunded by Facebook	app `access_token`	`string`
`created_time`	time when the order was created	app `access_token`	`string` containing an ISO-8601 datetime
`updated_time`	time when the order was last updated	app `access_token`	`string` containing an ISO-8601 datetime

Order Statuses

The status property of an order can have one of the following values:

Status	Description	Set By	Possible Next Statuses
`placed`	Once the user approves the transaction, Facebook holds the necessary number of credits from the user and the order is put into the placed state. It is then sent to the developer with a `payments_status_update` call at which time the developer should grant the user their item before moving the order to `settled` state.	Facebook	`settled` or `cancelled`
`settled`	Once the order is settled the funds are fully transferred from the user to the application	Developer	Usually the order is done here. However the order can still enter a `disputed` or `refunded` state at a later time
`refunded`	The order has been refunded and the user has been given back their purchase amount in credits for the underlying order. The order can be refunded due to various reasons, please see the Chargebacks and disputes doc for more info.	Facebook or Developer	None
`disputed`	The order has been disputed by the user and requires action on your part. See our disputes section for more information.	User	`settled` or `refunded`
`cancelled`	The order has been cancelled and no funds are transferred from the user to the application	Developer	None

Refund reason Codes

If you issue a HTTP GET request to /ORDER_ID and if the order in question has been refunded by Facebook, then there you will see the refund_reason_code which explains why the order was refunded by Facbook with one of values below. See more information about why Facebook refunds orders in the Chargebacks and disputes doc.

Compromised Account

Stolen Financial Instrument

Not Fraud

User Confusion

Dev System Issue

FB System Issue

Sample Response


{
   "id": "9006187786070",
   "from": 221159,
   "to": 221159,
   "amount": 1,
   "status": "settled",
   "application": {
      "name": "SampleApp",
      "canvas_name": "fbdschultzcredits",
      "namespace": "fbdschultzcredits",
      "id": "128163550571392"
   },
   "country": "US",
   "created_time": "2011-11-16T19:39:52+0000",
   "updated_time": "2011-11-16T19:39:55+0000"
}

Update Order

You can update properties an existing order by issuing a HTTP POST request to /ORDER_ID with the list of parameters you wish to update.

You may only issue a refund within 60 days of the initial transaction.

When updating a disputed order, you may only move the status to settled or refunded. In addition, you must provide the additional message parameter with a reason for either refunding or settling the disputed order. If you are updating a settled order to refunded for whatever reason, then you do not need to provide the message parameter.

This API is throttled to 100 calls per minute.

POST https://graph.facebook.com/[order id]?status=STATUS&message=MESSAGE

Parameters:

Property	Description
`status`	A string representing the status you want the order to move to. You can only update it to one of `settled` or `refunded`.
`message`	a message to associate with the update of the order, required when moving from a `disputed` status to `settled` or `refunded`.
`params`	optional JSON-encoded dictionary {'comment' => }

Returns:

`true` or `false` on failure

Updated about 5 months ago