Skip to main content

Update a tip

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

Updates the amount of the tip for a completed order.

To adjust the tip before an order is completed, see Update an order.

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
tip_amount_centsintegerRequiredThe updated tip amount in cents.

Request examples

curl --request PUT \
--url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/{order_id}/tip' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"tip_amount_cents": 1
}'

Response

FieldTypeRequiredDescription
idstringRequiredThe ID of the order.
statusstringRequiredThe current order status.
order_urlstringOptionalLink to view the order.
created_atstringOptionalThe time of order creation in ISO 8601 format.
cancellation_reasonstringOptionalThe reason the order was canceled.
localestringOptionalThe order's locale in POSIX format. Example: en_US.
is_expressbooleanOptionalDeprecated. Use `is_instacartplus` instead. Indicates whether the order received Instacart+ membership benefits. Defaults to false.
is_instacartplusbooleanOptionalIndicates whether the order received Instacart+ membership benefits. Defaults to false.
fulfillment_detailsOrderFulfillmentDetailsOptionalThe order delivery details.
warningsArray(Error)OptionalAny warnings associated with this request.
itemsArray(OrderItem)OptionalThe items in the order.

OrderFulfillmentDetails Object

FieldTypeRequiredDescription
store_locationstringOptionalThe location code of the store where the order was fulfilled. The store_location is often the same as the location_code that was used to create the order. However, orders can be fulfilled from a different store location.
window_starts_atstringRequiredThe start time of the delivery window in ISO 8601 format.
window_ends_atstringRequiredThe end time of the delivery window in ISO 8601 format.
delivered_atstringOptionalThe time the order was delivered in ISO 8601 format.
bag_countintegerOptionalThe number of bags in the order.
handoff_window_starts_atstringOptionalThe start time of the handoff window in ISO 8601 format.
handoff_window_ends_atstringOptionalThe end time of the handoff window in ISO 8601 format.

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.

OrderItem Object

FieldTypeRequiredDescription
line_numstringRequiredThe item's line number in the order.
qtynumberOptionalThe quantity of the item.
qty_unitstringOptionalThe quantity type, either "each" or "lb".
qty_fulfillednumberOptionalThe fulfilled quantity of the item.
qty_fulfilled_unitstringOptionalThe fulfilled quantity type, either "each" or "lb".
qty_requestednumberOptionalThe initally requested quantity of the item.
qty_requested_unitstringOptionalThe initally requested quantity type, either "each" or "lb".
replacedbooleanOptionalIndicates whether the item was replaced.
scan_codestringOptionalThe scan code of the item.
replacement_policystringOptionalThe replacement policy for the item.
shopper_provided_item_namestringOptionalThe item name provided by shoppers for items that they added.
shopper_provided_item_priceMoneyOptionalThe item price provided by shoppers for items that they added.
itemItemRequiredThe item's codes.

Money Object

FieldTypeRequiredDescription
amountnumberRequiredThe amount of a specified currency.
currencystringRequiredThe currency type in ISO 4217 format. For example: USD.

Item Object

FieldTypeRequiredDescription
upcstringOptionalThe item's universal product code (UPC).
rrcstringOptionalThe item's retailer reference code (RRC).
requested_upcstringOptionalThe requested item's universal product code (UPC).
requested_rrcstringOptionalThe requested item's retailer reference code (RRC).
delivered_upcstringOptionalThe delivered item's universal product code (UPC).
delivered_rrcstringOptionalThe delivered item's retailer reference code (RRC).

Response examples

200 Success

{
"id": "12345676789012345678780",
"status": "created",
"order_url": "https://example.com/example-order",
"created_at": "2018-02-22T00:00:00Z",
"cancellation_reason": "shopper_driven",
"locale": "en_US",
"is_express": true,
"is_instacartplus": true,
"fulfillment_details": {
"store_location": "000-32535",
"window_starts_at": "2018-02-22T00:00:00Z",
"window_ends_at": "2018-02-22T00:30:00Z"
},
"items": [
{
"line_num": "103",
"qty": 9,
"qty_unit": "each",
"replaced": false,
"scan_code": "00070481001218",
"replacement_policy": "shoppers_choice",
"item": {
"upc": "123456789114",
"rrc": "",
"requested_upc": "123456789114",
"requested_rrc": "",
"delivered_upc": "123456789114",
"delivered_rrc": ""
}
}
]
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400Invalid user id"User Not Found"1001{"key":"user_id"}
400Order not yet complete"Order has not been completed yet."1001{"key":"tip_amount_cents"}
400Missing parameters"can't be blank"1001{"key":"tip_amount_cents"}
403Inactive user"User Not Active"nullNot applicable