instacart Products API

openapi: 3.2.0
info:
  title: Instacart Products API
  termsOfService: https://www.instacart.com/terms
  version: '1.0'
  description: 'Operations tagged Products across 2 of this provider''s published API definitions: instacart-catalog-api-openapi.yml, instacart-developer-platform-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://connect.instacart.com
  description: Production Server
- url: https://connect.dev.instacart.tools
  description: Development Server
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'
      security:
      - bearerAuth: []
    servers:
    - url: https://connect.instacart.com
      description: Production Server
  /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'
      security:
      - apiKeyAuth: []
    servers:
    - url: https://connect.instacart.com
      description: Production Server
    - url: https://connect.dev.instacart.tools
      description: Development Server
  /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'
      security:
      - apiKeyAuth: []
    servers:
    - url: https://connect.instacart.com
      description: Production Server
    - url: https://connect.dev.instacart.tools
      description: Development Server
components:
  schemas:
    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.
    ProductSubmissionRequest:
      type: object
      required:
      - products
      properties:
        products:
          type: array
          description: The list of products to create or update.
          items:
            $ref: '#/components/schemas/Product'
    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.
    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.
    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'
    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.
    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.
    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.
    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.
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key authentication. Include your API key in the Authorization header.
x-refined-from:
- instacart-catalog-api-openapi.yml
- instacart-developer-platform-api-openapi.yml