Changelog - Fulfillment

The changelog summarizes the updates and enhancements made to the Instacart Connect Fulfillment API. The most recent changes are listed first.

All updates and enhancements listed here are non-breaking changes, which means that your applications will continue to run without you having to take any action. However, a non-breaking change might occasionally introduce a noticeable difference in behavior. For example, if an update adds new validations to a Service Options request, the API might begin to return an error for a request that would have been accepted previously. We recommend that you review enhancements regularly, and consider whether to update your applications accordingly to optimize your Connect integration.

May 12, 2025

• Added the delivery_photo_url to the Delivered callback event.

April 30, 2025

• Added the scan_codes field to the OrderItem object in event callbacks.

April 4, 2025

• Updated the Callback descriptions and Object descriptions sections in Event callbacks (webhooks).

March 21, 2025

• Increased the weight limit on big and bulky items.

March 10, 2025

• Updated the guidance in Customer communications on obtaining a customer's consent to receive SMS messages.

February 13, 2025

• Added details about the order status precondition in the following operations:
  • Update an order
  • Update a last mile delivery order
  • Update a dispatch last mile delivery order
  • Cancel an order
  • Cancel a dispatch last mile delivery order

February 11, 2025

• Added information on modifying items in the Update an order request.

February 10, 2025

• Added an APIs Overview tile to the Instacart Connect APIs homepage.

February 5, 2025

• Added the flags.long_distance_delivery field to the List time slots for last mile delivery response.

January 27, 2025

• Added information about conditional count and weight requirements in the following requests:
  • List time slots for delivery
  • List time slots for pickup
  • Create a delivery order
  • Create a pickup order

January 24, 2025

• On certain pages that group topics by category, such as Concepts and Account linking, the following changes have been made:
  • Fixed the Next button so that it now advances users to the next page.
  • Added cards that summarize and link to each of the category's topic pages.

January 21, 2025

• Added the option to include the retailer_id field in all callbacks. For more information, see Event callbacks.

January 9, 2025

• Added information about conditional phone number requirements in the create delivery order and create pickup order requests.

December 20, 2024

• Updated the guidance for how to use preview time slots.

December 19, 2024

• Added a description of the requests that accept desired windows.

November 21, 2024

• Added the initial order, unsubscribed, information requested, and help requested SMS types to Customer communications.

November 18, 2024

• Removed asap and added priority_eta as a possible service_options[].window.type value in the response to the following requests:
  • Preview time slots for delivery
  • Preview time slots for pickup
  • Preview time slots for last mile delivery
  • List time slots for delivery
  • List time slots for pickup
  • List time slots for last mile delivery

October 10, 2024

• Added the delivery_window field to the Brand New callback event.

April 23, 2024

• Added the bag_label field to the At store ETA callback event.

March 19, 2024

• Added the Some items are not deliverable error to the List time slots for delivery and Create Order endpoints.

February 29, 2024

• Added a checkout callback event.
• Added the following fields to the OrderItem object returned for checkout callbacks:
  • delivered_item_rrc
  • delivered_item_upc
  • requested_item_rrc
  • requested_item_upc

January 16, 2024

• Added the Duplicate items were provided error to the List time slots for pickup endpoint.
• Added an example for a response with warnings to the List time slots for pickup endpoint.

December 13, 2023

• Updated the Invalid items error code from 1001 to 2000 for the List time slots for delivery endpoint.

November 30, 2023

• Added a new error case for when the total weight of the items in your cart exceeds the maximum limit for a single delivery. The error was added to the following endpoints:
  • Create order
  • Update order
  • List time slots for delivery

November 15, 2023

• Added a new error case to Generate an access token and Revoke an access token for when you provide credentials as query parameters.

November 2, 2023

• Create order, Update order, and List time slots for delivery requests now return an error if the request body specifies an order containing items that exceed any of the following limits:
  • Maximum total quantity of items
  • Maximum total weight of beverage items
  • Maximum quantity of large or bulky items

August 22, 2023

• Connect now offers big and bulky item fulfillment. For more information, see Big and bulky.

  • Added the following customer notifications for big and bulky orders: order confirmation, delivery started, and shopper arriving.
  • Added the order_created_with_big_bulky field to the brand new and delivering callbacks.

