openapi: 3.0.3
info:
  title: Order placement API
  description: >-
    Beta - self-checkout / Associate App slice. Use this API to place orders for
    processing in the NewStore platform. A successful response means the order
    has been accepted; payment capture, receipt generation, and downstream
    processing complete asynchronously.
  version: 0.1.0
  x-audience: internal-company
  x-api-id: sales-order-placement
  x-api-status: beta
  x-domain-gateway-integration:
    serviceName: sales-order-placement
    eks:
      cluster: shared-eks
      ingress:
        targetNamespace: team-order-management
        targetService: sales-order-placement
  contact:
    name: team-order-management
    email: team-order-management@newstore.com
servers:
  - url: https://{tenant}.{environment}.newstore.net
    variables:
      tenant:
        default: dodici
      environment:
        enum:
          - p
          - s
        default: p
tags:
  - name: order-placement
    description: Place orders into the NewStore platform.
paths:
  /orders:
    post:
      tags:
        - order-placement
      summary: Place an order
      description: >-
        Place an order for processing in the NewStore platform. A successful
        response means the order has been accepted; payment capture, receipt
        generation, and downstream processing complete asynchronously.
      operationId: createOrderPlacement
      parameters:
        - name: idempotency-key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 256
            description: Caller-provided key used to make order placement safe to retry.
            title: Idempotency-Key
          description: Caller-provided key used to make order placement safe to retry.
        - name: x-newstore-request-id
          in: header
          required: false
          description: >-
            Optional caller-provided request correlation identifier. Generated
            by the service when omitted.
          schema:
            type: string
            maxLength: 255
          example: 2a0295b0-50a8-459c-82cd-5079d3f35bfb
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
            example:
              external_id: client-order-000123
              channel:
                name: self_checkout
                type: STORE
                store_id: store-01
                associate_id: associate-01
              catalog:
                name: storefront-catalog-en
                locale: en-US
              pricing:
                currency: USD
                method: TAX_INCLUDED
              line_items:
                - line_item_id: item-1
                  product_id: SKU-123
                  unit_external_id: ext-item-1
                  price:
                    list_price: 1999
                    price: 1999
              fulfillments:
                - line_item_ids:
                    - item-1
                  fulfillment_option:
                    service_level_identifier: IN_STORE_HANDOVER
                    price: 0
                    tax: 0
              payment:
                instruments:
                  - payment_method: card
                    amount: 1999
                    currency: USD
                    payment_provider: newstore
                    status: CAPTURED
                    processed_at: '2026-06-05T12:00:00Z'
                    card:
                      origin: terminal
                      reference: pi_3abc
                      card_brand: Visa
                      card_last4: '4242'
        description: The order to place.
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
              example:
                id: 2a0295b0-50a8-459c-82cd-5079d3f35bfb
                order_number: ORD0000123456
                external_id: client-order-000123
                items:
                  - product_id: SKU-123
                    external_item_id: ext-item-1
                    id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
          headers:
            x-newstore-request-id:
              description: >-
                Request correlation identifier echoed from the inbound
                `x-newstore-request-id` or generated by the service.
              schema:
                type: string
                maxLength: 255
        '400':
          description: The request is malformed or fails validation.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error_code: bad_request
                message: 'Request validation failed: body.pricing: Field required'
                request_id: 2a0295b0-50a8-459c-82cd-5079d3f35bfb
          headers:
            x-newstore-request-id:
              description: >-
                Request correlation identifier echoed from the inbound
                `x-newstore-request-id` or generated by the service.
              schema:
                type: string
                maxLength: 255
        '401':
          description: Authentication is missing or invalid.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error_code: unauthorized
                message: Authentication is missing or invalid.
                request_id: 2a0295b0-50a8-459c-82cd-5079d3f35bfb
          headers:
            x-newstore-request-id:
              description: >-
                Request correlation identifier echoed from the inbound
                `x-newstore-request-id` or generated by the service.
              schema:
                type: string
                maxLength: 255
        '409':
          description: The idempotency key conflicts with a different order payload.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                idempotencyKeyConflict:
                  summary: Idempotency key conflict
                  value:
                    error_code: idempotency_key_conflict
                    message: >-
                      idempotency-key was already used for a different order
                      payload
                    request_id: 2a0295b0-50a8-459c-82cd-5079d3f35bfb
                orderConflict:
                  summary: Generated order identifier conflict
                  value:
                    error_code: order_conflict
                    message: >-
                      Generated order identifier conflicts with an existing
                      order
                    request_id: 2a0295b0-50a8-459c-82cd-5079d3f35bfb
          headers:
            x-newstore-request-id:
              description: >-
                Request correlation identifier echoed from the inbound
                `x-newstore-request-id` or generated by the service.
              schema:
                type: string
                maxLength: 255
        '429':
          description: Too many requests; the rate limit has been exceeded.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error_code: rate_limit_exceeded
                message: Too many requests; please retry later.
                request_id: 2a0295b0-50a8-459c-82cd-5079d3f35bfb
          headers:
            x-newstore-request-id:
              description: >-
                Request correlation identifier echoed from the inbound
                `x-newstore-request-id` or generated by the service.
              schema:
                type: string
                maxLength: 255
            Retry-After:
              description: When to retry the request, as delta seconds or an HTTP-date.
              schema:
                type: string
                maxLength: 64
              example: '60'
        '500':
          description: An unexpected error occurred while processing the request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error_code: internal_server_error
                message: An unexpected error occurred while processing the request.
                request_id: 2a0295b0-50a8-459c-82cd-5079d3f35bfb
          headers:
            x-newstore-request-id:
              description: >-
                Request correlation identifier echoed from the inbound
                `x-newstore-request-id` or generated by the service.
              schema:
                type: string
                maxLength: 255
        '503':
          description: >-
            A downstream dependency is temporarily unavailable; the request can
            be retried.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error_code: service_unavailable
                message: >-
                  A downstream dependency is temporarily unavailable. Please
                  retry.
                request_id: 2a0295b0-50a8-459c-82cd-5079d3f35bfb
          headers:
            x-newstore-request-id:
              description: >-
                Request correlation identifier echoed from the inbound
                `x-newstore-request-id` or generated by the service.
              schema:
                type: string
                maxLength: 255
            Retry-After:
              description: When to retry the request, as delta seconds or an HTTP-date.
              schema:
                type: string
                maxLength: 64
              example: '60'
        default:
          description: Unexpected error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error_code: unexpected_error
                message: An unexpected error occurred.
                request_id: 2a0295b0-50a8-459c-82cd-5079d3f35bfb
          headers:
            x-newstore-request-id:
              description: >-
                Request correlation identifier echoed from the inbound
                `x-newstore-request-id` or generated by the service.
              schema:
                type: string
                maxLength: 255
      security:
        - oauth2:
            - orders:write
