openapi: 3.1.0
info:
  title: Instacart Catalog Authentication Orders API
  description: The Instacart Catalog API enables retailers to programmatically manage their product catalogs on the Instacart platform. Retailers can use the API to create or update products and items, with partial updates supported so that only the attributes included in the request body are modified. This API is designed for retailers who need to keep their Instacart product listings synchronized with their inventory management systems, ensuring accurate product information, pricing, and availability across the platform.
  version: '2.0'
  contact:
    name: Instacart Catalog Support
    url: https://docs.instacart.com/catalog/catalog_api/overview/
  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:
    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.
    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.
    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.
    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.
  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 using client credentials with the connect:data_ingestion scope.
externalDocs:
  description: Instacart Catalog API Documentation
  url: https://docs.instacart.com/catalog/catalog_api/overview/