Getting Started with the Orders API

Getting Started with the Orders API


Locate your API key


Interacting with the Orders API requires authentication using an API key issued through the Button Dashboard.

Head over to the Button Dashboard and log in using your Organization’s Button credentials



Once logged in, click on your Organization’s drop down icon in the top right to navigate menu options. Select Organization Settings



Within Organization Settings, scroll down to API Keys and select Generate Key



Give your API Key a name and select Generate



Copy the key generated and store it in your application’s secrets. Do not share this key.


Authenticating a Request with your API Key


Button expects API key authorization via Basic Auth. In order to construct an Authorization header value, follow these steps:

  1. Add a colon to the end of the api key (e.g. apiKey + ":")
  2. Base64 encode the resulting string
  3. The authorization method and a space i.e. "Basic " is then put before the encoded string. (e.g. "Basic " + base64Encode(apiKey + ":"))

The resulting key/value pair would then look like this:



Structure Your Request Payload to Report a New Order


Brands should report all successful orders to the Button Orders 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 Orders API


    curl https://api.usebutton.com/v1/order \
      -X POST \
      -H 'Authorization: "Basic QWxhZGRpbjpPcGVuU2VzYW11"' \
      -H "Content-Type: application/json" \
      -d '{
        "total": 50,
        "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"
        },
        "customer_order_id": "abcdef-123456"

      }'


Order Object


Request ParameterRequired/OptionalDescription
totalRequiredTotal 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.
currencyRequiredThree-letter ISO currency code as specified in ISO 4217.
order_idRequiredThe Order ID unique to this order. Treated as an ASCII string. 255 character maximum.
purchase_dateRequiredISO-8601 string representing the time the purchase was made by the user.
btn_refRequiredThe Button Attribution Token. A URL safe string up to 255 characters. This field is optional to create an order, but is required for attribution. When testing your integration, you should send dummy Attribution Tokens to Button, in the following format: ^fakesrctok-[a-f0-9]{16}$ (e.g. fakesrctok-abcdef0123456789). Note: even though this is marked as *optional*, you must provide a valid Button Attribution Token when reporting orders driven by a Button Publisher.
customerRequiredInformation regarding the Customer Object
customer_order_idRequiredThe 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_itemsRequiredAn array of the line item details that comprise the order.
statusRequiredA read-only field giving the order's current status.



Customer Object


Customer KeyRequired/OptionalDescription
idRequiredThe ID for the transacting customer in your system
email_sha256RequiredThe SHA-256 hash of the transacting customer's lowercase email, as a 64-character hex string. Note: The value of the e-mail address must be converted to lowercase before computing the hash. The hash itself may use uppercase or lowercase hex characters.
device_idRequiredThe customer's device ID (IDFA/AAID)



Line Items Object


Customer KeyRequired/OptionalDescription
identifierRequiredThe unique identifier for this line item, within the scope of this order. This must be unique across all line-items within the order. We suggest using the SKU or UPC of the product.
totalRequiredThe total price of all items bought in a particular line item (e.g. if 3 bananas were purchased for $3.00 each, total would be 900). Must be net of any discounts or taxes and represent the value a Brand expects to commission on. Must be an integer > 0.
quantityRequiredThe number of unique units represented by this line item. Must be an integer > 0. Defaults to 1.
skuRequiredThe Stock Keeping Unit of the line item. A Brand-specific identifier for the line item. String with a maximum length of 255.
upcRequiredThe Universal Product Code of the line item. Also referred to as UPC-A and GTIN-12. UPC-E (8-digit) codes should be converted to 12-digit codes. String with 12 numeric digits. For industries not regularly utilizing upc this can be your industry’s unique product identifier.
categoryRequiredThe category of the line item. An ordered list of strings, starting with the topmost (or most general) category. The total number of subcategories is capped at 7. Example: ["Electronics", "Computers", "Laptops", "Accessories", "Bags"].
descriptionRequiredText describing the line item.
attributesRequiredA key/value store for strings to specify additional information about a line item. Examples of attributes are: top level / meta category identifier with a category; secondary category identifier with a subcategory; primary manufacturer of the product with a brand; the UPC (universal product code) of an item with a upc.


Structure Your Request Payload to Update an Existing Order


Accurate billing relies on accurate order reporting. In cases where initial orders are modified, it is vital to update them to 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/<brand-order-id> \
      -X POST \
      -u YOUR_API_KEY: \
      -H "Content-Type: application/json" \
      -d '{
        "total": 8000,
        "currency": "USD",
        "order_id": "1989",
        "purchase_date": "2017-07-01T00:00:00Z",
        "finalization_date": "2017-08-02T19:26:08Z",
        "line_items": [
          {
            "identifier": "sku-789",
            "total": 5000,
            "quantity": 1,
            "description": "mattress"
          },
          {
            "identifier": "sku-012",
            "total": 3000,
            "quantity": 1,
            "description": "cover"
          }
        ],
        "customer": {
          "id": "mycustomer-1234",
          "email_sha256": "'`echo -n "user@example.com" | openssl dgst -sha256`'",
          "device_id": "XXXX-XXXXXX-XXX-XXXXXX"
        },
        "customer_order_id": "abcdef-123456"
      }'


Structure Your Request Payload to Cancel an Existing 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](/api#orders


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