openapi: 3.1.0
info:
  title: Instacart Catalog Authentication Chat 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: Chat
  description: Endpoints for shopper-customer communication including sending and retrieving chat messages.
paths:
  /v2/post_checkout/chat/{order_id}/messages:
    get:
      operationId: getChatMessages
      summary: Get chat messages for an order
      description: Retrieves all chat messages associated with an order between the customer and the shopper. Messages are returned in chronological order.
      tags:
      - Chat
      parameters:
      - $ref: '#/components/parameters/orderIdChat'
      responses:
        '200':
          description: List of chat messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMessagesResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: sendChatMessage
      summary: Send a message to the shopper
      description: Sends a chat message from the customer to the shopper associated with the order. Used for communicating about replacements, additions, or delivery instructions.
      tags:
      - Chat
      parameters:
      - $ref: '#/components/parameters/orderIdChat'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
      responses:
        '200':
          description: Message sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMessage'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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:
  parameters:
    orderIdChat:
      name: order_id
      in: path
      required: true
      description: The unique identifier for the order in the chat context.
      schema:
        type: string
  schemas:
    ChatMessage:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the message.
        sender:
          type: string
          enum:
          - customer
          - shopper
          description: Who sent the message.
        body:
          type: string
          description: The text content of the message.
        created_at:
          type: string
          format: date-time
          description: The timestamp when the message was sent.
    ChatMessagesResponse:
      type: object
      properties:
        messages:
          type: array
          description: The list of chat messages in chronological order.
          items:
            $ref: '#/components/schemas/ChatMessage'
    SendMessageRequest:
      type: object
      required:
      - body
      properties:
        body:
          type: string
          description: The text content of the message to send to the shopper.
          maxLength: 1000
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
        status:
          type: integer
          description: The HTTP status code.
  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/