• Updated documentation to provide more detail about support for the integer data type. For more information, see Data formats.

August 18, 2023

• Connect now offers certified delivery. For more information, see Certified delivery.
• Added the is_certified_delivery field to the following callbacks: brand new, delivering, and delivered.

August 14, 2023

• Updated documentation to provide more information about HTTP headers, including the following changes:
  • Added the Request headers section, and updated the Authentication section in the API Reference topic.
  • Added the Request headers topic.

August 2, 2023

• Added the has_partner_picker_shopper field to the delivered callback.

July 12, 2023

• Added information about stores being sorted by distance to customer to the following endpoints:
  • Find stores offering delivery
  • Find stores offering pickup
  • Find stores offering last mile delivery

July 6, 2023

• Added a new error case to Update order when it's too late to update an order.

June 30, 2023

• Updated the wording of some SMS notifications to reflect what is currently sent.

June 26, 2023

• Updated the wording of some SMS notifications to reflect what is currently sent.

May 26, 2023

• Added the city field to the Find stores offering last mile delivery endpoint.

May 15, 2023

• Enhanced the last mile delivery endpoint to support asynchronous order creation. For more information, see How to asynchronously create a last mile delivery order.

March 31, 2023

• Instacart Care is now called Instacart Customer Experience. Updated the site to make this change.

March 10, 2023

• Added the desired_windows field to the following endpoints:
  • Preview time slots for delivery
  • Preview time slots for last mile delivery
  • List time slots for last mile delivery

February 7, 2023

• Added the bag_scan_codes field to the Stage a last mile delivery order endpoint.

December 22, 2022

• Added best practices for sending credentials with the access token endpoints. For more information, see Generate an access token and Revoke an access token.

December 15, 2022

• Added a note about available callbacks for dispatch last mile delivery. For more information, see Event callbacks.
• Documented best practices for using preview time slots in the following topics:
  • Preview time slots
  • Preview time slots for delivery
  • Preview time slots for pickup
  • Preview time slots for last mile delivery

November 25, 2022

• Deprecated the get orders endpoint. For more information about deprecated endpoints, see Deprecated. For more information about Instacart's deprecation policy, see Deprecation policy.
• Removed the deprecated single-call last mile delivery endpoints. For a simpler last mile delivery implementation, use the Dispatch last mile delivery endpoints instead. For more information, see Implement dispatch last mile delivery.

November 7, 2022

• Updated the examples used in How to send your desired windows.

October 31, 2022

• Connect now offers the ability to send your desired delivery windows for delivery orders. For more information, see Desired windows and How to send your desired windows.
  • Added the desired windows object to the List time slots for delivery endpoint.
  • Added the Reserve a time slot for a desired window endpoint.

October 26, 2022

• Fixed an issue with the Late Delivery SMS only being sent if both the SMS and email were enabled.
• Updated documentation to clarify that the Late Delivery (No ETA) SMS is only sent for pickup orders. For more information, see customer notifications.

October 20, 2022

• In response to retailer feedback, we are restoring and enhancing the single-call last mile delivery endpoint. This fulfillment option is now called dispatch last mile delivery (dispatch LMD). For more information, see Dispatch last mile delivery, Dispatch last mile delivery user journey, and Implement dispatch last mile delivery.
  • Use the following endpoints to create and manage dispatch LMD orders:
    • Create a dispatch last mile delivery order
    • Find stores offering dispatch last mile delivery
    • Stage a dispatch last mile delivery order
    • Get a dispatch last mile delivery order
    • Update a dispatch last mile delivery order
    • Cancel a dispatch last mile delivery order

September 14, 2022

• Added documentation about the reasons for unavailability of service options to following service option endpoints:
  • List time slots for delivery
  • List time slots for pickup
  • List time slots for last mile delivery
  • Reserve a time slot
  • Preview time slots for delivery
  • Preview time slots for pickup
  • Preview time slots for last mile delivery

August 31, 2022

• Deprecated the reserve a previewed time slot endpoint. To reserve a time slot, use the reserve a time slot endpoint instead. For more information about Instacart's deprecation policy, see Deprecation policy.

August 18, 2022

• Added the shopper_provided_item_name and shopper_provided_item_price fields to the delivered callback and the responses for get an order and get orders. For more information, see Shopper-provided item details.

