> ## Documentation Index
> Fetch the complete documentation index at: https://segmentflow.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create or update catalog products in a batch

> Creates or updates up to 100 products by your product IDs. The batch is saved as a whole: when one product is invalid, none are saved. Products are keyed by your store's own product ID within the API source, so sending the same ID again updates the product instead of adding another. Retries are safe.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/catalog-products/batch
openapi: 3.0.3
info:
  title: SegmentFlow.ai API
  description: Unified SegmentFlow.ai API documentation
  version: 1.0.0
servers:
  - url: http://localhost:3001
    description: Local development
  - url: https://api-staging.segmentflow.ai
    description: Staging
  - url: https://api.segmentflow.ai
    description: Production
security:
  - apiKeyAuth: []
tags:
  - name: Profiles
    description: Profiles (Contacts)
  - name: Events
    description: Server-side business event tracking
  - name: Assets
    description: Assets
  - name: BackgroundJobs
    description: Background job progress
  - name: Brand-Kit
    description: Brand kits
  - name: Catalog-Products
    description: Catalog products
  - name: Templates
    description: Templates
  - name: Broadcasts
    description: Broadcasts
  - name: Segments
    description: Segments
  - name: Subscription-Groups
    description: Subscription groups
  - name: Privacy-Requests
    description: Privacy requests (GDPR data exports and erasures)
  - name: Journeys
    description: Journeys
  - name: Emails
    description: Email sends
