Skip to main content

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:

A CSV file with three rows. The first row contains the columns: bin, last four, approval code, store id, transaction timestamp, subtotal, total, id, total tax, cardholder name, and items. The second and third rows contain information about two different 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:

FieldTypeRequiredDescription
binnumberThe first six digits of the payment card. Values are 539186, 546683, 555370, or 551917.
last_fourstring1The last four digits of the primary account number or payment card number. For example: 7890.
approval_codenumber1The authorization code from the retailer’s point of sale system.
store_idstringThe identifier for the store. For example: 4211.
transaction_timestampstringThe 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_totalnumberThe total for the transaction excluding taxes and fees. For example: 10.23.
totalnumberThe total for the transaction including taxes and fees. For example: 12.32.
idstringThe unique identifier for the transaction. For example: 847473.
total_taxnumberThe total tax and fees for the transaction. For example: 1.25.
cardholder_namestringThe name associated with the payment card. For example: Instacart 12345.
itemsarrayContains item-level data. Instacart uses this information to reconcile weights and measurements and debug discrepancies between the online transaction and POS transaction.
sales_tax_statenumberThe portion of sales tax attributed to the state. For example: 1.23.
sales_tax_citynumberThe portion of sales tax attributed to the city. For example: 1.23.
sales_tax_countynumberThe portion of sales tax attributed to the county. For example: 1.23.
sales_tax_local_taxnumberThe 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_taxnumberThe alcoholic beverage taxes charged on an order. For example: 1.23.
bag_feenumberThe bag fees charged on an order. For example: 1.23.
battery_recycling_feenumberThe battery recycling fees charged on an order. For example: 1.23.
beverage_container_feenumberThe beverage container fees, beverage container deposits, and California Redemption Value (CRV) charged on an order. For example: 1.23.
beverage_taxnumberThe beverage taxes charged on an order. For example: 1.23.
eco_feenumberThe eco fees charged on an order. For example: 1.23.
env_waste_recycling_feenumberThe environmental waste recycling fees charged on an order. For example: 1.23.
excisenumberThe excise taxes charged on an order. For example: 1.23.
poison_controlnumberThe poison control surcharges on an order. For example: 1.23.
prepared_food_meals_taxnumberThe prepared food, beverages, and meals taxes on an order. For example: 1.23.
feenumberThe fees charged on an order. For example: 1.23.
recycling_feenumberThe recycling fees charged on an order. For example: 1.23.
other_mpf_taxes_and_feesnumberThe 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_feesnumberThe other non-marketplace facilitator eligible taxes charged on an order. For example: 1.23. Contact your Instacart representative before mapping to this field.
1 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:

FieldTypeRequiredDescription
line_item_numberstringThe unique identifier for the item in the transaction.
bar_codestringThe barcode or PLU of the item.
retailer_reference_codestringThe unique identifier for this item in the retailer’s catalog. This should be the same unique identifier sent in the inventory files.
descriptionstringThe name of the item.
categorystringThe general classification of the item.
price_per_unitnumberThe price of each individual unit of this item. For example, price per pound for produce.
item_pricenumberThe total price of the item excluding taxes and discounts.
quantityintegerThe amount of the item. For weighted items, the value is 1.
weightnumber1The weight of a weighted item. Exclude this field for unweighted items.
weight_unitstring1The unit of measure of a weighted item. Exclude this field for unweighted items. Values are lb, kg, g, or oz.
alcoholbooleanWhether the item is an alcohol item and subject to stricter handling guidelines by the shopper.
tobaccobooleanWhether the item is a tobacco item and subject to stricter handling guidelines by the shopper.
weight_certifiedbooleanWhether the item weight is certified by the retailer.
bar_code_missing_reasonstringThe reason why a barcode is missing. If this field is provided, then you can leave bar_code and retailer_reference_code blank.
measure_methodstringThe method used to measure item numbers or weights. Values are QUANTITY_BASED, PREPACKAGED_BY_WEIGHT or LOOSE_RANDOM_WEIGHT_BASED.
1 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.