Batch File – New Orders
This guide walks you through how to report new orders to Button via a batch file upload.
While Button's preferred integration path for reporting new orders, adjustments, and cancellations is via our Merchant Library or Orders API, we also support reporting these via a batch file. This guide walks through how to setup reporting via batch file – specifically, new orders.
General Guidelines
- Button will provide you with a dedicated SFTP directory for uploading your batch files
- For the first ever batch file upload, the file should contain all new order events from the previous interval (e.g. for a 24 hour cycle it should be yesterdays events)
- Subsequently, batch files should capture all new orders that occurred since the previous upload (e.g. for a 24 hour cycle the previous day from 00:00:00 UTC to 23:59:59 UTC)
- You cannot create adjust or cancel previously reported orders via this process; for adjustments and cancellations, see here
- If the order in the batch file matches to one already in the Button system (based on the order ID), but has been finalized or cancelled already, it will be ignored
Batch File Format
Batch files should be delivered in a comma-separated value (CSV) format and the file name should specify the date & time it was generated. For example, if on a 24 hour cadence, BRANDNAME_orders_2019-01-01.csv
.
Each line item in the order should have a row in the batch file (i.e. if there are 3 items in the order, there should be 3 rows: 1 for each line item).
There should be only one row for each order_id
and line_item_identifier
combination. If this combination appears multiple times in the batch file, we will accept the first row with that combination.
Note: We recommend the files be encoded in 'UTF-8'.
Required Data
All of these columns must be present with valid data in each row of the batch file for the order to be processed:
Column Name | Description | Data Type |
---|---|---|
Purchase date | The date / timestamp that the order took place. | ISO-8601 |
Order ID | The order id unique to this order. This is treated as an ASCII string. | String up to 255 characters |
Customer Order ID | The customer-facing order ID. Note: Use this field to report the order identifier as communicated to the customer. | Treated as a UTF-8 string up to 255 characters |
Order Total | 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. | Integer > 0 |
Currency | Three-letter ISO currency code | String, ISO 4217 |
Button Attribution Token | The Button Attribution Token. 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. | A URL safe string up to 255 characters |
Order Channel | The channel in which the user transacted. Accepted values for this field are app and webview . | String |
Line-item identifier | The 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, and if need be, concatenated with another value to ensure this identifier is wholly unique within the order. | String |
Line-item total (e.g. quantity * unit cost) | Total price of all items bought in a particular line item (e.g. if 3 medium pizzas were purchased for $10.00 each, total would be 3000); represented in the smallest currency unit (e.g., 100 for $1.00) in the same currency as the initial order. | Integer > 0 |
Line-item quantity | The number of unique units represented by this line item. Defaults to 1. | Integer > 0 |
Line-item sku | The Stock Keeping Unit of the line item. A Brand-specific identifier for the line item. | String up to 255 characters |
Line-item category | The category of the line item. If multiple, use “:” as the delimiter | String |
Line-item description | Text describing the line item | String |
Customer ID | The ID for the transacting customer in your system. | String |
Hashed Customer Email (using sha-256) | The 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. | String |
Device id | The customer's device ID (iOS: IDFA, Android: AAID) | String |
New / existing customer | A Boolean value indicating whether or not the customer has previously made a purchase. Pass true if this is their first purchase, otherwise pass false . | Boolean |
Optional Data
Column Name | Description | Data Type |
---|---|---|
Coupon code | If applicable, the coupon code used by the user. | String |
Any key/value pair | Add a column for other important attributes | String |
Sample CSV
purchase_date,order_id,customer_order_id,order_total,currency,attribution_token,order_channel,line_item_identifier,line_item_total,line_item_quantity,line_item_sku,line_item_category,line_item_description,coupon_code,hashed_email,device_id,user_status
2021-02-01T20:00:00Z,o-1a2b3c,1a2b3c,1000,USD,srctok-0123456789abcdefgh,app,menuitem-abcd,600,1,menuitem-abcd,pizza,pepperoni Pizza - Large,FirstPurchaseCoupon,userId123,1234-abcd-567891234-abcd-5678,ABCD-1234-EFGH-5678912345-ABCD,true
2021-02-01T20:00:00Z,o-1a2b3c,1a2b3c,1000,USD,srctok-0123456789abcdefgh,app,menuitem-efgh,400,1,menuitem-efgh,sides,Garlic Knots,FirstPurchaseCoupon,userId123,1234-abcd-567891234-abcd-5678,ABCD-1234-EFGH-5678912345-ABCD,true
2021-02-02T20:00:00Z,o-4d5e6f,4d5e6f,1500,USD,srctok-abcdefgh0123456789,webview,menuitem-xyz,1500,1,menuitem-xyz,pizza,Hawaiian Pizza – XLarge,,userId123,,,false
The above batch file when processed will attempt to cancel two orders in Button's systems:
- Order with id
o-1a2b3c
will be created with two line items and will have customer attributes that include user ID, hashed email, device ID and "new" user state. - Order with id
o-4d5e6f
will be created with one line item and will have customer attributes that include User ID and "existing" user state.
Updated over 1 year ago