paths:
  /api/v1/catalog-products/batch:
    post:
      tags:
        - Catalog-Products
      summary: Create or update catalog products in a batch
      description: >-
        Creates or updates up to 100 products by your product IDs. The batch is
        saved as a whole: when one product is invalid, none are saved. Products
        are keyed by your store's own product ID within the API source, so
        sending the same ID again updates the product instead of adding another.
        Retries are safe.
      operationId: Catalog-Products_CatalogProducts_BatchUpsert
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                products:
                  minItems: 1
                  maxItems: 100
                  type: array
                  items:
                    type: object
                    properties:
                      title:
                        type: string
                        minLength: 1
                        maxLength: 500
                      description:
                        description: >-
                          Plain text or the store's HTML description. HTML is
                          stored as plain text.
                        nullable: true
                        anyOf:
                          - type: string
                            maxLength: 20000
                          - type: string
                            enum:
                              - ''
                      status:
                        default: active
                        description: >-
                          `active` products can appear in emails. `hidden`
                          products stay in the catalog but out of emails.
                          `archived` products leave the catalog.
                        type: string
                        enum:
                          - active
                          - hidden
                          - archived
                      price:
                        type: string
                        minLength: 1
                        maxLength: 50
                        pattern: ^\d+(?:\.\d+)?$
                        example: '19.90'
                      compareAtPrice:
                        description: The price before a discount, shown struck through.
                        nullable: true
                        anyOf:
                          - type: string
                            minLength: 1
                            maxLength: 50
                            pattern: ^\d+(?:\.\d+)?$
                          - type: string
                            enum:
                              - ''
                      currency:
                        type: string
                        enum:
                          - USD
                          - EUR
                          - GBP
                          - CAD
                          - AUD
                          - NZD
                          - SEK
                          - NOK
                          - DKK
                          - CHF
                          - PLN
                          - CZK
                          - JPY
                      productUrl:
                        type: string
                        maxLength: 2000
                        format: uri
                        description: The product page that product cards in emails link to.
                      imageUrl:
                        description: >-
                          The product's main image. Segmentflow shows it from
                          this URL and copies it only when an email needs its
                          own copy.
                        nullable: true
                        anyOf:
                          - type: string
                            maxLength: 2000
                            format: uri
                          - type: string
                            enum:
                              - ''
                      category:
                        nullable: true
                        anyOf:
                          - type: string
                            minLength: 1
                            maxLength: 200
                          - type: string
                            enum:
                              - ''
                      tags:
                        default: []
                        maxItems: 50
                        type: array
                        items:
                          type: string
                          minLength: 1
                          maxLength: 100
                      sku:
                        nullable: true
                        anyOf:
                          - type: string
                            minLength: 1
                            maxLength: 200
                          - type: string
                            enum:
                              - ''
                      externalId:
                        type: string
                        minLength: 1
                        maxLength: 255
                        description: >-
                          Your store's own product ID, without control
                          characters. Sending the same ID again updates the
                          product.
                        example: '8812345'
                    required:
                      - title
                      - price
                      - currency
                      - productUrl
                      - externalId
              required:
                - products
        required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  created:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  updated:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        externalId:
                          type: string
                        id:
                          type: string
                          format: uuid
                          pattern: >-
                            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        outcome:
                          type: string
                          enum:
                            - created
                            - updated
                      required:
                        - externalId
                        - id
                        - outcome
                      additionalProperties: false
                required:
                  - success
                  - created
                  - updated
                  - results
                additionalProperties: false
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded. Wait for `Retry-After` seconds, then retry.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Requests allowed in the current window.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Requests left in the current window.
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until the current window resets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        errorCode:
          description: >-
            Stable machine-readable error code. SDKs map this to typed exception
            classes.
          example: TEMPLATE_NAME_EXISTS
          allOf:
            - $ref: '#/components/schemas/SegmentflowErrorCode'
        message:
          type: string
          description: >-
            Human-readable error message. May change between releases; do not
            parse.
          example: Template name 'Hello' already exists in this organization.
        details:
          description: >-
            Optional structured detail. `issues` carries per-field validation
            problems; other keys are reserved.
          type: object
          properties:
            issues:
              type: array
              items:
                $ref: '#/components/schemas/ErrorIssue'
          additionalProperties:
            description: Any JSON value.
            nullable: true
      required:
        - errorCode
        - message
      additionalProperties: false
      description: 'Canonical error envelope (ADR-0008): `{ errorCode, message, details? }`.'
    RateLimitedErrorResponse:
      type: object
      properties:
        errorCode:
          type: string
          enum:
            - RATE_LIMITED
          description: The request was rejected by an API rate limit.
          example: RATE_LIMITED
        message:
          type: string
          description: >-
            Human-readable error message. May change between releases; do not
            parse.
          example: Rate limit exceeded. Retry after 12 seconds.
        details:
          type: object
          properties:
            retryAfterSeconds:
              type: integer
              minimum: 0
              maximum: 9007199254740991
              description: >-
                Seconds to wait before retrying. Matches the `Retry-After`
                response header.
              example: 12
          required:
            - retryAfterSeconds
          additionalProperties: false
          description: When the client may retry.
      required:
        - errorCode
        - message
        - details
      additionalProperties: false
      description: >-
        429 error envelope (ADR-0008) sent when an API rate limit rejects the
        request.
    SegmentflowErrorCode:
      type: string
      enum:
        - BAD_REQUEST
        - UNAUTHORIZED
        - FORBIDDEN
        - NOT_FOUND
        - CONFLICT
        - GONE
        - UNPROCESSABLE_ENTITY
        - PAYLOAD_TOO_LARGE
        - TOO_MANY_REQUESTS
        - VALIDATION_ERROR
        - RATE_LIMITED
        - INTERNAL_ERROR
        - NOT_IMPLEMENTED
        - SERVICE_UNAVAILABLE
        - DATABASE_ERROR
        - IDEMPOTENCY_KEY_TOO_LONG
        - IDEMPOTENCY_KEY_REUSED
        - IDEMPOTENCY_IN_FLIGHT
        - JOURNEY_NOT_FOUND
        - JOURNEY_WRONG_ENTRY_NODE
        - JOURNEY_MISSING_RECIPIENT_EMAIL
        - JOURNEY_MISSING_REQUIRED_VARIABLES
        - JOURNEY_RECIPIENT_ERASED
        - BROADCAST_NOT_FOUND
        - BROADCAST_SCHEDULING_NOT_IMPLEMENTED
        - BROADCAST_INVALID_STATE
        - BROADCAST_SEND_NOT_ALLOWED
        - PREPARED_SEND_NOT_FOUND
        - PREPARED_SEND_EXPIRED
        - PREPARED_SEND_CROSS_USER
        - PREPARED_SEND_CORRUPT
        - PREPARED_SEND_CONCURRENT_REDEEM
        - PREPARED_SEND_VALIDATION_FAILED
        - SEGMENT_COUNT_CHANGED
        - NAME_TAKEN
        - DRAFT_CHANGED
        - DASHBOARD_EDITOR_REQUIRED
        - TEMPLATE_NOT_FOUND
        - TEMPLATE_NAME_EXISTS
        - TEMPLATE_GROUP_NOT_FOUND
        - TEMPLATE_GROUP_IN_USE
        - PROFILE_NOT_FOUND
        - PROFILE_SUBSCRIPTION_GROUP_NOT_FOUND
        - PROFILE_TRAITS_WRITE_UNSUPPORTED
        - PROFILE_PROPERTY_VALUE_INVALID
        - PROFILE_PROPERTY_NOT_EDITABLE
        - BULK_OPERATION_NOT_UNDOABLE
        - ANALYSIS_ALREADY_USED
        - ANALYSIS_EXPIRED
        - IMPORT_PLAN_INVALID
        - MISSING_CREDENTIAL
        - INVALID_API_KEY
        - INVALID_OAUTH_TOKEN
        - AMBIGUOUS_CREDENTIAL
        - INSUFFICIENT_SCOPE
        - MULTIPLE_CREDENTIALS_PRESENT
        - BEARER_CREDENTIAL_REMOVED
        - SESSION_ROLE_INSUFFICIENT
        - API_KEY_SCOPE_INSUFFICIENT
        - BILLING_DISABLED
        - BILLING_NOT_CONFIGURED
        - EMAIL_NOT_VERIFIED
        - ORGANIZATION_SUSPENDED
        - AI_ALLOWANCE_EXHAUSTED
        - WARMING_REQUIRED
        - WARMING_CAPACITY_EXHAUSTED
        - WARMING_NOT_REQUIRED
      description: >-
        Stable machine-readable error code. SDK codegen maps these to typed
        exception classes.
    ErrorIssue:
      type: object
      properties:
        path:
          anyOf:
            - type: string
            - type: array
              items:
                anyOf:
                  - type: string
                  - type: number
          description: >-
            Where in the request the issue occurred. String for simple paths;
            array for nested paths.
          example: name
        code:
          type: string
          description: >-
            Stable, machine-readable kind of issue (e.g. 'required',
            'invalid_type').
          example: duplicate
        message:
          type: string
          description: Human-readable description of the issue.
          example: Template name already exists in this organization.
      required:
        - path
        - code
        - message
      additionalProperties: false
      description: A single validation issue inside an error response's `details.issues[]`.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Unified API key for server-side SDK and API integrations

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.