Skip to main content

Send point of sale transaction information

POST /v2/retailer_transaction/pos_transactions

Sends point of sale (POS) transaction information to Instacart. Instacart uses the POS transaction information to match POS transactions to online transactions and to audit orders.

Best Practice

Send transaction information within 10 minutes of finalizing the transaction to ensure seamless reconciliation and timely payments.

Security​

FieldInDescription
AuthorizationheaderThe Authorization header with the bearer token acquired during authentication.

Request​

FieldTypeRequiredDescription
binstringOptionalThe first six digits of the payment card. One of 539186, 546683, 555370, or 551917.
last_fourstringRequiredThe last four digits of the primary account number or payment card number. For example: 7890.
transaction_timestampstringRequiredThe time of the transaction. Append the timezone at the end or use the UTC format. For example: 2022-03-09T11:37:00-5:00 or 2022-03-09T16:37:00Z.
idstringRequiredThe global unique identifier for the transaction across all stores and banners. Avoid reusing the ID. For example: 847473.
store_idstringRequiredThe identifier for the store. For example: 4211.
checkout_idstringOptionalThe identifier submitted in checkout registration.
sub_totalnumberOptionalThe total for the transaction, excluding taxes and fees. For example: 10.23.
totalnumberRequiredThe total for the transaction, including taxes and fees. For example: 12.32.
currency_codestringOptionalThe currency type in ISO 4217 format. Default is USD.
total_taxnumberRequiredThe total tax for the transaction. For example: 1.25.
cardholder_namestringOptionalThe name associated with the payment card. For example: Instacart 12345.
customer_referencestringOptionalCustomer reference. For example, an ID, email, or phone number.
tendersArray(PosTender)OptionalThe various ways the transaction was paid for.
itemsArray(PosItem)OptionalThe items involved in the transaction.
taxesArray(PosTax)OptionalThe taxes and fees for the transaction.

PosTender Object​

FieldTypeRequiredDescription
typestringRequiredThe type of tender. One of CASH, CREDIT_CARD, DEBIT_CARD, GIFT_CARD, BYPASS, or REFUND.
amountnumberRequiredThe amount that this tender contributed to paying for the transaction.
idstringOptionalWhen the tender type is BYPASS, the ID is the pos_checkout_request_id.
approval_processed_by_codestringRequiredThe system that approved the process. One of RETAILER or INSTACART.

PosItem Object​

FieldTypeRequiredDescription
line_item_numberstringRequiredThe unique identifier for the item in the transaction.
bar_codestringRequired1The barcode or PLU of the item.
retailer_reference_codestringRequired1The unique identifier for this item in the retailer's catalog. This should be the same unique identifier sent in the inventory files.
descriptionstringOptionalThe name of the item.
categorystringOptionalA general classification of the item.
price_per_unitnumberOptionalThe price of each individual unit of this item. For example, price per pound for produce.
item_pricenumberOptionalThe total price of the item excluding taxes and discounts. For voided items, enter this value as a negative value.
quantityintegerRequiredThe amount of the item. For weighted items, the value is 1. For voided items, enter this value as a negative value.
weightnumberRequired2The weight of a weighted item. Exclude this field for unweighted items. If measure_method is PREPACKAGED_BY_WEIGHT or LOOSE_RANDOM_WEIGHT_BASED, then this field is required. For voided items, enter this value as a negative value.
weight_unitstringRequired2The unit of measure of a weighted item. Exclude this field for unweighted items. One of lb, kg, g, or oz. If measure_method is PREPACKAGED_BY_WEIGHT or LOOSE_RANDOM_WEIGHT_BASED, then this field is required.
alcoholbooleanOptionalWhether the item is an alcohol item and subject to stricter handling guidelines by the shopper.
tobaccobooleanOptionalWhether the item is a tobacco item and subject to stricter handling guidelines by the shopper.
weight_certifiedbooleanOptionalWhether the item weight is certified by the retailer.
bar_code_missing_reasonstringOptionalThe reason why a barcode is missing. If this field is provided, then leave bar_code and retailer_reference_code blank.
measure_methodstringRequiredThe method used to measure item numbers or weights. One of QUANTITY_BASED, PREPACKAGED_BY_WEIGHT, or LOOSE_RANDOM_WEIGHT_BASED.
taxesArray(PosTax)OptionalThe taxes and fees for this item in the transaction.
  1. You must provide either the bar_code or retailer_reference_code.
  2. If the measure_method is PREPACKAGED_BY_WEIGHT or LOOSE_RANDOM_WEIGHT_BASED, then the weight and weight_unit are required.

PosTax Object​

FieldTypeRequiredDescription
typestringRequiredThe type of tax. One of OTHER, SALES_TAX_STATE, SALES_TAX_CITY, SALES_TAX_COUNTRY, SALES_TAX_LOCAL_TAX, ALCOHOL_TAX, BAG_FEE, BATTERY_RECYCLING_FEE, BEVERAGE_CONTAINER_FEE, EXCISE, POISON_CONTROL, PREPARED_FOOD_MEALS_TAX, FEE, or RECYCLING_FEE.
type_otherstringOptionalA freeform text representation of a tax type not captured by the type field. For example, custom taxes added by municipalities.
amountnumberRequiredThe amount of tax in dollars. For example, use 2.75 to represent $2.75.
ratenumberOptionalThe tax or fee rate. For example, use 5.25 to represent 5.25% tax. For type BAG_FEE, this field is used to indicate the number of bags used (2.0 for 2 bags).
flat_ratenumberOptionalThe flat-fee tax rate. For example, use 2.75 to represent $2.75.
taxable_amountnumberOptionalThe total taxable amount.

Request examples​

curl --request POST \
  --url https://connect.instacart.com/v2/retailer_transaction/pos_transactions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "bin": "string",
  "last_four": "string",
  "transaction_timestamp": "string",
  "id": "string",
  "store_id": "string",
  "checkout_id": "string",
  "sub_total": 1,
  "total": 1,
  "currency_code": "string",
  "total_tax": 1,
  "cardholder_name": "string",
  "customer_reference": "string",
  "tenders": [
    {
      "type": "CASH",
      "amount": 1,
      "id": "string",
      "approval_processed_by_code": "INSTACART"
    }
  ],
  "items": [
    {
      "line_item_number": "string",
      "bar_code": "string",
      "retailer_reference_code": "string",
      "description": "string",
      "category": "string",
      "price_per_unit": 1,
      "item_price": 1,
      "quantity": 1,
      "weight": 1,
      "weight_unit": "string",
      "alcohol": true,
      "tobacco": true,
      "weight_certified": true,
      "bar_code_missing_reason": "string",
      "measure_method": "string",
      "taxes": [
        {
          "type": "OTHER",
          "type_other": "string",
          "amount": 1,
          "rate": 1,
          "flat_rate": 1,
          "taxable_amount": 1
        }
      ]
    }
  ],
  "taxes": [
    {
      "type": "OTHER",
      "type_other": "string",
      "amount": 1,
      "rate": 1,
      "flat_rate": 1,
      "taxable_amount": 1
    }
  ]
}'

Response​

FieldTypeRequiredDescription
idstringOptionalID of the transaction submitted.

Response examples​

200 Success​

{
  "id": "transaction-id-123"
}

4XX Errors​

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400Request fails"invalid input"1001Not applicable
Last updated on