August 17, 2022

• Released the Fulfillment Testing Center and documentation. For more information, see Fulfillment Testing Center. For more information about testing, see Testing.

August 16, 2022

• Updated the description for the reasons field of the availability object. The description lists the reasons for unavailability of a service option and states that the unavailability reasons are subject to change without notice. This change affects the Availability object in the Response sections of Service option preview and Service option cart endpoints. For more information, see Service options.

July 7, 2022

• Updated description for invalid_grant authentication error. For more information, see Generate an access token and Generate a linking token.

June 29, 2022

• Deprecated Express membership fields in favor of Instacart+ fields. For more information, see Instacart+ membership and event callbacks:
  • Deprecated express_member in favor of instacartplus_member.
  • Deprecated is_express in favor of is_instacartplus.
  • Deprecated applied_express in favor of applied_instacartplus.

June 24, 2022

• Renamed the Instacart Partner Platform application to Instacart Platform Portal. For more information, see Instacart Platform Portal.

June 22, 2022

• Removed support and documentation of the status_link field. Use the pickup_link in the staged event callback instead.

June 17, 2022

• Added the bag_label field to the following last mile delivery endpoints:
  • Create a last mile delivery order
  • Update a last mile delivery order
  • Stage a last mile delivery order

June 14, 2022

• Renamed the Express membership to Instacart+ membership. For more information, see Instacart+ membership.

June 8, 2022

• Updated the Instacart login page that appears when your customers link their Instacart account. For more information, see Account linking.
• Updated the Instacart login page URL.
• Deprecated the previous Instacart login page URL.

June 3, 2022

• Added the After an order is completed section to the Implement delivery tutorial.
• Added the After an order is completed section to the Implement last mile delivery tutorial.

May 6, 2022

• Added order feedback endpoints. For more information about order feedback, see Order feedback. For backend implementations, see Create or update order feedback (backend). For frontend implementations, see Create or update order feedback (frontend).
• Added callback events for order feedback. Callbacks added are the rating updated and rating reminder callbacks.

April 11, 2022

• Deprecated using only a postal code to find stores offering last mile delivery.

April 8, 2022

• Added the qty_fulfilled and substitution_status fields to all order event callbacks that contain items.
• Connect now reports the expiration date of Express memberships. Also, Connect flags orders placed by Express members to help invoicing teams identify Express orders. For more information, see Express memberships and How to verify Express membership and orders.
  • Added the expired_at field to the get Instacart account information response.
  • Added the is_express field to the following callbacks: acknowledged, brand new, delivered, and staged.
  • Added the is_express field to the responses for create a delivery order, get orders, and get an order.

April 5, 2022

• Upcoming policy change Instacart is improving the quality of fulfillment networks and shoppers by changing how long customers have to adjust their tip.

  • The time to decrease a tip is changing from 24 hours to 2 hours.
  • The time to increase a tip is changing from 24 hours to 14 days.

This policy change is effective as of May 1, 2022. If your site currently allows customers to decrease tips after 2 hours, Connect will continue to support the existing functionality until Nov 1, 2022.

March 2, 2022

• Connect now offers time-sensitive last mile delivery of orders, such as order ahead meals. To enable time-sensitive last mile delivery, Instacart calculates the handoff time, which is the estimated time of arrival of the Instacart Shopper at the store. For more information, see Order ahead meals and How to support time-sensitive last mile delivery. The with_handoff_time field was added to the following endpoints:
  • Preview time slots for last mile delivery
  • List time slots of last mile delivery
  • Create a last mile delivery order

February 15, 2022

• Added store_location to all order event callbacks.

February 1, 2022

• Clarified the scheduled service option definition to state that time slot duration and availability might vary.

January 28, 2022

• Added an order_location callback event.

January 6, 2022

• Added the Revoke an access token endpoint. Renamed the Authentication topic to Generate an access token to be parallel with the new topic.

December 14, 2021

• Fixed the Event callbacks topic to indicate that all callbacks are optional. Previously, the topic incorrectly stated that some callbacks were always enabled.

November 30, 2021

• Added the following optional callbacks to support the pickup flow:
  • Customer acknowledged
  • Pickup runner started
  • Unable to find customer
  • Runner not found
  • Pickup Geofence reached

