Order API Best Practices

Understanding the finalization_date field

The finalization_date is a field set by your organization to reflect your Brand’s cancel/return policy, and should not be used when sending new orders to the Button Orders API. As orders are reported to Button, they enter a pending state which is persisted until the finalization_date is reached.

Once the finalization_date has been reached, the order will move to a validated status and begin the commissioning process. If you choose to adjust or cancel the order, you may do so before the finalization_date.

If a finalization_date is specified when reporting a new order to the Button Orders API, this will override your Brand’s default policy and is not recommended.

Handling Button Attribution Tokens

The format in which the Button Attribution Token is passed to your Checkout API depends on the interface between your mobile clients and your Checkout API. We recommend using a key of btn_ref to pass this value for consistency.

When testing your integration and sending dummy Attribution Tokens to Button, send in the format of ^fakesrctok-[a-f0-9]{16}$ (e.g. "btn_ref": "fakesrctok-abcdef0123456789"). For more information on this, see our Testing Section.

When updating orders, there is no need to include the Button Attribution token (btn_ref) as we already have it associated with the unique order identifier reported to Button.

Differences between order updates and cancellations

Cancellations only occur if an entire order for every line item has been cancelled. If only some of an order’s line-items have been cancelled, then it is considered an update.

Reporting Discounts & Coupons

Types of Discounts

There are 2 types of discounts we traditionally see:

1. Product Level Discounts - applied to item(s) within a user's cart (e.g. "$10 off product X", "5% off item Y", etc.)
2. Order Level Discounts - applied to a user's cart (e.g. "$10 off your order", "5% off your entire basket", etc.)

Where to Report Discounts

These discounts should be accounted for in the following JSON fields passed in the request body when reporting orders to Button's API for more on this API call):

1. total, which represents the total value of the order (e.g. the GMS, absent taxes & fees)
2. line_items[n].total, which represents the line-item total (e.g. quantity * product unit cost)
3. line_items[n].attributes.coupon_code, which represents the actual discount/coupon code that the customer entered to obtain the discount.

How to Report Discounts

Reporting Product Level Discounts

• total - Deduct the discount amount from the order total
• line_items[n].total - Deduct the discount amount from the specific line-item total the discount was applied (e.g. where n represents the index of the specific product discounted)
• line_items[n].attributes.coupon_code - Report the discount/coupon code itself within the line-item the discount was applied (e.g. where n represents the index of the specific product discounted)

Reporting Order Level Discounts

• total - Deduct the discount amount from the order total (same as product level discounts)
• line_items[*].total - The discount amount deducted, should be distributed across all line-item totals within the order (e.g. deducting a piece of the overall discount from each line-item total). While you should make your best effort to distribute this evenly across all line-item totals, you can however, use your discretion to distribute unevenly if/where necessary (e.g. fractional amounts as a result of rounding)
• line_items[*].attributes.coupon_code - Report the discount/coupon code itself in all the line-items for the order.

Please note that in all cases, the order.total must equal the sum of all order.line_items[*].total, and in all cases neither values can be negative amounts.