instacart Chat API

openapi: 3.2.0
info:
  title: Instacart Connect Post-Checkout Chat 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: 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:
  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.
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
        status:
          type: integer
          description: The HTTP status code.
    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
  parameters:
    orderIdChat:
      name: order_id
      in: path
      required: true
      description: The unique identifier for the order in the chat context.
      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/