> ## 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 a catalog product by your product ID

> Creates the product, or replaces its fields when a product with this ID already exists. Fields you leave out are cleared, except `status`, which becomes `active`. 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 put /api/v1/catalog-products/by-external-id/{externalId}
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/by-external-id/{externalId}:
    put:
      tags:
        - Catalog-Products
      summary: Create or update a catalog product by your product ID
      description: >-
        Creates the product, or replaces its fields when a product with this ID
        already exists. Fields you leave out are cleared, except `status`, which
        becomes `active`. 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_Upsert
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            example: '8812345'
          in: path
          name: externalId
          required: true
          description: >-
            Your store's own product ID, without control characters. Sending the
            same ID again updates the product.
      requestBody:
        content:
          application/json:
            schema:
              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:
                        - ''
              required:
                - title
                - price
                - currency
                - productUrl
        required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  outcome:
                    type: string
                    enum:
                      - created
                      - updated
                  data:
                    $ref: '#/components/schemas/ExternalProductResponse'
                required:
                  - success
                  - outcome
                  - data
                additionalProperties: false
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  outcome:
                    type: string
                    enum:
                      - created
                      - updated
                  data:
                    $ref: '#/components/schemas/ExternalProductResponse'
                required:
                  - success
                  - outcome
                  - data
                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:
    ExternalProductResponse:
      type: object
      properties:
        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)$
        externalId:
          nullable: true
          type: string
        source:
          type: string
          enum:
            - shopify
            - woocommerce
            - manual
            - api
        status:
          type: string
          enum:
            - active
            - hidden
            - archived
        title:
          type: string
        handle:
          nullable: true
          type: string
        description:
          nullable: true
          type: string
        price:
          type: string
        compareAtPrice:
          nullable: true
          type: string
        currency:
          nullable: true
          type: string
        primaryImageId:
          nullable: true
          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)$
        primaryImageUrl:
          nullable: true
          type: string
        primaryImageExternalId:
          nullable: true
          type: string
        primaryImageAltText:
          nullable: true
          type: string
        primaryImageIssue:
          nullable: true
          type: object
          properties:
            code:
              type: string
              enum:
                - size_exceeded
                - download_failed
                - invalid_content_type
                - ssrf_rejected
                - fetch_error
            message:
              type: string
            sourceUrl:
              nullable: true
              type: string
            occurredAt:
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            details:
              type: object
              additionalProperties:
                description: Any JSON value.
                nullable: true
          required:
            - code
            - message
            - occurredAt
          additionalProperties: false
        imageIds:
          type: array
          items:
            type: string
        galleryImages:
          type: array
          items:
            type: object
            properties:
              externalId:
                nullable: true
                type: string
              url:
                type: string
              altText:
                nullable: true
                type: string
              position:
                type: integer
                minimum: 0
                maximum: 9007199254740991
            required:
              - externalId
              - url
              - altText
              - position
            additionalProperties: false
        productUrl:
          nullable: true
          type: string
        category:
          nullable: true
          type: string
        tags:
          type: array
          items:
            type: string
        sku:
          nullable: true
          type: string
        vendor:
          nullable: true
          type: string
        featured:
          type: boolean
        lastSyncedAt:
          nullable: true
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
        updatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
      required:
        - id
        - externalId
        - source
        - status
        - title
        - handle
        - description
        - price
        - compareAtPrice
        - currency
        - primaryImageId
        - primaryImageUrl
        - primaryImageExternalId
        - primaryImageAltText
        - primaryImageIssue
        - imageIds
        - galleryImages
        - productUrl
        - category
        - tags
        - sku
        - vendor
        - featured
        - lastSyncedAt
        - createdAt
        - updatedAt
      additionalProperties: false
      description: >-
        Unified API catalog product response without organization-internal
        fields.
    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.