> ## 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.

# Track order transaction

> Accept one order-transaction.v2 Order Transaction: a paid order with its products, or a refund of one. The source and orderId (plus refundId for a refund) identify it, so sending it again updates it instead of adding another. Orders marked historical never start a Journey.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/events/order-transactions
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/events/order-transactions:
    post:
      tags:
        - Events
      summary: Track order transaction
      description: >-
        Accept one order-transaction.v2 Order Transaction: a paid order with its
        products, or a refund of one. The source and orderId (plus refundId for
        a refund) identify it, so sending it again updates it instead of adding
        another. Orders marked historical never start a Journey.
      operationId: Events_Events_TrackOrderTransaction
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - order
                    source:
                      type: string
                      minLength: 1
                      maxLength: 100
                      pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
                      description: >-
                        The store this order comes from, named by the caller,
                        for example `my-shop` or `salla:4821`. Case-sensitive.
                        Together with orderId it identifies the order, and it
                        names the store for Personal Picks and diagnostics.
                    orderId:
                      type: string
                      minLength: 1
                      maxLength: 255
                      description: >-
                        Your order ID. Sending the same source and orderId again
                        updates the order.
                    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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                      description: When the order was paid.
                    currency:
                      type: string
                      pattern: ^[A-Z]{3}$
                      description: ISO 4217 currency code, for example EUR.
                    totals:
                      type: object
                      properties:
                        total:
                          type: number
                          minimum: 0
                          maximum: 1000000000000
                          description: Amount the customer paid for the order.
                        subtotal:
                          type: number
                          minimum: 0
                          maximum: 1000000000000
                        tax:
                          type: number
                          minimum: 0
                          maximum: 1000000000000
                        shipping:
                          type: number
                          minimum: 0
                          maximum: 1000000000000
                        discount:
                          type: number
                          minimum: 0
                          maximum: 1000000000000
                      required:
                        - total
                      additionalProperties: false
                      description: Order totals in the order currency.
                    customer:
                      type: object
                      properties:
                        email:
                          description: >-
                            Customer email. Resolves the Profile, or creates one
                            when no Profile matches.
                          format: email
                          minLength: 1
                          pattern: >-
                            ^(?:[A-Za-z0-9_'+-]+\.)*[A-Za-z0-9_'+-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9-]*\.)+[A-Za-z]{2,}$
                          type: string
                        externalCustomerId:
                          description: >-
                            Your customer ID, scoped to the authenticated
                            Organization. Resolves an existing Profile; a new
                            Profile needs an email.
                          type: string
                          minLength: 1
                          maxLength: 255
                        marketingConsent:
                          type: string
                          enum:
                            - subscribed
                            - unsubscribed
                          description: >-
                            Email marketing consent the customer gave with this
                            order. `subscribed` never re-subscribes someone who
                            unsubscribed; `unsubscribed` stops marketing email
                            unless the Profile subscribed again after the order.
                      additionalProperties: false
                      description: The customer who placed the order.
                    lineItems:
                      default: []
                      description: >-
                        Products in the order. Orders without line items still
                        count for revenue.
                      maxItems: 500
                      type: array
                      items:
                        type: object
                        properties:
                          productId:
                            description: >-
                              Your product ID. Matches the Catalog Product with
                              this ID from the same source.
                            type: string
                            minLength: 1
                            maxLength: 255
                          variantId:
                            description: Your variant ID, when the product has variants.
                            type: string
                            minLength: 1
                            maxLength: 255
                          sku:
                            description: >-
                              SKU. Matches a Catalog Product from the same
                              source when productId is missing.
                            type: string
                            minLength: 1
                            maxLength: 255
                          title:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: Product title as the customer saw it.
                          quantity:
                            type: integer
                            minimum: 1
                            maximum: 1000000
                            description: Units bought, or units refunded on a refund.
                          unitPrice:
                            type: number
                            minimum: 0
                            maximum: 1000000000000
                            description: >-
                              Price of one unit in the order currency, or the
                              refunded amount per unit on a refund.
                        required:
                          - title
                          - quantity
                          - unitPrice
                        additionalProperties: false
                        description: One product line of an order or a refund.
                    historical:
                      default: false
                      description: >-
                        Past order or refund imported as history. It counts like
                        any other but never starts a Journey, also not through
                        Segment entry.
                      type: boolean
                  required:
                    - type
                    - source
                    - orderId
                    - occurredAt
                    - currency
                    - totals
                    - customer
                  additionalProperties: false
                  description: A paid order.
                - type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - refund
                    source:
                      type: string
                      minLength: 1
                      maxLength: 100
                      pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
                      description: >-
                        The store this order comes from, named by the caller,
                        for example `my-shop` or `salla:4821`. Case-sensitive.
                        Together with orderId it identifies the order, and it
                        names the store for Personal Picks and diagnostics.
                    orderId:
                      type: string
                      minLength: 1
                      maxLength: 255
                      description: The order this refund belongs to.
                    refundId:
                      type: string
                      minLength: 1
                      maxLength: 255
                      description: >-
                        Your refund ID. Sending the same source, orderId and
                        refundId again updates the refund.
                    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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                      description: When the refund was issued.
                    currency:
                      type: string
                      pattern: ^[A-Z]{3}$
                      description: ISO 4217 currency code, for example EUR.
                    amount:
                      description: >-
                        Refunded amount. Defaults to the sum of the refunded
                        line items.
                      type: number
                      minimum: 0
                      maximum: 1000000000000
                    customer:
                      description: >-
                        The customer. Optional: without it the refund belongs to
                        the Profile of its order, which must already be stored.
                      type: object
                      properties:
                        email:
                          description: >-
                            Customer email. Resolves the Profile, or creates one
                            when no Profile matches.
                          format: email
                          minLength: 1
                          pattern: >-
                            ^(?:[A-Za-z0-9_'+-]+\.)*[A-Za-z0-9_'+-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9-]*\.)+[A-Za-z]{2,}$
                          type: string
                        externalCustomerId:
                          description: >-
                            Your customer ID, scoped to the authenticated
                            Organization. Resolves an existing Profile; a new
                            Profile needs an email.
                          type: string
                          minLength: 1
                          maxLength: 255
                        marketingConsent:
                          type: string
                          enum:
                            - subscribed
                            - unsubscribed
                          description: >-
                            Email marketing consent the customer gave with this
                            order. `subscribed` never re-subscribes someone who
                            unsubscribed; `unsubscribed` stops marketing email
                            unless the Profile subscribed again after the order.
                      additionalProperties: false
                    lineItems:
                      default: []
                      description: >-
                        Refunded items. They stop counting as purchased. Leave
                        empty for a refund of an amount only.
                      maxItems: 500
                      type: array
                      items:
                        type: object
                        properties:
                          productId:
                            description: >-
                              Your product ID. Matches the Catalog Product with
                              this ID from the same source.
                            type: string
                            minLength: 1
                            maxLength: 255
                          variantId:
                            description: Your variant ID, when the product has variants.
                            type: string
                            minLength: 1
                            maxLength: 255
                          sku:
                            description: >-
                              SKU. Matches a Catalog Product from the same
                              source when productId is missing.
                            type: string
                            minLength: 1
                            maxLength: 255
                          title:
                            type: string
                            minLength: 1
                            maxLength: 500
                            description: Product title as the customer saw it.
                          quantity:
                            type: integer
                            minimum: 1
                            maximum: 1000000
                            description: Units bought, or units refunded on a refund.
                          unitPrice:
                            type: number
                            minimum: 0
                            maximum: 1000000000000
                            description: >-
                              Price of one unit in the order currency, or the
                              refunded amount per unit on a refund.
                        required:
                          - title
                          - quantity
                          - unitPrice
                        additionalProperties: false
                        description: One product line of an order or a refund.
                    historical:
                      default: false
                      description: >-
                        Past order or refund imported as history. It counts like
                        any other but never starts a Journey, also not through
                        Segment entry.
                      type: boolean
                  required:
                    - type
                    - source
                    - orderId
                    - refundId
                    - occurredAt
                    - currency
                  additionalProperties: false
                  description: A refund of an order, in full or in part.
              description: >-
                One order-transaction.v2 Order Transaction: a paid order with
                its products, or a refund of one.
        description: >-
          One order-transaction.v2 Order Transaction: a paid order with its
          products, or a refund of one.
      responses:
        '202':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  eventId:
                    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)$
                    description: The stored Order Transaction.
                  profileId:
                    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)$
                    description: Resolved Profile id.
                  outcome:
                    type: string
                    enum:
                      - created
                      - updated
                      - unchanged
                    description: >-
                      created: first time this order or refund was sent.
                      updated: it was stored before and its details changed.
                      unchanged: a retry with the same details.
                  matchedJourneys:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                    description: Active Journeys whose entry event matched.
                  enrolledJourneys:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                    description: Journey enrollments this order started.
                  skippedJourneys:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                    description: Matched Journeys skipped by filters or eligibility.
                required:
                  - eventId
                  - profileId
                  - outcome
                  - matchedJourneys
                  - enrolledJourneys
                  - skippedJourneys
                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'
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
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.