November 12, 2021

• Added the pos_payment_method field to the get an order response.
• Added the pos_payment_method field to the following callbacks: canceled, delivered, and delivering

November 9, 2021

• Added an at_store_eta event for last mile delivery orders.

November 8, 2021

• Connect now offers delivery or pickup for over-the-counter medication that doesn't contain a prohibited controlled substance. To enable this capability, contact your Instacart representative. For more information, see Over-the-counter medication.
• Removed redundant 200 HTTP response status code examples.

November 4, 2021

• Updated the Update order endpoint so that if alcohol is added to the order, the leave_unattended parameter is set to false automatically.

October 25, 2021

• Connect now offers the same long distance delivery areas as Marketplace for deliveries that take from 30 to 60 minutes. For more information, see Service areas for delivery. To add long distance delivery areas for your stores, contact your Instacart representative. The long_distance_delivery flag was added to the following endpoints:
  • Create a user and validate an address
  • Find stores for delivery
  • List time slots for delivery
  • Find stores for last mile delivery
  • List time slots for last mile delivery

October 22, 2021

• Added a scope field to the authentication request. The scope restricts a generated token to the specified APIs. For more information, see Generate an access token and Permissions and scopes.

October 21, 2021

• Added the priority ETA service option to the delivery and last mile delivery workflows. For more information, see Service options, How to retrieve ETA time slots, List time slots for delivery, and List time slots for last mile delivery.

October 15, 2021

• Added the ability to search by postal_code only to Find stores offering last mile delivery.

October 6, 2021

• Added the ETA service option for last mile delivery. For more information, see Service options and How to retrieve an ETA time slot.

September 24, 2021

• Added the earliest_option_start_at field to Preview time slots for last mile delivery and List time slots for last mile delivery. You can now indicate the earliest time when an order can be ready. The time slots you retrieve occur after this earliest time.
• Added the units_count field to Preview time slots for last mile delivery and List time slots for last mile delivery. Use the units_count field to represent how many items are in the order and use the items_count field to represent how many types of items are in the order.

September 23, 2021

• Added delivery_eta field to the Delivering Callback Event.

September 13, 2021

• Added last mile delivery endpoints with URIs that are consistent in format with the delivery and pickup URIs. This change reflects our commitment to making our API more intuitive to use when implementing multiple fulfillment workflows in your ecommerce site.
  • Create user and validate an address
  • Find stores offering last mile delivery
  • Preview time slots for last mile delivery
  • List time slots for last mile delivery
  • Create a last mile delivery order
  • Update a last mile delivery order
  • Stage a last mile delivery order
• Deprecated the existing last mile delivery endpoints. The deprecated endpoints are still supported for existing implementations. For new implementations, use the revised endpoints.

August 23, 2021

• Added the Connect Orders view for last mile deliveries to the Instacart Partner Platform (also known as Instacart Retailer Platform). Select an order to view tracking information and order details.

August 16, 2021

• Added the ETA service option for delivery. The estimated time of arrival (ETA) is the time by which the customer can expect to receive their order. For more information, see Service options and How to retrieve an ETA time slot.

August 11, 2021

• Implemented rate limiting.

July 16, 2021

• Removed the descriptions for Items object and Item object from the Response sections of the last mile delivery topics. These objects are not applicable to the last mile delivery order endpoints.

July 14, 2021

• Added a type field to the service option windows. The field makes it easier to distinguish the type of service option being returned. Example: delivery get cart service options.

July 12, 2021

• Connect now uses the same smart service areas as Marketplace for deliveries under 30 minutes. Smart service areas are calculated based on the store location, delivery location, and other factors.
• Added callback events that improve partner integrations with our last mile delivery offering. Callbacks added are: at_store, acknowledged_for_delivery, bags_verified, arrival_at_customers. For more information about these callbacks, see Event callbacks.

July 9, 2021

• Added support for customizing the text in SMS messages. For more information about options for communicating with customers, see Customer communications.

July 5, 2021

• Added support for start_at and end_at window in multiple call last mile order creation.

June 28, 2021

• Added support for user data deletion requests.

June 17, 2021

• Added order_url to all order event callbacks.
• Deprecated status_link in favor of pickup_link in the staged event callback.

