openapi: 3.1.0
info:
  title: Instacart Catalog Authentication Items 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: Items
  description: Endpoints for updating item-level attributes such as pricing and availability at specific store locations. Items contain information that can vary from one store to another.
paths:
  /v2/data_ingestion/catalog/item/submission:
    post:
      operationId: submitItems
      summary: Create or update items
      description: Updates or sets item-level attributes for a product at a specific store location. Items contain information that can vary from one retailer store to another, such as pricing, availability, and inventory levels. Changes can take around two to three hours before they are displayed on the storefront.
      tags:
      - Items
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemSubmissionRequest'
      responses:
        '200':
          description: Items submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionResponse'
        '400':
          description: Bad request due to invalid item data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests - rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ItemSubmissionRequest:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          description: The list of items to create or update at specific store locations.
          items:
            $ref: '#/components/schemas/Item'
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
        status:
          type: integer
          description: The HTTP status code.
    Item:
      type: object
      required:
      - product_code
      - store_code
      properties:
        product_code:
          type: string
          description: The retailer's unique product identifier linking this item to its parent product.
        store_code:
          type: string
          description: The retailer's unique store identifier where this item is sold.
        price:
          type: number
          format: double
          description: The current selling price of the item at this store.
          minimum: 0
        sale_price:
          type: number
          format: double
          description: The promotional or sale price, if applicable.
          minimum: 0
        sale_start_date:
          type: string
          format: date
          description: The start date of the sale period.
        sale_end_date:
          type: string
          format: date
          description: The end date of the sale period.
        available:
          type: boolean
          description: Whether the item is currently available for purchase at this store.
        inventory_count:
          type: integer
          description: The current inventory count at this store.
          minimum: 0
        aisle:
          type: string
          description: The store aisle where the item is located.
        shelf:
          type: string
          description: The shelf location within the aisle.
    SubmissionResponse:
      type: object
      properties:
        submission_id:
          type: string
          description: A unique identifier for tracking the submission.
        status:
          type: string
          enum:
          - accepted
          - processing
          - completed
          - failed
          description: The current status of the submission.
        submitted_count:
          type: integer
          description: The number of records submitted.
        errors:
          type: array
          description: Any validation errors found in the submitted data.
          items:
            type: object
            properties:
              index:
                type: integer
                description: The index of the record with the error.
              message:
                type: string
                description: The error message describing the issue.
  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/