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

# Submit a quoted API print order

> Requires a scoped API key or an anonymous Test Mode session and Idempotency-Key. Anonymous sessions always use sandbox, no-charge simulation. Live API keys retain billable production behavior. The quote is account/environment scoped and freezes exactly one resolved provider; submission cannot alter it or split a mixed-provider order.



## OpenAPI

````yaml https://api.batchrelay.com/openapi.json post /v1/print-orders
openapi: 3.1.0
info:
  description: >-
    Provider-neutral print catalog and prepared-media validation. This document
    covers only routes owned by the Go service; it deliberately excludes
    migration-proxied order lifecycle routes and all provider payloads.
  license:
    name: Proprietary
    url: https://github.com/SENTINELITE/Batch-Relay-Go/blob/main/README.md
  title: Batch Relay API
  version: 1.0.1
servers:
  - url: https://api.batchrelay.com
security: []
tags:
  - description: Service health and the public API description.
    name: System
  - description: Test Mode session creation and API credential entry points.
    name: Authentication
  - description: >-
      Provider-neutral canonical catalog resources and platform-owned semantic
      definitions.
    name: Catalog
  - description: Studio-scoped guest checkout-link management.
    name: Checkout links
  - description: >-
      One-way operational event messages. Alert emails contain no message body
      and recipients read messages after Batch Relay authentication.
    name: Studio messages
  - description: >-
      Explicit, reviewable sandbox-to-Live promotion plans for forms, catalog,
      and storefront configuration.
    name: Sandbox promotions
  - description: Provider-neutral validation, quoting, and order lifecycle operations.
    name: Print orders
  - description: Managed fulfillment asset ingestion and metadata.
    name: Managed assets
  - description: Studio-scoped original asset upload sessions and objects.
    name: Studio assets
  - description: Prepared and confirmed event roster team changes.
    name: Event team changes
  - description: Authenticated studio, event, and form-management operations.
    name: Studio management
  - description: >-
      Authenticated studio retail catalog management. Draft and publication
      lifecycles are explicit per product or package.
    name: Studio catalog
  - description: >-
      Authenticated singular storefront assortment management. PATCH atomically
      publishes a new immutable assortment revision; no storefront draft
      lifecycle exists yet.
    name: Storefront
  - description: Managed media used by the studio retail catalog.
    name: Studio catalog assets
  - description: Template rendering job creation and retrieval.
    name: Template renders
  - description: >-
      Published browser-side template packages and short-lived server proof
      renders. Preview artifacts are never fulfillment artwork.
    name: Browser previews
  - description: API account and credential administration.
    name: API accounts
paths:
  /v1/print-orders:
    parameters:
      - $ref: '#/components/parameters/ClientSurface'
      - $ref: '#/components/parameters/ClientVersion'
      - $ref: '#/components/parameters/InvocationMode'
    post:
      tags:
        - Print orders
      summary: Submit a quoted API print order
      description: >-
        Requires a scoped API key or an anonymous Test Mode session and
        Idempotency-Key. Anonymous sessions always use sandbox, no-charge
        simulation. Live API keys retain billable production behavior. The quote
        is account/environment scoped and freezes exactly one resolved provider;
        submission cannot alter it or split a mixed-provider order.
      operationId: submitAPIPrintOrder
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema:
            minLength: 1
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitAPIOrderRequest'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIOrder'
          description: Order reserved for payment/fulfillment
        '400':
          $ref: '#/components/responses/InvalidRequestJSON'
        '401':
          $ref: '#/components/responses/APIKeyAuthenticationRequired'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '422':
          $ref: '#/components/responses/OrderValidationFailed'
        '429':
          $ref: '#/components/responses/AnonymousSessionRateLimited'
        '503':
          $ref: '#/components/responses/StatefulAPIUnavailable'
      security:
        - bearerAuth: []
