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

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:

  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.

Did this page help you?