instacart Orders API

openapi: 3.2.0
info:
  title: Instacart Connect Post-Checkout Orders API
  description: The Instacart Connect Post-Checkout API allows retailers to provide their customers with real-time order tracking and shopper interaction after an order has been placed. Retailers can use this API to build custom order status pages that display order details, live tracking information, and shopper communication. Customers can see updates while their order is being shopped and delivered, approve or decline item replacements suggested by shoppers, and communicate directly with shoppers via chat about replacements and additions.
  version: '2.0'
  contact:
    name: Instacart Connect Support
    url: https://docs.instacart.com/connect/post-checkout/
  termsOfService: https://www.instacart.com/terms
servers:
- url: https://connect.instacart.com
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Orders
  description: Endpoints for retrieving order status, handling details, and item information after checkout.
paths:
  /v2/post_checkout/orders/{order_id}/handling:
    get:
      operationId: getOrderHandling
      summary: Get order handling information
      description: Retrieves handling information for a specific order, including the delivery or pickup address, the coordinates of the delivery or pickup address, information about the current shopper, and any notes or instructions included with the order.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/orderId'
      responses:
        '200':
          description: Order handling details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderHandlingResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/post_checkout/orders/{order_id}/items:
    get:
      operationId: getOrderItems
      summary: Get order items
      description: Retrieves the list of items for a specific order. Each item includes item details of the ordered item, the current status of that item, and the current replacement for that item if one exists. Poll this endpoint while a shopper is picking the order to get real-time item status updates.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/orderId'
      responses:
        '200':
          description: List of order items with their statuses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderItemsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OrderHandlingResponse:
      type: object
      properties:
        order_id:
          type: string
          description: The unique identifier for the order.
        status:
          type: string
          enum:
          - brand_new
          - acknowledged
          - picking
          - staging
          - delivering
          - delivered
          - canceled
          description: The current status of the order.
        address:
          type: object
          description: The delivery or pickup address.
          properties:
            address_line_1:
              type: string
              description: The street address.
            address_line_2:
              type: string
              description: Additional address information.
            city:
              type: string
              description: The city.
            state:
              type: string
              description: The state or province.
            postal_code:
              type: string
              description: The postal or ZIP code.
        coordinates:
          type: object
          description: The geographic coordinates of the delivery or pickup address.
          properties:
            latitude:
              type: number
              format: double
              description: The latitude coordinate.
            longitude:
              type: number
              format: double
              description: The longitude coordinate.
        shopper:
          type: object
          description: Information about the current shopper assigned to the order.
          properties:
            name:
              type: string
              description: The first name of the shopper.
            phone_number:
              type: string
              description: A masked phone number for contacting the shopper.
        notes:
          type: string
          description: Any delivery or pickup instructions included with the order.
    Replacement:
      type: object
      description: Details about the replacement product suggested by the shopper.
      properties:
        product_name:
          type: string
          description: The name of the replacement product.
        product_id:
          type: string
          description: The product identifier of the replacement.
        quantity:
          type: integer
          description: The quantity of the replacement product.
    OrderItemsResponse:
      type: object
      properties:
        items:
          type: array
          description: The list of items in the order with their current statuses.
          items:
            $ref: '#/components/schemas/PostCheckoutOrderItem'
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
        status:
          type: integer
          description: The HTTP status code.
    PostCheckoutOrderItem:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the order item.
        product_name:
          type: string
          description: The name of the ordered product.
        quantity:
          type: integer
          description: The ordered quantity.
        status:
          type: string
          enum:
          - pending
          - found
          - replaced
          - refunded
          - not_found
          description: The current status of the item during shopping.
        replacement:
          $ref: '#/components/schemas/Replacement'
        replacement_status:
          type: string
          enum:
          - PENDING
          - APPROVED
          - REJECTED
          description: The customer's decision on the replacement, if one was suggested.
  parameters:
    orderId:
      name: order_id
      in: path
      required: true
      description: The unique identifier for the order.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token obtained from the access token endpoint. A user access token is required for post-checkout operations.
externalDocs:
  description: Instacart Connect Post-Checkout API Documentation
  url: https://docs.instacart.com/connect/post-checkout/