June 8, 2021

• Added requested_item_upc, requested_item_rrc, delivered_item_upc, and delivered_item_rrc to order item replacement callback.

June 4, 2021

• Documented additional HTTP 400 Bad Request responses related to failed alcohol compliance checks for create order, update order, create pickup order, create last mile delivery order, update last mile delivery order, list time slots for pickup, and reserve previewed time slot.
• Added requested_upc, requested_rrc, delivered_upc, and delivered_rrc to order item response.

June 3, 2021

• Specified that the optional locale field for user creation, order creation, and last mile delivery order creation should be provided in IETF Language Tag format (Example: en-US).

May 27, 2021

• Added locale field to create order response.
• Reorganized the documentation to improve clarity. All links have changed; please update your bookmarks.
  • Separated concepts, tutorials, and how-to content from the API content.
  • Reorganized the API content around the core resources.
  • Added a Get an access token tutorial.
  • Merged delivery and pickup versions of the callbacks pages to make it easier to see similarities and differences.
  • Merged delivery and pickup versions of the notifications pages to make it easier to see similarities and differences.

May 19, 2021

• Added status_link field to staged callback for pickup orders.

May 18, 2021

• Added Canadian server names to overview.
• Added locale as an optional param to user creation, order creation, and last mile delivery order creation.

May 17, 2021

• Added customer_mia event to delivery order callbacks.

May 5, 2021

• Added order_item_replacement and order_item_refund callback events for delivery and pickup.
• Added refunded to the OrderItem object for delivery and pickup.
• Updated Order Item Response to include both upc and rrc codes.

April 29, 2021

• Added scan_code to the OrderItem object for delivery and pickup.
• Added new SMS notifications for delivery and pickup.

April 22, 2021

• Updated the last mile create user and address to return existing user_id if one exists.

April 12, 2021

• Added a late_pickup event.
• Renamed delivery_window to new_window for late_delivery and rescheduled events.
• Added a new Reserve a previewed time slot.

April 6, 2021

• Updated Delivery Notifications to include unattended delivery use case.

March 31, 2021

• Added the Pickup User Journey and Compliance. Updated Alcohol Compliance.

March 30, 2021

• Added an sms_opt_in parameter to create delivery order.

March 29, 2021

• Fixed an error that could occur when sending an invalid find_by object to get stores.

March 26, 2021

• Added a tip_adjustment callback event.

March 25, 2021

• Added a Delivery User Journey.

March 22, 2021

• Added item_codes to get service options availability object returned in delivery get cart service options.
• Added support for post-order tip update.

March 17, 2021

• Added delivery_window to the delivering callback event.

March 11, 2021

• Added support for account linking.

March 4, 2021

• Added new error message cases for create delivery order and delivery get cart service options.
• Added a new error case to update order when no phone number is present on user or order.

March 2, 2021

• Updated location_code field to specify location used to look-up items. Used in create delivery order and delivery get cart service options.

February 23, 2021

• Made user.phone_number an optional field for create delivery order, create pickup order, and update order.
• Added order locale support.

February 22, 2021

• Added support for last mile delivery orders.

February 19, 2021

• Changed route for delivery get cart service options.
• Changed route for pickup get cart service options.
• Changed route for delivery get stores.

February 17, 2021

• Added documentation for preview delivery service options.
• Added documentation for preview pickup service options.

February 8, 2021

• Added documentation for localization.
• Added new SMS notifications for delivery.

February 5, 2021

• Added support for searching by postal code only in the Get pickup stores request.

February 4, 2021

• Added cancellation_reason to the Get order response.

January 21, 2021

• Added documentation for pickup order specific endpoints: Get pickup stores, get pickup cart service options, create pickup order, pickup order callbacks, pickup notifications.

January 18, 2021

• Added documentation for order callbacks.

January 7, 2021

• Added enum support for the replacement_policy field in request and response examples of order related endpoints (Example: order creation).

January 6, 2021

• Added response example for malformed find_by object in get stores.

December 22, 2020

• Made address_line_1 required in get stores when finding by address.

December 18, 2020

• Removed support for search_range_miles in get stores.

December 14, 2020

• Added support for replacement_items in order creation.
• Added support for replacement_policy in order creation and update.

December 2, 2020

• Added changelog.