Add an adjustment

POST /v1/items/quantitylimits/adjustments

Records a single, unique point-of-sale (POS) transaction in FoodStorm and adjusts corresponding Quantity Limit totals against menu items in FoodStorm. You can send multiple requests (one transaction per request) at the same time.

tip

Post the POS transactions in real-time rather than in scheduled batches to improve the accuracy of order matching and stock adjustments.

Before making a requested adjustment, the matching system assesses whether a corresponding order in FoodStorm has already accounted for the adjustment. In the request response, the note field contains the match result as one of: No match or Matched order <number> for transaction id <number>. For more information about matching, see Adjustments.

Security

Name	In	Description
Authorization	header	Standard Authorization header using the Bearer scheme. Example: "bearer {token}"

Parameters

None.

Request

All item_id values in the items array must have a matching item in the FoodStorm OMS. If an item_id value is not found, the request returns an error.

Field	Type	Required	Description
items	Array(Items)		Menu items purchased within the same POS transaction.
site_code	string		The unique site identifier of the store where the POS transaction occurred.
adjustment_reason	string		The type of adjustment. If the adjustment_amount is negative, specify "external_sale". If the adjustment_amount is positive, specify “external_refund”.
adjustment_datetime	string		The timestamp of the physical POS transaction. Value must be in UTC and ISO8601 format as per contract. For example: 2022-03-09T11:37:00-5:00 or 2022-03-09T16:37:00Z.
transaction	Hash		The transaction details for the adjustment.

Items Object

Field	Type	Required	Description
item_id	string		The scanned barcode, which represents a physical product (e.g. turkey).
adjustment_amount	integer		The number of units sold for the given item_id in this POS transaction.

Transaction Object

Field	Type	Required	Description
id	string		Unique identifier of a physical POS transaction.

Request Examples

cURL

curl --request POST \
  --url https://connect.instacart.com/v1/items/quantitylimits/adjustments \
  --header 'Accept: application/json' \
  --header 'Authorization: string' \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "item_id": "string",
      "adjustment_amount": 1
    }
  ],
  "site_code": "string",
  "adjustment_reason": "string",
  "adjustment_datetime": "string",
  "transaction": {
    "id": "string"
  }
}'

Java

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v1/items/quantitylimits/adjustments")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "string")
  .body("{\n  \"items\": [\n    {\n      \"item_id\": \"string\",\n      \"adjustment_amount\": 1\n    }\n  ],\n  \"site_code\": \"string\",\n  \"adjustment_reason\": \"string\",\n  \"adjustment_datetime\": \"string\",\n  \"transaction\": {\n    \"id\": \"string\"\n  }\n}")
  .asString();

Python

import http.client

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

payload = "{\n  \"items\": [\n    {\n      \"item_id\": \"string\",\n      \"adjustment_amount\": 1\n    }\n  ],\n  \"site_code\": \"string\",\n  \"adjustment_reason\": \"string\",\n  \"adjustment_datetime\": \"string\",\n  \"transaction\": {\n    \"id\": \"string\"\n  }\n}"

headers = {
    'Accept': "application/json",
    'Content-Type': "application/json",
    'Authorization': "string"
}

conn.request("POST", "/v1/items/quantitylimits/adjustments", 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/v1/items/quantitylimits/adjustments"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"item_id\": \"string\",\n      \"adjustment_amount\": 1\n    }\n  ],\n  \"site_code\": \"string\",\n  \"adjustment_reason\": \"string\",\n  \"adjustment_datetime\": \"string\",\n  \"transaction\": {\n    \"id\": \"string\"\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", "string")

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

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

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

}

Response

Field	Type	Required	Description
items	Array(Items)		Menu items purchased within the same POS transaction.
site_code	string		The unique site identifier that will be sent to FoodStorm.
adjustment_reason	string		Allowed values are "external_sale" or "external_refund".
adjustment_datetime	string		Timestamp of a physical POS transaction. Value must be in ISO8601 format.
matched_order_no	string		The order number which matches the given POS transaction.
transaction	Hash		The transaction details for the adjustment.
note	string		Brief on the adjustment outcome.

Items Object

Field	Type	Required	Description
item_id	string		The scanned barcode, which represents a physical product (e.g. turkey).
adjustment_amount	integer		The number of units sold for the given item_id in this POS transaction.

Transaction Object

Field	Type	Required	Description
id	string		Unique identifier of a physical POS transaction.

Response Examples

200 Success

200 Without matching order

{
  "items": [
    {
      "item_id": "0028065123",
      "adjustment_amount": -2
    },
    {
      "item_id": "0031546396",
      "adjustment_amount": -1
    }
  ],
  "site_code": "S2",
  "adjustment_reason": "external_sale",
  "adjustment_datetime": "2023-11-03T12:01:20.2842433+11:00",
  "transaction": {
    "id": "123123"
  },
  "note": "no matching order found. negative adjustment applied"
}

200 With matching order

{
  "items": [
    {
      "item_id": "0028065123",
      "adjustment_amount": -2
    },
    {
      "item_id": "0031546396",
      "adjustment_amount": -1
    }
  ],
  "site_code": "S2",
  "adjustment_reason": "external_sale",
  "adjustment_datetime": "2023-11-03T12:01:20.2842449+11:00",
  "matched_order_no": "31235",
  "transaction": {
    "id": "123123"
  },
  "note": "transaction 123123 matched to order 31235"
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
400	Item Category Not Found	""	""	Not applicable