Learn how to prepare your point of sale (POS) transaction information in a CSV or TXT file and then upload the file to Instacart.
To get started with uploading transaction information, contact your Instacart representative.
Before you begin
You need complete the following actions:
- Contact your Instacart representative to learn about your upload location and the required credentials.
- Work with your Instacart representative to prepare a sample file. This ensures that Instacart can help identify issues, such as missing data, and determine how your columns map to Instacart’s data structure.
Prepare the file
Files contains a header row followed by transaction rows. The header row contains the columns that you want to provide transaction information about. Transaction rows contain POS transaction information for the transaction. Each file can contain multiple transactions, and you can upload multiple files.
The following image shows an example CSV file with POS transaction information for two transactions:
Use the following guidelines when preparing the files.
File structure and naming
- Determine your file type and delimiter. The delimiter must be the same delimiter used by the inventory file.
- If your inventory file uses comma-separated data, send comma-separated values in a CSV file.
- If your inventory file uses pipe-separated data, send pipe-separated values in a TXT file.
- If your inventory file uses tab-separated data, send tab-separated values in a TXT file.
- Encode files in UTF-8.
- Use consistent column names for all files and versions. The order of columns does not have to be consistent.
- Append the banner’s name and date in the filename for better traceability.
- During the testing phase, append
_test_filein the filename. After going live, remove this appended text.
- Avoid the string
_bad_datain the filename. Files with this filename are automatically rejected.
Account for different time zones for individual stores and accurately report the timestamps in one of the following timestamp formats:
- Append the time zone at the end. For example:
- Use the UTC format. For example:
Instacart recommends appending the time zone at the end. If you use the UTC format, it is possible that the transaction date might change in some cases.
- Append the time zone at the end. For example:
Ensure that these timestamps are not based on derived data. It is acceptable to have a few minutes delay, but the Instacart matching algorithm typically fails to match transactions beyond 10 minutes of the transaction.
- Transaction IDs must be globally unique across all transactions.
- The total must include all taxes and fees. Missing information from the total amount, such as bag fees or bottle deposits, can lead to mismatches.
Choose your columns
Columns are the fields that you want to provide POS transaction information about. There are required columns that you must include and optional columns that you can choose to include in your file.
To ensure that Instacart can effectively audit transactions, include as many columns as you can.
The following table describes the columns that you can include in your file:
|bin||number||The first six digits of the payment card. Values are |
|last_four||string||✅ 1||The last four digits of the primary account number or payment card number. For example: |
|approval_code||number||✅ 1||The authorization code from the retailer’s point of sale system.|
|store_id||string||✅||The identifier for the store. For example: |
|transaction_timestamp||string||✅||The time that the POS transaction was finalized in Coordinated Universal Time (UTC) format or in local time with the time zone offset appended. For example: |
|sub_total||number||✅||The total for the transaction excluding taxes and fees. For example: |
|total||number||✅||The total for the transaction including taxes and fees. For example: |
|id||string||✅||The unique identifier for the transaction. For example: |
|total_tax||number||✅||The total tax and fees for the transaction. For example: |
|cardholder_name||string||The name associated with the payment card. For example: |
|items||array||Contains item-level data. Instacart uses this information to reconcile weights and measurements and debug discrepancies between the online transaction and POS transaction.|
|sales_tax_state||number||The portion of sales tax attributed to the state. For example: |
|sales_tax_city||number||The portion of sales tax attributed to the city. For example: |
|sales_tax_county||number||The portion of sales tax attributed to the county. For example: |
|sales_tax_local_tax||number||The portion of sales tax attributed to the local taxes, for example, sales tax districts, local improvement districts, special purpose districts, and transit districts. For example: |
|alcohol_tax||number||The alcoholic beverage taxes charged on an order. For example: |
|bag_fee||number||The bag fees charged on an order. For example: |
|battery_recycling_fee||number||The battery recycling fees charged on an order. For example: |
|beverage_container_fee||number||The beverage container fees, beverage container deposits, and California Redemption Value (CRV) charged on an order. For example: |
|beverage_tax||number||The beverage taxes charged on an order. For example: |
|eco_fee||number||The eco fees charged on an order. For example: |
|env_waste_recycling_fee||number||The environmental waste recycling fees charged on an order. For example: |
|excise||number||The excise taxes charged on an order. For example: |
|poison_control||number||The poison control surcharges on an order. For example: |
|prepared_food_meals_tax||number||The prepared food, beverages, and meals taxes on an order. For example: |
|fee||number||The fees charged on an order. For example: |
|recycling_fee||number||The recycling fees charged on an order. For example: |
|other_mpf_taxes_and_fees||number||The other marketplace facilitator eligible taxes charged on an order. For example: |
|other_non_mpf_taxes_and_fees||number||The other non-marketplace facilitator eligible taxes charged on an order. For example: |
The following table lists the fields that you can include in the items array:
|line_item_number||string||The unique identifier for the item in the transaction.|
|bar_code||string||The barcode or PLU of the item.|
|retailer_reference_code||string||The unique identifier for this item in the retailer’s catalog. This should be the same unique identifier sent in the inventory files.|
|description||string||The name of the item.|
|category||string||The general classification of the item.|
|price_per_unit||number||The price of each individual unit of this item. For example, price per pound for produce.|
|item_price||number||The total price of the item excluding taxes and discounts.|
|quantity||integer||The amount of the item. For weighted items, the value is 1.|
|weight||number||✅ 1||The weight of a weighted item. Exclude this field for unweighted items.|
|weight_unit||string||✅ 1||The unit of measure of a weighted item. Exclude this field for unweighted items. Values are |
|alcohol||boolean||Whether the item is an alcohol item and subject to stricter handling guidelines by the shopper.|
|tobacco||boolean||Whether the item is a tobacco item and subject to stricter handling guidelines by the shopper.|
|weight_certified||boolean||Whether the item weight is certified by the retailer.|
|bar_code_missing_reason||string||The reason why a barcode is missing. If this field is provided, then you can leave |
|measure_method||string||The method used to measure item numbers or weights. Values are |
Items array example
The following example shows a sample items array that you can include in the items column:
"description": "Lean Ground Beef",
Upload the file
Use SFTP to upload the file to the upload location. Upload files as frequently as possible to keep the file sizes small. Send transaction information to Instacart at least once daily.
To unlock fraud detection and weight-adjustment flows, Instacart recommends sending transaction information hourly.
Instacart removes the uploaded file from the upload location as soon as Instacart’s systems start processing it.
If your file doesn't pass the validations, Instacart emails a validation report. The validation report mentions all the validations that failed while processing your file. Instacart sends one validation report per file. If you don't received an email about failures, then your file passed the validations.