Report a New Order

Brands should report all successful orders to the Button Order API before reporting back to the end user, and after fulfilling that order in your own inventory system. Order reporting at this time guarantees both that the order was successfully acknowledged, and that any promotions from other applications involved in this purchase are carried out.

Here is a sample request using the cURL terminal command. For more information on this API’s specifications, visit the Order API.

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 "[email protected]" | openssl dgst -sha256`'",
      "device_id": "XXXX-XXXXXX-XXX-XXXXXX",
      "is_new": true
    },
    "customer_order_id": "abcdef-123456"
    "line_items": [
            {
                "identifier": "sku-1234",
                "total": 4000,
                "amount": 2000,
                "quantity":2,
                "sku": "sku-1234",
                "upc": "400000000001",
                "category": ["Clothes"],
                "description": "T-shirts",
                "attributes":{
                    "size": "M"
                }
            },{
                "identifier": "sku-4567",
                "total": 3000,
                "amount": 3000,
                "quantity":1,
                "sku": "sku-4567",
                "upc": "400000000002",
                "category": ["Clothes"],
                "description": "Pants",
                "attributes":{
                    "size": "L"
                }
            }
    ],
  }'

Note: You'll need to authenticate your API requests; see our authentication reference for more details.

Order Object

All fields below are required when reporting orders to Button:

Customer Object

All fields below are required when reporting orders to Button:

Line Items Object

All fields below are required when reporting orders to Button:

Update an Order

Accurate billing relies on accurate order reporting. In cases where initial orders are modified, it is vital to update them via the Button Orders API.

Because of this, Brands must also report all successful order updates to the Button Orders API whenever the order’s value, content, or status changes in your e-commerce backend. Similar to reporting a new order, updating orders is done via POST request containing the order’s updated information.

Important: Partial returns are considered “updates” and should be reported using this update method.

Here is a sample request using the cURL terminal command. For more information on this API’s specifications, visit the Orders API.

curl https://api.usebutton.com/v1/order/ord-xxx \
  -X POST \
  -u my-api-key: \
  -H "Content-Type: application/json" \
  -d '{
    "total": 4000,
    "line_items": [
            {
                "identifier": "sku-1234",
                "total": 4000,
                "amount": 2000,
                "quantity":2,
                "sku": "sku-1234",
                "upc": "400000000001",
                "category": ["Clothes"],
                "description": "T-shirts",
                "attributes":{
                    "size": "M"
                }
            }
    ],
  }'

Cancel an Order

Lastly, for all orders that are cancelled within your Brand’s Order Management System, you must report this to the Button Order API to avoid improper billing or commissioning to your Brand or other parties involved in the transaction. Cancellations are reported via http DELETE request, and are only valid for entire order cancellations. Partial order cancellations are considered an order update. Once a cancellation is made, it cannot be reversed.

Here is a sample request using the cURL terminal command. For more information on this API’s specifications, visit the Orders API.

curl https://api.usebutton.com/v1/order/<brand-order-id> \
       -X DELETE \
       -u YOUR_API_KEY:

Receiving a Response

A successful response body from the Offers API will return a meta.status of ok for all transmissions, differing only under the object field to reflect either the new order being registered, updated, or cancelled.

// Sample response:
    {
        "meta": {
            "status": "ok"
        },
        "object": {
            "id": "f00b4r",
            "active": true
        }
    }