Skip to main content

Set item replacements

PUT /v2/fulfillment/users/{user_id}/orders/{order_id}/replacement_selections

For each line item in a delivery or pickup order, you can use this idempotent operation to provide the customer's replacement selections[]. If the requested line item is out of stock or can't be found, these selections[] define the customer's preferred replacement.

To successfully perform this operation, the order's status must be brand_new, acknowledged or picking. After status advances beyond picking, the request fails.

You can’t use this operation to add line items to the order. If your request contains line_num values that don’t exist in the order, then those values are listed in the error's message.

tip

After an order is created, you can use the update an order operation to add line items.

If you’ve already used a create delivery, create pickup, or update order operation to set a line item’s replacement items, and you specify a replacement_items[] for that same line item in this request, then the new value overwrites the existing values.

Security​

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

Parameters​

NameInTypeRequiredDescription
user_idpathstringRequiredThe ID of the user.
order_idpathstringRequiredThe ID of the order.

Request​

FieldTypeRequiredDescription
selectionsArray(OrderItemSelection)RequiredThis array contains the customer's order item replacement selections. These selections are used in the event the requested product is out of stock or can't be found. The array can contain a maximum of ten OrderItemSelection objects.

OrderItemSelection Object​

FieldTypeRequiredDescription
line_numstringRequiredThe order item's line number.
countintegerOptionalThe preferred count of the replacement item. Must be greater than '0'. Depending on the item's catalog configuration, either this field or 'weight' is required.
weightnumberOptionalThe preferred weight of the replacement item. Must be greater than '0'. Depending on the item's catalog configuration, either this field or 'count' is required. The unit of measure, such as lb or kg, assigned to this field is based on the item's catalog configuration.
replacement_policystringOptionalThe policy on how replacements should be handled. One of 'no_replacements', 'users_choice', or 'shoppers_choice' (default). If 'replacement_items' exists, then this field must be 'users_choice'.
replacement_itemsArray(Replacement_items)OptionalAn array containing the customer’s preferred replacement items. If 'replacement_policy' is 'users_choice', then the number of Replacement_items objects in this array must be '1'.
itemItemRequiredThe code of the order line item.

Replacement_items Object​

One of the following:

FieldTypeRequiredDescription
upcstringRequiredThe item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringRequiredThe item's retailer reference code (rrc).

Item Object​

One of the following:

FieldTypeRequiredDescription
upcstringRequiredThe item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringRequiredThe item's retailer reference code (rrc).

Request examples​

curl --request PUT \
  --url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/{order_id}/replacement_selections' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "selections": [
    {
      "line_num": "string",
      "count": 1,
      "weight": 1,
      "replacement_policy": "no_replacements",
      "replacement_items": [
        {
          "upc": "string"
        }
      ],
      "item": {
        "upc": "string"
      }
    }
  ]
}'

Response​

FieldTypeRequiredDescription
idstringRequiredThe ID of the order.
warningsArray(Error)OptionalAny warnings associated with this request.

Error Object​

FieldTypeRequiredDescription
errorErrorDetailsOptionalInformation relevant to the error.
metaMetaErrorOptionalThe error metadata.

ErrorDetails Object​

FieldTypeRequiredDescription
messagestringOptionalThe error message.
error_codeintegerOptionalThe error code.

MetaError Object​

FieldTypeRequiredDescription
itemsArray(ItemInfo)OptionalThe items that triggered the error.

ItemInfo Object​

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

Response examples​

200 Success

{
  "id": "123"
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400Invalid replacement_policy"is not included in the list"1001{"key":"selections[0].replacement_policy"}
400Missing required fields"can't be blank"1001{"key":"selections[0].item"}
400Invalid count"must be greater than or equal to 0"1001{"key":"selections[0].count"}
400Invalid weight"must be greater than or equal to 0"1001{"key":"selections[0].weight"}
400Too many selections"Maximum 10 items allowed"1001{"key":"selections"}
400Duplicate line numbers"Duplicate line_num values not allowed"2006{"duplicate_line_nums":["1"]}
400Both count and weight present"Exactly one of count or weight must be present for line_nums: 1"4001Not applicable
400Neither count nor weight present"Exactly one of count or weight must be present for line_nums: 1"4001Not applicable
400Invalid replacement policy with replacement items"Replacement policy must be users_choice when replacement_items are present for line_nums: 1"4001Not applicable
400Invalid replacement policy with users_choice replacement policy"Replacement items must contain one item when replacement policy is users_choice for line_nums: 1"4001Not applicable
404Order not found"Order not found"4000Not applicable
404Missing line numbers"Order line item not found for line_nums: 2"4000Not applicable
Last updated on