While Button's **preferred** integration path for reporting new orders, adjustments, and cancellations is via our [Orders API](https://developer.usebutton.com/docs/order-api-overview), we also support reporting these via a batch file. This guide walks through how to setup reporting via batch file – specifically, adjustments and cancellations.

## 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 the order adjustment and cancellation events from the previous interval (e.g. for a 24 hour cycle it should be yesterday's events)
- Subsequently, batch files should capture all adjustment and cancellation events 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 an order via this process
- The entire new order state after the adjustment/cancellation should be reflected in the batch file
- If there is an order in the batch file that cannot be matched to an original order in Button’s systems (based on the order ID), it will be ignored
- 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 `updated_date`, `order_id`, `line_item_identifier` combination. If this combination appears multiple times in the batch file, we will accept the row with the latest `updated_date`.

### Immutable Data

The following fields cannot be changed from the original order. If they are included in the batch file, that entire column will be ignored.

- `currency`
- `customer_order_id`
- `purchase_date`
- `btn_ref`
- `customer_id`
- `customer_email_sha256`
- `customer_advertising_id`

## Reporting Adjustments

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:

- Line Item quantity increase
- Line Item quantity decrease
- Line Item total increase
- Line Item total decrease
- Line Item addition
- Line Item removal

### Sample CSV

```text
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
```

### Required Data for Adjustments

All of these columns must be present in the batch file with valid data for the order adjustment to be processed:

| Column Name           | Description                                                                                          | Data Type                                    |
|-----------------------|------------------------------------------------------------------------------------------------------|----------------------------------------------|
| `action`              | The type of update being applied to the line item                                                   | String (accepted inputs: `ADJUST`, `NONE`) |
| `updated_date`        | Date representing the time the order was updated                                                    | ISO-8601 string                              |
| `order_id`            | The order id unique to this order that was passed to Button when the order was created.             | ASCII string (max 255 characters)           |
| `line_item_identifier`| The unique identifier for this line item, within the scope of this order.                          | String                                       |
| `line_item_total`     | 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                                  |

### Optional Data

| Column Name           | Description                                                                                          | Data Type                                    |
|-----------------------|------------------------------------------------------------------------------------------------------|----------------------------------------------|
| `line_item_sku`       | The Stock Keeping Unit of the line item. A Merchant-specific identifier for the line item           | String (max 255 characters)                  |
| `line_item_upc`       | 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)                   |
| `line_item_category`   | The top-most category of the line item                                                              | String                                       |
| `line_item_subcategory`| The second-level category of the line item (i.e. immediately below the topmost category)           | String                                       |
| `line_item_description`| Text describing the line item                                                                        | String                                       |

The above batch file when processed will attempt to adjust two orders in Button's systems:

1. Order with ID `OI-1024` which will now have two line items with IDs `LI-2048` and `LI-512`
2. Order with ID `OI-4096` which will now have one line item with ID `LI-256`

## Reporting Cancellations

If any of the line items in an order has a “CANCEL” action, the entire order will be cancelled.

Cancellations are final and cannot be reversed.

### Required Data for Cancellations / Invalidations

All of these columns must be present in the batch file with valid data for the order cancellation to be processed:

| Column Name           | Description                                                                                          | Data Type                                    |
|-----------------------|------------------------------------------------------------------------------------------------------|----------------------------------------------|
| `action`              | The type of update being applied to the line item                                                   | String; accepted inputs: `CANCEL`, `NONE`   |
| `updated_date`        | Date representing the time the order was updated                                                    | ISO-8601 string                              |
| `order_id`            | The order id unique to this order that was passed to Button when the order was created.             | ASCII string (max 255 characters)           |

### Sample CSV

```text
action,updated_date,order_id
CANCEL,2019-04-30T00:04:32Z,OI-1024
CANCEL,2019-04-30T15:45:00Z,OI-4096
```

The above batch file when processed will attempt to cancel two orders in Button's systems:

1. Order with id `OI-1024` will be cancelled completely
2. Order with id `OI-4096` will be cancelled completely

Updated about 1 year ago.