> ## 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 transactions in a batch

> Accept up to 100 order-transaction.v2 orders and refunds, one by one in request order, with one result each. Use it to import past orders marked historical. Sending a batch again is safe.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/events/order-transactions/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/events/order-transactions/batch:
    post:
      tags:
        - Events
      summary: Track order transactions in a batch
      description: >-
        Accept up to 100 order-transaction.v2 orders and refunds, one by one in
        request order, with one result each. Use it to import past orders marked
        historical. Sending a batch again is safe.
      operationId: Events_Events_BatchTrackOrderTransactions
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                transactions:
                  minItems: 1
                  maxItems: 100
                  type: array
                  items:
                    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: >-
                    Orders and refunds, accepted one by one in this order. Mark
                    past orders historical.
              required:
                - transactions
              additionalProperties: false
        required: true
      responses:
        '202':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      oneOf:
                        - 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.
                            index:
                              type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            status:
                              type: string
                              enum:
                                - accepted
                          required:
                            - eventId
                            - profileId
                            - outcome
                            - matchedJourneys
                            - enrolledJourneys
                            - skippedJourneys
                            - index
                            - status
                          additionalProperties: false
                        - type: object
                          properties:
                            index:
                              type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            status:
                              type: string
                              enum:
                                - rejected
                            code:
                              type: string
                              enum:
                                - profile_not_found
                                - profile_erased
                                - identity_conflict
                                - order_not_found
                              description: >-
                                profile_not_found: no Profile matches and there
                                is no email to create one. profile_erased: the
                                Profile was erased. identity_conflict: the email
                                and customer ID belong to different Profiles, or
                                the order belongs to another Profile.
                                order_not_found: a refund without a customer
                                references an order that isn't stored.
                            message:
                              type: string
                          required:
                            - index
                            - status
                            - code
                            - message
                          additionalProperties: false
                    description: One result per transaction, in request order.
                  summary:
                    type: object
                    properties:
                      accepted:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      rejected:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                    required:
                      - accepted
                      - rejected
                    additionalProperties: false
                required:
                  - results
                  - summary
                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.