openapi: 3.1.0
info:
  title: SCM API
  version: 0.1.0-draft
  description: |
    Sales Cycle Management (SCM).

    Contract notes:
    - API Gateway base path: `/scm`
    - Org-gated: supply `x-orgcode`.
    - Logical facility context required for operational actions (`x-logical-guid`). Org-level policy/list endpoints do not require logical context unless provided in the body.
    - Sales channel context required for orders and fulfillment (`x-channel-code`). List/search/policy endpoints may supply `channel_code` in the body or omit when org-scoped.
    - Request context is captured for auditability (org/facility/channel/roles/cost-centre).
    - Auth: either `x-session-guid` (user session) or `x-api-key` (org-bound service account).
      Headers are canonical; body `session_guid`/`api_key` accepted for compatibility on POST.
    - Orders reference PMC sellable listings and use PPM price snapshots.
    - Roles: `scm_order` for prep, `scm_discount_approve` for overrides,
      `scm_special_order_approve` and `scm_backorder_approve` for approvals.
servers:
  - url: https://api.g3nretailstack.com/scm
security:
  - sessionAuth: []
  - apiKeyAuth: []
components:
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: header
      name: x-session-guid
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  parameters:
    OrgHeader:
      in: header
      name: x-orgcode
      required: true
      schema: { type: string }
    LogicalHeader:
      in: header
      name: x-logical-guid
      required: true
      schema: { type: string }
    ChannelHeader:
      in: header
      name: x-channel-code
      required: true
      schema: { type: string }
  schemas:
    BuildMeta:
      type: object
      properties:
        build_major: { type: string }
        build_minor: { type: string }
        build_id: { type: string }
      required: [build_major, build_minor, build_id]
    Stats:
      type: object
      properties:
        call: { type: string }
        service: { type: string, enum: [scm] }
        request_id: { type: string }
        timestamp_utc: { type: string, format: date-time }
        build: { $ref: '#/components/schemas/BuildMeta' }
        actor: { type: string }
        context_source:
          type: string
          enum: [session, api_key, operator, system]
        session_fingerprint:
          type: string
          description: Non-reversible SHA-256 fingerprint of the caller session (`session_guid`) for correlation (never an auth credential).
        api_key_fingerprint:
          type: string
          description: Non-reversible SHA-256 fingerprint of the caller `api_key` for correlation (never an auth credential).
        orgcode: { type: string }
        cccode: { type: string }
        logical_guid: { type: string }
        channel_code: { type: string }
        roles:
          type: array
          items: { type: string }
      required: [call, service, timestamp_utc, build]
    Error:
      type: object
      properties:
        error_code: { type: string }
        http_status: { type: integer }
        retryable: { type: boolean }
        request_id: { type: string }
        trace_id: { type: string }
        major: { type: string }
        minor: { type: string }
        message: { type: string }
        details: { type: object }
    Envelope:
      type: object
      properties:
        success: { type: boolean }
        data: { type: object }
        error: { $ref: '#/components/schemas/Error' }
        stats: { $ref: '#/components/schemas/Stats' }
    SourceRef:
      type: object
      properties:
        kind: { type: string }
        id: { type: string }
      required: [kind, id]
    SourceRefs:
      type: array
      items: { $ref: '#/components/schemas/SourceRef' }
    IdempotencyKey:
      type: string
      description: Client-supplied idempotency key (ASCII <=128 chars). Scope is orgcode+route+idempotency_key; replay returns original response, mismatch returns 409 idempotency-conflict (retained 24h).
      maxLength: 128
    RequestContext:
      type: object
      properties:
        orgcode: { type: string }
        logical_guid: { type: string }
        channel_code: { type: string }
        cccode: { type: string }
        actor: { type: string }
        roles:
          type: array
          items: { type: string }
        context_source:
          type: string
          enum: [session, api_key, operator, system]
        session_fingerprint: { type: string }
        api_key_fingerprint: { type: string }
      required: [orgcode, actor, context_source]
      additionalProperties: false
    PolicyRefs:
      type: object
      properties:
        tax_policy_version: { type: string }
        pricing_policy_version: { type: string }
        promotion_policy_version: { type: string }
        discount_policy_version: { type: string }
        stacking_policy_version: { type: string }
        reservation_policy_version: { type: string }
        allocation_policy_version: { type: string }
        commit_policy_version: { type: string }
        approval_policy_version: { type: string }
        tender_policy_version: { type: string }
        returns_policy_version: { type: string }
        loyalty_policy_version: { type: string }
        stored_value_policy_version: { type: string }
        earning_policy_version: { type: string }
        backorder_policy_version: { type: string }
        special_order_policy_version: { type: string }
        transfer_policy_version: { type: string }
        count_policy_version: { type: string }
        adjustment_policy_version: { type: string }
        po_policy_version: { type: string }
        matching_policy_version: { type: string }
        tolerance_policy_version: { type: string }
        receiving_policy_version: { type: string }
        qc_policy_version: { type: string }
        rtv_policy_version: { type: string }
        credit_policy_version: { type: string }
        shipping_policy_version: { type: string }
        export_policy_version: { type: string }
      additionalProperties: true
    Money:
      type: object
      properties:
        currency: { type: string }
        amount: { type: number }
      required: [currency, amount]
    PaymentTerms:
      type: object
      properties:
        terms_code: { type: string }
        net_days: { type: number }
        discount_days: { type: number }
        discount_percent: { type: number }
        due_day: { type: number }
        notes: { type: string }
    CreditSnapshot:
      type: object
      properties:
        account_guid: { type: string }
        account_code: { type: string }
        status: { type: string }
        credit_limit: { $ref: '#/components/schemas/Money' }
        credit_used: { $ref: '#/components/schemas/Money' }
        credit_available: { $ref: '#/components/schemas/Money' }
        credit_hold: { type: boolean }
        as_of: { type: string, format: date-time }
    UomQuantity:
      type: object
      properties:
        qty: { type: number }
        uom: { type: string }
        uom_multiplier: { type: number }
      required: [qty, uom]
    PriceSnapshot:
      type: object
      properties:
        price_as_of: { type: string, format: date-time }
        list_price: { $ref: '#/components/schemas/Money' }
        sell_price: { $ref: '#/components/schemas/Money' }
        policy_versions:
          type: object
          properties:
            pricing_policy_version: { type: string }
            promotion_policy_version: { type: string }
            stacking_policy_version: { type: string }
            discount_policy_version: { type: string }
    CatalogSnapshot:
      type: object
      properties:
        pmc_revision_guid: { type: string }
        pmc_product_guid: { type: string }
    DiscountApplication:
      type: object
      properties:
        source: { type: string, enum: [manual, coupon, loyalty, promo, other] }
        code: { type: string }
        amount: { $ref: '#/components/schemas/Money' }
        percent: { type: number }
    TaxContext:
      type: object
      properties:
        tax_policy_version: { type: string }
        tax_jurisdiction_code: { type: string }
        tax_basis: { type: string, enum: [included, added] }
        tax_liability_trigger: { type: string, enum: [order, invoice, shipment] }
        tax_holiday_applied: { type: boolean }
        tax_override_applied: { type: boolean }
        tax_override_reason: { type: string }
        tax_override_approved_by: { type: string }
        tax_override_approved_at: { type: string, format: date-time }
    DutyComponent:
      type: object
      description: |
        A single duty/tariff component computed from a matching trade agreement.
      properties:
        agreement_id: { type: string }
        agreement_type: { type: string, enum: [fta, gsp, preferential, bilateral, unilateral] }
        hs_code: { type: string }
        origin_country: { type: string }
        destination_country: { type: string }
        duty_rate_bps: { type: integer, description: Duty rate in basis points (1 bps = 0.01%) }
        amount: { $ref: '#/components/schemas/Money' }
    TaxComponent:
      type: object
      properties:
        tax_code: { type: string }
        jurisdiction_code: { type: string }
        rate: { type: number }
        taxable_base: { $ref: '#/components/schemas/Money' }
        tax_basis: { type: string, enum: [included, added] }
        tax_on_tax:
          type: array
          items: { type: string }
          description: |
            References to tax_code values whose computed amounts were added to the taxable base
            for this compound rule (tax-on-tax cascading). Present only on compound components.
        holiday_applied: { type: boolean }
        exemption_applied: { type: boolean }
        exemption_reason: { type: string }
        amount: { $ref: '#/components/schemas/Money' }
    TaxConnector:
      type: object
      properties:
        type: { type: string, enum: [internal_rate, passthrough] }
        name: { type: string }
        version: { type: string }
        note: { type: string }
    TaxJurisdictionRule:
      type: object
      description: |
        A jurisdiction-level tax rule. Rules with `tax_on_tax` are compound rules — their taxable base
        is the original base amount plus the computed amounts of the referenced tax codes (two-pass
        cascading). Example: Canada PST on GST+price where `tax_on_tax: ["GST"]`.
      properties:
        jurisdiction_code: { type: string }
        tax_code: { type: string }
        tax_type: { type: string }
        rate: { type: number }
        tax_basis: { type: string, enum: [included, added] }
        tax_on_tax:
          type: array
          items: { type: string }
          description: |
            References to other jurisdiction rule tax_code values. When present, this rule is computed
            in a second pass — the taxable base is adjusted by adding the computed amounts of the
            referenced tax codes. If a referenced tax_code was not computed (exempted or filtered), 0
            is used for that reference.
        thresholds:
          type: object
          properties:
            min_amount: { type: number }
            max_amount: { type: number }
        product_tax_codes:
          type: array
          items: { type: string }
        note: { type: string }
      required: [jurisdiction_code, tax_code, rate]
    TaxPolicy:
      type: object
      properties:
        policy_version: { type: string }
        status: { type: string }
        effective_from: { type: string, format: date-time }
        effective_to: { type: string, format: date-time }
        tax_basis_default: { type: string, enum: [included, added] }
        tax_liability_trigger_default: { type: string, enum: [order, invoice, shipment] }
        rounding:
          type: object
          properties:
            mode: { type: string, enum: [round, floor, ceil] }
            precision: { type: integer }
        connector: { $ref: '#/components/schemas/TaxConnector' }
        jurisdictions:
          type: array
          items: { $ref: '#/components/schemas/TaxJurisdictionRule' }
        note: { type: string }
        revision: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
      required: [policy_version, tax_basis_default, tax_liability_trigger_default, jurisdictions]
    TaxPolicySetRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        policy: { $ref: '#/components/schemas/TaxPolicy' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        expected_revision: { type: integer }
        set_current: { type: boolean }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
      required: [policy, reason, source_refs]
    TaxPolicyGetRequest:
      type: object
      properties:
        policy_version: { type: string }
        effective_as_of: { type: string, format: date-time }
    TaxPolicyListRequest:
      type: object
      properties:
        limit: { type: integer }
        next_token: { type: string }
    TaxCertificateRef:
      type: object
      properties:
        certificate_id: { type: string }
        applied: { type: boolean }
        reason: { type: string }
        tax_codes:
          type: array
          items: { type: string }
    TaxQuoteLineInput:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        tax_code: { type: string }
        hs_code:
          type: string
          description: Harmonized System code for tariff/duty lookup. When provided with origin_country, triggers duty computation against cached trade agreements.
        origin_country:
          type: string
          description: ISO 3166-1 alpha-2 country of origin. Required alongside hs_code for duty computation.
        qty: { $ref: '#/components/schemas/UomQuantity' }
        unit_price: { $ref: '#/components/schemas/Money' }
        taxable_base: { $ref: '#/components/schemas/Money' }
      required: [qty, unit_price]
    TaxQuoteLine:
      type: object
      properties:
        line_id: { type: string }
        taxable_base: { $ref: '#/components/schemas/Money' }
        tax_total: { $ref: '#/components/schemas/Money' }
        taxes:
          type: array
          items: { $ref: '#/components/schemas/TaxComponent' }
        duties:
          type: array
          items: { $ref: '#/components/schemas/DutyComponent' }
          description: Duty/tariff components computed from matching trade agreements (present only when line has hs_code + origin_country).
        duty_total:
          $ref: '#/components/schemas/Money'
          description: Sum of duty amounts for this line.
      required: [line_id]
    TaxQuoteTotals:
      type: object
      properties:
        taxable_total: { $ref: '#/components/schemas/Money' }
        tax_total: { $ref: '#/components/schemas/Money' }
        duty_total:
          $ref: '#/components/schemas/Money'
          description: Sum of all duty amounts across lines (present only when duties were computed).
    TaxQuote:
      type: object
      properties:
        tax_quote_id: { type: string }
        status: { type: string }
        logical_guid: { type: string }
        channel_code: { type: string }
        jurisdiction_code: { type: string }
        destination_country:
          type: string
          description: ISO 3166-1 alpha-2 destination country for duty filtering.
        tax_basis: { type: string, enum: [included, added] }
        tax_liability_trigger: { type: string, enum: [order, invoice, shipment] }
        policy_versions: { $ref: '#/components/schemas/PolicyRefs' }
        connector: { $ref: '#/components/schemas/TaxConnector' }
        certificate: { $ref: '#/components/schemas/TaxCertificateRef' }
        tax_holiday_applied: { type: boolean }
        lines:
          type: array
          items: { $ref: '#/components/schemas/TaxQuoteLine' }
        totals: { $ref: '#/components/schemas/TaxQuoteTotals' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        revision: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
      required: [tax_quote_id, status, jurisdiction_code]
    TaxQuoteRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        tax_quote:
          type: object
          properties:
            tax_quote_id: { type: string }
            jurisdiction_code: { type: string }
            policy_version: { type: string }
            effective_as_of: { type: string, format: date-time }
            tax_basis: { type: string, enum: [included, added] }
            tax_liability_trigger: { type: string, enum: [order, invoice, shipment] }
            tax_holiday_applied: { type: boolean }
            destination_country:
              type: string
              description: ISO 3166-1 alpha-2 destination country for duty filtering against trade agreements.
            connector_override: { $ref: '#/components/schemas/TaxConnector' }
            certificate_id: { type: string }
            certificate_snapshot: { type: object }
            tax_components:
              type: array
              items: { $ref: '#/components/schemas/TaxComponent' }
            lines:
              type: array
              items: { $ref: '#/components/schemas/TaxQuoteLineInput' }
            request_context: { $ref: '#/components/schemas/RequestContext' }
          required: [jurisdiction_code, lines]
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
      required: [tax_quote, reason, source_refs]
    TaxRecord:
      type: object
      properties:
        tax_record_id: { type: string }
        status: { type: string }
        logical_guid: { type: string }
        channel_code: { type: string }
        target_ref:
          type: object
          properties:
            kind: { type: string }
            id: { type: string }
          required: [kind, id]
        jurisdiction_code: { type: string }
        destination_country:
          type: string
          description: ISO 3166-1 alpha-2 destination country for duty filtering.
        tax_basis: { type: string, enum: [included, added] }
        tax_liability_trigger: { type: string, enum: [order, invoice, shipment] }
        policy_versions: { $ref: '#/components/schemas/PolicyRefs' }
        connector: { $ref: '#/components/schemas/TaxConnector' }
        certificate: { $ref: '#/components/schemas/TaxCertificateRef' }
        tax_holiday_applied: { type: boolean }
        lines:
          type: array
          items: { $ref: '#/components/schemas/TaxQuoteLine' }
        totals: { $ref: '#/components/schemas/TaxQuoteTotals' }
        tax_quote_id: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        revision: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
      required: [tax_record_id, status, target_ref]
    TaxFinalizeRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        tax_final:
          type: object
          properties:
            tax_record_id: { type: string }
            tax_quote_id: { type: string }
            target_ref:
              type: object
              properties:
                kind: { type: string }
                id: { type: string }
              required: [kind, id]
            jurisdiction_code: { type: string }
            destination_country:
              type: string
              description: ISO 3166-1 alpha-2 destination country (inherited from quote if omitted).
            tax_basis: { type: string, enum: [included, added] }
            tax_liability_trigger: { type: string, enum: [order, invoice, shipment] }
            policy_versions: { $ref: '#/components/schemas/PolicyRefs' }
            connector: { $ref: '#/components/schemas/TaxConnector' }
            certificate: { $ref: '#/components/schemas/TaxCertificateRef' }
            tax_holiday_applied: { type: boolean }
            lines:
              type: array
              items: { $ref: '#/components/schemas/TaxQuoteLine' }
            totals: { $ref: '#/components/schemas/TaxQuoteTotals' }
            request_context: { $ref: '#/components/schemas/RequestContext' }
          required: [target_ref]
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
      required: [tax_final, reason, source_refs]
    TenderApplication:
      type: object
      properties:
        tender_code: { type: string }
        amount: { $ref: '#/components/schemas/Money' }
        tender_ref: { type: string }
        loyalty_points_earned: { type: number }
        loyalty_points_redeemed: { type: number }
    SlaTarget:
      type: object
      properties:
        sla_code: { type: string }
        promise_by: { type: string, format: date-time }
        ship_by: { type: string, format: date-time }
        deliver_by: { type: string, format: date-time }
        pickup_by: { type: string, format: date-time }
    SubstitutionPolicy:
      type: object
      properties:
        allow_substitutions: { type: boolean }
        mode:
          type: string
          enum: [none, same_item, similar, any_sellable]
        max_substitutions: { type: integer }
        require_approval: { type: boolean }
        note: { type: string }
    OrderLine:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        cancelled_qty: { $ref: '#/components/schemas/UomQuantity' }
        cancel_reason_code: { type: string }
        cancel_note: { type: string }
        cancelled_at: { type: string, format: date-time }
        price_snapshot: { $ref: '#/components/schemas/PriceSnapshot' }
        discounts:
          type: array
          items: { $ref: '#/components/schemas/DiscountApplication' }
        taxes:
          type: array
          items: { $ref: '#/components/schemas/TaxComponent' }
        line_total: { $ref: '#/components/schemas/Money' }
      required: [qty]
    Substitution:
      type: object
      properties:
        original_variant_id: { type: string }
        substitute_variant_id: { type: string }
        reason_code: { type: string }
        applied_at: { type: string, format: date-time }
    LineUpdate:
      type: object
      properties:
        line_id: { type: string }
        fulfilled_qty: { $ref: '#/components/schemas/UomQuantity' }
        short_qty: { $ref: '#/components/schemas/UomQuantity' }
        short_reason_code: { type: string }
        short_note: { type: string }
        short_at: { type: string, format: date-time }
      required: [line_id]
    ShipmentLine:
      type: object
      properties:
        line_id: { type: string }
        order_line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        fulfilled_qty: { $ref: '#/components/schemas/UomQuantity' }
        short_qty: { $ref: '#/components/schemas/UomQuantity' }
        short_reason_code: { type: string }
        short_note: { type: string }
        short_at: { type: string, format: date-time }
        substitution: { $ref: '#/components/schemas/Substitution' }
      required: [qty]
    Shipment:
      type: object
      properties:
        shipment_id: { type: string }
        order_id: { type: string }
        status: { type: string }
        fulfillment_type:
          type: string
          enum: [ship_to_home, ship_from_store, pickup, curbside, delivery, digital, rental]
        fulfillment_group_id: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        carrier_code: { type: string }
        tracking_ref: { type: string }
        pickup_window_start: { type: string, format: date-time }
        pickup_window_end: { type: string, format: date-time }
        pickup_ready_at: { type: string, format: date-time }
        pickup_completed_at: { type: string, format: date-time }
        pickup_no_show_at: { type: string, format: date-time }
        sla: { $ref: '#/components/schemas/SlaTarget' }
        exception_code: { type: string }
        exception_note: { type: string }
        exception_at: { type: string, format: date-time }
        exception_resolved_code: { type: string }
        exception_resolved_note: { type: string }
        exception_resolved_at: { type: string, format: date-time }
        cancel_code: { type: string }
        cancel_note: { type: string }
        cancelled_at: { type: string, format: date-time }
        policy_versions:
          type: object
          properties:
            shipping_policy_version: { type: string }
        substitution_policy: { $ref: '#/components/schemas/SubstitutionPolicy' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/ShipmentLine' }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        created_at: { type: string, format: date-time }
        picked_at: { type: string, format: date-time }
        packed_at: { type: string, format: date-time }
        shipped_at: { type: string, format: date-time }
        delivered_at: { type: string, format: date-time }
        revision: { type: integer }
    ShipmentDraft:
      type: object
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        reason: { type: string }
        order_id: { type: string }
        status: { type: string }
        fulfillment_type:
          type: string
          enum: [ship_to_home, ship_from_store, pickup, curbside, delivery, digital, rental]
        fulfillment_group_id: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        carrier_code: { type: string }
        tracking_ref: { type: string }
        pickup_window_start: { type: string, format: date-time }
        pickup_window_end: { type: string, format: date-time }
        sla: { $ref: '#/components/schemas/SlaTarget' }
        substitution_policy: { $ref: '#/components/schemas/SubstitutionPolicy' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/ShipmentLine' }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [request_context, reason, order_id, lines, source_refs]
    OrderPromiseLine:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        reason_code: { type: string }
      required: [qty]
    OrderPromise:
      type: object
      properties:
        status: { type: string }
        reservation_id: { type: string }
        reservation_revision: { type: integer }
        allocation_id: { type: string }
        allocation_revision: { type: integer }
        commit_id: { type: string }
        commit_revision: { type: integer }
        expires_at: { type: string, format: date-time }
        released_at: { type: string, format: date-time }
        release_reason_code: { type: string }
        updated_at: { type: string, format: date-time }
        lines:
          type: array
          items: { $ref: '#/components/schemas/OrderPromiseLine' }
    OrderTotals:
      type: object
      properties:
        subtotal: { $ref: '#/components/schemas/Money' }
        discount_total: { $ref: '#/components/schemas/Money' }
        tax_total: { $ref: '#/components/schemas/Money' }
        total: { $ref: '#/components/schemas/Money' }
        paid: { $ref: '#/components/schemas/Money' }
        balance_due: { $ref: '#/components/schemas/Money' }
        approval_required: { type: boolean }
        approval_reasons:
          type: array
          items: { type: string }
    Order:
      type: object
      properties:
        order_id: { type: string }
        status: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        customer_ref: { type: string }
        payment_terms: { $ref: '#/components/schemas/PaymentTerms' }
        credit_snapshot: { $ref: '#/components/schemas/CreditSnapshot' }
        catalog_snapshot: { $ref: '#/components/schemas/CatalogSnapshot' }
        price_snapshot: { $ref: '#/components/schemas/PriceSnapshot' }
        policy_versions:
          type: object
          properties:
            pricing_policy_version: { type: string }
            discount_policy_version: { type: string }
            stacking_policy_version: { type: string }
            tax_policy_version: { type: string }
            approval_policy_version: { type: string }
            returns_policy_version: { type: string }
            tender_policy_version: { type: string }
            loyalty_policy_version: { type: string }
            credit_policy_version: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        tax_context: { $ref: '#/components/schemas/TaxContext' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/OrderLine' }
        promise: { $ref: '#/components/schemas/OrderPromise' }
        sla: { $ref: '#/components/schemas/SlaTarget' }
        substitution_policy: { $ref: '#/components/schemas/SubstitutionPolicy' }
        tenders:
          type: array
          items: { $ref: '#/components/schemas/TenderApplication' }
        totals: { $ref: '#/components/schemas/OrderTotals' }
        cancel_code: { type: string }
        cancel_note: { type: string }
        cancelled_at: { type: string, format: date-time }
        created_at: { type: string, format: date-time }
        submitted_at: { type: string, format: date-time }
        revision: { type: integer }
    OrderDraft:
      type: object
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        reason: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        customer_ref: { type: string }
        payment_terms: { $ref: '#/components/schemas/PaymentTerms' }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/OrderLine' }
        sla: { $ref: '#/components/schemas/SlaTarget' }
        substitution_policy: { $ref: '#/components/schemas/SubstitutionPolicy' }
        tenders:
          type: array
          items: { $ref: '#/components/schemas/TenderApplication' }
        notes: { type: string }
        station_guid: { type: string, description: "Optional OFM station GUID (POS pass-through metadata)" }
        till_guid: { type: string, description: "Optional SCM till GUID (POS pass-through metadata)" }
      required: [request_context, reason, source_refs]
    OrderCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        order: { $ref: '#/components/schemas/OrderDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [order, reason, source_refs]
    OrderPlaceRequest:
      type: object
      properties:
        order_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [order_id, reason, source_refs]
    OrderCancelRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        order_id: { type: string }
        expected_revision: { type: integer }
        cancel_code: { type: string }
        cancel_note: { type: string }
        cancelled_at: { type: string, format: date-time }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [order_id, cancel_code, reason, source_refs]
    OrderLineCancelRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        order_id: { type: string }
        line_id: { type: string }
        cancel_qty: { $ref: '#/components/schemas/UomQuantity' }
        cancel_reason_code: { type: string }
        cancel_note: { type: string }
        cancelled_at: { type: string, format: date-time }
        expected_revision: { type: integer }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [order_id, line_id, cancel_qty, cancel_reason_code, reason, source_refs]
    OrderPromiseReserveRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        order_id: { type: string }
        expected_revision: { type: integer }
        reservation_id: { type: string }
        ttl_seconds:
          type: integer
          default: 900
          description: Defaults to 900 seconds when omitted (unless expires_at is provided).
        expires_at: { type: string, format: date-time }
        lines:
          type: array
          items: { $ref: '#/components/schemas/OrderPromiseLine' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [order_id, reason, source_refs]
    OrderPromiseAllocateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        order_id: { type: string }
        expected_revision: { type: integer }
        allocation_id: { type: string }
        ttl_seconds:
          type: integer
          default: 1800
          description: Defaults to 1800 seconds when omitted (unless expires_at is provided).
        expires_at: { type: string, format: date-time }
        lines:
          type: array
          items: { $ref: '#/components/schemas/OrderPromiseLine' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [order_id, reason, source_refs]
    OrderPromiseCommitRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        order_id: { type: string }
        expected_revision: { type: integer }
        commit_id: { type: string }
        ttl_seconds:
          type: integer
          default: 3600
          description: Defaults to 3600 seconds when omitted (unless expires_at is provided).
        expires_at: { type: string, format: date-time }
        lines:
          type: array
          items: { $ref: '#/components/schemas/OrderPromiseLine' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [order_id, reason, source_refs]
    OrderPromiseReleaseRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        order_id: { type: string }
        expected_revision: { type: integer }
        release_type: { type: string, enum: [reservation, allocation, commit] }
        reservation_id: { type: string }
        allocation_id: { type: string }
        commit_id: { type: string }
        release_reason_code: { type: string }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [order_id, reason, source_refs]
    OrderGetRequest:
      type: object
      properties:
        order_id: { type: string }
        include_lines: { type: boolean }
      required: [order_id]
    OrderListRequest:
      type: object
      properties:
        status: { type: string }
        channel_code: { type: string }
        customer_ref: { type: string }
        created_from: { type: string, format: date-time }
        created_to: { type: string, format: date-time }
        limit: { type: integer }
        next_token: { type: string }
    OrderSearchRequest:
      type: object
      properties:
        q: { type: string }
        mode: { type: string, enum: [prefix, contains, regex], default: contains }
        status: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        customer_ref: { type: string }
        created_from: { type: string, format: date-time }
        created_to: { type: string, format: date-time }
        limit: { type: integer }
        next_token: { type: string }
      required: [q]
    ChannelPolicy:
      type: object
      properties:
        channel_code: { type: string }
        logical_guid: { type: string }
        policy:
          type: object
          properties:
            sla: { $ref: '#/components/schemas/SlaTarget' }
            substitution_policy: { $ref: '#/components/schemas/SubstitutionPolicy' }
        revision: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
      required: [channel_code, policy, revision]
    ChannelPolicyGetRequest:
      type: object
      properties:
        channel_code: { type: string }
        logical_guid: { type: string }
      required: [channel_code]
    ChannelPolicySetRequest:
      type: object
      properties:
        channel_code: { type: string }
        logical_guid: { type: string }
        policy:
          type: object
          properties:
            sla: { $ref: '#/components/schemas/SlaTarget' }
            substitution_policy: { $ref: '#/components/schemas/SubstitutionPolicy' }
        expected_revision: { type: integer }
        request_context: { $ref: '#/components/schemas/RequestContext' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [channel_code, policy, request_context, reason, source_refs]
    RoutingPolicySpec:
      type: object
      properties:
        mode: { type: string, enum: [closest, cost, sla, balanced] }
        split_shipments: { type: boolean }
        max_splits: { type: integer }
        enforce_capacity: { type: boolean }
        allow_partial: { type: boolean }
        note: { type: string }
    RoutingPolicy:
      type: object
      properties:
        channel_code: { type: string }
        logical_guid: { type: string }
        policy: { $ref: '#/components/schemas/RoutingPolicySpec' }
        revision: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
      required: [channel_code, policy, revision]
    RoutingPolicyGetRequest:
      type: object
      properties:
        channel_code: { type: string }
        logical_guid: { type: string }
      required: [channel_code]
    RoutingPolicyListRequest:
      type: object
      properties:
        channel_code: { type: string }
        limit: { type: integer }
        next_token: { type: string }
      required: [channel_code]
    RoutingPolicySetRequest:
      type: object
      properties:
        channel_code: { type: string }
        logical_guid: { type: string }
        policy: { $ref: '#/components/schemas/RoutingPolicySpec' }
        expected_revision: { type: integer }
        request_context: { $ref: '#/components/schemas/RequestContext' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [channel_code, policy, request_context, reason, source_refs]
    RoutingPlanLine:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        requested_qty: { type: number }
        uom: { type: string }
      required: [line_id, requested_qty, uom]
    RoutingPlanShipment:
      type: object
      properties:
        logical_guid: { type: string }
        lines:
          type: array
          items: { $ref: '#/components/schemas/RoutingPlanLine' }
        atp_ok: { type: boolean }
        ctp_ok: { type: boolean }
        confidence: { type: number }
        promise_by: { type: string, format: date-time }
        sla_met: { type: boolean }
      required: [logical_guid, lines, confidence]
    RoutingPlan:
      type: object
      properties:
        plan_id: { type: string }
        status: { type: string, enum: [planned, partial] }
        policy: { $ref: '#/components/schemas/RoutingPolicySpec' }
        shipments:
          type: array
          items: { $ref: '#/components/schemas/RoutingPlanShipment' }
        unassigned_lines:
          type: array
          items: { $ref: '#/components/schemas/RoutingPlanLine' }
        confidence: { type: number }
      required: [plan_id, status, policy, shipments, unassigned_lines]
    PromiseQuoteLine:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
      required: [qty]
    PromiseCandidateAvailability:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        available_qty: { type: number }
        on_order_qty: { type: number }
        expected_at: { type: string, format: date-time }
    PromiseCandidate:
      type: object
      properties:
        logical_guid: { type: string }
        distance_km: { type: number }
        cost_cents: { type: integer }
        lead_time_days: { type: number }
        capacity_remaining: { type: number }
        capacity_uom: { type: string }
        fulfillment_types:
          type: array
          items:
            type: string
            enum: [ship_to_home, ship_from_store, pickup, curbside, delivery, digital, rental]
        availability:
          type: array
          items: { $ref: '#/components/schemas/PromiseCandidateAvailability' }
      required: [logical_guid]
    PromiseLineResult:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        requested_qty: { type: number }
        uom: { type: string }
        available_qty: { type: number }
        on_order_qty: { type: number }
        status: { type: string, enum: [available, capable, partial, unavailable] }
        promise_at: { type: string, format: date-time }
        ctp_at: { type: string, format: date-time }
        confidence: { type: number }
      required: [line_id, requested_qty, uom, status, confidence]
    PromiseOption:
      type: object
      properties:
        logical_guid: { type: string }
        distance_km: { type: number }
        cost_cents: { type: integer }
        lead_time_days: { type: number }
        capacity_remaining: { type: number }
        capacity_uom: { type: string }
        capacity_ok: { type: boolean }
        atp_ok: { type: boolean }
        ctp_ok: { type: boolean }
        sla_met: { type: boolean }
        promise_by: { type: string, format: date-time }
        confidence: { type: number }
        lines:
          type: array
          items: { $ref: '#/components/schemas/PromiseLineResult' }
      required: [logical_guid, capacity_ok, atp_ok, ctp_ok, confidence, lines]
    PromiseQuote:
      type: object
      properties:
        quote_id: { type: string }
        fulfillment_type: { type: string }
        policy: { $ref: '#/components/schemas/RoutingPolicySpec' }
        sla: { $ref: '#/components/schemas/SlaTarget' }
        plan: { $ref: '#/components/schemas/RoutingPlan' }
        options:
          type: array
          items: { $ref: '#/components/schemas/PromiseOption' }
      required: [quote_id, policy, plan, options]
    OrderPromiseQuoteRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        fulfillment_type:
          type: string
          enum: [ship_to_home, ship_from_store, pickup, curbside, delivery, digital, rental]
        lines:
          type: array
          items: { $ref: '#/components/schemas/PromiseQuoteLine' }
        candidates:
          type: array
          items: { $ref: '#/components/schemas/PromiseCandidate' }
        routing_policy: { $ref: '#/components/schemas/RoutingPolicySpec' }
        sla: { $ref: '#/components/schemas/SlaTarget' }
        use_ics: { type: boolean }
        max_options: { type: integer }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        request_context: { $ref: '#/components/schemas/RequestContext' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [lines, candidates, request_context, reason, source_refs]
    RoutingPlanCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        plan_id: { type: string }
        order_id: { type: string }
        fulfillment_type:
          type: string
          enum: [ship_to_home, ship_from_store, pickup, curbside, delivery, digital, rental]
        lines:
          type: array
          items: { $ref: '#/components/schemas/PromiseQuoteLine' }
        candidates:
          type: array
          items: { $ref: '#/components/schemas/PromiseCandidate' }
        routing_policy: { $ref: '#/components/schemas/RoutingPolicySpec' }
        sla: { $ref: '#/components/schemas/SlaTarget' }
        use_ics: { type: boolean }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        request_context: { $ref: '#/components/schemas/RequestContext' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [lines, candidates, request_context, reason, source_refs]
    RoutingPlanGetRequest:
      type: object
      properties:
        plan_id: { type: string }
      required: [plan_id]
    RoutingPlanListRequest:
      type: object
      properties:
        order_id: { type: string }
        limit: { type: integer }
        next_token: { type: string }
    ShipmentCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment: { $ref: '#/components/schemas/ShipmentDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment, reason, source_refs]
    ShipmentGetRequest:
      type: object
      properties:
        shipment_id: { type: string }
      required: [shipment_id]
    ShipmentListRequest:
      type: object
      properties:
        status: { type: string }
        order_id: { type: string }
        limit: { type: integer }
        next_token: { type: string }
    ShipmentPickRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        picked_at: { type: string, format: date-time }
        line_updates:
          type: array
          items: { $ref: '#/components/schemas/LineUpdate' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, reason, source_refs]
    ShipmentPackRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        packed_at: { type: string, format: date-time }
        line_updates:
          type: array
          items: { $ref: '#/components/schemas/LineUpdate' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, reason, source_refs]
    ShipmentShipRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        shipped_at: { type: string, format: date-time }
        carrier_code: { type: string }
        tracking_ref: { type: string }
        line_updates:
          type: array
          items: { $ref: '#/components/schemas/LineUpdate' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, reason, source_refs]
    ShipmentDeliverRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        delivered_at: { type: string, format: date-time }
        line_updates:
          type: array
          items: { $ref: '#/components/schemas/LineUpdate' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, reason, source_refs]
    ShipmentPickupReadyRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        pickup_ready_at: { type: string, format: date-time }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, reason, source_refs]
    ShipmentPickupCompleteRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        pickup_completed_at: { type: string, format: date-time }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, reason, source_refs]
    ShipmentPickupNoShowRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        pickup_no_show_at: { type: string, format: date-time }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, reason, source_refs]
    ShipmentExceptionRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        exception_code: { type: string }
        exception_note: { type: string }
        exception_at: { type: string, format: date-time }
        line_updates:
          type: array
          items: { $ref: '#/components/schemas/LineUpdate' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, exception_code, reason, source_refs]
    ShipmentExceptionShortPickRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        exception_note: { type: string }
        exception_at: { type: string, format: date-time }
        line_updates:
          type: array
          items: { $ref: '#/components/schemas/LineUpdate' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, line_updates, reason, source_refs]
    ShipmentExceptionDamagedRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        exception_note: { type: string }
        exception_at: { type: string, format: date-time }
        line_updates:
          type: array
          items: { $ref: '#/components/schemas/LineUpdate' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, line_updates, reason, source_refs]
    ShipmentExceptionCarrierFailureRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        exception_note: { type: string }
        exception_at: { type: string, format: date-time }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, reason, source_refs]
    ShipmentExceptionPartialRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        exception_note: { type: string }
        exception_at: { type: string, format: date-time }
        line_updates:
          type: array
          items: { $ref: '#/components/schemas/LineUpdate' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, line_updates, reason, source_refs]
    ShipmentExceptionResolveRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        resolution_code: { type: string }
        resolution_note: { type: string }
        resolve_status: { type: string }
        resolved_at: { type: string, format: date-time }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, resolution_code, reason, source_refs]
    ShipmentCancelRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        shipment_id: { type: string }
        expected_revision: { type: integer }
        cancel_code: { type: string }
        cancel_note: { type: string }
        cancelled_at: { type: string, format: date-time }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, cancel_code, reason, source_refs]
    ShipmentSubstitutionApplyRequest:
      type: object
      properties:
        shipment_id: { type: string }
        line_id: { type: string }
        expected_revision: { type: integer }
        substitution:
          type: object
          properties:
            substitute_variant_id: { type: string }
            reason_code: { type: string }
          required: [substitute_variant_id, reason_code]
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [shipment_id, line_id, substitution, reason, source_refs]
    CommentAttachment:
      type: object
      properties:
        mrs_guid: { type: string }
        caption: { type: string }
        filename: { type: string }
        content_type: { type: string }
        size_bytes: { type: integer, minimum: 0 }
      required: [mrs_guid]
    Comment:
      type: object
      properties:
        comment_id: { type: string }
        target_type: { type: string }
        target_id: { type: string }
        parent_comment_id: { type: string }
        caption: { type: string }
        body: { type: string }
        attachments:
          type: array
          items: { $ref: '#/components/schemas/CommentAttachment' }
        total_size_bytes: { type: integer }
        hashtags:
          type: array
          items: { type: string }
        mentions_users:
          type: array
          items: { type: string }
        mentions_teams:
          type: array
          items: { type: string }
        status:
          type: string
          enum: [current, archived, doomed, all]
          default: current
          description: Default current; use all to include archived/doomed.
        current_revision: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        author_guid: { type: string }
      required: [comment_id, target_type, target_id, status, current_revision, created_at]
    CommentAddRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        target_type: { type: string }
        target_id: { type: string }
        parent_comment_id: { type: string }
        caption: { type: string }
        body: { type: string }
        attachments:
          type: array
          items: { $ref: '#/components/schemas/CommentAttachment' }
        hashtags:
          type: array
          items: { type: string }
        mentions_users:
          type: array
          items: { type: string }
        mentions_teams:
          type: array
          items: { type: string }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
      required: [target_type, target_id]
    CommentGetRequest:
      type: object
      properties:
        comment_id: { type: string }
        target_type: { type: string }
        target_id: { type: string }
      required: [comment_id, target_type, target_id]
    CommentListRequest:
      type: object
      properties:
        target_type: { type: string }
        target_id: { type: string }
        user_guid: { type: string }
        org_wide: { type: boolean }
        status: { type: string, enum: [current, archived, doomed] }
        hashtag: { type: string }
        created_after: { type: string, format: date-time }
        created_before: { type: string, format: date-time }
        limit: { type: integer, minimum: 1, maximum: 100 }
        next_token: { type: string }
      description: Requires target_type+target_id, user_guid, or org_wide=true.
    CommentReviseRequest:
      type: object
      properties:
        comment_id: { type: string }
        target_type: { type: string }
        target_id: { type: string }
        caption: { type: string }
        body: { type: string }
        attachments:
          type: array
          items: { $ref: '#/components/schemas/CommentAttachment' }
        hashtags:
          type: array
          items: { type: string }
        mentions_users:
          type: array
          items: { type: string }
        mentions_teams:
          type: array
          items: { type: string }
        expected_revision: { type: integer }
      required: [comment_id, target_type, target_id]
    CommentStatusRequest:
      type: object
      properties:
        comment_id: { type: string }
        target_type: { type: string }
        target_id: { type: string }
        status: { type: string, enum: [current, archived, doomed] }
      required: [comment_id, target_type, target_id, status]
    CommentReportRequest:
      type: object
      properties:
        limit: { type: integer, minimum: 1, maximum: 100 }
    CommentEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                comment: { $ref: '#/components/schemas/Comment' }
              required: [comment]
    CommentListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                items:
                  type: array
                  items: { $ref: '#/components/schemas/Comment' }
                next_token: { type: string }
              required: [items]
    CommentReportEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      comment_id: { type: string }
                      target_type: { type: string }
                      target_id: { type: string }
                      status: { type: string }
                      total_size_bytes: { type: integer }
                      created_at: { type: string, format: date-time }
                      current_revision: { type: integer }
                    required: [comment_id, target_type, target_id]
              required: [items]
    InboxNotification:
      type: object
      properties:
        notification_id: { type: string }
        team_guid: { type: string }
        status:
          type: string
          enum: [inbox, archived, all]
          default: inbox
          description: Default inbox; use all to include archived.
        state: { type: string, enum: [pending, completed, deferred] }
        priority: { type: string, enum: [low, medium, high, show_stopper] }
        act_by: { type: string, format: date-time }
        title: { type: string }
        body: { type: string }
        record_type: { type: string }
        record_id: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        created_by: { type: string }
      required: [notification_id, team_guid, status, state, priority, title]
    InboxCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        notification_id: { type: string }
        team_guid: { type: string }
        status: { type: string, enum: [inbox, archived] }
        state: { type: string, enum: [pending, completed, deferred] }
        priority: { type: string, enum: [low, medium, high, show_stopper] }
        act_by: { type: string, format: date-time }
        title: { type: string }
        body: { type: string }
        record_type: { type: string }
        record_id: { type: string }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
      required: [team_guid, title]
    InboxGetRequest:
      type: object
      properties:
        notification_id: { type: string }
      required: [notification_id]
    InboxListRequest:
      type: object
      properties:
        team_guid: { type: string }
        org_wide: { type: boolean }
        status: { type: string, enum: [inbox, archived] }
        state: { type: string, enum: [pending, completed, deferred] }
        limit: { type: integer, minimum: 1, maximum: 100 }
        next_token: { type: string }
      description: Requires team_guid unless org_wide=true (owner-only).
    InboxStatusRequest:
      type: object
      properties:
        notification_id: { type: string }
        status: { type: string, enum: [inbox, archived] }
      required: [notification_id, status]
    InboxStateRequest:
      type: object
      properties:
        notification_id: { type: string }
        state: { type: string, enum: [pending, completed, deferred] }
      required: [notification_id, state]
    InboxEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                notification: { $ref: '#/components/schemas/InboxNotification' }
              required: [notification]
    InboxListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                items:
                  type: array
                  items: { $ref: '#/components/schemas/InboxNotification' }
                next_token: { type: string }
              required: [items]
    PayloadRef:
      type: object
      properties:
        ref_type: { type: string }
        ref_id: { type: string }
        ref_uri: { type: string }
        content_type: { type: string }
        content_length: { type: integer }
      required: [ref_type, ref_id]
    EdiStatusHistoryEntry:
      type: object
      properties:
        status: { type: string, enum: [received, parsed, accepted, rejected, queued, sent, acknowledged, error] }
        at: { type: string, format: date-time }
        reason: { type: string }
        actor: { type: string }
      required: [status, at, reason]
    EdiRecord:
      type: object
      properties:
        edi_id: { type: string }
        status: { type: string, enum: [received, parsed, accepted, rejected, queued, sent, acknowledged, error] }
        direction: { type: string, enum: [inbound, outbound] }
        doc_type: { type: string }
        logical_guid: { type: string }
        channel_code: { type: string }
        partner_code: { type: string }
        control_number: { type: string }
        external_ref: { type: string }
        payload_format: { type: string }
        payload_ref: { $ref: '#/components/schemas/PayloadRef' }
        payload:
          oneOf:
            - type: string
            - type: object
        subject_refs: { $ref: '#/components/schemas/SourceRefs' }
        status_history:
          type: array
          items: { $ref: '#/components/schemas/EdiStatusHistoryEntry' }
        status_detail:
          type: object
          additionalProperties: true
        status_notes: { type: string }
        ack_ref: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        revision: { type: integer }
      required: [edi_id, status, direction, doc_type]
    EdiRecordDraft:
      type: object
      properties:
        edi_id: { type: string }
        status: { type: string, enum: [received, parsed, accepted, rejected, queued, sent, acknowledged, error] }
        direction: { type: string, enum: [inbound, outbound] }
        doc_type: { type: string }
        logical_guid: { type: string }
        channel_code: { type: string }
        partner_code: { type: string }
        control_number: { type: string }
        external_ref: { type: string }
        payload_format: { type: string }
        payload_ref: { $ref: '#/components/schemas/PayloadRef' }
        payload:
          oneOf:
            - type: string
            - type: object
        subject_refs: { $ref: '#/components/schemas/SourceRefs' }
        status_detail:
          type: object
          additionalProperties: true
        status_notes: { type: string }
        ack_ref: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [direction, doc_type]
    EdiRecordRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        edi_record: { $ref: '#/components/schemas/EdiRecordDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [edi_record, reason, source_refs]
    EdiGetRequest:
      type: object
      properties:
        edi_id: { type: string }
      required: [edi_id]
    EdiListRequest:
      type: object
      properties:
        status: { type: string, enum: [received, parsed, accepted, rejected, queued, sent, acknowledged, error] }
        direction: { type: string, enum: [inbound, outbound] }
        doc_type: { type: string }
        partner_code: { type: string }
        logical_guid: { type: string }
        channel_code: { type: string }
        created_from: { type: string, format: date-time }
        created_to: { type: string, format: date-time }
        limit: { type: integer }
        next_token: { type: string }
    EdiStatusSetRequest:
      type: object
      properties:
        edi_id: { type: string }
        status: { type: string, enum: [received, parsed, accepted, rejected, queued, sent, acknowledged, error] }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        status_detail:
          type: object
          additionalProperties: true
        status_notes: { type: string }
        ack_ref: { type: string }
      required: [edi_id, status, expected_revision, reason, source_refs]
    EdiEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                edi_record: { $ref: '#/components/schemas/EdiRecord' }
              required: [edi_record]
    EdiListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                edi_records:
                  type: array
                  items: { $ref: '#/components/schemas/EdiRecord' }
                next_token: { type: string }
              required: [edi_records]
    RentalAgreement:
      type: object
      properties:
        rental_id: { type: string }
        status:
          type: string
          enum: [created, active, return_pending, returned, inspected, closed, extended]
        customer_ref: { type: string }
        variant_id: { type: string }
        serial_number: { type: string }
        rental_rate_id: { type: string }
        quantity: { type: integer }
        duration_days: { type: integer }
        start_date: { type: string, format: date-time }
        expected_return_date: { type: string, format: date-time }
        actual_return_date: { type: string, format: date-time }
        deposit_minor: { type: integer }
        deposit_currency: { type: string }
        deposit_status:
          type: string
          enum: [held, refunded, forfeited, partial]
        condition_on_checkout: { type: string }
        condition_on_return: { type: string }
        condition_notes: { type: string }
        late_fee_minor: { type: integer }
        damage_fee_minor: { type: integer }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        reason: { type: string }
        idempotency_key: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        revision: { type: integer }
    RentalAgreementDraft:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        reason: { type: string }
        customer_ref: { type: string }
        variant_id: { type: string }
        serial_number: { type: string }
        rental_rate_id: { type: string }
        quantity: { type: integer }
        duration_days: { type: integer }
        start_date: { type: string, format: date-time }
        expected_return_date: { type: string, format: date-time }
        deposit_minor: { type: integer }
        deposit_currency: { type: string }
        condition_on_checkout: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
      required: [customer_ref, variant_id, duration_days, source_refs, reason, idempotency_key]
    RentalAgreementEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                rental_agreement: { $ref: '#/components/schemas/RentalAgreement' }
              required: [rental_agreement]
    RentalAgreementListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                rental_agreements:
                  type: array
                  items: { $ref: '#/components/schemas/RentalAgreement' }
                next_token: { type: string }
              required: [rental_agreements]
    OrderEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                order: { $ref: '#/components/schemas/Order' }
              required: [order]
    OrderListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                orders:
                  type: array
                  items: { $ref: '#/components/schemas/Order' }
                next_token: { type: string }
              required: [orders]
    ChannelPolicyEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                policy: { $ref: '#/components/schemas/ChannelPolicy' }
              required: [policy]
    RoutingPolicyEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                policy: { $ref: '#/components/schemas/RoutingPolicy' }
              required: [policy]
    RoutingPolicyListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                policies:
                  type: array
                  items: { $ref: '#/components/schemas/RoutingPolicy' }
                next_token: { type: string }
              required: [policies]
    RoutingPlanEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                plan: { $ref: '#/components/schemas/RoutingPlan' }
                options:
                  type: array
                  items: { $ref: '#/components/schemas/PromiseOption' }
              required: [plan]
    RoutingPlanListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                plans:
                  type: array
                  items: { $ref: '#/components/schemas/RoutingPlan' }
                next_token: { type: string }
              required: [plans]
    TaxPolicyEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                policy: { $ref: '#/components/schemas/TaxPolicy' }
              required: [policy]
    TaxPolicyListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                policies:
                  type: array
                  items: { $ref: '#/components/schemas/TaxPolicy' }
                next_token: { type: string }
              required: [policies]
    TaxQuoteEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                tax_quote: { $ref: '#/components/schemas/TaxQuote' }
              required: [tax_quote]
    TaxRecordEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                tax_record: { $ref: '#/components/schemas/TaxRecord' }
              required: [tax_record]
    PromiseQuoteEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                quote: { $ref: '#/components/schemas/PromiseQuote' }
              required: [quote]
    ShipmentEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                shipment: { $ref: '#/components/schemas/Shipment' }
              required: [shipment]
    ShipmentListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                shipments:
                  type: array
                  items: { $ref: '#/components/schemas/Shipment' }
                next_token: { type: string }
              required: [shipments]
    Quote:
      type: object
      properties:
        quote_id: { type: string }
        status: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        customer_ref: { type: string }
        payment_terms: { $ref: '#/components/schemas/PaymentTerms' }
        catalog_snapshot: { $ref: '#/components/schemas/CatalogSnapshot' }
        price_snapshot: { $ref: '#/components/schemas/PriceSnapshot' }
        policy_versions:
          type: object
          properties:
            pricing_policy_version: { type: string }
            promotion_policy_version: { type: string }
            discount_policy_version: { type: string }
            tax_policy_version: { type: string }
            approval_policy_version: { type: string }
            stacking_policy_version: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/OrderLine' }
        totals: { $ref: '#/components/schemas/OrderTotals' }
        created_at: { type: string, format: date-time }
        approved_at: { type: string, format: date-time }
        expires_at: { type: string, format: date-time }
        revision: { type: integer }
    QuoteDraft:
      type: object
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        reason: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        customer_ref: { type: string }
        payment_terms: { $ref: '#/components/schemas/PaymentTerms' }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/OrderLine' }
        notes: { type: string }
        expires_at: { type: string, format: date-time }
      required: [request_context, reason, source_refs]
    QuoteCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        quote: { $ref: '#/components/schemas/QuoteDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [quote, reason, source_refs]
    QuoteApproveRequest:
      type: object
      properties:
        quote_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [quote_id, reason, source_refs]
    QuoteConvertRequest:
      type: object
      properties:
        quote_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [quote_id, reason, source_refs]
    QuoteGetRequest:
      type: object
      properties:
        quote_id: { type: string }
        include_lines: { type: boolean }
      required: [quote_id]
    QuoteListRequest:
      type: object
      properties:
        status: { type: string }
        channel_code: { type: string }
        customer_ref: { type: string }
        created_from: { type: string, format: date-time }
        created_to: { type: string, format: date-time }
        limit: { type: integer }
        next_token: { type: string }
    QuoteEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                quote: { $ref: '#/components/schemas/Quote' }
              required: [quote]
    QuoteListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                quotes:
                  type: array
                  items: { $ref: '#/components/schemas/Quote' }
                next_token: { type: string }
              required: [quotes]
    BackorderLine:
      type: object
      properties:
        line_id: { type: string }
        order_line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        promised_at: { type: string, format: date-time }
        reason_code: { type: string }
      required: [qty]
    Backorder:
      type: object
      properties:
        backorder_id: { type: string }
        status: { type: string }
        order_id: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        customer_ref: { type: string }
        policy_versions:
          type: object
          properties:
            backorder_policy_version: { type: string }
            approval_policy_version: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/BackorderLine' }
        created_at: { type: string, format: date-time }
        fulfilled_at: { type: string, format: date-time }
        cancel_code: { type: string }
        cancel_note: { type: string }
        cancelled_at: { type: string, format: date-time }
        revision: { type: integer }
    BackorderDraft:
      type: object
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        reason: { type: string }
        order_id: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        customer_ref: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/BackorderLine' }
        notes: { type: string }
      required: [request_context, reason, source_refs]
    BackorderCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        backorder: { $ref: '#/components/schemas/BackorderDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [backorder, reason, source_refs]
    BackorderApproveRequest:
      type: object
      properties:
        backorder_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [backorder_id, reason, source_refs]
    BackorderFulfillRequest:
      type: object
      properties:
        backorder_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [backorder_id, reason, source_refs]
    BackorderCancelRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        backorder_id: { type: string }
        expected_revision: { type: integer }
        cancel_code: { type: string }
        cancel_note: { type: string }
        cancelled_at: { type: string, format: date-time }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [backorder_id, cancel_code, reason, source_refs]
    BackorderGetRequest:
      type: object
      properties:
        backorder_id: { type: string }
        include_lines: { type: boolean }
      required: [backorder_id]
    BackorderListRequest:
      type: object
      properties:
        status: { type: string }
        channel_code: { type: string }
        customer_ref: { type: string }
        order_id: { type: string }
        created_from: { type: string, format: date-time }
        created_to: { type: string, format: date-time }
        limit: { type: integer }
        next_token: { type: string }
    BackorderEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                backorder: { $ref: '#/components/schemas/Backorder' }
              required: [backorder]
    BackorderListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                backorders:
                  type: array
                  items: { $ref: '#/components/schemas/Backorder' }
                next_token: { type: string }
              required: [backorders]
    SpecialOrderLine:
      type: object
      properties:
        line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        requested_price: { $ref: '#/components/schemas/Money' }
      required: [qty]
    SpecialOrder:
      type: object
      properties:
        special_order_id: { type: string }
        status: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        customer_ref: { type: string }
        payment_terms: { $ref: '#/components/schemas/PaymentTerms' }
        policy_versions:
          type: object
          properties:
            special_order_policy_version: { type: string }
            approval_policy_version: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/SpecialOrderLine' }
        deposit: { $ref: '#/components/schemas/Money' }
        procurement_ref: { type: string }
        created_at: { type: string, format: date-time }
        submitted_at: { type: string, format: date-time }
        cancel_code: { type: string }
        cancel_note: { type: string }
        cancelled_at: { type: string, format: date-time }
        revision: { type: integer }
    SpecialOrderDraft:
      type: object
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        reason: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        customer_ref: { type: string }
        payment_terms: { $ref: '#/components/schemas/PaymentTerms' }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/SpecialOrderLine' }
        deposit: { $ref: '#/components/schemas/Money' }
        notes: { type: string }
      required: [request_context, reason, source_refs]
    SpecialOrderCreateRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        special_order: { $ref: '#/components/schemas/SpecialOrderDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [special_order, reason, source_refs]
    SpecialOrderApproveRequest:
      type: object
      properties:
        special_order_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [special_order_id, reason, source_refs]
    SpecialOrderSubmitRequest:
      type: object
      properties:
        special_order_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [special_order_id, reason, source_refs]
    SpecialOrderCancelRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        special_order_id: { type: string }
        expected_revision: { type: integer }
        cancel_code: { type: string }
        cancel_note: { type: string }
        cancelled_at: { type: string, format: date-time }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [special_order_id, cancel_code, reason, source_refs]
    SpecialOrderGetRequest:
      type: object
      properties:
        special_order_id: { type: string }
        include_lines: { type: boolean }
      required: [special_order_id]
    SpecialOrderListRequest:
      type: object
      properties:
        status: { type: string }
        channel_code: { type: string }
        customer_ref: { type: string }
        created_from: { type: string, format: date-time }
        created_to: { type: string, format: date-time }
        limit: { type: integer }
        next_token: { type: string }
    SpecialOrderEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                special_order: { $ref: '#/components/schemas/SpecialOrder' }
              required: [special_order]
    SpecialOrderListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                special_orders:
                  type: array
                  items: { $ref: '#/components/schemas/SpecialOrder' }
                next_token: { type: string }
              required: [special_orders]
    ReturnLine:
      type: object
      properties:
        line_id: { type: string }
        order_line_id: { type: string }
        variant_id: { type: string }
        sku: { type: string }
        qty: { $ref: '#/components/schemas/UomQuantity' }
        reason_code: { type: string }
        condition: { type: string }
      required: [qty]
    Return:
      type: object
      properties:
        return_id: { type: string }
        status: { type: string }
        order_id: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        customer_ref: { type: string }
        policy_versions:
          type: object
          properties:
            returns_policy_version: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/ReturnLine' }
        created_at: { type: string, format: date-time }
        received_at: { type: string, format: date-time }
        revision: { type: integer }
    ReturnDraft:
      type: object
      properties:
        request_context: { $ref: '#/components/schemas/RequestContext' }
        policy_refs: { $ref: '#/components/schemas/PolicyRefs' }
        reason: { type: string }
        order_id: { type: string }
        channel_code: { type: string }
        logical_guid: { type: string }
        customer_ref: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        lines:
          type: array
          items: { $ref: '#/components/schemas/ReturnLine' }
        notes: { type: string }
      required: [request_context, reason, source_refs]
    ReturnRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        return: { $ref: '#/components/schemas/ReturnDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [return, reason, source_refs]
    ReturnReceiveRequest:
      type: object
      properties:
        return_id: { type: string }
        expected_revision: { type: integer }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [return_id, reason, source_refs]
    ReturnGetRequest:
      type: object
      properties:
        return_id: { type: string }
        include_lines: { type: boolean }
      required: [return_id]
    ReturnListRequest:
      type: object
      properties:
        status: { type: string }
        channel_code: { type: string }
        customer_ref: { type: string }
        order_id: { type: string }
        created_from: { type: string, format: date-time }
        created_to: { type: string, format: date-time }
        limit: { type: integer }
        next_token: { type: string }
    Refund:
      type: object
      properties:
        refund_id: { type: string }
        status: { type: string }
        order_id: { type: string }
        amount: { $ref: '#/components/schemas/Money' }
        tender_ref: { type: string }
        issued_at: { type: string, format: date-time }
        policy_versions:
          type: object
          properties:
            returns_policy_version: { type: string }
            tender_policy_version: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        revision: { type: integer }
    TenderLiability:
      type: object
      properties:
        liability_type: { type: string }
        liability_state: { type: string, enum: [open, settled, voided] }
        liability_amount: { $ref: '#/components/schemas/Money' }
        liability_ref: { type: string }
        opened_at: { type: string, format: date-time }
        settled_at: { type: string, format: date-time }
        voided_at: { type: string, format: date-time }
    Tender:
      type: object
      properties:
        tender_id: { type: string }
        status: { type: string }
        order_id: { type: string }
        tender_code: { type: string }
        tender_ref: { type: string }
        amount: { $ref: '#/components/schemas/Money' }
        liability: { $ref: '#/components/schemas/TenderLiability' }
        channel_code: { type: string }
        logical_guid: { type: string }
        captured_at: { type: string, format: date-time }
        voided_at: { type: string, format: date-time }
        policy_versions:
          type: object
          properties:
            tender_policy_version: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        revision: { type: integer }
    TenderDraft:
      type: object
      properties:
        tender_id: { type: string }
        order_id: { type: string }
        tender_code: { type: string }
        tender_ref: { type: string }
        amount: { $ref: '#/components/schemas/Money' }
        liability: { $ref: '#/components/schemas/TenderLiability' }
        channel_code: { type: string }
        logical_guid: { type: string }
        policy_refs:
          type: object
          properties:
            tender_policy_version: { type: string }
        request_context: { $ref: '#/components/schemas/RequestContext' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [order_id, tender_code, amount, request_context, reason, source_refs]
    RefundRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        refund: { $ref: '#/components/schemas/Refund' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [refund, reason, source_refs]
    TenderCaptureRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        tender: { $ref: '#/components/schemas/TenderDraft' }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        cccode: { type: string }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [tender, reason, source_refs]
    TenderVoidRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        tender_id: { type: string }
        expected_revision: { type: integer }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [tender_id, reason, source_refs]
    TenderSettleRequest:
      type: object
      x-idempotency-scope: orgcode+route+idempotency_key
      x-idempotency-retention-hours: 24
      x-idempotency-replay: return_original_response
      properties:
        tender_id: { type: string }
        expected_revision: { type: integer }
        liability_ref: { type: string }
        settled_at: { type: string, format: date-time }
        idempotency_key: { $ref: '#/components/schemas/IdempotencyKey' }
        reason: { type: string }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
      required: [tender_id, reason, source_refs]
    TenderGetRequest:
      type: object
      properties:
        tender_id: { type: string }
      required: [tender_id]
    TenderListRequest:
      type: object
      properties:
        order_id: { type: string }
        status: { type: string }
        limit: { type: integer }
        next_token: { type: string }
    ReturnEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                return: { $ref: '#/components/schemas/Return' }
              required: [return]
    ReturnListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                returns:
                  type: array
                  items: { $ref: '#/components/schemas/Return' }
                next_token: { type: string }
              required: [returns]
    RefundEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                refund: { $ref: '#/components/schemas/Refund' }
              required: [refund]
    TenderEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                tender: { $ref: '#/components/schemas/Tender' }
              required: [tender]
    TenderListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                tenders:
                  type: array
                  items: { $ref: '#/components/schemas/Tender' }
                next_token: { type: string }
              required: [tenders]
    WarrantyClaimDraft:
      type: object
      properties:
        claim_id: { type: string }
        warranty_id: { type: string }
        customer_ref: { type: string }
        serial_number: { type: string }
        variant_id: { type: string }
        issue_description: { type: string }
      required: [warranty_id, customer_ref, issue_description]
    WarrantyClaim:
      type: object
      properties:
        claim_id: { type: string }
        orgcode: { type: string }
        warranty_id: { type: string }
        customer_ref: { type: string }
        serial_number: { type: string }
        variant_id: { type: string }
        status: { type: string, enum: [filed, approved, in_repair, resolved, denied] }
        issue_description: { type: string }
        filed_at: { type: string, format: date-time }
        approved_at: { type: string, format: date-time }
        approved_by: { type: string }
        disposition: { type: string, enum: [repair, replace, credit, deny] }
        resolution_notes: { type: string }
        resolved_at: { type: string, format: date-time }
        source_refs: { $ref: '#/components/schemas/SourceRefs' }
        logical_guid: { type: string }
        reason: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        revision: { type: integer }
    WarrantyClaimEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                claim: { $ref: '#/components/schemas/WarrantyClaim' }
              required: [claim]
    WarrantyClaimListEnvelope:
      allOf:
        - { $ref: '#/components/schemas/Envelope' }
        - type: object
          properties:
            data:
              type: object
              properties:
                claims:
                  type: array
                  items: { $ref: '#/components/schemas/WarrantyClaim' }
                next_token: { type: string }
              required: [claims]
paths:
  /stat:
    get:
      summary: Health check
      description: |
        Health check. Tenant routes require x-orgcode; /stat health checks do not. Org-scoped reads may
        return 404 for non-associated callers (anti-enumeration). Route class Tier A (p95 500ms).
      x-route-class: Tier A
      x-qps-target: 5
      x-concurrency-target: 2
      x-latency-p95-ms: 500
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Envelope' }
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          service: { type: string }
                          status: { type: string }
  /order/create:
    post:
      summary: Create order (draft)
      description: |
        Create order (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 1000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderEnvelope' }
  /order/place:
    post:
      summary: Place order (draft)
      description: |
        Place order (draft). Verifies product compliance against PVM catalog (H6) and
        price validity against PPM active price entries (M9). Returns 409
        `price-drift-detected` if any line's unit_price does not match an active PPM
        sell_price for the variant. Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 1000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderPlaceRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderEnvelope' }
  /order/cancel:
    post:
      summary: Cancel order (draft)
      description: |
        Cancel order (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 350ms, p99 800ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 350
      x-latency-p99-ms: 800
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderCancelRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderEnvelope' }
  /order/line/cancel:
    post:
      summary: Cancel order line quantities (partial cancel)
      description: |
        Cancel order line quantities (partial cancel). Auth is via headers; org identity uses x-orgcode or
        body placement as documented. Route class Tier D (p95 350ms, p99 800ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 350
      x-latency-p99-ms: 800
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderLineCancelRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderEnvelope' }
  /order/promise/reserve:
    post:
      summary: Reserve inventory for order (draft)
      description: |
        Reserve inventory for order (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier D (p95 300ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 1000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderPromiseReserveRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderEnvelope' }
  /order/promise/allocate:
    post:
      summary: Allocate reserved inventory (draft)
      description: |
        Allocate reserved inventory (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier D (p95 300ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 1000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderPromiseAllocateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderEnvelope' }
  /order/promise/commit:
    post:
      summary: Commit allocated inventory (draft)
      description: |
        Commit allocated inventory (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. If this updates a revisioned record, expected_revision is required (428 if
        missing; 409 on mismatch). Route class Tier D (p95 300ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 1000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderPromiseCommitRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderEnvelope' }
  /order/promise/commit-direct:
    post:
      summary: Direct commit inventory (fast POS) (draft)
      description: |
        Direct commit — single-step inventory commit that bypasses reservation and allocation phases.
        Calls ICS /commit/create-direct to atomically move stock from available to committed. Designed
        for in-store POS fast checkout. Sets commit_mode: 'direct' on the promise record. Route class
        Tier D (p95 250ms, p99 500ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 1500
      x-latency-p95-ms: 250
      x-latency-p99-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderPromiseCommitRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderEnvelope' }
  /order/promise/release:
    post:
      summary: Release inventory promise (draft)
      description: |
        Release inventory promise (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier D (p95 350ms, p99 800ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 500
      x-concurrency-target: 800
      x-latency-p95-ms: 350
      x-latency-p99-ms: 800
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderPromiseReleaseRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderEnvelope' }
  /order/promise/quote:
    post:
      summary: Quote inventory promise (ATP/CTP) (draft)
      description: |
        Quote inventory promise (ATP/CTP) (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier C (p95 400ms, p99 900ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 400
      x-latency-p99-ms: 900
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderPromiseQuoteRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PromiseQuoteEnvelope' }
  /order/get:
    post:
      summary: Get order (draft)
      description: |
        Get order (draft). Auth is via headers; org identity uses x-orgcode or body placement as documented.
        Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route class Tier B
        (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderEnvelope' }
  /order/list:
    post:
      summary: List orders (draft)
      description: |
        List orders (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderListEnvelope' }
  /order/search:
    post:
      summary: Search orders (partial match)
      description: |
        Search orders (partial match). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Search results may be eventually consistent; use exact-match reads for immediate
        consistency. Route class Tier C (p95 250ms, p99 600ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 1000
      x-concurrency-target: 1500
      x-latency-p95-ms: 250
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderSearchRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderListEnvelope' }
  /order/fulfill:
    post:
      summary: Fulfill order (draft)
      description: |
        Fulfill order (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 1000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderFulfillRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderEnvelope' }
  /order/close:
    post:
      summary: Close order (draft)
      description: |
        Close order (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 1000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OrderCloseRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderEnvelope' }
  /checkout:
    post:
      summary: Composite checkout (draft)
      description: |
        Composite checkout orchestration. Creates order, places it, commits inventory via ICS, captures
        tender, and optionally computes inline tax. When checkout.fast_commit is true, uses a single
        direct-commit step (ICS /commit/create-direct) bypassing reserve+allocate phases — ideal for
        in-store POS. Otherwise uses standard 3-phase reserve/allocate/commit. On failure, performs
        compensating rollback (promise release + order cancel). Auth is via headers. Route class Tier D
        (p95 800ms / 400ms fast, p99 1500ms / 700ms fast).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 500
      x-concurrency-target: 800
      x-latency-p95-ms: 800
      x-latency-p99-ms: 1500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              x-idempotency-scope: orgcode+route+idempotency_key
              x-idempotency-retention-hours: 24
              x-idempotency-replay: return_original_response
              required: [checkout, reason, source_refs]
              properties:
                checkout:
                  type: object
                  required: [order, tender]
                  properties:
                    order: { type: object }
                    tender: { type: object }
                    promise: { type: object }
                    tax: { type: object }
                    fast_commit:
                      type: boolean
                      description: When true, uses single-step direct commit (skips reserve+allocate) for in-store POS speed.
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
                idempotency_key: { type: string }
                session_guid: { type: string }
                api_key: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      checkout:
                        type: object
                        properties:
                          order_id: { type: string }
                          order: { type: object }
                          tender: { type: object }
                          promise: { type: object }
                          tax_quote: { type: object }
                          steps: { type: array, items: { type: object } }
                          total_duration_ms: { type: number }
  /channel/policy/get:
    post:
      summary: Get channel policy (draft)
      description: |
        Get channel policy (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ChannelPolicyGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ChannelPolicyEnvelope' }
  /channel/policy/set:
    post:
      summary: Set channel policy (draft)
      description: |
        Set channel policy (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier B (p95 350ms, p99 800ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 150
      x-concurrency-target: 250
      x-latency-p95-ms: 350
      x-latency-p99-ms: 800
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ChannelPolicySetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ChannelPolicyEnvelope' }
  /tax/policy/get:
    post:
      summary: Get tax policy (draft)
      description: |
        Get tax policy (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TaxPolicyGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaxPolicyEnvelope' }
  /tax/policy/list:
    post:
      summary: List tax policies (draft)
      description: |
        List tax policies (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TaxPolicyListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaxPolicyListEnvelope' }
  /tax/policy/set:
    post:
      summary: Set tax policy (draft)
      description: |
        Set tax policy (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier C (p95 350ms, p99 800ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 150
      x-concurrency-target: 250
      x-latency-p95-ms: 350
      x-latency-p99-ms: 800
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TaxPolicySetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaxPolicyEnvelope' }
  /tax/quote:
    post:
      summary: Quote taxes (draft)
      description: |
        Quote taxes (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier C (p95 400ms, p99 900ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 400
      x-latency-p99-ms: 900
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TaxQuoteRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaxQuoteEnvelope' }
  /tax/finalize:
    post:
      summary: Finalize taxes (draft)
      description: |
        Finalize taxes (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier C (p95 450ms, p99 1000ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 350
      x-latency-p95-ms: 450
      x-latency-p99-ms: 1000
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TaxFinalizeRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaxRecordEnvelope' }
  /routing/policy/get:
    post:
      summary: Get routing policy (draft)
      description: |
        Get routing policy (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RoutingPolicyGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RoutingPolicyEnvelope' }
  /routing/policy/list:
    post:
      summary: List routing policies (draft)
      description: |
        List routing policies (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RoutingPolicyListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RoutingPolicyListEnvelope' }
  /routing/policy/set:
    post:
      summary: Set routing policy (draft)
      description: |
        Set routing policy (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier C (p95 350ms, p99 800ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 150
      x-concurrency-target: 250
      x-latency-p95-ms: 350
      x-latency-p99-ms: 800
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RoutingPolicySetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RoutingPolicyEnvelope' }
  /routing/plan/create:
    post:
      summary: Create routing plan (draft)
      description: |
        Create routing plan (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier C (p95 450ms, p99 1000ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 350
      x-latency-p95-ms: 450
      x-latency-p99-ms: 1000
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RoutingPlanCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RoutingPlanEnvelope' }
  /routing/plan/get:
    post:
      summary: Get routing plan (draft)
      description: |
        Get routing plan (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RoutingPlanGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RoutingPlanEnvelope' }
  /routing/plan/list:
    post:
      summary: List routing plans (draft)
      description: |
        List routing plans (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RoutingPlanListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RoutingPlanListEnvelope' }
  /fulfillment/shipment/create:
    post:
      summary: Create fulfillment shipment (draft)
      description: |
        Create fulfillment shipment (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. If this updates a revisioned record, expected_revision is required (428 if
        missing; 409 on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 1000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/get:
    post:
      summary: Get shipment (draft)
      description: |
        Get shipment (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/list:
    post:
      summary: List shipments (draft)
      description: |
        List shipments (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentListEnvelope' }
  /fulfillment/shipment/pick:
    post:
      summary: Mark shipment picked (draft)
      description: |
        Mark shipment picked (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 300
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentPickRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/pack:
    post:
      summary: Mark shipment packed (draft)
      description: |
        Mark shipment packed (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 300
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentPackRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/ship:
    post:
      summary: Mark shipment shipped (draft)
      description: |
        Mark shipment shipped (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 300
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentShipRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/deliver:
    post:
      summary: Mark shipment delivered (draft)
      description: |
        Mark shipment delivered (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Route class Tier D (p95 300ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 300
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentDeliverRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/pickup/ready:
    post:
      summary: Mark shipment pickup ready (draft)
      description: |
        Mark shipment pickup ready (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier D (p95 300ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 300
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentPickupReadyRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/pickup/complete:
    post:
      summary: Mark shipment pickup completed (draft)
      description: |
        Mark shipment pickup completed (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier D (p95 300ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 300
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentPickupCompleteRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/pickup/no_show:
    post:
      summary: Mark shipment pickup no-show (draft)
      description: |
        Mark shipment pickup no-show (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier D (p95 300ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 300
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentPickupNoShowRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/exception:
    post:
      summary: Mark shipment exception (draft)
      description: |
        Mark shipment exception (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Route class Tier D (p95 350ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 400
      x-concurrency-target: 600
      x-latency-p95-ms: 350
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentExceptionRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/exception/short-pick:
    post:
      summary: Record short pick exception (draft)
      description: |
        Record short pick exception (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier D (p95 350ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 400
      x-concurrency-target: 600
      x-latency-p95-ms: 350
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentExceptionShortPickRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/exception/damaged:
    post:
      summary: Record damaged exception (draft)
      description: |
        Record damaged exception (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Route class Tier D (p95 350ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 400
      x-concurrency-target: 600
      x-latency-p95-ms: 350
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentExceptionDamagedRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/exception/carrier-failure:
    post:
      summary: Record carrier failure exception (draft)
      description: |
        Record carrier failure exception (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier D (p95 350ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 400
      x-concurrency-target: 600
      x-latency-p95-ms: 350
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentExceptionCarrierFailureRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/exception/partial:
    post:
      summary: Record partial fulfillment exception (draft)
      description: |
        Record partial fulfillment exception (draft). Auth is via headers; org identity uses x-orgcode or
        body placement as documented. Route class Tier D (p95 350ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 400
      x-concurrency-target: 600
      x-latency-p95-ms: 350
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentExceptionPartialRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/exception/resolve:
    post:
      summary: Resolve shipment exception (draft)
      description: |
        Resolve shipment exception (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Org-scoped reads may return 404 for non-associated callers
        (anti-enumeration). Route class Tier D (p95 350ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 400
      x-concurrency-target: 600
      x-latency-p95-ms: 350
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentExceptionResolveRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/cancel:
    post:
      summary: Cancel shipment (draft)
      description: |
        Cancel shipment (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 350ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 400
      x-concurrency-target: 600
      x-latency-p95-ms: 350
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentCancelRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/substitution/apply:
    post:
      summary: Apply substitution to shipment line (draft)
      description: |
        Apply substitution to shipment line (draft). Auth is via headers; org identity uses x-orgcode or
        body placement as documented. Route class Tier D (p95 350ms, p99 700ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 400
      x-concurrency-target: 600
      x-latency-p95-ms: 350
      x-latency-p99-ms: 700
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ShipmentSubstitutionApplyRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /quote/create:
    post:
      summary: Create quote (draft)
      description: |
        Create quote (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/QuoteCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/QuoteEnvelope' }
  /quote/approve:
    post:
      summary: Approve quote (draft)
      description: |
        Approve quote (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/QuoteApproveRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/QuoteEnvelope' }
  /quote/convert:
    post:
      summary: Convert quote to order (draft)
      description: |
        Convert quote to order (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/QuoteConvertRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OrderEnvelope' }
  /quote/get:
    post:
      summary: Get quote (draft)
      description: |
        Get quote (draft). Auth is via headers; org identity uses x-orgcode or body placement as documented.
        Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route class Tier B
        (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/QuoteGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/QuoteEnvelope' }
  /quote/list:
    post:
      summary: List quotes (draft)
      description: |
        List quotes (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/QuoteListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/QuoteListEnvelope' }
  /quote/send:
    post:
      summary: Send quote (draft)
      description: |
        Send quote (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/QuoteSendRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/QuoteEnvelope' }
  /quote/accept:
    post:
      summary: Accept quote (draft)
      description: |
        Accept quote (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/QuoteAcceptRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/QuoteEnvelope' }
  /quote/expire:
    post:
      summary: Expire quote (draft)
      description: |
        Expire quote (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/QuoteExpireRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/QuoteEnvelope' }
  /quote/reject:
    post:
      summary: Reject quote (draft)
      description: |
        Reject quote (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/QuoteRejectRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/QuoteEnvelope' }
  /backorder/create:
    post:
      summary: Create backorder (draft)
      description: |
        Create backorder (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackorderCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackorderEnvelope' }
  /backorder/approve:
    post:
      summary: Approve backorder (draft)
      description: |
        Approve backorder (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackorderApproveRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackorderEnvelope' }
  /backorder/fulfill:
    post:
      summary: Fulfill backorder (draft)
      description: |
        Fulfill backorder (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackorderFulfillRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackorderEnvelope' }
  /backorder/cancel:
    post:
      summary: Cancel backorder (draft)
      description: |
        Cancel backorder (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 350ms, p99 800ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 350
      x-latency-p99-ms: 800
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackorderCancelRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackorderEnvelope' }
  /backorder/promise:
    post:
      summary: Promise backorder (draft)
      description: |
        Promise backorder (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackorderPromiseRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackorderEnvelope' }
  /backorder/partial-fulfill:
    post:
      summary: Partial fulfill backorder (draft)
      description: |
        Partial fulfill backorder (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackorderPartialFulfillRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackorderEnvelope' }
  /backorder/expire:
    post:
      summary: Expire backorder (draft)
      description: |
        Expire backorder (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackorderExpireRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackorderEnvelope' }
  /backorder/get:
    post:
      summary: Get backorder (draft)
      description: |
        Get backorder (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackorderGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackorderEnvelope' }
  /backorder/list:
    post:
      summary: List backorders (draft)
      description: |
        List backorders (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/BackorderListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BackorderListEnvelope' }
  /special-order/create:
    post:
      summary: Create special order (draft)
      description: |
        Create special order (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SpecialOrderCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SpecialOrderEnvelope' }
  /special-order/approve:
    post:
      summary: Approve special order (draft)
      description: |
        Approve special order (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SpecialOrderApproveRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SpecialOrderEnvelope' }
  /special-order/submit:
    post:
      summary: Submit special order (draft)
      description: |
        Submit special order (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SpecialOrderSubmitRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SpecialOrderEnvelope' }
  /special-order/cancel:
    post:
      summary: Cancel special order (draft)
      description: |
        Cancel special order (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 350ms, p99 800ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 600
      x-concurrency-target: 800
      x-latency-p95-ms: 350
      x-latency-p99-ms: 800
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SpecialOrderCancelRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SpecialOrderEnvelope' }
  /special-order/get:
    post:
      summary: Get special order (draft)
      description: |
        Get special order (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SpecialOrderGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SpecialOrderEnvelope' }
  /special-order/list:
    post:
      summary: List special orders (draft)
      description: |
        List special orders (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SpecialOrderListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SpecialOrderListEnvelope' }
  /special-order/status:
    post:
      summary: Update special order status (generic FSM transition)
      description: |
        Generic status transition for special orders. Valid transitions:
        draft→approved, approved→submitted, submitted→sourcing,
        sourcing→in_transit, in_transit→arrived, arrived→notified,
        notified→completed/forfeited. All statuses can transition to cancelled.
      x-status: active
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [special_order_id, status, reason, source_refs]
              properties:
                special_order_id: { type: string }
                status: { type: string, enum: [approved, submitted, sourcing, in_transit, arrived, notified, completed, forfeited, cancelled] }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
                expected_revision: { type: integer }
                estimated_arrival_date: { type: string, format: date-time }
                procurement_ref: { type: object }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SpecialOrderEnvelope' }
  /special-order/notify:
    post:
      summary: Notify customer that special order has arrived
      description: |
        Transitions special order from arrived → notified. Sets pickup_window_expires_at
        based on channel policy (default 14 days).
      x-status: active
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [special_order_id, reason, source_refs]
              properties:
                special_order_id: { type: string }
                notification_method: { type: string, default: system }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SpecialOrderEnvelope' }
  /special-order/pickup:
    post:
      summary: Customer picks up special order and pays remaining balance
      description: |
        Transitions special order from notified → completed. Accepts optional
        payment_amount for balance payment. Uses price_snapshot if price_lock is enabled.
      x-status: active
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [special_order_id, reason, source_refs]
              properties:
                special_order_id: { type: string }
                payment_amount: { type: number }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SpecialOrderEnvelope' }
  /special-order/recalculate:
    post:
      tags: [POS]
      summary: Recalculate special order status from PO receipt and payments
      description: |
        Checks PO receipt status for auto-arrival, re-sums payments, fixes balance and status.
      x-status: active
      x-route-class: Tier D
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      x-latency-p99-ms: 1000
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [special_order_id]
              properties:
                special_order_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SpecialOrderEnvelope' }
  /layaway/create:
    post:
      summary: Create a layaway
      description: |
        Creates a layaway with initial deposit. Validates minimum deposit against
        channel policy (default 20%). Snapshots layaway policy at creation time.
        Calculates service fee and expiration date.
      x-status: active
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              x-idempotency-scope: orgcode+route+idempotency_key
              x-idempotency-retention-hours: 24
              x-idempotency-replay: return_original_response
              required: [layaway]
              properties:
                layaway:
                  type: object
                  required: [customer_ref, lines, totals, deposit_amount]
                  properties:
                    customer_ref: { type: string }
                    lines: { type: array, items: { type: object } }
                    totals: { type: object, properties: { grand_total: { type: number }, tax: { type: number }, currency: { type: string } } }
                    deposit_amount: { type: number }
                    order_id: { type: string }
                    request_context: { type: object }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
                idempotency_key: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LayawayEnvelope' }
  /layaway/list:
    post:
      summary: List layaways
      description: |
        List layaways by status, customer_ref, or logical_guid.
        Paginated with limit/next_token.
      x-status: active
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string, enum: [layaway_pending, completed, layaway_cancelled, layaway_expired, layaway_forfeited] }
                customer_ref: { type: string }
                logical_guid: { type: string }
                limit: { type: integer }
                next_token: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LayawayListEnvelope' }
  /layaway/recall:
    post:
      summary: Recall layaway with payment history
      description: |
        Returns layaway details and full payment history. Read-only basket recall.
      x-status: active
      x-route-class: Tier A
      x-qps-target: 500
      x-concurrency-target: 800
      x-latency-p95-ms: 200
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [layaway_id]
              properties:
                layaway_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LayawayRecallEnvelope' }
  /layaway/payment:
    post:
      summary: Record layaway payment
      description: |
        Records a payment against a pending layaway. If balance reaches zero,
        transitions to completed. Emits layaway-payment or layaway-completed event.
      x-status: active
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              x-idempotency-scope: orgcode+route+idempotency_key
              x-idempotency-retention-hours: 24
              x-idempotency-replay: return_original_response
              required: [layaway_id, amount, reason, source_refs]
              properties:
                layaway_id: { type: string }
                amount: { type: number }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
                expected_revision: { type: integer }
                idempotency_key: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LayawayEnvelope' }
  /layaway/cancel:
    post:
      summary: Cancel a layaway
      description: |
        Cancels a pending layaway. Calculates refund (total_paid minus restocking fee
        and service fee). Gated by allow_layaway_cancel policy.
      x-status: active
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              x-idempotency-scope: orgcode+route+idempotency_key
              x-idempotency-retention-hours: 24
              x-idempotency-replay: return_original_response
              required: [layaway_id, cancel_code, reason, source_refs]
              properties:
                layaway_id: { type: string }
                cancel_code: { type: string }
                cancel_note: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
                expected_revision: { type: integer }
                idempotency_key: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LayawayCancelEnvelope' }
  /layaway/partial-pickup:
    post:
      summary: Partial pickup from layaway
      description: |
        Releases specific lines from a pending layaway. Gated by
        allow_layaway_partial_pickup policy. Validates that total_paid covers
        the value of all picked items.
      x-status: active
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [layaway_id, pickup_lines, reason, source_refs]
              properties:
                layaway_id: { type: string }
                pickup_lines: { type: array, items: { type: object, properties: { line_index: { type: integer }, qty: { type: number } } } }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LayawayEnvelope' }
  /layaway/recalculate:
    post:
      tags: [POS]
      summary: Recalculate layaway balance from payments
      description: |
        Re-sums all payment records, fixes total_paid and remaining_balance,
        auto-completes if fully paid.
      x-status: active
      x-route-class: Tier D
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      x-latency-p99-ms: 1000
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [layaway_id]
              properties:
                layaway_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LayawayEnvelope' }
  /return/request:
    post:
      summary: Request return (draft)
      description: |
        Request return (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReturnRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReturnEnvelope' }
  /return/receive:
    post:
      summary: Receive return (draft)
      description: |
        Receive return (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReturnReceiveRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReturnEnvelope' }
  /return/get:
    post:
      summary: Get return (draft)
      description: |
        Get return (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReturnGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReturnEnvelope' }
  /return/list:
    post:
      summary: List returns (draft)
      description: |
        List returns (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReturnListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReturnListEnvelope' }
  /return/authorize:
    post:
      summary: Authorize return (draft)
      description: |
        Authorize return (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReturnAuthorizeRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReturnEnvelope' }
  /return/inspect:
    post:
      summary: Inspect return (draft)
      description: |
        Inspect return (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReturnInspectRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReturnEnvelope' }
  /return/resolve:
    post:
      summary: Resolve return (draft)
      description: |
        Resolve return (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReturnResolveRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ReturnEnvelope' }
  /refund/issue:
    post:
      summary: Issue refund (draft)
      description: |
        Issue refund (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier D (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RefundRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RefundEnvelope' }
  /tender/capture:
    post:
      summary: Capture tender (draft)
      description: |
        Capture tender (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier D (p95 300ms, p99 600ms).
        If `gateway_code` is provided, it is validated against active payment gateways (400 `invalid-gateway` if not found).
        Active tender policy amount limits (`max_amount_minor` / `min_amount_minor`) are enforced (400 `tender-amount-exceeds-maximum` / `tender-amount-below-minimum`).
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 1000
      x-concurrency-target: 2000
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
        - { $ref: '#/components/parameters/ChannelHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TenderCaptureRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TenderEnvelope' }
  /tender/void:
    post:
      summary: Void tender (draft)
      description: |
        Void tender (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier C (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TenderVoidRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TenderEnvelope' }
  /tender/settle:
    post:
      summary: Settle tender liability (draft)
      description: |
        Settle tender liability (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. If this updates a revisioned record, expected_revision is required (428 if missing;
        409 on mismatch). Route class Tier C (p95 300ms, p99 600ms).
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TenderSettleRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TenderEnvelope' }
  /tender/get:
    post:
      summary: Get tender (draft)
      description: |
        Get tender (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TenderGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TenderEnvelope' }
  /tender/list:
    post:
      summary: List tenders (draft)
      description: |
        List tenders (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TenderListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TenderListEnvelope' }
  /comment:
    post:
      summary: Add comment (draft)
      description: |
        Add comment (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommentAddRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommentEnvelope' }
  /comment/get:
    post:
      summary: Get comment (draft)
      description: |
        Get comment (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommentGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommentEnvelope' }
  /comment/list:
    post:
      summary: List comments (draft)
      description: |
        List comments (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommentListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommentListEnvelope' }
  /comment/revise:
    post:
      summary: Revise comment (draft)
      description: |
        Revise comment (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommentReviseRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommentEnvelope' }
  /comment/status:
    post:
      summary: Update comment status (draft)
      description: |
        Update comment status (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommentStatusRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommentEnvelope' }
  /comment/report:
    post:
      summary: Report top-N largest comments (draft)
      description: |
        Report top-N largest comments (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CommentReportRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommentReportEnvelope' }
  /inbox/create:
    post:
      summary: Create inbox notification (draft)
      description: |
        Create inbox notification (draft). Auth is via headers; org identity uses x-orgcode or body
        placement as documented. If this updates a revisioned record, expected_revision is required (428 if
        missing; 409 on mismatch). Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InboxCreateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InboxEnvelope' }
  /inbox/get:
    post:
      summary: Get inbox notification (draft)
      description: |
        Get inbox notification (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InboxGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InboxEnvelope' }
  /inbox/list:
    post:
      summary: List inbox notifications (draft)
      description: |
        List inbox notifications (draft). Auth is via headers; org identity uses x-orgcode or body placement
        as documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InboxListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InboxListEnvelope' }
  /inbox/status:
    post:
      summary: Update inbox status (draft)
      description: |
        Update inbox status (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InboxStatusRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InboxEnvelope' }
  /inbox/state:
    post:
      summary: Update inbox state (draft)
      description: |
        Update inbox state (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/InboxStateRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/InboxEnvelope' }
  /edi/record:
    post:
      summary: Record EDI message (draft)
      description: |
        Record EDI message (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EdiRecordRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EdiEnvelope' }
  /edi/status/set:
    post:
      summary: Set EDI record status (draft)
      description: |
        Set EDI record status (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. If this updates a revisioned record, expected_revision is required (428 if missing; 409
        on mismatch). Route class Tier A (p95 500ms).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EdiStatusSetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EdiEnvelope' }
  /edi/get:
    post:
      summary: Get EDI record (draft)
      description: |
        Get EDI record (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Org-scoped reads may return 404 for non-associated callers (anti-enumeration). Route
        class Tier B (p95 300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EdiGetRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EdiEnvelope' }
  /edi/list:
    post:
      summary: List EDI records (draft)
      description: |
        List EDI records (draft). Auth is via headers; org identity uses x-orgcode or body placement as
        documented. Paginated with limit/next_token (default 8; clamp 1–256). Route class Tier B (p95
        300ms).
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EdiListRequest' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EdiListEnvelope' }
  /warranty-claim/file:
    post:
      operationId: warrantyClaimFile
      summary: File a warranty claim
      description: |
        Create a warranty claim with idempotency. Lifecycle: filed → approved → in_repair → resolved.
        Resolves G52 (warranty claim/RMA entity).
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [claim, reason, source_refs]
              properties:
                claim:
                  $ref: '#/components/schemas/WarrantyClaimDraft'
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
                idempotency_key: { type: string }
              x-idempotency-scope: WARRANTY_CLAIM_FILE
              x-idempotency-retention-hours: 24
              x-idempotency-replay: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WarrantyClaimEnvelope' }
  /warranty-claim/get:
    post:
      operationId: warrantyClaimGet
      summary: Get a warranty claim by claim_id
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 500
      x-concurrency-target: 1000
      x-latency-p95-ms: 100
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [claim_id]
              properties:
                claim_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WarrantyClaimEnvelope' }
  /warranty-claim/list:
    post:
      operationId: warrantyClaimList
      summary: List warranty claims by status, warranty_id, or customer_ref (paginated)
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 300
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string, enum: [filed, approved, in_repair, resolved, denied] }
                warranty_id: { type: string }
                customer_ref: { type: string }
                limit: { type: integer }
                next_token: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WarrantyClaimListEnvelope' }
  /warranty-claim/approve:
    post:
      operationId: warrantyClaimApprove
      summary: Approve a filed warranty claim
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [claim_id, reason, source_refs]
              properties:
                claim_id: { type: string }
                approved_by: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WarrantyClaimEnvelope' }
  /warranty-claim/resolve:
    post:
      operationId: warrantyClaimResolve
      summary: Resolve an approved warranty claim with disposition
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [claim_id, disposition, reason, source_refs]
              properties:
                claim_id: { type: string }
                disposition: { type: string, enum: [repair, replace, credit, deny] }
                resolution_notes: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WarrantyClaimEnvelope' }
  /rental-agreement/create:
    post:
      operationId: rentalAgreementCreate
      summary: Create a new rental agreement
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RentalAgreementDraft'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RentalAgreementEnvelope' }
  /rental-agreement/activate:
    post:
      operationId: rentalAgreementActivate
      summary: Activate a created rental agreement
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [rental_id, reason, source_refs]
              properties:
                rental_id: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RentalAgreementEnvelope' }
  /rental-agreement/return-request:
    post:
      operationId: rentalAgreementReturnRequest
      summary: Request return of a rented item
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [rental_id, reason, source_refs]
              properties:
                rental_id: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RentalAgreementEnvelope' }
  /rental-agreement/return-receive:
    post:
      operationId: rentalAgreementReturnReceive
      summary: Receive a returned rental item
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [rental_id, reason, source_refs]
              properties:
                rental_id: { type: string }
                actual_return_date: { type: string, format: date-time }
                condition_on_return: { type: string }
                condition_notes: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RentalAgreementEnvelope' }
  /rental-agreement/inspect:
    post:
      operationId: rentalAgreementInspect
      summary: Inspect a returned rental item and assess fees
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [rental_id, reason, source_refs]
              properties:
                rental_id: { type: string }
                late_fee_minor: { type: integer }
                damage_fee_minor: { type: integer }
                condition_notes: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RentalAgreementEnvelope' }
  /rental-agreement/close:
    post:
      operationId: rentalAgreementClose
      summary: Close a rental agreement after inspection
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [rental_id, deposit_status, reason, source_refs]
              properties:
                rental_id: { type: string }
                deposit_status: { type: string, enum: [refunded, forfeited, partial] }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RentalAgreementEnvelope' }
  /rental-agreement/extend:
    post:
      operationId: rentalAgreementExtend
      summary: Extend a rental agreement after inspection
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [rental_id, duration_days, reason, source_refs]
              properties:
                rental_id: { type: string }
                duration_days: { type: integer }
                expected_return_date: { type: string, format: date-time }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RentalAgreementEnvelope' }
  /rental-agreement/get:
    post:
      operationId: rentalAgreementGet
      summary: Get a rental agreement by ID
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 200
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [rental_id]
              properties:
                rental_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RentalAgreementEnvelope' }
  /rental-agreement/list:
    post:
      operationId: rentalAgreementList
      summary: List rental agreements with optional filters
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string }
                customer_ref: { type: string }
                limit: { type: integer }
                next_token: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RentalAgreementListEnvelope' }
  /delivery-slot/set:
    post:
      operationId: deliverySlotSet
      summary: Create or update a delivery slot
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [facility_code, label, start_time, end_time, capacity, source_refs, reason]
              properties:
                slot_id: { type: string }
                facility_code: { type: string }
                channel_code: { type: string }
                label: { type: string }
                day_of_week: { type: integer, minimum: 0, maximum: 6 }
                specific_date: { type: string, format: date }
                start_time: { type: string }
                end_time: { type: string }
                capacity: { type: integer }
                lead_time_hours: { type: number }
                source_refs: { type: array, items: { type: object } }
                reason: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /delivery-slot/get:
    post:
      operationId: deliverySlotGet
      summary: Get a delivery slot by ID
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [slot_id]
              properties:
                slot_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /delivery-slot/list:
    post:
      operationId: deliverySlotList
      summary: List delivery slots with optional filters
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                facility_code: { type: string }
                status: { type: string }
                limit: { type: integer }
                next_token: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /delivery-slot/status/set:
    post:
      operationId: deliverySlotStatusSet
      summary: Activate or deactivate a delivery slot
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [slot_id, status, reason, source_refs]
              properties:
                slot_id: { type: string }
                status: { type: string, enum: [active, inactive] }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /appointment/book:
    post:
      operationId: appointmentBook
      summary: Book a new appointment
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [customer_ref, variant_id, facility_code, scheduled_start, scheduled_end, duration_minutes, source_refs, reason]
              properties:
                appointment_id: { type: string }
                order_id: { type: string }
                customer_ref: { type: string }
                variant_id: { type: string }
                facility_code: { type: string }
                provider_ref: { type: string }
                scheduled_start: { type: string, format: date-time }
                scheduled_end: { type: string, format: date-time }
                duration_minutes: { type: integer }
                notes: { type: string }
                source_refs: { type: array, items: { type: object } }
                reason: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /appointment/get:
    post:
      operationId: appointmentGet
      summary: Get an appointment by ID
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [appointment_id]
              properties:
                appointment_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /appointment/list:
    post:
      operationId: appointmentList
      summary: List appointments with optional filters
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_ref: { type: string }
                facility_code: { type: string }
                status: { type: string }
                limit: { type: integer }
                next_token: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /appointment/confirm:
    post:
      operationId: appointmentConfirm
      summary: Confirm a booked appointment
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [appointment_id, reason, source_refs]
              properties:
                appointment_id: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /appointment/start:
    post:
      operationId: appointmentStart
      summary: Start an appointment (mark in progress)
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [appointment_id, reason, source_refs]
              properties:
                appointment_id: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /appointment/complete:
    post:
      operationId: appointmentComplete
      summary: Complete an appointment
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [appointment_id, reason, source_refs]
              properties:
                appointment_id: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /appointment/cancel:
    post:
      operationId: appointmentCancel
      summary: Cancel an appointment
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [appointment_id, cancel_reason, reason, source_refs]
              properties:
                appointment_id: { type: string }
                cancel_reason: { type: string }
                cancel_note: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /appointment/no-show:
    post:
      operationId: appointmentNoShow
      summary: Mark appointment as no-show
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [appointment_id, reason, source_refs]
              properties:
                appointment_id: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /appointment/reschedule:
    post:
      operationId: appointmentReschedule
      summary: Reschedule an appointment
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [appointment_id, scheduled_start, scheduled_end, reason, source_refs]
              properties:
                appointment_id: { type: string }
                scheduled_start: { type: string, format: date-time }
                scheduled_end: { type: string, format: date-time }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /fulfillment/shipment/delivery/schedule:
    post:
      operationId: shipmentDeliverySchedule
      summary: Schedule delivery for a shipment
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipment_id, delivery_window_start, delivery_window_end, reason, source_refs]
              properties:
                shipment_id: { type: string }
                delivery_window_start: { type: string, format: date-time }
                delivery_window_end: { type: string, format: date-time }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/delivery/complete:
    post:
      operationId: shipmentDeliveryComplete
      summary: Mark delivery as completed
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipment_id, reason, source_refs]
              properties:
                shipment_id: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/install/schedule:
    post:
      operationId: shipmentInstallSchedule
      summary: Schedule installation for a delivered shipment
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipment_id, installation_scheduled_at, reason, source_refs]
              properties:
                shipment_id: { type: string }
                installation_scheduled_at: { type: string, format: date-time }
                installer_ref: { type: string }
                installation_notes: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /fulfillment/shipment/install/complete:
    post:
      operationId: shipmentInstallComplete
      summary: Mark installation as completed
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipment_id, reason, source_refs]
              properties:
                shipment_id: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ShipmentEnvelope' }
  /till/open:
    post:
      operationId: tillOpen
      summary: Open a new till session
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              x-idempotency-scope: orgcode+route+idempotency_key
              x-idempotency-retention-hours: 24
              x-idempotency-replay: return_original_response
              required: [till, reason, source_refs]
              properties:
                till:
                  type: object
                  required: [facility_code, float_amount_minor, currency]
                  properties:
                    station_guid: { type: string }
                    facility_code: { type: string }
                    float_amount_minor: { type: integer, minimum: 0 }
                    currency: { type: string, minLength: 3, maxLength: 3 }
                    shift_ref: { type: string }
                    notes: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
                idempotency_key: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      till: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /till/get:
    post:
      operationId: tillGet
      summary: Fetch a till by ID
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2000
      x-concurrency-target: 1000
      x-latency-p95-ms: 100
      x-latency-p99-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [till_id]
              properties:
                till_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      till: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /till/close:
    post:
      operationId: tillClose
      summary: Close a till session with optional count
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              x-idempotency-scope: orgcode+route+idempotency_key
              x-idempotency-retention-hours: 24
              x-idempotency-replay: return_original_response
              required: [till_id, expected_revision, reason, source_refs]
              properties:
                till_id: { type: string }
                counted_amount_minor: { type: integer }
                notes: { type: string }
                expected_revision: { type: integer }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
                idempotency_key: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      till: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /till/list:
    post:
      operationId: tillList
      summary: List tills with optional filters
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2000
      x-concurrency-target: 1000
      x-latency-p95-ms: 150
      x-latency-p99-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string, enum: [open, counting, closed] }
                facility_code: { type: string }
                station_guid: { type: string }
                limit: { type: integer, minimum: 1, maximum: 256, default: 8 }
                next_token: { type: object }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      tills: { type: array, items: { type: object } }
                      next_token: { type: object, nullable: true }
                      count: { type: integer }
                  stats: { $ref: '#/components/schemas/Stats' }
  /payment-gateway/set:
    post:
      operationId: paymentGatewaySet
      summary: Create or update a payment gateway configuration
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              x-idempotency-scope: orgcode+route+idempotency_key
              x-idempotency-retention-hours: 24
              x-idempotency-replay: return_original_response
              required: [payment_gateway, reason, source_refs]
              properties:
                payment_gateway:
                  type: object
                  required: [provider]
                  properties:
                    gateway_id: { type: string }
                    code: { type: string }
                    caption: { type: string }
                    status: { type: string, enum: [draft, active, suspended, archived, doomed] }
                    provider: { type: string, enum: [stripe, square, adyen, paypal, custom, offline] }
                    supported_tender_codes: { type: array, items: { type: string } }
                    supported_currencies: { type: array, items: { type: string } }
                    channel_codes: { type: array, items: { type: string } }
                    webhook_url: { type: string }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
                idempotency_key: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      payment_gateway: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /payment-gateway/get:
    post:
      operationId: paymentGatewayGet
      summary: Fetch a payment gateway by ID
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2000
      x-concurrency-target: 1000
      x-latency-p95-ms: 150
      x-latency-p99-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [gateway_id]
              properties:
                gateway_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      payment_gateway: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /payment-gateway/list:
    post:
      operationId: paymentGatewayList
      summary: List payment gateways with optional status filter
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2000
      x-concurrency-target: 1000
      x-latency-p95-ms: 150
      x-latency-p99-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string, enum: [draft, active, suspended, archived, doomed] }
                limit: { type: integer, minimum: 1, maximum: 256, default: 50 }
                next_token: { type: object }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      payment_gateways: { type: array, items: { type: object } }
                      next_token: { type: object, nullable: true }
                      count: { type: integer }
                  stats: { $ref: '#/components/schemas/Stats' }
  /payment-gateway/status/set:
    post:
      operationId: paymentGatewayStatusSet
      summary: Update payment gateway status
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 800
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [gateway_id, status, reason, source_refs]
              properties:
                gateway_id: { type: string }
                status: { type: string, enum: [draft, active, suspended, archived, doomed] }
                expected_revision: { type: integer }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      payment_gateway: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /tender-policy/set:
    post:
      operationId: tenderPolicySet
      summary: Create or update a tender policy
      x-status: draft
      x-route-class: Tier D
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              x-idempotency-scope: orgcode+route+idempotency_key
              x-idempotency-retention-hours: 24
              x-idempotency-replay: return_original_response
              required: [tender_policy, reason, source_refs]
              properties:
                tender_policy:
                  type: object
                  required: [rules]
                  properties:
                    policy_id: { type: string }
                    code: { type: string }
                    caption: { type: string }
                    status: { type: string, enum: [draft, active, suspended, archived, doomed] }
                    rules:
                      type: array
                      items:
                        type: object
                        properties:
                          tender_code: { type: string }
                          requires_ebt_eligible: { type: boolean }
                          max_amount_minor: { type: integer }
                          min_amount_minor: { type: integer }
                          combinable_with: { type: array, items: { type: string } }
                          blocked_with: { type: array, items: { type: string } }
                reason: { type: string }
                source_refs: { type: array, items: { type: object } }
                idempotency_key: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      tender_policy: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /tender-policy/get:
    post:
      operationId: tenderPolicyGet
      summary: Fetch a tender policy by ID
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2000
      x-concurrency-target: 1000
      x-latency-p95-ms: 150
      x-latency-p99-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [policy_id]
              properties:
                policy_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      tender_policy: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /tender-policy/list:
    post:
      operationId: tenderPolicyList
      summary: List tender policies with optional status filter
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2000
      x-concurrency-target: 1000
      x-latency-p95-ms: 150
      x-latency-p99-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string, enum: [draft, active, suspended, archived, doomed] }
                limit: { type: integer, minimum: 1, maximum: 256, default: 50 }
                next_token: { type: object }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      tender_policies: { type: array, items: { type: object } }
                      next_token: { type: object, nullable: true }
                      count: { type: integer }
                  stats: { $ref: '#/components/schemas/Stats' }
  /eligibility/check:
    post:
      operationId: eligibilityCheck
      summary: Check item eligibility for a given tender type
      x-status: draft
      x-route-class: Tier C
      x-qps-target: 2000
      x-concurrency-target: 1000
      x-latency-p95-ms: 200
      x-latency-p99-ms: 400
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
        - { $ref: '#/components/parameters/LogicalHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tender_code, items]
              properties:
                tender_code: { type: string }
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      variant_id: { type: string }
                      ebt_eligible: { type: boolean }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      eligible: { type: boolean }
                      results:
                        type: array
                        items:
                          type: object
                          properties:
                            variant_id: { type: string }
                            eligible: { type: boolean }
                            reasons: { type: array, items: { type: string } }
                  stats: { $ref: '#/components/schemas/Stats' }
  /self-service/order/get:
    post:
      operationId: selfServiceOrderGet
      summary: Get order by ID for customer self-service
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 200
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [order_id, customer_ref]
              properties:
                order_id: { type: string }
                customer_ref: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      order: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /self-service/order/list:
    post:
      operationId: selfServiceOrderList
      summary: List orders for a customer
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 100
      x-concurrency-target: 500
      x-latency-p95-ms: 500
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [customer_ref]
              properties:
                customer_ref: { type: string }
                status: { type: string }
                limit: { type: integer }
                next_token: { type: object }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      orders: { type: array, items: { type: object } }
                      next_token: { type: object, nullable: true }
                  stats: { $ref: '#/components/schemas/Stats' }
  /self-service/return/request:
    post:
      operationId: selfServiceReturnRequest
      summary: Request a customer-initiated return (G94)
      x-status: draft
      x-route-class: Tier A
      x-qps-target: 50
      x-concurrency-target: 200
      x-latency-p95-ms: 1000
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [order_id, customer_ref, reason]
              properties:
                order_id: { type: string }
                customer_ref: { type: string }
                reason: { type: string }
                lines:
                  type: array
                  items:
                    type: object
                    properties:
                      line_id: { type: string }
                      quantity: { type: integer }
                      reason: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      return_id: { type: string }
                      status: { type: string }
                  stats: { $ref: '#/components/schemas/Stats' }
  /self-service/return/get:
    post:
      operationId: selfServiceReturnGet
      summary: Get return by ID for customer self-service
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 200
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [return_id, customer_ref]
              properties:
                return_id: { type: string }
                customer_ref: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      return_request: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /self-service/shipment/track:
    post:
      operationId: selfServiceShipmentTrack
      summary: Get shipment tracking info for customer
      x-status: draft
      x-route-class: Tier B
      x-qps-target: 200
      x-concurrency-target: 500
      x-latency-p95-ms: 300
      parameters:
        - { $ref: '#/components/parameters/OrgHeader' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipment_id, customer_ref]
              properties:
                shipment_id: { type: string }
                customer_ref: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      shipment: { type: object }
                      tracking: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }

  /carrier/config/set:
    post:
      summary: Set carrier configuration
      operationId: scm_carrier_config_set
      tags: [carrier]
      x-status: draft
      x-route-class: write
      x-qps-target: 10
      x-concurrency-target: 5
      x-latency-p95-ms: 300
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [carrier_code, name, provider]
              properties:
                carrier_code: { type: string }
                name: { type: string }
                provider: { type: string, enum: [ups, fedex, usps, dhl, custom] }
                api_mode: { type: string, enum: [live, sandbox, mock] }
                credentials_ref: { type: string }
                default_service_level: { type: string }
                supported_services: { type: array, items: { type: string } }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      carrier: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }

  /carrier/config/get:
    post:
      summary: Get carrier configuration
      operationId: scm_carrier_config_get
      tags: [carrier]
      x-status: draft
      x-route-class: read
      x-qps-target: 50
      x-concurrency-target: 10
      x-latency-p95-ms: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [carrier_code]
              properties:
                carrier_code: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      carrier: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }

  /carrier/config/list:
    post:
      summary: List carrier configurations
      operationId: scm_carrier_config_list
      tags: [carrier]
      x-status: draft
      x-route-class: read
      x-qps-target: 50
      x-concurrency-target: 10
      x-latency-p95-ms: 300
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit: { type: integer }
                next_token: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      carriers: { type: array, items: { type: object } }
                      next_token: { type: string }
                  stats: { $ref: '#/components/schemas/Stats' }

  /carrier/config/status/set:
    post:
      summary: Set carrier configuration status
      operationId: scm_carrier_config_status_set
      tags: [carrier]
      x-status: draft
      x-route-class: write
      x-qps-target: 10
      x-concurrency-target: 5
      x-latency-p95-ms: 300
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [carrier_code, status]
              properties:
                carrier_code: { type: string }
                status: { type: string, enum: [active, inactive] }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      carrier: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }

  /carrier/rate/quote:
    post:
      summary: Get carrier rate quotes
      operationId: scm_carrier_rate_quote
      tags: [carrier]
      x-status: draft
      x-route-class: read
      x-qps-target: 50
      x-concurrency-target: 10
      x-latency-p95-ms: 500
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [destination]
              properties:
                shipment_id: { type: string }
                destination:
                  type: object
                  properties:
                    postal_code: { type: string }
                    country_code: { type: string }
                    state: { type: string }
                package_info:
                  type: object
                  properties:
                    weight_kg: { type: number }
                    length_cm: { type: number }
                    width_cm: { type: number }
                    height_cm: { type: number }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      rates: { type: array, items: { type: object } }
                  stats: { $ref: '#/components/schemas/Stats' }

  /carrier/label/create:
    post:
      summary: Create shipping label
      operationId: scm_carrier_label_create
      tags: [carrier]
      x-status: draft
      x-route-class: write
      x-qps-target: 10
      x-concurrency-target: 5
      x-latency-p95-ms: 500
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipment_id, carrier_code, service_level]
              properties:
                shipment_id: { type: string }
                carrier_code: { type: string }
                service_level: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      label_ref: { type: string }
                      shipment_id: { type: string }
                  stats: { $ref: '#/components/schemas/Stats' }

  /carrier/tracking/get:
    post:
      summary: Get carrier tracking info
      operationId: scm_carrier_tracking_get
      tags: [carrier]
      x-status: draft
      x-route-class: read
      x-qps-target: 50
      x-concurrency-target: 10
      x-latency-p95-ms: 300
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [shipment_id]
              properties:
                shipment_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      shipment_id: { type: string }
                      carrier_code: { type: string }
                      tracking_ref: { type: string }
                      status: { type: string }
                  stats: { $ref: '#/components/schemas/Stats' }

  /receipt/template/set:
    post:
      summary: Set receipt template
      operationId: scm_receipt_template_set
      tags: [receipt]
      x-status: draft
      x-route-class: write
      x-qps-target: 10
      x-concurrency-target: 5
      x-latency-p95-ms: 300
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [template_id, name, type, format]
              properties:
                template_id: { type: string }
                name: { type: string }
                type: { type: string, enum: [sale, return, exchange, gift] }
                format: { type: string, enum: [thermal, a4, email] }
                sections: { type: array, items: { type: object } }
                header_text: { type: string }
                footer_text: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      template: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }

  /receipt/template/get:
    post:
      summary: Get receipt template
      operationId: scm_receipt_template_get
      tags: [receipt]
      x-status: draft
      x-route-class: read
      x-qps-target: 50
      x-concurrency-target: 10
      x-latency-p95-ms: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [template_id]
              properties:
                template_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      template: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }

  /receipt/template/list:
    post:
      summary: List receipt templates
      operationId: scm_receipt_template_list
      tags: [receipt]
      x-status: draft
      x-route-class: read
      x-qps-target: 50
      x-concurrency-target: 10
      x-latency-p95-ms: 300
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit: { type: integer }
                next_token: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      templates: { type: array, items: { type: object } }
                      next_token: { type: string }
                  stats: { $ref: '#/components/schemas/Stats' }

  /receipt/generate:
    post:
      summary: Generate receipt for order
      operationId: scm_receipt_generate
      tags: [receipt]
      x-status: draft
      x-route-class: write
      x-qps-target: 20
      x-concurrency-target: 10
      x-latency-p95-ms: 500
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [order_id, template_id]
              properties:
                order_id: { type: string }
                template_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      receipt: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }

  /receipt/get:
    post:
      summary: Get receipt record
      operationId: scm_receipt_get
      tags: [receipt]
      x-status: draft
      x-route-class: read
      x-qps-target: 50
      x-concurrency-target: 10
      x-latency-p95-ms: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [order_id, receipt_id]
              properties:
                order_id: { type: string }
                receipt_id: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      receipt: { type: object }
                  stats: { $ref: '#/components/schemas/Stats' }
  /warranty-config/set:
    post:
      summary: Set per-org warranty config (L1)
      tags: [warranty]
      x-status: draft
      x-route-class: write
      x-qps-target: 10
      x-concurrency-target: 5
      x-latency-p95-ms: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [serial_number_required]
              properties:
                serial_number_required: { type: boolean }
                expected_revision: { type: integer }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  /warranty-config/get:
    post:
      summary: Get per-org warranty config (L1)
      tags: [warranty]
      x-status: draft
      x-route-class: read
      x-qps-target: 50
      x-concurrency-target: 10
      x-latency-p95-ms: 100
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Envelope' }
  # POS Scan (T1-02, T1-03)
  /pos/scan:
    post:
      tags: [POS]
      operationId: posScan
      summary: Scan barcode/PLU — composite product+price+stock resolution
      description: Single round-trip barcode→product→dept gating→price→stock. Target <100ms via direct DDB reads.
      x-route-class: Tier D
      x-qps-target: 300
      x-concurrency-target: 400
      x-latency-p95-ms: 100
      x-latency-p99-ms: 200
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [value], properties: { value: { type: string }, station_guid: { type: string }, customer_ref: { type: string }, customer_tier: { type: string }, employee_price: { type: boolean } } } } } }
      responses: { '200': { description: Scan result, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/search:
    post:
      tags: [POS]
      operationId: posSearch
      summary: Item lookup search (fallback for non-barcode)
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [q], properties: { q: { type: string }, limit: { type: integer } } } } } }
      responses: { '200': { description: Search results, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  # POS Discounts (T1-04)
  /pos/discount/line:
    post:
      tags: [POS]
      operationId: posDiscountLine
      summary: Apply line-level discount
      description: Percent or amount discount with profile enforcement (limits, dept overrides, below-cost check).
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id, line_id, discount_type, discount_value], properties: { order_id: { type: string }, line_id: { type: string }, discount_type: { type: string, enum: [percent, amount] }, discount_value: { type: number }, reason_code: { type: string }, override_code: { type: string } } } } } }
      responses: { '200': { description: Discount applied, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/discount/line/remove:
    post:
      tags: [POS]
      operationId: posDiscountLineRemove
      summary: Remove line-level manual discount
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id, line_id], properties: { order_id: { type: string }, line_id: { type: string } } } } } }
      responses: { '200': { description: Discount removed, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/discount/order:
    post:
      tags: [POS]
      operationId: posDiscountOrder
      summary: Apply order-level discount (distributed proportionally)
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id, discount_type, discount_value], properties: { order_id: { type: string }, discount_type: { type: string, enum: [percent, amount] }, discount_value: { type: number }, reason_code: { type: string }, override_code: { type: string } } } } } }
      responses: { '200': { description: Order discount applied, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/discount/order/remove:
    post:
      tags: [POS]
      operationId: posDiscountOrderRemove
      summary: Remove all manual discounts from order
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id], properties: { order_id: { type: string } } } } } }
      responses: { '200': { description: Discounts removed, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  # POS Sale Completion (T1-06)
  /pos/complete:
    post:
      tags: [POS]
      operationId: posComplete
      summary: Complete POS sale
      description: Verifies tender balance, commits inventory (ICS fast path), generates receipt, emits sale-completed event.
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id], properties: { order_id: { type: string }, facility_code: { type: string } } } } } }
      responses: { '200': { description: Sale completed with receipt, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  # POS Tax (T1-05)
  /pos/tax/recalc:
    post:
      tags: [POS]
      operationId: posTaxRecalc
      summary: Recalculate basket taxes
      description: Wraps existing tax engine. Supports tax-inclusive (AU/UK/EU) and tax-exclusive (US/CA).
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [jurisdiction_code, lines], properties: { order_id: { type: string }, jurisdiction_code: { type: string }, lines: { type: array }, tax_basis: { type: string }, certificate_id: { type: string } } } } } }
      responses: { '200': { description: Tax calculation, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/tax/classes:
    post:
      tags: [POS]
      operationId: posTaxClasses
      summary: List tax classes for jurisdiction
      description: For misc sale tax class selection.
      x-route-class: Tier B
      x-qps-target: 100
      x-concurrency-target: 300
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      requestBody: { required: true, content: { application/json: { schema: { type: object, properties: { jurisdiction_code: { type: string } } } } } }
      responses: { '200': { description: Tax class list, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  # POS Hold/Recall (T1-08)
  /pos/hold:
    post:
      tags: [POS]
      operationId: posHold
      summary: Hold (park) current sale
      description: Transitions draft order to held status with station affinity.
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id], properties: { order_id: { type: string }, station_guid: { type: string }, hold_reason: { type: string } } } } } }
      responses: { '200': { description: Sale held, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/recall:
    post:
      tags: [POS]
      operationId: posRecall
      summary: Recall held sale
      description: Restores held order to draft. Cross-station requires scm_pos_admin.
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id], properties: { order_id: { type: string }, station_guid: { type: string } } } } } }
      responses: { '200': { description: Sale recalled with full order, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/hold/list:
    post:
      tags: [POS]
      operationId: posHoldList
      summary: List held sales
      description: Paginated. Station-filtered for cashiers, all for managers.
      x-route-class: Tier B
      x-qps-target: 100
      x-concurrency-target: 300
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      requestBody: { required: true, content: { application/json: { schema: { type: object, properties: { station_guid: { type: string }, limit: { type: integer }, next_token: { type: string } } } } } }
      responses: { '200': { description: Held order list, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  # POS Customer (T1-09)
  /pos/customer/search:
    post:
      tags: [POS]
      operationId: posCustomerSearch
      summary: Search customers for POS attachment
      description: By phone, email, name, or customer_code.
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, properties: { phone: { type: string }, email: { type: string }, customer_code: { type: string }, q: { type: string }, limit: { type: integer } } } } } }
      responses: { '200': { description: Customer results, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/customer/attach:
    post:
      tags: [POS]
      operationId: posCustomerAttach
      summary: Attach customer to order
      description: |
        Attach customer to order, re-resolve prices, compute effective tenders, loyalty preview (via CRM policy),
        fraud hold check. Returns 409 fraud-hold-active if customer has active fraud hold unless
        acknowledge_fraud_hold=true is set.
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id, customer_guid], properties: { order_id: { type: string }, customer_guid: { type: string }, acknowledge_fraud_hold: { type: boolean, description: 'Set true to proceed despite active fraud hold' } } } } } }
      responses: { '200': { description: Customer attached with repriced lines, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/customer/detach:
    post:
      tags: [POS]
      operationId: posCustomerDetach
      summary: Detach customer from order
      description: Reverts to base pricing.
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id], properties: { order_id: { type: string } } } } } }
      responses: { '200': { description: Customer detached, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  # POS Returns (T1-07)
  /pos/return/start:
    post:
      tags: [POS]
      operationId: posReturnStart
      summary: Start return — look up receipt
      description: Receipt number lookup, show returnable lines with already-returned quantities.
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [receipt_number], properties: { receipt_number: { type: string } } } } } }
      responses: { '200': { description: Returnable lines, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/return/process:
    post:
      tags: [POS]
      operationId: posReturnProcess
      summary: Process POS return
      description: Auto-authorize, auto-receive, ICS restock, refund issue in single call.
      x-route-class: Tier C
      x-qps-target: 200
      x-concurrency-target: 400
      x-latency-p95-ms: 400
      x-latency-p99-ms: 800
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id, lines], properties: { order_id: { type: string }, lines: { type: array }, refund_method: { type: string, enum: [cash, store_credit, original_tender] }, override_code: { type: string } } } } } }
      responses: { '200': { description: Return processed, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  # POS Audit (T1-10)
  /pos/audit/query:
    post:
      tags: [POS]
      operationId: posAuditQuery
      summary: Query POS audit trail
      description: By time range + optional filters (station, actor, action, order). Requires scm_pos_admin.
      x-route-class: Tier B
      x-qps-target: 100
      x-concurrency-target: 300
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      requestBody: { required: true, content: { application/json: { schema: { type: object, properties: { station_guid: { type: string }, actor_guid: { type: string }, order_id: { type: string }, action: { type: string }, from_date: { type: string }, to_date: { type: string }, limit: { type: integer }, next_token: { type: string } } } } } }
      responses: { '200': { description: Audit records, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/audit/transaction:
    post:
      tags: [POS]
      operationId: posAuditTransaction
      summary: Audit trail for specific order
      description: All audit records for a specific order, chronological.
      x-route-class: Tier B
      x-qps-target: 100
      x-concurrency-target: 300
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id], properties: { order_id: { type: string }, limit: { type: integer }, next_token: { type: string } } } } } }
      responses: { '200': { description: Transaction audit timeline, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }

  # ── POS Cash Management (T2-01) ──────────────────────────────────────────────
  /pos/cash/paid-in:
    post:
      tags: [POS]
      operationId: posCashPaidIn
      summary: Record cash paid into till
      description: Cash received into the drawer from outside normal sales (change fund replenishment, etc.).
      x-route-class: Tier C
      x-qps-target: 50
      x-concurrency-target: 100
      x-latency-p95-ms: 200
      x-latency-p99-ms: 500
      requestBody: { required: true, content: { application/json: { schema: { type: object, x-idempotency-scope: org_till, x-idempotency-retention-hours: 24, x-idempotency-replay: return_original_response, required: [till_id, amount_minor, reason], properties: { till_id: { type: string }, amount_minor: { type: integer, minimum: 1 }, received_from: { type: string }, reason: { type: string }, idempotency_key: { type: string } } } } } }
      responses: { '200': { description: Movement recorded, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/cash/paid-out:
    post:
      tags: [POS]
      operationId: posCashPaidOut
      summary: Record cash paid out from till
      description: Cash removed from drawer for a business expense. Profile max_paid_out enforced.
      x-route-class: Tier C
      x-qps-target: 50
      x-concurrency-target: 100
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      requestBody: { required: true, content: { application/json: { schema: { type: object, x-idempotency-scope: org_till, x-idempotency-retention-hours: 24, x-idempotency-replay: return_original_response, required: [till_id, amount_minor, paid_to, reason], properties: { till_id: { type: string }, amount_minor: { type: integer, minimum: 1 }, paid_to: { type: string }, reason: { type: string }, authorization: { type: object }, idempotency_key: { type: string } } } } } }
      responses: { '200': { description: Movement recorded or challenge, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/cash/deposit:
    post:
      tags: [POS]
      operationId: posCashDeposit
      summary: Record bank deposit from till
      description: Cash removed from till for bank deposit. Requires scm_pos_admin role.
      x-route-class: Tier C
      x-qps-target: 20
      x-concurrency-target: 50
      x-latency-p95-ms: 200
      x-latency-p99-ms: 500
      requestBody: { required: true, content: { application/json: { schema: { type: object, x-idempotency-scope: org_till, x-idempotency-retention-hours: 24, x-idempotency-replay: return_original_response, required: [till_id, amount_minor, reference], properties: { till_id: { type: string }, amount_minor: { type: integer, minimum: 1 }, reference: { type: string }, reason: { type: string }, idempotency_key: { type: string } } } } } }
      responses: { '200': { description: Deposit recorded, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/cash/drawer:
    post:
      tags: [POS]
      operationId: posCashDrawer
      summary: Open cash drawer without a sale
      description: No-sale drawer open. Profile allow_open_drawer enforced.
      x-route-class: Tier C
      x-qps-target: 50
      x-concurrency-target: 100
      x-latency-p95-ms: 200
      x-latency-p99-ms: 500
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [till_id], properties: { till_id: { type: string }, reason: { type: string }, authorization: { type: object } } } } } }
      responses: { '200': { description: Drawer opened, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/cash/movements:
    post:
      tags: [POS]
      operationId: posCashMovements
      summary: List cash movements
      description: Query movements by till, facility, or org. Paginated, reverse chronological.
      x-route-class: Tier B
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 200
      x-latency-p99-ms: 500
      requestBody: { required: true, content: { application/json: { schema: { type: object, properties: { till_id: { type: string }, facility_code: { type: string }, movement_type: { type: string, enum: [paid_in, paid_out, bank_deposit, open_drawer] }, limit: { type: integer }, next_token: { type: string } } } } } }
      responses: { '200': { description: Movement list, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/till/report:
    post:
      tags: [POS]
      operationId: posTillReport
      summary: Generate till/shift summary report
      description: Aggregated sales, tender breakdown, cash movements, expected vs counted.
      x-route-class: Tier B
      x-qps-target: 50
      x-concurrency-target: 100
      x-latency-p95-ms: 500
      x-latency-p99-ms: 1000
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [till_id], properties: { till_id: { type: string } } } } } }
      responses: { '200': { description: Shift report, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }

  # ── POS Receipt Reprint & Journal (T2-05) ─────────────────────────────────────
  /pos/reprint:
    post:
      tags: [POS]
      operationId: posReprint
      summary: Reprint receipt
      description: Look up and return a receipt by receipt_number or order_id. Persisted receipt returned if available; regenerated from order as fallback.
      x-route-class: Tier B
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 200
      x-latency-p99-ms: 500
      requestBody: { required: true, content: { application/json: { schema: { type: object, properties: { receipt_number: { type: string }, order_id: { type: string }, receipt_id: { type: string } } } } } }
      responses: { '200': { description: Receipt payload, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/journal:
    post:
      tags: [POS]
      operationId: posJournal
      summary: Transaction journal
      description: List completed transactions by shift, date range, or station. Paginated.
      x-route-class: Tier B
      x-qps-target: 50
      x-concurrency-target: 100
      x-latency-p95-ms: 500
      x-latency-p99-ms: 1000
      requestBody: { required: true, content: { application/json: { schema: { type: object, properties: { shift_id: { type: string }, from_date: { type: string }, to_date: { type: string }, limit: { type: integer }, next_token: { type: string } } } } } }
      responses: { '200': { description: Journal entries, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }

  # ── POS Void Transaction (T2-02) ─────────────────────────────────────────────
  /pos/void:
    post:
      tags: [POS]
      operationId: posVoid
      summary: Pre-completion void
      description: Cancel an open (draft/placed/held) order. Reverses tenders, releases ICS promise.
      x-route-class: Tier C
      x-qps-target: 50
      x-concurrency-target: 100
      x-latency-p95-ms: 300
      x-latency-p99-ms: 600
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id, reason], properties: { order_id: { type: string }, reason: { type: string }, reason_code: { type: string }, authorization: { type: object } } } } } }
      responses: { '200': { description: Order voided or challenge, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/post-void:
    post:
      tags: [POS]
      operationId: posPostVoid
      summary: Post-completion void
      description: Reverse a completed sale (same-shift). Reverses tenders, ICS stock, loyalty. Requires scm_pos_admin.
      x-route-class: Tier C
      x-qps-target: 20
      x-concurrency-target: 50
      x-latency-p95-ms: 800
      x-latency-p99-ms: 2000
      requestBody: { required: true, content: { application/json: { schema: { type: object, properties: { order_id: { type: string }, receipt_number: { type: string }, reason: { type: string }, reason_code: { type: string }, authorization: { type: object } } } } } }
      responses: { '200': { description: Sale voided, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }

  # ── POS Misc / Trade-In (T2-03) ──────────────────────────────────────────────
  /pos/misc/add:
    post:
      tags: [POS]
      operationId: posMiscAdd
      summary: Add miscellaneous line to basket
      description: Non-catalog item with manual price, description, and tax class.
      x-route-class: Tier C
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 200
      x-latency-p99-ms: 500
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id, description, price, tax_code], properties: { order_id: { type: string }, description: { type: string, maxLength: 200 }, price: { type: number, minimum: 0.01 }, quantity: { type: integer, minimum: 1, default: 1 }, tax_code: { type: string }, department_code: { type: string }, category_code: { type: string } } } } } }
      responses: { '200': { description: Line added, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/misc/remove:
    post:
      tags: [POS]
      operationId: posMiscRemove
      summary: Remove miscellaneous line
      description: Remove a misc-type line from the basket.
      x-route-class: Tier C
      x-qps-target: 100
      x-concurrency-target: 200
      x-latency-p95-ms: 200
      x-latency-p99-ms: 500
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id, line_id], properties: { order_id: { type: string }, line_id: { type: string } } } } } }
      responses: { '200': { description: Line removed, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/trade-in/add:
    post:
      tags: [POS]
      operationId: posTradeInAdd
      summary: Add trade-in credit to basket
      description: Negative-value line for traded-in merchandise. Tax exempt.
      x-route-class: Tier C
      x-qps-target: 50
      x-concurrency-target: 100
      x-latency-p95-ms: 200
      x-latency-p99-ms: 500
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id, description, amount], properties: { order_id: { type: string }, description: { type: string, maxLength: 200 }, amount: { type: number, minimum: 0.01 }, condition: { type: string, enum: [excellent, good, fair, poor] }, grade: { type: string }, serial_number: { type: string }, department_code: { type: string } } } } } }
      responses: { '200': { description: Trade-in line added, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }
  /pos/trade-in/remove:
    post:
      tags: [POS]
      operationId: posTradeInRemove
      summary: Remove trade-in line
      description: Remove a trade-in-type line from the basket.
      x-route-class: Tier C
      x-qps-target: 50
      x-concurrency-target: 100
      x-latency-p95-ms: 200
      x-latency-p99-ms: 500
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [order_id, line_id], properties: { order_id: { type: string }, line_id: { type: string } } } } } }
      responses: { '200': { description: Line removed, content: { application/json: { schema: { $ref: '#/components/schemas/Envelope' } } } } }