Checkout code scans

POST /v2/retailer_transaction/checkout_code_scans

Use this operation to block in-store payment until Instacart has successfully validated codes sent by your point-of-sale system (POS). Implementing this API helps ensure your system gets the data it needs to carry out various operations, such as tax suppression, loyalty program management, and order mapping.

For more information, see In-store checkout code scans.

Security

Name	In	Description
Authorization	header	The Authorization header with the bearer token acquired during authentication.

For more information, see Get an access token.

Parameters

None.

Request

Field	Type	Required	Description
store_id	string		The identifier of the store, as defined by the retailer.
code_scans	Array(CheckoutCodeScan)		A list of the codes scanned by your POS.

CheckoutCodeScan Object

Field	Type	Required	Description
code	string		The checkout code scanned by the POS. Its format depends on your specific implementation. Pass its value through verbatim, without transformation.
scan_time	string		When the code was scanned. The timestamp is validated but not used in processing logic. Potentially useful for auditing purposes. Must be in ISO 8601 format. UTC and explicit timezone offsets are accepted.

Request examples

cURL

curl --request POST \
  --url https://connect.instacart.com/v2/retailer_transaction/checkout_code_scans \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "store_id": "string",
  "code_scans": [
    {
      "code": "string",
      "scan_time": "string"
    }
  ]
}'

Java

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/retailer_transaction/checkout_code_scans")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"store_id\": \"string\",\n  \"code_scans\": [\n    {\n      \"code\": \"string\",\n      \"scan_time\": \"string\"\n    }\n  ]\n}")
  .asString();

Python

import http.client

conn = http.client.HTTPSConnection("connect.instacart.com")

payload = "{\n  \"store_id\": \"string\",\n  \"code_scans\": [\n    {\n      \"code\": \"string\",\n      \"scan_time\": \"string\"\n    }\n  ]\n}"

headers = {
    'Accept': "application/json",
    'Content-Type': "application/json",
    'Authorization': "Bearer <token>"
}

conn.request("POST", "/v2/retailer_transaction/checkout_code_scans", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Go

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://connect.instacart.com/v2/retailer_transaction/checkout_code_scans"

	payload := strings.NewReader("{\n  \"store_id\": \"string\",\n  \"code_scans\": [\n    {\n      \"code\": \"string\",\n      \"scan_time\": \"string\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Node.js

const http = require('https');

const options = {
  method: 'POST',
  hostname: 'connect.instacart.com',
  port: null,
  path: '/v2/retailer_transaction/checkout_code_scans',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    Authorization: 'Bearer <token>'
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({store_id: 'string', code_scans: [{code: 'string', scan_time: 'string'}]}));
req.end();

Response

If one or more of the CheckoutCodeScan objects you provided are not found in Instacart’s system or the associated order is in a non-checkout state, then status has a value of Error and the errors array contains a list of all the scans that failed. Otherwise, status is Ok and errors is not present.

If the request is malformed or missing required fields, then a 400 Bad Request is returned with error and meta fields that can be used to identify the problem. For more information, see Understanding scan failures.

Field	Type	Required	Description
status	string		The status of all the code scans. Its value is Ok when all the scans are accepted or Error when one or more of the scans failed.
errors	Array(CheckoutCodeScanError)		A list of checkout code scan errors. Only present when status is Error. Each entry in the list maps to a failed scan code.

CheckoutCodeScanError Object

Field	Type	Required	Description
scan_code	string		If the request contains an invalid CheckoutCodeScan, then that object’s code is assigned to this field.
error_code	string		A machine-readable error code.
error	string		A human-readable description of the error. Some possible values include Code is not found in the system, Code is found but the corresponding order is not in checkout, and Invalid code. The specific values are dependent on your implementation. For more information, contact your Instacart development team.

Response examples

Success

200 Request fails

{
  "status": "Error",
  "errors": [
    {
      "scan_code": "12345",
      "error_code": "1002",
      "error": "Invalid code"
    }
  ]
}

201 Request successful

{
  "status": "Ok"
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
400	store_id is missing	"can't be blank"	1001	{"key":"store_id"}
400	code_scans is missing	"can't be blank"	1001	{"key":"code_scans"}
400	code is missing	"can't be blank"	1001	{"key":"code_scans[0].code"}
400	scan_time is not a valid ISO 8601 timestamp	"is not a valid ISO 8601 formatted timestamp"	1001	{"key":"code_scans[0].scan_time"}