Skip to main content

Validate items

POST /v2/fulfillment/validate_items

For a given delivery address or pickup store location, this operation validates each provided item against Instacart’s current instance of the store's catalog. Specifically, it checks whether each items[] exists and whether its quantity parameter (count or weight) matches the product-type configuration.

If your request defines address and omits location_code, Instacart finds the store nearest to that delivery location and performs the checks against its catalog. If your request defines location_code and omits address, Instacart validates the items using the catalog of the store associated with that code. In the event both fields are defined, location_code takes precedence.

The response contains a validation_failures array. Each object in this array references an item and contains an error that describes the check that failed. An empty array indicates all the items passed the validations.

Unlike create order, the validate items operation doesn't accept an order or user reference, so it checks each item individually rather than as a set. Specifically, it doesn't validate whether:

  • All the items comply with alcohol and over-the-counter medication laws.
  • The total number of items, as well as those classified as big and bulky, exceeds what’s allowed.
  • The total weight of the items, as well as those classified as beverages, exceeds what’s allowed.
  • The customer’s account is inactive or deactivated.

Additionally, calling this endpoint doesn’t place a hold on or reserve the provided items[], and an empty validation_failures array doesn’t guarantee the success of the downstream create order call.

Security​

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

Parameters​

None.

Request​

FieldTypeRequiredDescription
itemsArray(ItemToValidate)Required

The items to validate.

addressExpandedAddressOptional

The customer's delivery address. Either this field or location_code is required.

location_codestringOptional

The code that identifies the store's location. Either this field or address is required.

ItemToValidate Object​

FieldTypeRequiredDescription
itemItemRequired

The item's code. Must be unique within the request.

countintegerOptional

The item's count. Must be a non-negative integer. Depending on the item's catalog configuration, either this field or weight is required.

weightnumberOptional

The item's weight. Must be a non-negative number. Depending on the item's catalog configuration, either this field or count is required. The unit of measure (such as lb or kg) is determined by the item's catalog configuration.

Item Object​

One of the following:

FieldTypeRequiredDescription
upcstringRequired

The item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringRequired

The item's retailer reference code (rrc).

ExpandedAddress Object​

FieldTypeRequiredDescription
address_line_1stringRequired

The first line of the address, e.g., 123 Main St.

address_line_2stringOptional

The second line of the address, e.g., Apt 4B.

address_typestringOptional

The type of address, e.g., residential.

postal_codestringRequired

The postal or zip code of the address.

citystringOptional

The city or town of the address, e.g., Chicago.

Request examples​

curl --request POST \
  --url https://connect.instacart.com/v2/fulfillment/validate_items \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "item": {
        "upc": "string"
      },
      "count": 1,
      "weight": 1
    }
  ],
  "address": {
    "address_line_1": "string",
    "address_line_2": "string",
    "address_type": "string",
    "postal_code": "string",
    "city": "string"
  },
  "location_code": "string"
}'

Response​

FieldTypeRequiredDescription
validation_failuresArray(ValidationFailure)Optional

Per-item validation errors. An empty array indicates all submitted items passed validation.

ValidationFailure Object​

FieldTypeRequiredDescription
itemItemUpcOrRrcOptional

The code of the item that failed validation.

errorErrorOptional

The error that occurred while validating the item.

ItemUpcOrRrc Object​

FieldTypeRequiredDescription
upcstringOptional

The item's universal product code (UPC).

rrcstringOptional

The item's retailer reference code (RRC).

Error Object​

FieldTypeRequiredDescription
errorErrorDetailsOptional

The error details.

metaMetaErrorOptional

Metadata about the error, including the items associated with it.

ErrorDetails Object​

FieldTypeRequiredDescription
messagestringOptional

A human-readable description of the error.

error_codeintegerOptional

A numeric code that identifies the error type.

MetaError Object​

FieldTypeRequiredDescription
itemsArray(ItemInfo)Optional

The items that triggered the error.

ItemInfo Object​

FieldTypeRequiredDescription
item_codestringOptional

The retailer reference code (RRC) or universal product code (UPC) of an item that triggered the error.

Response examples​

200 Success with validation failures​

{
  "validation_failures": [
    {
      "item": {
        "upc": "0002373491093004"
      },
      "error": {
        "error": {
          "message": "1 item not found.",
          "error_code": 2000
        },
        "meta": {
          "items": [
            {
              "item_code": "0002373491093004"
            }
          ]
        }
      }
    }
  ]
}

200 Success

{
  "validation_failures": []
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400Duplicate items were provided"Duplicate items provided for this request."2007{"duplicate_items":[{"item_upc":"111"}]}
400Invalid location code"Could not find specified store."1001{"key":"location_code"}
400Without items"can't be blank"1001{"key":"items"}
400Neither location_code nor address provided"Either location_code or address must be provided"1001{"key":"base"}
Last updated on