Batch File – New Orders

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 yesterday's 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 or cancel previously reported orders via this process; for adjustments and cancellations, see here
If the order in the batch file matches 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

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.