This guide walks you through how to report order adjustments and cancellations to Button via a batch file upload. In this guide, we’ll review:
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,
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
line_item_identifier combination. If this combination appears multiple times in the batch file, we will accept the row with the latest
All of these columns must be present in the batch file with valid data for the order adjustment or cancellation to be processed
|Column Name||Description||Data Type|
||The type of update being applied to the line item||String (accepted inputs:
||ISO-8601 string representing the time the order was updated||ISO-8601 format|
||The order id unique to this order that was passed to Button when the order was created. This is treated as an ASCII string||String (max 255 characters)|
||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||String|
||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)|
||The number of unique units represented by this line item. Defaults to 1||Integer (>0)|
|Column Name||Description||Data Type|
||The Stock Keeping Unit of the line item. A Merchant-specific identifier for the line item||String (max 255 characters)|
||The Universal Product Code of the line item. Also referred to as UPC-A and GTIN-12. UPC-E (8-digit) codes should be converted to 12-digit codes||String (12 numeric digits)|
||The topmost category of the line item||String|
||The second-level category of the line item (i.e. immediately below the topmost category)||String|
||Text describing the line item||String|
The following fields cannot be changed from the original order. If they are included in the batch file, that entire column will be ignored.
When adjusting an order, you must provide the current state of the order rather than the delta. If line items that are present in the original order are not included in the adjustment file, they will be removed from the order. All of these scenarios must be accounted for:
action, updated_date, order_id, line_item_identifier, line_item_total, line_item_quantity, line_item_sku, line_item_upc, line_item_category, line_item_subcategory, line_item_description ADJUST, 2019-04-30T00:04:32Z, OI-1024, LI-2048, 199, 1, 1234-XCYZ, 100000299906, Grocery, Fruits, Fuji Apples ADJUST, 2019-04-30T00:04:32Z, OI-1024, LI-512, 420, 6, 2405-CDGF, 100000249906, Grocery, Fruits, Bananas ADJUST, 2019-04-30T15:45:00Z, OI-4096, LI-256, 998, 1, 1704-SNGV, 100000249904, Grocery, Drinks, Oat Milk
The above batch file when processed will attempt to adjust two orders in Button's systems:
OI-1024which will now have two line items with IDs
OI-4096which will now have one line item with ID
If any of the line items in an order has a “CANCEL” action, the entire order will be cancelled, trumping any other.
Cancellations are final and cannot be reversed.
action, updated_date, order_id, line_item_identifier, line_item_total, line_item_quantity, line_item_sku, line_item_upc, line_item_category, line_item_subcategory, line_item_description CANCEL, 2019-04-30T00:04:32Z, OI-1024, LI-2048, 0, 1, 1234-XCYZ, 100000299906, Grocery, Fruits, Fuji Apples ADJUST, 2019-04-30T00:04:32Z, OI-1024, LI-512, 420, 6, 2405-CDGF, 100000249906, Grocery, Fruits, Bananas CANCEL, 2019-04-30T15:45:00Z, OI-4096, LI-256, 0, 1, 1704-SNGV, 100000249904, Grocery, Drinks, Oat Milk
The above batch file when processed will attempt to cancel two orders in Button's systems:
OI-1024will be cancelled completely even though one of the line items has action =
OI-4096will be cancelled entirely