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

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

Parameters

Name	In	Type	Required	Description
user_id	path	string		The ID of the user.
order_id	path	string		The ID of the order.

Request

Field	Type	Required	Description
tip_amount_cents	integer		The updated tip amount in cents.

Request examples

cURL

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
}'

Java

HttpResponse<String> response = Unirest.put("https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/{order_id}/tip")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"tip_amount_cents\": 1\n}")
  .asString();

Python

import http.client

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

payload = "{\n  \"tip_amount_cents\": 1\n}"

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

conn.request("PUT", "/v2/fulfillment/users/{user_id}/orders/{order_id}/tip", 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/fulfillment/users/{user_id}/orders/{order_id}/tip"

	payload := strings.NewReader("{\n  \"tip_amount_cents\": 1\n}")

	req, _ := http.NewRequest("PUT", 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))

}

Response

Field	Type	Required	Description
id	string		The retailer-generated order ID.
status	string		The current status of the order.
order_url	string		The URL of the Instacart-hosted order status page. If the retailer has opted not to use this feature, this field will be null or empty.
created_at	string		The time of order creation in ISO 8601 format.
cancellation_reason	string		The reason the order was canceled. Only present in canceled orders. One of the following: customer_driven: The customer triggered the cancellation instacart_driven: Instacart triggered the cancellation retailer_driven: The retailer triggered the cancellation shopper_driven: The shopper triggered the cancellation unbatchable: The Instacart batch system triggered the cancellation other: The cancellation was triggered for another reason not listed above.
locale	string		Indicates how the order is localized.
is_express	boolean		Deprecated. Use is_instacartplus instead. Indicates whether the order received Instacart+ membership benefits. Defaults to false.
is_instacartplus	boolean		Indicates whether the order received Instacart+ membership benefits. Defaults to false.
metadata	Hash		The order-level metadata.
fulfillment_details	OrderFulfillmentDetails		The order's fulfillment details.
warnings	Array(Error)		Any warnings associated with this request.
items	Array(OrderItem)		The items in the order.

OrderFulfillmentDetails Object

Field	Type	Required	Description
store_location	string		The location code of the store where the order was fulfilled. This field's value is often the same as the location_code included in the create order request. However, orders can be fulfilled from a store that's different from the one specified by location_code.
window_starts_at	string		The start of the fulfillment window in ISO 8601 format.
window_ends_at	string		The end of the fulfillment window in ISO 8601 format.
delivered_at	string		The time the order was delivered to the customer in ISO 8601 format. Only present for completed deliveries.
bag_count	integer		The number of bags in the order, as reported by the shopper.
handoff_window_starts_at	string		The start of the store-associate-to-Instacart-shopper handoff window in ISO 8601 format. This field is only populated for last mile delivery (i.e., delivery only) orders.
handoff_window_ends_at	string		The end of the store-associate-to-Instacart-shopper handoff window in ISO 8601 format. This field is only populated for last mile delivery (i.e., delivery only) orders.

Error Object

Field	Type	Required	Description
error	ErrorDetails		Information relevant to the error.
meta	MetaError		The error metadata.

ErrorDetails Object

Field	Type	Required	Description
message	string		The error message.
error_code	integer		The error code.

MetaError Object

Field	Type	Required	Description
items	Array(ItemInfo)		The items that triggered the error.

ItemInfo Object

Field	Type	Required	Description
item_code	string		The retailer reference code (RRC) or universal product code (UPC) of an item that triggered the error.

OrderItem Object

Field	Type	Required	Description
line_num	string		The item's line number as provided by the retailer in the create order request.
qty	number		The quantity of the item. For unpicked items, this is the ordered quantity. For picked items, this is the delivered quantity.
qty_unit	string		The unit of measure for the quantity. Either each for count-based items or lb for weight-based items.
qty_fulfilled	number		The fulfilled quantity of the item (the actual quantity picked and delivered).
qty_fulfilled_unit	string		The unit of measure for the fulfilled quantity. Either each for count-based items or lb for weight-based items.
qty_requested	number		The initially requested quantity of the item (what the customer originally ordered).
qty_requested_unit	string		The unit of measure for the initially requested quantity. Either each for count-based items or lb for weight-based items.
replaced	boolean		Indicates whether the item was replaced. This is true if the item that was picked and delivered differs from the item that was originally requested by the customer.
scan_code	string		The barcode or scan code that the shopper scanned when picking this item.
replacement_policy	string		The replacement policy for the item. One of the following: no_replacements: Do not replace if unavailable. users_choice: Replace only with customer-approved alternatives. shoppers_choice: Shopper selects best replacement.
shopper_provided_item_name	string		The item name provided by shoppers for items that they added.
metadata	Hash		The item-level metadata.
shopper_provided_item_price	Money		The item price provided by shoppers for items that they added.
item	Item		The item's codes.

Money Object

Field	Type	Required	Description
amount	number		The amount of a specified currency.
currency	string		The currency type in ISO 4217 format. For example: USD.

Item Object

Field	Type	Required	Description
upc	string		The item's universal product code (UPC). For unpicked items, this is the requested UPC. For picked items, this is the delivered UPC.
rrc	string		The item's retailer reference code (RRC). For unpicked items, this is the requested RRC. For picked items, this is the delivered RRC.
requested_upc	string		The UPC of the item that the customer originally requested to purchase.
requested_rrc	string		The RRC of the item that the customer originally requested to purchase.
delivered_upc	string		The UPC of the item that was actually picked and delivered to the customer. If the item was replaced, this will differ from the requested_upc.
delivered_rrc	string		The RRC of the item that was actually picked and delivered to the customer. If the item was replaced, this will differ from the requested_rrc.

Response examples

200 Success

200 Order tip updated

{
  "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-32722",
    "window_starts_at": "2018-02-22T00:00:00Z",
    "window_ends_at": "2018-02-22T00:30:00Z"
  },
  "items": [
    {
      "line_num": "113",
      "qty": 12,
      "qty_unit": "each",
      "replaced": false,
      "scan_code": "00070481001226",
      "replacement_policy": "shoppers_choice",
      "rx": false,
      "item": {
        "upc": "123456789126",
        "rrc": "",
        "requested_upc": "123456789126",
        "requested_rrc": "",
        "delivered_upc": "123456789126",
        "delivered_rrc": ""
      }
    }
  ]
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
400	Invalid user id	"User Not Found"	1001	{"key":"user_id"}
400	Order not yet complete	"Order has not been completed yet."	1001	{"key":"tip_amount_cents"}
400	Tip update temporary error	"OrderDeliveries::TipService error"	2003	{"wait":10,"retry":true}
400	Missing parameters	"can't be blank"	1001	{"key":"tip_amount_cents"}
400	Invalid order params*	"There were issues with your request"	9999	Not applicable
403	Inactive user	"User Not Active"	null	Not applicable
409	Cannot update tip while another update is in progress	"Cannot update tip while another update is in progress. Please retry shortly."	1001	Not applicable

* Multiple error