components:
  parameters:
    ClientSurface:
      description: >-
        Untrusted optional analytics hint naming the calling client surface. It
        never affects authorization, routing, pricing, or behavior.
      in: header
      name: X-BatchRelay-Client-Surface
      required: false
      schema:
        maxLength: 100
        minLength: 1
        type: string
    ClientVersion:
      description: >-
        Untrusted optional analytics hint naming the calling client version. It
        never affects authorization, routing, pricing, or behavior.
      in: header
      name: X-BatchRelay-Client-Version
      required: false
      schema:
        maxLength: 100
        minLength: 1
        type: string
    InvocationMode:
      description: >-
        Untrusted optional analytics hint naming the invocation mode. It never
        affects authorization, routing, pricing, or behavior.
      in: header
      name: X-BatchRelay-Invocation-Mode
      required: false
      schema:
        maxLength: 100
        minLength: 1
        type: string
  schemas:
    SubmitAPIOrderRequest:
      additionalProperties: false
      properties:
        integration_source:
          default: direct_api
          description: >-
            Analytics attribution only; it cannot alter authorization, pricing,
            settlement, or provider selection.
          enum:
            - direct_api
            - zapier
            - n8n
            - custom_code
          type: string
        order:
          $ref: '#/components/schemas/OrderRequest'
        quote_id:
          minLength: 1
          type: string
      required:
        - quote_id
        - order
      type: object
    APIOrder:
      additionalProperties: false
      properties:
        api_account_id:
          type: string
        channel:
          const: api
          type: string
        created_at:
          format: date-time
          type: string
        external_order_id:
          type: string
        id:
          pattern: ^bro_
          type: string
        merchant_of_record:
          const: batch_relay
          type: string
        order_code:
          description: >-
            Batch Relay-owned human-facing order reference. It is always
            serialized, but may be empty for legacy records that predate
            allocation.
          type: string
        price:
          $ref: '#/components/schemas/PriceBreakdown'
        provider:
          $ref: '#/components/schemas/ResolvedProvider'
        provider_offer_lines:
          description: Immutable copy of the reserved quote's public offer evidence.
          items:
            $ref: '#/components/schemas/ProviderOfferQuoteLine'
          minItems: 1
          type: array
        quote_id:
          type: string
        status:
          type: string
        updated_at:
          format: date-time
          type: string
      required:
        - id
        - order_code
        - external_order_id
        - api_account_id
        - quote_id
        - status
        - channel
        - merchant_of_record
        - price
        - provider
        - provider_offer_lines
        - created_at
        - updated_at
      type: object
    OrderRequest:
      additionalProperties: false
      properties:
        customer:
          $ref: '#/components/schemas/CustomerContact'
        external_order_id:
          minLength: 1
          type: string
        items:
          items:
            $ref: '#/components/schemas/OrderLine'
          minItems: 1
          type: array
        schema_version:
          const: 1
          type: integer
        ship_from:
          $ref: '#/components/schemas/Address'
        ship_to:
          $ref: '#/components/schemas/Address'
        shipping_service:
          $ref: '#/components/schemas/ShippingService'
      required:
        - schema_version
        - external_order_id
        - ship_to
        - ship_from
        - shipping_service
        - items
      type: object
    PriceBreakdown:
      additionalProperties: false
      properties:
        currency:
          const: USD
          type: string
        fee_base_cents:
          minimum: 0
          type: integer
        merchandise_cents:
          minimum: 0
          type: integer
        minimum_fee_cents:
          const: 500
          type: integer
        platform_fee_basis_points:
          const: 1500
          type: integer
        platform_fee_cents:
          minimum: 500
          type: integer
        platform_fee_label:
          const: Batch Relay API Access Fee
          type: string
        policy_id:
          const: api-access-fee-v1
          type: string
        shipping_cents:
          minimum: 0
          type: integer
        tax_cents:
          minimum: 0
          type: integer
        total_cents:
          minimum: 1
          type: integer
      required:
        - policy_id
        - currency
        - merchandise_cents
        - shipping_cents
        - fee_base_cents
        - platform_fee_basis_points
        - minimum_fee_cents
        - platform_fee_cents
        - platform_fee_label
        - tax_cents
        - total_cents
      type: object
    ResolvedProvider:
      additionalProperties: false
      properties:
        provider_availability:
          $ref: '#/components/schemas/ProviderAvailability'
        provider_capability_revision:
          type: string
        provider_environment:
          enum:
            - sandbox
            - production
          type: string
        provider_id:
          $ref: '#/components/schemas/ProviderID'
        provider_recipe_revision:
          type: string
        provider_selection_source:
          $ref: '#/components/schemas/ProviderSelectionSource'
      required:
        - provider_id
        - provider_selection_source
        - provider_environment
        - provider_availability
        - provider_capability_revision
        - provider_recipe_revision
      type: object
    ProviderOfferQuoteLine:
      additionalProperties: false
      description: >-
        Immutable public-offer evidence for one API quote line. It intentionally
        excludes provider-native SKU, UID, recipe, credentials, and raw provider
        payloads.
      properties:
        availability:
          const: available
          type: string
        configuration:
          additionalProperties:
            type: string
          type: object
        currency:
          const: USD
          type: string
        line_subtotal_cents:
          minimum: 0
          type: integer
        offer_id:
          type: string
        pricing_revision:
          minLength: 1
          type: string
        product:
          $ref: '#/components/schemas/ProductReference'
        provider_id:
          $ref: '#/components/schemas/ProviderID'
        quantity:
          minimum: 1
          type: integer
        unit_cost_cents:
          minimum: 0
          type: integer
      required:
        - offer_id
        - provider_id
        - product
        - configuration
        - currency
        - unit_cost_cents
        - quantity
        - line_subtotal_cents
        - availability
        - pricing_revision
      type: object
    Error:
      additionalProperties: false
      properties:
        code:
          description: Stable machine-readable error code.
          type: string
        docs_url:
          format: uri
          type: string
        error:
          description: Backward-compatible human-readable error.
          type: string
        message:
          type: string
        request_id:
          type: string
      required:
        - error
        - code
        - message
        - docs_url
        - request_id
      type: object
    CustomerContact:
      additionalProperties: false
      description: For quote and submit API routes, at least email or phone is required.
      properties:
        email:
          format: email
          type: string
        external_id:
          type: string
        name:
          type: string
        phone:
          pattern: ^\+[1-9][0-9]{1,14}$
          type: string
      type: object
    OrderLine:
      additionalProperties: false
      properties:
        assets:
          items:
            $ref: '#/components/schemas/OrderAssetSource'
          type: array
        options:
          items:
            $ref: '#/components/schemas/OptionSelection'
          type: array
        product:
          $ref: '#/components/schemas/ProductReference'
        quantity:
          minimum: 1
          type: integer
        texts:
          description: >-
            Text values keyed by the selected product's published semantic
            slots. Each slot may occur at most once; preserve intentional
            whitespace exactly.
          items:
            $ref: '#/components/schemas/TextValue'
          type: array
      required:
        - product
        - quantity
        - assets
      type: object
    Address:
      additionalProperties: false
      properties:
        address_1:
          minLength: 1
          type: string
        address_2:
          type: string
        city:
          minLength: 1
          type: string
        country:
          minLength: 1
          type: string
        name:
          minLength: 1
          type: string
        phone:
          description: E.164 phone number, for example +16516468263
          pattern: ^\+[1-9][0-9]{1,14}$
          type: string
        postal_code:
          minLength: 1
          type: string
        state:
          minLength: 1
          type: string
      required:
        - name
        - address_1
        - city
        - state
        - postal_code
        - country
        - phone
      type: object
    ShippingService:
      description: >-
        Required domestic US delivery service. The server freezes the exact
        deterministic provider shipping quote before payment; a service can be
        unavailable when provider eligibility, a one-day zone result, or
        required provider cost evidence is unavailable.
      enum:
        - economy_untracked
        - economy
        - expedited
        - standard_one_day
        - priority_one_day
      type: string
    ProviderAvailability:
      enum:
        - preview
        - sandbox_verified
        - production_verified
        - unavailable
      type: string
    ProviderID:
      enum:
        - whcc
        - rpl
      type: string
    ProviderSelectionSource:
      enum:
        - explicit
        - event
        - account_default
        - legacy_default
      type: string
    ProductReference:
      additionalProperties: false
      properties:
        id:
          minLength: 1
          type: string
        revision:
          minimum: 1
          type: integer
      required:
        - id
        - revision
      type: object
    OrderAssetSource:
      additionalProperties: false
      description: >-
        Public asset source. Supply role plus exactly one of url or asset_id.
        Batch Relay resolves and freezes immutable metadata during quote;
        optional metadata is a non-authoritative preflight hint. Products with
        template_requirement=required accept only the asset_id from a succeeded
        Batch Relay template render plus template_render_id. Public submission
        never passes a source URL to a provider.
      oneOf:
        - required:
            - url
        - required:
            - asset_id
      properties:
        asset_id:
          description: >-
            Existing authorized bra_ managed asset or same-studio image asset;
            reused in place.
          type: string
        file_size_bytes:
          description: Optional non-authoritative preflight hint.
          minimum: 1
          type: integer
        format:
          description: Optional non-authoritative preflight hint.
          enum:
            - jpeg
            - png
            - tiff
          type: string
        hash:
          type: string
        origin:
          $ref: '#/components/schemas/AssetOrigin'
          description: >-
            Ignored for template provenance; the server derives it from
            template_render_id.
        pixel_height:
          description: Optional non-authoritative preflight hint.
          minimum: 1
          type: integer
        pixel_width:
          description: Optional non-authoritative preflight hint.
          minimum: 1
          type: integer
        printed_file_name:
          type: string
        role:
          $ref: '#/components/schemas/AssetRole'
        template_render_id:
          description: >-
            Required with asset_id for a template-required product. Batch Relay
            verifies the succeeded render owns the selected artifact.
          type: string
        url:
          description: HTTPS source copied into managed fulfillment storage during quote.
          format: uri
          pattern: ^https://
          type: string
      required:
        - role
      type: object
    OptionSelection:
      additionalProperties: false
      properties:
        option_id:
          minLength: 1
          type: string
        value:
          minLength: 1
          type: string
      required:
        - option_id
        - value
      type: object
    TextValue:
      additionalProperties: false
      properties:
        slot:
          $ref: '#/components/schemas/TextSlotID'
        value:
          type: string
      required:
        - slot
        - value
      type: object
    AssetOrigin:
      additionalProperties: false
      properties:
        design_id:
          type: string
        design_version:
          minimum: 1
          type: integer
        kind:
          $ref: '#/components/schemas/AssetOriginKind'
        template_render_id:
          readOnly: true
          type: string
        template_revision_id:
          readOnly: true
          type: string
      type: object
    AssetRole:
      enum:
        - artwork
        - background
        - individual
        - team
        - logo
        - front
        - back
      type: string
    TextSlotID:
      enum:
        - text-1
        - text-2
        - text-3
        - text-4
        - text-5
        - text-6
      type: string
    AssetOriginKind:
      enum:
        - whcc-preset
        - batch-relay-design
        - studio-design
        - community-design
        - custom-upload
      type: string
  responses:
    InvalidRequestJSON:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The body was malformed, contained unknown fields, or was not exactly one
        JSON object.
    APIKeyAuthenticationRequired:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: A valid Batch Relay API key or anonymous Test Mode session is required.
    PaymentRequired:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Payment method setup or customer action is required before fulfillment.
    IdempotencyConflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: The idempotency key has already been used with a different request.
    OrderValidationFailed:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The order did not satisfy the catalog, option, quantity, address, or
        prepared-media requirements.
    AnonymousSessionRateLimited:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        Anonymous Test Mode capacity has been reached. Retry only after
        Retry-After.
      headers:
        Retry-After:
          schema:
            minimum: 1
            type: integer
    StatefulAPIUnavailable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The stateful order service is not configured or is temporarily
        unavailable.
  securitySchemes:
    bearerAuth:
      bearerFormat: Batch Relay API key or anonymous session
      description: >-
        Batch Relay scoped API key or an anonymous Test Mode session. Scope
        names document required capabilities. Anonymous sessions are
        sandbox-only and do not authorize studio, event, billing, or Live Mode
        operations.
      scheme: bearer
      type: http

````