openapi: 3.1.0
info:
  title: Instacart Catalog Authentication Products 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: Products
  description: Endpoints for creating and updating products in the retailer's catalog on Instacart. Products are the same across all of a retailer's stores.
paths:
  /v2/data_ingestion/catalog/product/submission:
    post:
      operationId: submitProducts
      summary: Create or update products
      description: Creates new products or updates existing products in the retailer's catalog on Instacart. When creating a new product, it takes 1-3 business days for the product to be displayed on the storefront. When updating a product, only the attributes included in the request body are modified and changes are displayed within a few hours.
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductSubmissionRequest'
      responses:
        '200':
          description: Products submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionResponse'
        '400':
          description: Bad request due to invalid product 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'
  /idp/v1/products/products_link:
    post:
      operationId: createShoppingListPage
      summary: Create a shopping list page
      description: Creates a shopping list page on Instacart Marketplace and returns a unique URL. The page displays a list of products that users can add to their Instacart cart. Each call generates a new page with a unique URL.
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShoppingListRequest'
      responses:
        '200':
          description: Shopping list page created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsLinkResponse'
        '400':
          description: Bad request due to invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '429':
          description: Too many requests - rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
  /idp/v1/products/recipe:
    post:
      operationId: createRecipePage
      summary: Create a recipe page
      description: Creates a recipe page on Instacart Marketplace and returns a unique URL. The page displays recipe details including title, image, ingredients, and cooking instructions. Users can add recipe ingredients to their Instacart cart directly from the page.
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipeRequest'
      responses:
        '200':
          description: Recipe page created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductsLinkResponse'
        '400':
          description: Bad request due to invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '429':
          description: Too many requests - rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
components:
  schemas:
    Ingredient:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the ingredient.
        display_text:
          type: string
          description: Custom display text for the ingredient on the recipe page.
        product_ids:
          type: array
          description: Instacart product identifiers to match specific products.
          items:
            type: string
        upcs:
          type: array
          description: Universal Product Codes to match specific products.
          items:
            type: string
        measurements:
          type: object
          description: Measurement details for the ingredient.
          properties:
            amount:
              type: number
              description: The measurement amount.
            unit:
              type: string
              description: The measurement unit.
        filters:
          type: object
          description: Filters to narrow product matching for this ingredient.
          properties:
            department:
              type: string
              description: The store department to filter products by.
    Error_2:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message describing what went wrong.
        status:
          type: integer
          description: The HTTP status code of the error response.
    ProductSubmissionRequest:
      type: object
      required:
      - products
      properties:
        products:
          type: array
          description: The list of products to create or update.
          items:
            $ref: '#/components/schemas/Product'
    RecipeRequest:
      type: object
      required:
      - title
      - ingredients
      properties:
        title:
          type: string
          description: The title of the recipe displayed on the recipe page.
        image_url:
          type: string
          format: uri
          description: URL of an image to display for the recipe.
        author:
          type: string
          description: The name of the recipe author.
        servings:
          type: integer
          description: The number of servings the recipe makes.
          minimum: 1
        cooking_time:
          type: string
          description: The estimated cooking time for the recipe.
        external_reference_id:
          type: string
          description: An external identifier for the recipe from the partner system.
        content_creator_credit_info:
          type: object
          description: Information for crediting the content creator on the recipe page.
          properties:
            name:
              type: string
              description: The name of the content creator.
            url:
              type: string
              format: uri
              description: URL to the content creator's website or profile.
        expires_in:
          type: integer
          description: The number of seconds until the generated recipe link expires.
          minimum: 1
        instructions:
          type: array
          description: Step-by-step cooking instructions for the recipe.
          items:
            type: string
        ingredients:
          type: array
          description: The list of ingredients required for the recipe.
          items:
            $ref: '#/components/schemas/Ingredient'
    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.
    ProductsLinkResponse:
      type: object
      properties:
        products_link_url:
          type: string
          format: uri
          description: The unique URL to the generated shopping list or recipe page on Instacart Marketplace.
    ShoppingListRequest:
      type: object
      required:
      - title
      - line_items
      properties:
        title:
          type: string
          description: The title displayed at the top of the shopping list page.
        image_url:
          type: string
          format: uri
          description: URL of an image to display on the shopping list page.
        link_type:
          type: string
          description: The type of product link to create.
        expires_in:
          type: integer
          description: The number of seconds until the generated link expires.
          minimum: 1
        instructions:
          type: string
          description: Additional instructions or notes to display on the page.
        line_items:
          type: array
          description: The list of products to include on the shopping list page.
          items:
            $ref: '#/components/schemas/LineItem'
        landing_page_configuration:
          type: object
          description: Configuration options for the landing page appearance and behavior.
          properties:
            partner_linkback_url:
              type: string
              format: uri
              description: URL to link back to the partner site from the landing page.
    Product:
      type: object
      required:
      - product_code
      - name
      properties:
        product_code:
          type: string
          description: The retailer's unique product identifier used to match the product in the Instacart system.
        name:
          type: string
          description: The display name of the product.
        brand:
          type: string
          description: The brand name of the product.
        description:
          type: string
          description: A detailed description of the product.
        size:
          type: string
          description: The size or quantity description of the product.
        upc:
          type: string
          description: The Universal Product Code for the product.
        image_url:
          type: string
          format: uri
          description: URL to the primary product image.
        category:
          type: string
          description: The product category in the retailer's taxonomy.
        subcategory:
          type: string
          description: The product subcategory.
        department:
          type: string
          description: The store department the product belongs to.
        attributes:
          type: object
          description: Additional product attributes such as dietary information or certifications.
          additionalProperties:
            type: string
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
        status:
          type: integer
          description: The HTTP status code.
    LineItem:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the product.
        quantity:
          type: number
          description: The quantity of the product to add.
          minimum: 1
        unit:
          type: string
          description: The unit of measurement for the quantity.
        display_text:
          type: string
          description: Custom display text for the line item on the page.
        product_ids:
          type: array
          description: Instacart product identifiers to match specific products.
          items:
            type: string
        upcs:
          type: array
          description: Universal Product Codes to match specific products.
          items:
            type: string
        line_item_measurements:
          type: object
          description: Measurement details for the line item.
          properties:
            amount:
              type: number
              description: The measurement amount.
            unit:
              type: string
              description: The measurement unit.
        filters:
          type: object
          description: Filters to narrow product matching.
          properties:
            department:
              type: string
              description: The store department to filter products by.
  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/