Sequenzy Products API

openapi: 3.2.0
info:
  title: Sequenzy Products API
  description: Sequenzy API for managing subscribers, tags, events, sequences, and transactional emails
  version: 1.0.0
servers:
- url: https://api.sequenzy.com/api/v1
  description: Production server
- url: https://api.sequenzy.com/v1
  description: Legacy production server alias
security:
- bearerAuth: []
tags:
- name: Products
  description: Product catalog for any e-commerce platform via the Commerce API
paths:
  /products/{productId}/delivery:
    put:
      operationId: attachProductDelivery
      summary: Attach delivery file to product
      description: Attaches the distributable file delivered after a purchase of this product. Purchase events then expose it as download.url / download.name. Accepts the internal product id or, for Commerce API products, your productId.
      tags:
      - Products
      parameters:
      - name: productId
        in: path
        required: true
        description: Internal product id, or your own productId for products pushed via the Commerce API.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  description: Public http(s) URL of the file.
                source:
                  type: string
                  enum:
                  - upload
                  - url
                  default: url
                fileName:
                  type: string
                fileSizeBytes:
                  type: integer
                mimeType:
                  type: string
      responses:
        '200':
          description: Delivery attached
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  product:
                    $ref: '#/components/schemas/Product'
        '400':
          description: Invalid URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
    delete:
      operationId: removeProductDelivery
      summary: Remove delivery file from product
      description: Removes the attached distributable file from a product. Accepts the internal product id or, for Commerce API products, your productId.
      tags:
      - Products
      parameters:
      - name: productId
        in: path
        required: true
        description: Internal product id, or your own productId for products pushed via the Commerce API.
        schema:
          type: string
      responses:
        '200':
          description: Delivery removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  product:
                    $ref: '#/components/schemas/Product'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
  /products/delivery/upload-url:
    post:
      operationId: createProductDeliveryUploadUrl
      summary: Create delivery file upload URL
      description: Returns a presigned URL to upload a distributable file. PUT the file bytes to uploadUrl, then attach publicUrl to a product.
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - filename
              - contentType
              - fileSizeBytes
              properties:
                filename:
                  type: string
                contentType:
                  type: string
                  example: application/pdf
                fileSizeBytes:
                  type: integer
                  maximum: 104857600
      responses:
        '200':
          description: Upload URL created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  uploadUrl:
                    type: string
                  publicUrl:
                    type: string
                  fileName:
                    type: string
        '400':
          description: Unsupported file type or size
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Uploads not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /products/sync:
    post:
      operationId: syncStripeProducts
      summary: Sync Stripe products
      description: Queues a sync of the Stripe product catalog into the products list. Requires an active Stripe integration with bulk sync enabled.
      tags:
      - Products
      parameters:
      - name: integrationId
        in: query
        required: false
        description: Stripe integration to sync. When omitted, the most recently connected active integration with bulk sync enabled is used.
        schema:
          type: string
      responses:
        '200':
          description: Sync queued
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  jobId:
                    type:
                    - string
                    - 'null'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No active Stripe integration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Every active Stripe integration has bulk sync disabled, or the selected integration has bulk sync disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /products:
    get:
      summary: List products
      description: Lists products in the catalog. Includes products synced from Stripe, Shopify/WooCommerce, and products pushed via the Commerce API.
      operationId: listProducts
      tags:
      - Products
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        description: Maximum number of products to return
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Number of products to skip
      - name: provider
        in: query
        schema:
          type: string
          enum:
          - api
          - stripe
          - shopify
          - woocommerce
          - manual
        description: Filter products by source provider
      - name: search
        in: query
        schema:
          type: string
        description: Filter products by title
      responses:
        '200':
          description: Products listed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/CommerceProduct'
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
                      count:
                        type: integer
                        description: Number of products in this page
                      total:
                        type: integer
                        description: Total products matching the filters across the whole catalog
                      hasMore:
                        type: boolean
                        description: Whether more products remain. Page until this is false.
        '400':
          description: Invalid provider filter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
    post:
      summary: Upsert products
      description: Creates or updates up to 100 products, keyed by your productId. Products pushed here behave like Shopify/WooCommerce products - they power product blocks, replenishment reminders, and back-in-stock notifications. Stock transitions trigger back-in-stock events for waiting subscribers. Updates are partial - omitted optional fields keep their stored values; pass an explicit null to clear one.
      operationId: upsertProducts
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - products
              properties:
                products:
                  type: array
                  minItems: 1
                  maxItems: 100
                  description: Products to create or update
                  items:
                    type: object
                    required:
                    - productId
                    - title
                    properties:
                      productId:
                        type: string
                        description: Your product identifier. Used as the upsert key.
                        example: SKU-PROTEIN-1KG
                      title:
                        type: string
                        example: Protein Powder
                      description:
                        type:
                        - string
                        - 'null'
                        example: Whey protein, 1kg bag
                      imageUrl:
                        type:
                        - string
                        - 'null'
                        example: https://cdn.example.com/protein.jpg
                      url:
                        type:
                        - string
                        - 'null'
                        description: Public product page URL
                        example: https://store.example.com/products/protein
                      priceCents:
                        type:
                        - integer
                        - 'null'
                        description: Price in cents. Defaults to the lowest variant price when variants are provided.
                        example: 8850
                      compareAtPriceCents:
                        type:
                        - integer
                        - 'null'
                        example: 9900
                      currency:
                        type:
                        - string
                        - 'null'
                        description: ISO 4217 currency code
                        example: USD
                      inStock:
                        type: boolean
                        description: Defaults to true, or to whether any variant is available when variants are provided.
                      providerCreatedAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                        description: Product creation time in the source catalog. Omit to preserve the stored value; pass null to clear it.
                      variants:
                        type: array
                        description: Product variants. When provided, the variant list is replaced entirely (an empty array removes all variants). Omit to leave existing variants unchanged.
                        items:
                          type: object
                          required:
                          - variantId
                          - title
                          properties:
                            variantId:
                              type: string
                              description: Your variant identifier
                              example: SKU-PROTEIN-1KG-VANILLA
                            title:
                              type: string
                              example: Vanilla
                            sku:
                              type:
                              - string
                              - 'null'
                            priceCents:
                              type:
                              - integer
                              - 'null'
                            compareAtPriceCents:
                              type:
                              - integer
                              - 'null'
                            imageUrl:
                              type:
                              - string
                              - 'null'
                            inStock:
                              type: boolean
                              description: Defaults to inventoryQuantity > 0 when provided, otherwise true.
                            inventoryQuantity:
                              type:
                              - integer
                              - 'null'
                            options:
                              type: array
                              items:
                                type: object
                                required:
                                - name
                                - value
                                properties:
                                  name:
                                    type: string
                                    example: Flavor
                                  value:
                                    type: string
                                    example: Vanilla
      responses:
        '200':
          description: Products upserted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  upserted:
                    type: integer
                    example: 1
                  backInStockEventsTriggered:
                    type: integer
                    description: Number of back-in-stock notifications triggered by stock transitions in this upsert
                    example: 0
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/CommerceProduct'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /products/{productId}:
    get:
      summary: Get product
      description: Returns a product previously pushed via the Commerce API, identified by your productId.
      operationId: getProduct
      tags:
      - Products
      parameters:
      - name: productId
        in: path
        required: true
        schema:
          type: string
        description: Your product identifier
      responses:
        '200':
          description: Product found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  product:
                    $ref: '#/components/schemas/CommerceProduct'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
    delete:
      summary: Delete product
      description: Deletes a product previously pushed via the Commerce API, identified by your productId. Products synced from other providers are not affected.
      operationId: deleteProduct
      tags:
      - Products
      parameters:
      - name: productId
        in: path
        required: true
        schema:
          type: string
        description: Your product identifier
      responses:
        '200':
          description: Product deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  deleted:
                    type: boolean
                    example: true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
  /back-in-stock:
    post:
      summary: Register back-in-stock request
      description: Registers a customer's request to be notified when a product (pushed via the Commerce API) is back in stock. When a later product upsert marks the product or variant in stock again, the ecommerce.back_in_stock event fires for waiting subscribers.
      operationId: registerBackInStock
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - productId
              - customer
              properties:
                productId:
                  type: string
                  description: Your product identifier
                  example: SKU-PROTEIN-1KG
                variantId:
                  type: string
                  description: Your variant identifier. Defaults to productId for products without variants.
                  example: SKU-PROTEIN-1KG-VANILLA
                productTitle:
                  type: string
                  description: Product title snapshot. Defaults to the synced product title.
                variantTitle:
                  type: string
                  description: Variant title snapshot. Defaults to the synced variant title.
                customer:
                  $ref: '#/components/schemas/CommerceCustomer'
      responses:
        '200':
          description: Back-in-stock request registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  subscriberId:
                    type: string
        '400':
          description: Failed to create subscriber
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  headers:
    RetryAfter:
      description: Number of seconds to wait before retrying the request.
      schema:
        type: integer
        minimum: 1
        example: 1
  responses:
    TransientDatabaseUnavailable:
      description: The database was temporarily unavailable. The request may be retried after the delay in Retry-After.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: The service could not reach its database for a moment. Retry the request.
            code: SERVICE_UNAVAILABLE
  schemas:
    CommerceCustomer:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
          example: buyer@example.com
        externalId:
          type: string
          description: Customer-owned app/customer/user ID
          example: user_123
        firstName:
          type: string
          example: Jane
        lastName:
          type: string
          example: Doe
        attributes:
          type: object
          additionalProperties: true
          description: Custom subscriber attributes to merge into the profile. Synced to ClickHouse for segment filtering.
          example:
            acquisitionChannel: tiktok
            country: US
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Error message
        code:
          type: string
          description: Optional stable machine-readable error discriminator when available.
          example: COMPANY_CREATE_REQUIRES_PERSONAL_KEY
        retryable:
          type: boolean
          description: Whether retrying the request can recover from the error.
        issues:
          type: array
          description: Field-level problems with the request, when the endpoint reports them. Up to ten entries; `error` summarizes the first three.
          items:
            $ref: '#/components/schemas/InputIssue'
      required:
      - error
    CommerceProduct:
      type: object
      properties:
        id:
          type: string
          description: Internal Sequenzy product ID
        productId:
          type:
          - string
          - 'null'
          description: Your product identifier (providerProductId)
          example: SKU-PROTEIN-1KG
        providerProductId:
          type:
          - string
          - 'null'
          description: Provider product identifier
          example: prod_ABC123
        provider:
          type: string
          enum:
          - api
          - stripe
          - shopify
          - woocommerce
          - manual
          example: api
        title:
          type: string
          example: Protein Powder
        description:
          type:
          - string
          - 'null'
        imageUrl:
          type:
          - string
          - 'null'
        url:
          type:
          - string
          - 'null'
        price:
          type:
          - integer
          - 'null'
          description: Unit price in cents
          example: 8850
        priceCents:
          type:
          - integer
          - 'null'
          example: 8850
        compareAtPrice:
          type:
          - integer
          - 'null'
        compareAtPriceCents:
          type:
          - integer
          - 'null'
        currency:
          type:
          - string
          - 'null'
          example: USD
        inStock:
          type: boolean
        providerCreatedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Product creation time reported by the source catalog. Used for newest-product ranking.
        digitalDelivery:
          $ref: '#/components/schemas/ProductDigitalDelivery'
        variants:
          type: array
          description: For Stripe products, every active Stripe price of the product (variantId is the Stripe price ID).
          items:
            type: object
            properties:
              variantId:
                type: string
              title:
                type: string
              sku:
                type:
                - string
                - 'null'
              priceCents:
                type:
                - integer
                - 'null'
              compareAtPriceCents:
                type:
                - integer
                - 'null'
              currency:
                type:
                - string
                - 'null'
                description: The variant's own currency. Stripe products can have active prices in several currencies, so this can differ from the product-level currency.
                example: USD
              imageUrl:
                type:
                - string
                - 'null'
              inStock:
                type: boolean
              inventoryQuantity:
                type:
                - integer
                - 'null'
              options:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    value:
                      type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Product:
      type: object
      properties:
        id:
          type: string
          example: prod_internal_1
        provider:
          type: string
          enum:
          - api
          - stripe
          - shopify
          - woocommerce
          - manual
        providerProductId:
          type:
          - string
          - 'null'
          example: prod_ABC123
        title:
          type: string
          example: The Indie Hacker Guide
        description:
          type:
          - string
          - 'null'
        imageUrl:
          type:
          - string
          - 'null'
        price:
          type:
          - integer
          - 'null'
          description: Price in cents
          example: 4900
        currency:
          type:
          - string
          - 'null'
          example: USD
        url:
          type:
          - string
          - 'null'
        inStock:
          type:
          - boolean
          - 'null'
          description: For Stripe products, false means archived in Stripe.
        digitalDelivery:
          $ref: '#/components/schemas/ProductDigitalDelivery'
        createdAt:
          type:
          - string
          - 'null'
          format: date-time
        updatedAt:
          type:
          - string
          - 'null'
          format: date-time
    InputIssue:
      type: object
      properties:
        path:
          type: string
          description: Dotted field path, such as `audience.subscriberIds[0]`. Empty when the problem is with the request body itself.
          example: kind
        message:
          type: string
          description: What is wrong with the field.
          example: must be "add_tags"
        allowedValues:
          type: array
          description: Accepted values when the field only takes a fixed set of values.
          items: {}
          example:
          - add_tags
      required:
      - path
      - message
    ProductDigitalDelivery:
      type:
      - object
      - 'null'
      description: Distributable file delivered after a purchase of this product.
      properties:
        url:
          type: string
          example: https://images.sequenzy.com/product-files/comp_123/9f2.../guide.pdf
        source:
          type: string
          enum:
          - upload
          - url
        fileName:
          type:
          - string
          - 'null'
          example: guide.pdf
        fileSizeBytes:
          type:
          - integer
          - 'null'
        mimeType:
          type:
          - string
          - 'null'
          example: application/pdf
        updatedAt:
          type:
          - string
          - 'null'
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token