components:
  schemas:
    Address:
      properties:
        title:
          title: Title
          description: e.g. Dr., Prof., Pres.
          example: Dr.
          nullable: true
          type: string
          maxLength: 32
        suffix:
          title: Suffix
          description: e.g. Jr., Sr., III.
          example: Jr.
          nullable: true
          type: string
          maxLength: 32
        salutation:
          title: Salutation
          description: e.g. Mr., Ms., Mrs.
          example: Ms.
          nullable: true
          type: string
          maxLength: 32
        first_name:
          title: First Name
          description: First name.
          example: Ada
          nullable: true
          type: string
          maxLength: 64
        last_name:
          title: Last Name
          description: Last name.
          example: Lovelace
          nullable: true
          type: string
          maxLength: 64
        country:
          type: string
          maxLength: 2
          minLength: 2
          title: Country
          description: The code of the country in the ISO ALPHA-2 format.
          example: US
        zip_code:
          title: Zip Code
          description: Postal/ZIP code.
          example: '10012'
          nullable: true
          type: string
          maxLength: 32
        city:
          title: City
          description: City.
          example: New York
          nullable: true
          type: string
          maxLength: 64
        state:
          title: State
          description: State or region.
          example: NY
          nullable: true
          type: string
          maxLength: 32
        address_line_1:
          type: string
          maxLength: 128
          minLength: 1
          title: Address Line 1
          description: First line of the street address.
          example: 121 Spring Street
        address_line_2:
          title: Address Line 2
          description: Second line of the street address.
          example: Floor 2
          nullable: true
          type: string
          maxLength: 256
        phone:
          title: Phone
          description: Phone number.
          example: +1-212-555-0100
          nullable: true
          type: string
          maxLength: 128
      type: object
      required:
        - country
        - address_line_1
      title: Address
      description: A postal address.
    CardDetails:
      properties:
        origin:
          title: Origin
          description: >-
            How the card payment was taken, for example `terminal` or
            `apple_tap_to_pay`.
          example: terminal
          nullable: true
          type: string
          maxLength: 64
        reference:
          type: string
          maxLength: 128
          title: Reference
          description: >-
            The payment provider's reference for this payment, for example the
            PSP reference.
          example: pi_3abc
        card_brand:
          title: Card Brand
          description: The card brand, for example `Visa` or `Mastercard`.
          example: Visa
          nullable: true
          type: string
          maxLength: 32
        card_last4:
          title: Card Last4
          description: The last four digits of the card number.
          example: '4242'
          nullable: true
          type: string
          maxLength: 4
        wallet:
          title: Wallet
          description: >-
            The wallet used to present the card, for example `apple_pay` or
            `google_pay`.
          example: apple_pay
          nullable: true
          type: string
          maxLength: 64
        merchant_account:
          title: Merchant Account
          description: >-
            The merchant account at the payment provider that settled this
            payment. Applies to Adyen only.
          example: BurtonUSA
          nullable: true
          type: string
          maxLength: 64
        terminal_receipt:
          title: Terminal Receipt
          description: >-
            Raw terminal receipt data captured at the point of sale, when
            available. Applies to Adyen only.
          example: {}
          nullable: true
          type: object
      type: object
      required:
        - reference
      title: CardDetails
      description: Card-specific payment details.
    CardPayment:
      properties:
        amount:
          type: integer
          maximum: 2147483647
          minimum: 1
          title: Amount
          description: Payment amount, in the currency's minor unit.
          example: 8999
          format: int64
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: The currency of the payment.
        payment_provider:
          type: string
          maxLength: 64
          minLength: 1
          title: Payment Provider
          description: >-
            The payment provider that processed the payment, for example
            `newstore` or `adyen`.
          example: newstore
        status:
          allOf:
            - $ref: '#/components/schemas/PaymentStatus'
          description: Whether the payment is already authorized or already captured.
          example: CAPTURED
        processed_at:
          type: string
          format: date-time
          title: Processed At
          description: >-
            When the payment was processed, as an RFC 3339 (ISO 8601) date-time
            including date, time and timezone.
          example: '2026-06-25T10:30:00Z'
          maxLength: 64
        billing_address:
          allOf:
            - $ref: '#/components/schemas/Address'
          description: >-
            Billing address for this payment instrument. Optional. When supplied
            on more than one instrument, all must be identical (the platform
            currently supports a single billing address per order).
          nullable: true
          type: object
        payment_method:
          type: string
          title: Payment Method
          description: The payment method.
          enum:
            - card
        card:
          allOf:
            - $ref: '#/components/schemas/CardDetails'
          description: Card-specific details.
      type: object
      required:
        - amount
        - currency
        - payment_provider
        - status
        - processed_at
        - payment_method
        - card
      title: CardPayment
      description: A card payment (credit or debit).
      example:
        amount: 1999
        card:
          card_brand: Visa
          card_last4: '4242'
          origin: terminal
          reference: pi_3abc
        currency: USD
        payment_method: card
        payment_provider: newstore
        processed_at: '2026-06-25T10:30:00Z'
        status: CAPTURED
    CashDetails:
      properties:
        change_amount:
          title: Change Amount
          description: Change handed back to the customer, in the currency's minor unit.
          example: 1001
          nullable: true
          type: integer
          maximum: 2147483647
          minimum: 0
          format: int64
      type: object
      title: CashDetails
      description: Cash-specific payment details.
    CashPayment:
      properties:
        amount:
          type: integer
          maximum: 2147483647
          minimum: 1
          title: Amount
          description: Payment amount, in the currency's minor unit.
          example: 8999
          format: int64
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: The currency of the payment.
        payment_provider:
          type: string
          title: Payment Provider
          description: The payment provider for a cash payment; always `cash`.
          example: cash
          enum:
            - cash
        status:
          allOf:
            - $ref: '#/components/schemas/PaymentStatus'
          description: Whether the payment is already authorized or already captured.
          example: CAPTURED
        processed_at:
          type: string
          format: date-time
          title: Processed At
          description: >-
            When the payment was processed, as an RFC 3339 (ISO 8601) date-time
            including date, time and timezone.
          example: '2026-06-25T10:30:00Z'
          maxLength: 64
        billing_address:
          allOf:
            - $ref: '#/components/schemas/Address'
          description: >-
            Billing address for this payment instrument. Optional. When supplied
            on more than one instrument, all must be identical (the platform
            currently supports a single billing address per order).
          nullable: true
          type: object
        payment_method:
          type: string
          title: Payment Method
          description: The payment method.
          enum:
            - cash
        cash:
          allOf:
            - $ref: '#/components/schemas/CashDetails'
          description: Cash-specific details.
      type: object
      required:
        - amount
        - currency
        - payment_provider
        - status
        - processed_at
        - payment_method
        - cash
      title: CashPayment
      description: A cash payment.
      example:
        amount: 10000
        cash:
          change_amount: 1001
        currency: USD
        payment_method: cash
        payment_provider: cash
        processed_at: '2026-06-25T10:30:00Z'
        status: CAPTURED
    Catalog:
      properties:
        name:
          type: string
          maxLength: 128
          minLength: 1
          title: Name
          description: The catalog containing the items of the order.
          example: storefront-catalog-en
        locale:
          type: string
          maxLength: 128
          minLength: 1
          title: Locale
          description: The locale of the customer used for the shop, in RFC 5646.
          example: en-US
      type: object
      required:
        - name
        - locale
      title: Catalog
      description: The catalogue and locale used to resolve the order's items.
    Channel:
      properties:
        name:
          type: string
          maxLength: 64
          minLength: 1
          title: Name
          description: >-
            Caller-provided source label used to distinguish store order
            clients, for example `self_checkout` or `associate_app`.
          example: self_checkout
        type:
          allOf:
            - $ref: '#/components/schemas/ChannelType'
          example: STORE
        store_id:
          type: string
          maxLength: 256
          minLength: 1
          title: Store Id
          description: >-
            ID of the store where this order was placed. Used to resolve the
            store's address for IN_STORE_HANDOVER fulfillment.
          example: store-01
        associate_id:
          title: Associate Id
          description: >-
            ID of the store associate who processed this order, when an
            associate was involved.
          example: associate-01
          nullable: true
          type: string
          maxLength: 256
          minLength: 1
      type: object
      required:
        - name
        - type
        - store_id
      title: Channel
      description: Describes the origin of the order.
    ChannelType:
      type: string
      enum:
        - STORE
      title: ChannelType
      description: The origin type of the order.
    Currency:
      type: string
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BHD
        - BIF
        - BMD
        - BND
        - BOB
        - BOV
        - BRL
        - BSD
        - BTN
        - BWP
        - BYR
        - BYN
        - BZD
        - CAD
        - CDF
        - CHE
        - CHF
        - CHW
        - CLF
        - CLP
        - CNY
        - COP
        - COU
        - CRC
        - CUC
        - CUP
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ERN
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - INR
        - IQD
        - IRR
        - ISK
        - JMD
        - JOD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KPW
        - KRW
        - KWD
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - LTL
        - LVL
        - LYD
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MRO
        - MUR
        - MVR
        - MWK
        - MXN
        - MXV
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - OMR
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SDG
        - SEK
        - SGD
        - SHP
        - SLL
        - SOS
        - SRD
        - SSP
        - STD
        - SVC
        - SYP
        - SZL
        - THB
        - TJS
        - TMT
        - TND
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - USN
        - USS
        - UYI
        - UYU
        - UZS
        - VEF
        - VND
        - VUV
        - WST
        - XAF
        - XAG
        - XAU
        - XBA
        - XBB
        - XBC
        - XBD
        - XCD
        - XDR
        - XFU
        - XOF
        - XPD
        - XPF
        - XPT
        - XSU
        - XTS
        - XUA
        - YER
        - ZAR
        - ZMW
        - ZWL
      title: Currency
      description: Enumerates all supported currencies
    Fulfillment:
      properties:
        line_item_ids:
          items:
            type: string
            maxLength: 64
          type: array
          maxItems: 100
          minItems: 1
          title: Line Item Ids
          description: >-
            The line items fulfilled by this fulfillment. Each value must match
            a `line_items[].line_item_id` in the same order. A given
            `line_item_id` must appear in exactly one fulfillment.
          example:
            - item-1
        fulfillment_option:
          $ref: '#/components/schemas/FulfillmentOption'
      type: object
      required:
        - line_item_ids
        - fulfillment_option
      title: Fulfillment
      description: Groups line items under a single fulfillment option.
    FulfillmentOption:
      properties:
        service_level_identifier:
          type: string
          maxLength: 64
          minLength: 1
          title: Service Level Identifier
          description: >-
            Service level identifier of the fulfillment option. Set it to
            IN_STORE_HANDOVER in case of an in-store purchase order.
          example: IN_STORE_HANDOVER
        price:
          type: integer
          maximum: 2147483647
          minimum: 0
          title: Price
          description: >-
            The price of the fulfillment option before discounts, in the
            currency's minor unit. It might include taxes depending on the
            pricing method.
          example: 0
          format: int64
        tax:
          type: integer
          maximum: 2147483647
          minimum: 0
          title: Tax
          description: >-
            The tax applied to the fulfillment option, in the currency's minor
            unit.
          example: 0
          format: int64
      type: object
      required:
        - service_level_identifier
        - price
        - tax
      title: FulfillmentOption
      description: >-
        Service-level fulfillment option (e.g. in-store handover).


        The source spec models this as a `oneOf`; this MVP supports only the

        service-level variant and omits the shipping (`shipping_offer_token`)
        one.
    LineItem:
      properties:
        line_item_id:
          type: string
          maxLength: 64
          minLength: 1
          title: Line Item Id
          description: >-
            Caller-provided identifier for this line item. Must be unique within
            the order.
          example: item-1
        product_id:
          type: string
          maxLength: 64
          minLength: 1
          title: Product Id
          description: The identifier of the product as it was fetched from the catalog.
          example: SKU-123
        unit_external_id:
          title: Unit External Id
          description: >-
            Caller-provided external identifier for this item. Echoed back as
            `external_item_id` in the response. Null when not supplied.
          example: ext-item-1
          nullable: true
          type: string
          maxLength: 64
          minLength: 1
        price:
          $ref: '#/components/schemas/LineItemPrice'
      type: object
      required:
        - line_item_id
        - product_id
        - price
      title: LineItem
      description: A single ordered product line.
    LineItemPrice:
      properties:
        list_price:
          type: integer
          maximum: 2147483647
          minimum: 0
          title: List Price
          description: Standard/Original price, in the currency's minor unit.
          example: 1999
          format: int64
        price:
          type: integer
          maximum: 2147483647
          minimum: 0
          title: Price
          description: Actual price of item, in the currency's minor unit.
          example: 1999
          format: int64
        price_tax:
          type: integer
          maximum: 2147483647
          minimum: 0
          title: Price Tax
          description: >-
            Total tax amount for the item, in the currency's minor unit. With
            tax_excluded pricing the customer pays `price` plus this tax; with
            tax_included pricing this is the tax already contained in `price`.
            Defaults to 0.
          default: 0
          example: 0
          format: int64
        tax_lines:
          items:
            $ref: '#/components/schemas/TaxLine'
          type: array
          maxItems: 100
          title: Tax Lines
          description: Optional breakdown of the taxes that make up `price_tax`.
          example: []
      type: object
      required:
        - list_price
        - price
      title: LineItemPrice
      description: The required price points for a line item, in the currency's minor unit.
    OrderRequest:
      properties:
        external_id:
          title: External Id
          description: >-
            Caller-supplied external identifier for correlation and external
            lookup. Must be unique per tenant when supplied. The order number is
            generated by the system.
          example: client-order-000123
          nullable: true
          type: string
          maxLength: 64
          minLength: 1
          pattern: .*\S.*
        checkout_id:
          title: Checkout Id
          description: Associated checkout ID for reconciliation.
          example: 8f3b2c1d-4e5a-4b6c-9d7e-1a2b3c4d5e6f
          nullable: true
          type: string
          maxLength: 64
          minLength: 1
        channel:
          $ref: '#/components/schemas/Channel'
        catalog:
          $ref: '#/components/schemas/Catalog'
        pricing:
          $ref: '#/components/schemas/Pricing'
        line_items:
          items:
            $ref: '#/components/schemas/LineItem'
          type: array
          maxItems: 100
          minItems: 1
          title: Line Items
          example:
            - line_item_id: item-1
              price:
                list_price: 1999
                price: 1999
              product_id: SKU-123
        fulfillments:
          items:
            $ref: '#/components/schemas/Fulfillment'
          type: array
          maxItems: 10
          minItems: 1
          title: Fulfillments
          example:
            - fulfillment_option:
                price: 0
                service_level_identifier: IN_STORE_HANDOVER
                tax: 0
              line_item_ids:
                - item-1
        payment:
          $ref: '#/components/schemas/Payment'
      type: object
      required:
        - channel
        - catalog
        - pricing
        - line_items
        - fulfillments
        - payment
      title: OrderRequest
      description: |-
        The minimum-viable order placement request.

        Required fields only. This first slice supports in-store cash-and-carry
        orders from self-checkout machines and Associate App.
    OrderResponse:
      properties:
        id:
          type: string
          maxLength: 36
          minLength: 36
          title: Id
          description: The unique identifier of the order assigned by the system.
          example: 2a0295b0-50a8-459c-82cd-5079d3f35bfb
        order_number:
          type: string
          maxLength: 256
          minLength: 1
          title: Order Number
          description: Human-readable order number generated by the system.
          example: GD000067894
        external_id:
          title: External Id
          description: >-
            Caller-provided external identifier echoed back when supplied in the
            request.
          example: client-order-000123
          nullable: true
          type: string
          maxLength: 64
          minLength: 1
        items:
          items:
            $ref: '#/components/schemas/ResponseUnitItem'
          type: array
          maxItems: 100
          minItems: 1
          title: Items
          description: Identifiers of the order items.
          example:
            - external_item_id: ext-item-1
              id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
              product_id: SKU-123
      type: object
      required:
        - id
        - order_number
        - items
      title: OrderResponse
      description: The response returned after an order is accepted.
    Payment:
      properties:
        instruments:
          items:
            oneOf:
              - $ref: '#/components/schemas/CardPayment'
              - $ref: '#/components/schemas/CashPayment'
          type: array
          maxItems: 40
          minItems: 0
          title: Instruments
          description: >-
            Already-authorized or already-captured payments to attach to the
            order. Must be empty for zero-value orders.
          example:
            - amount: 1999
              card:
                card_brand: Visa
                card_last4: '4242'
                origin: terminal
                reference: pi_3abc
              currency: USD
              payment_method: card
              payment_provider: newstore
              processed_at: '2026-06-05T12:00:00Z'
              status: CAPTURED
      type: object
      required:
        - instruments
      title: Payment
      description: The payments attached to an order.
    PaymentStatus:
      type: string
      enum:
        - AUTHORIZED
        - CAPTURED
      title: PaymentStatus
      description: Whether the supplied payment is already authorized or already captured.
    Pricing:
      properties:
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: The currency for all the prices contained within this payload.
        method:
          allOf:
            - $ref: '#/components/schemas/PricingMethod'
          description: >-
            Specifies whether all item and fulfillment prices include tax
            (`tax_included`) or exclude it (`tax_excluded`).
          example: TAX_INCLUDED
        tax_exemption:
          allOf:
            - $ref: '#/components/schemas/TaxExemption'
          description: >-
            Optional order-level tax exemption to apply to all prices in the
            payload.
          nullable: true
          type: object
      type: object
      required:
        - currency
        - method
      title: Pricing
      description: Currency and tax treatment for all prices in the payload.
      example:
        currency: USD
        method: TAX_INCLUDED
    PricingMethod:
      type: string
      enum:
        - TAX_INCLUDED
        - TAX_EXCLUDED
      title: PricingMethod
      description: Whether supplied prices include or exclude tax.
    ResponseUnitItem:
      properties:
        product_id:
          type: string
          maxLength: 256
          minLength: 1
          title: Product Id
          description: The product id from the catalog.
          example: SKU-123
        external_item_id:
          title: External Item Id
          description: >-
            The external order item id as specified in the request
            (`unit_external_id`). Null when not supplied.
          example: ext-item-1
          nullable: true
          type: string
          maxLength: 64
          minLength: 1
        id:
          type: string
          maxLength: 36
          minLength: 36
          title: Id
          description: An identifier that is assigned to the item by the system.
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      type: object
      required:
        - product_id
        - id
      title: ResponseUnitItem
      description: An item identifier triplet echoed back in the order response.
    TaxExemption:
      properties:
        class:
          title: Class
          description: >-
            The tax exemption category the order qualifies under, for example
            `CHARITY_ORGANIZATION`.
          example: CHARITY_ORGANIZATION
          nullable: true
          type: string
          minLength: 1
        number:
          title: Number
          description: Tax exemption certificate number.
          example: CERT-12345
          nullable: true
          type: string
          minLength: 1
      type: object
      title: TaxExemption
      description: >-
        Order-level tax exemption: the exemption category and certificate
        number.
    TaxLine:
      properties:
        amount:
          type: integer
          maximum: 2147483647
          minimum: 0
          title: Amount
          description: The tax amount, in the currency's minor unit.
          example: 320
          format: int64
        rate:
          type: number
          maximum: 1
          minimum: 0
          title: Rate
          description: The tax rate, as a ratio between 0 and 1 (not a percentage).
          example: 0.16
        name:
          type: string
          maxLength: 256
          minLength: 1
          title: Name
          description: A description of the tax type.
          example: Sales Tax
        country_code:
          title: Country Code
          description: >-
            The country of the tax in ISO 3166 ALPHA-2 format, e.g. GB, DE or
            US.
          example: US
          nullable: true
          type: string
          maxLength: 2
          minLength: 2
      type: object
      required:
        - amount
        - rate
        - name
      title: TaxLine
      description: A single tax applied to a line item, itemising part of its `price_tax`.
    ErrorResponse:
      description: Standard error body, served as `application/problem+json`.
      properties:
        error_code:
          description: A short reference that identifies the problem type.
          maxLength: 255
          title: Error Code
          type: string
          example: bad_request
        message:
          description: A short, human-readable summary of the problem type.
          maxLength: 1024
          title: Message
          type: string
          example: The order payload failed validation.
        request_id:
          description: Unique identifier of the failed request.
          maxLength: 255
          title: Request Id
          type: string
          example: 2a0295b0-50a8-459c-82cd-5079d3f35bfb
      required:
        - error_code
        - message
        - request_id
      title: ErrorResponse
      type: object
  securitySchemes:
    oauth2:
      type: oauth2
      description: NewStore OAuth2 client-credentials access token.
      flows:
        clientCredentials:
          tokenUrl: >-
            https://id.newstore.net/auth/realms/newstore/protocol/openid-connect/token
          scopes:
            orders:write: Grants privileges to place orders.