Upload files with transaction information

Learn how to prepare your point of sale (POS) transaction information in a CSV or TXT file and then upload the file to Instacart.

note

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_file in the filename. After going live, remove this appended text.
• Avoid the string _bad_data in the filename. Files with this filename are automatically rejected.

Timestamps

• 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: 2022-03-09T11:37:00-5:00.
  • Use the UTC format. For example: 2022-03-09T16:37:00Z
    note

    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.

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

Field values

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

tip

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:

Field	Type	Required	Description
bin	number		The first six digits of the payment card. Values are 539186, 546683, 555370, or 551917.
last_four	string	✅ 1	The last four digits of the primary account number or payment card number. For example: 7890.
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: 4211.
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: 2022-03-09T16:37:00Z or 2022-03-09T11:37:00-5:00.
sub_total	number	✅	The total for the transaction excluding taxes and fees. For example: 10.23.
total	number	✅	The total for the transaction including taxes and fees. For example: 12.32.
id	string	✅	The unique identifier for the transaction. For example: 847473.
total_tax	number	✅	The total tax and fees for the transaction. For example: 1.25.
cardholder_name	string		The name associated with the payment card. For example: Instacart 12345.
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: 1.23.
sales_tax_city	number		The portion of sales tax attributed to the city. For example: 1.23.
sales_tax_county	number		The portion of sales tax attributed to the county. For example: 1.23.
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: 1.23.
alcohol_tax	number		The alcoholic beverage taxes charged on an order. For example: 1.23.
bag_fee	number		The bag fees charged on an order. For example: 1.23.
battery_recycling_fee	number		The battery recycling fees charged on an order. For example: 1.23.
beverage_container_fee	number		The beverage container fees, beverage container deposits, and California Redemption Value (CRV) charged on an order. For example: 1.23.
beverage_tax	number		The beverage taxes charged on an order. For example: 1.23.
eco_fee	number		The eco fees charged on an order. For example: 1.23.
env_waste_recycling_fee	number		The environmental waste recycling fees charged on an order. For example: 1.23.
excise	number		The excise taxes charged on an order. For example: 1.23.
poison_control	number		The poison control surcharges on an order. For example: 1.23.
prepared_food_meals_tax	number		The prepared food, beverages, and meals taxes on an order. For example: 1.23.
fee	number		The fees charged on an order. For example: 1.23.
recycling_fee	number		The recycling fees charged on an order. For example: 1.23.
other_mpf_taxes_and_fees	number		The other marketplace facilitator eligible taxes charged on an order. For example: 1.23. Contact your Instacart representative before mapping to this field.
other_non_mpf_taxes_and_fees	number		The other non-marketplace facilitator eligible taxes charged on an order. For example: 1.23. Contact your Instacart representative before mapping to this field.

¹ You must provide either the last four digits or the approval code for the transaction.

Items array

The following table lists the fields that you can include in the items array:

Field	Type	Required	Description
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 lb, kg, g, or oz.
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 bar_code and retailer_reference_code blank.
measure_method	string		The method used to measure item numbers or weights. Values are QUANTITY_BASED, PREPACKAGED_BY_WEIGHT or LOOSE_RANDOM_WEIGHT_BASED.

¹ If the measure method is prepackaged by weight or loose random weight based, then the weight and weight unit are required.

Items array example

The following example shows a sample items array that you can include in the items column:

[
  {
    "line_item_number": 0,
    "bar_code": 299776218782,
    "retailer_reference_code": 99776,
    "description": "Lean Ground Beef",
    "category": "Grocery",
    "price_per_unit": 6.29,
    "item_price": 18.78,
    "quantity": 1,
    "weight": 2.98,
    "weight_unit": "lb",
    "alcohol": false,
    "tobacco": false,
    "weight_certified": true,
    "bar_code_missing_reason": "",
    "measure_method": "QUANTITY_BASED"
  },
  {
    "line_item_number": 0,
    "bar_code": 466583218782,
    "retailer_reference_code": 99776,
    "description": "Bread",
    "category": "Grocery",
    "price_per_unit": 1.29,
    "item_price": 2.78,
    "quantity": 2,
    "weight": 1.98,
    "weight_unit": "lb",
    "alcohol": false,
    "tobacco": false,
    "weight_certified": false,
    "bar_code_missing_reason": "",
    "measure_method": "PREPACKAGED_BY_WEIGHT"
  }
]

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.

Best Practice

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.