Report an Order

Line items unlock the ability to set segmented rates, allow for Publishers to run targeted product/category/event campaigns, and permit for easier debugging and customer service. Please read this section for more information.

You should report all orders regardless of the presence of a Button attribution token to allow seamless customer support and investigation with Loyalty & Rewards Publishers. This call must be made with authentication.

Response

You will be returned an object that corresponds to your POST-ed order along with a Button Order ID. You do not need to store this ID as you can always manage orders in Button using the Order ID that you reported with the Order (your Order ID). Note a Button Order ID is not included in 202 Accepted responses.

total

int32
required
Total value of the order. Includes any discounts, if applicable. Must exclude VAT, all other taxes, surcharges and any additional costs such as delivery. This value represents the commissionable total. Must be an integer >= 0. Example: 1234 for $12.34

currency

string
required
Three-letter ISO currency code as specified in ISO 4217.

order_id

string
required
The Order ID unique to this order. Treated as an ASCII string. 255 character maximum.

purchase_date

string
required
ISO-8601 string representing the time the purchase was made by the user.

btn_ref

string
required
The Button source token. This field is optional to create an order, but is required for attribution. When testing your integration, you should send dummy source tokens to Button, in the following format: ^fakesrctok-[a-f0-9]{16}$ (e.g. fakesrctok-abcdef0123456789). URL safe string up to 255 characters.

customer

object
customerobject

customer_order_id

string
The customer-facing order ID. Treated as a UTF-8 string. 255 character maximum. Note: Use this field to report the order identifier as communicated to the customer.

line_items

object
line_itemsobject

partner_order_channel

string
Represents the channel in which the user transacted. Accepted values for this field are "app" and "webview".

total_as_decimal

string
Value indicating whether the total being passed on the order is a decimal value. Set this flag to override the default behavior. For example, pass true if the order total is $3.00 and the value for total is set to 3.00. Leave unset or pass false for the default behavior, where $3.00 is represented in total as 300.

finalization_date

string
In advanced usages, provide a specific finalization_date. Normally this value is set automatically by Button. See our Order API Best Practices guide for more details.

accept

string
enum
Defaults to application/json

Generated from available response content types

Allowed:

application/json text/plain

Example Request

curl https://api.usebutton.com/v1/order \
  -X POST \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "total": 7000,
    "currency": "USD",
    "order_id": "1994",
    "purchase_date": "2017-07-25T08:23:52Z",
    "finalization_date": "2017-08-02T19:26:08Z",
    "btn_ref": "srctok-XXX",
    "customer": {
      "id": "mycustomer-1234",
      "email_sha256": "'`echo -n "user@example.com" | openssl dgst -sha256`'",
      "device_id": "XXXX-XXXXXX-XXX-XXXXXX",
      "is_new": true
    },
    "customer_order_id": "abcdef-123456",
    "line_items": [
            {
                "identifier": "sku-1234",
                "total": 4000,
                "quantity":2,
                "sku": "sku-1234",
                "upc": "400000000001",
                "category": ["Clothes"],
                "description": "T-shirts",
                "attributes":{
                    "size": "M"
                }
            },{
                "identifier": "sku-4567",
                "total": 3000,
                "quantity":1,
                "sku": "sku-4567",
                "upc": "400000000002",
                "category": ["Clothes"],
                "description": "Pants",
                "attributes":{
                    "size": "L"
                }
            }
    ]
  }'

HTTP Status Codes