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 NameDescriptionData Type
Purchase dateThe date / timestamp that the order took place.ISO-8601
Order IDThe order id unique to this order. This is treated as an ASCII string.String up to 255 characters
Customer Order IDThe 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 TotalTotal 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
CurrencyThree-letter ISO currency codeString, ISO 4217
Button Attribution TokenThe 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 ChannelThe channel in which the user transacted. Accepted values for this field are app and webview.String
Line-item identifierThe 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 quantityThe number of unique units represented by this line item. Defaults to 1.Integer > 0
Line-item skuThe Stock Keeping Unit of the line item. A Brand-specific identifier for the line item.String up to 255 characters
Line-item categoryThe category of the line item. If multiple, use “:” as the delimiterString
Line-item descriptionText describing the line itemString
Customer IDThe 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 idThe customer's device ID (iOS: IDFA, Android: AAID)String
New / existing customerA 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 NameDescriptionData Type
Coupon codeIf applicable, the coupon code used by the user.String
Any key/value pairAdd a column for other important attributesString

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:

  1. 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.
  2. 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.