openapi: 3.0.3
info:
  title: NCR Voyix Commerce Platform APIs Catalog Order API
  description: 'REST APIs for the NCR Voyix Commerce Platform (Business Services Platform), the API-based cloud architecture that powers NCR Voyix unified-commerce solutions for retailers and restaurants. This specification covers the core commerce surfaces exercised by the publicly published NCR Voyix sample applications: Catalog (items, item-prices, item-attributes, item-details search), Category and Group management, Selling Service carts, Order creation and lookup, Site (location) provisioning, Security (authentication, authorization, passwords), and Provisioning (users and user profiles). Requests are signed with HMAC SHA-512 AccessKey authentication and scoped with the nep-organization and nep-enterprise-unit headers. Paths and schemas were reconstructed from the NCR Voyix sample applications (NCRVoyix-Corporation/ncr-retail-demo, NCRVoyix-Corporation/sample-app-burgers, NCRVoyix-Corporation/ncr-bsp-hmac); consult developer.ncrvoyix.com for the authoritative contract.'
  version: '1.0'
  contact:
    name: NCR Voyix Developer Experience
    url: https://developer.ncrvoyix.com/
  license:
    name: Proprietary
    url: https://www.ncrvoyix.com/
  x-generated-from: documentation
  x-last-validated: '2026-06-02'
servers:
- url: https://api.ncr.com
  description: Production (Business Services Platform)
- url: https://gateway-staging.ncrcloud.com
  description: Staging
security:
- hmacAccessKey: []
tags:
- name: Order
  description: Order creation, lookup, update, and search.
paths:
  /order/3/orders/1:
    post:
      tags:
      - Order
      summary: NCR Voyix Create Order
      description: Create a new order at a site. Requires the nep-enterprise-unit header identifying the location.
      operationId: createOrder
      parameters:
      - $ref: '#/components/parameters/NepEnterpriseUnit'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
            examples:
              CreateOrderRequestExample:
                summary: Default createOrder request
                x-microcks-default: true
                value:
                  channel: Web
                  comments: Customer request
                  customer:
                    email: jsmith@example.com
                    firstName: Downtown Store
                    lastName: Downtown Store
                  orderLines:
                  - productId:
                      type: example
                      value: Cheeseburger
                    quantity:
                      unitOfMeasure: EA
                      unitOfMeasureLabel: example
                      value: 9.99
                    unitPrice: 9.99
      responses:
        '201':
          description: The created order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                CreateOrder201Example:
                  summary: Default createOrder 201 response
                  x-microcks-default: true
                  value:
                    channel: Web
                    comments: Customer request
                    customer:
                      email: jsmith@example.com
                      firstName: Downtown Store
                      lastName: Downtown Store
                    orderLines:
                    - productId:
                        type: {}
                        value: {}
                      quantity:
                        unitOfMeasure: {}
                        unitOfMeasureLabel: {}
                        value: {}
                      unitPrice: 9.99
                    id: '500123'
                    status: ACTIVE
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /order/3/orders/1/{orderId}:
    parameters:
    - name: orderId
      in: path
      required: true
      description: The order identifier.
      schema:
        type: string
    get:
      tags:
      - Order
      summary: NCR Voyix Get Order by Id
      description: Retrieve a single order by its identifier.
      operationId: getOrderById
      responses:
        '200':
          description: The order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                GetOrderById200Example:
                  summary: Default getOrderById 200 response
                  x-microcks-default: true
                  value:
                    channel: Web
                    comments: Customer request
                    customer:
                      email: jsmith@example.com
                      firstName: Downtown Store
                      lastName: Downtown Store
                    orderLines:
                    - productId:
                        type: {}
                        value: {}
                      quantity:
                        unitOfMeasure: {}
                        unitOfMeasureLabel: {}
                        value: {}
                      unitPrice: 9.99
                    id: '500123'
                    status: ACTIVE
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      tags:
      - Order
      summary: NCR Voyix Update Order by Id
      description: Update mutable fields on an existing order at a site.
      operationId: updateOrderById
      parameters:
      - $ref: '#/components/parameters/NepEnterpriseUnit'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
            examples:
              UpdateOrderByIdRequestExample:
                summary: Default updateOrderById request
                x-microcks-default: true
                value:
                  channel: Web
                  comments: Customer request
                  customer:
                    email: jsmith@example.com
                    firstName: Downtown Store
                    lastName: Downtown Store
                  orderLines:
                  - productId:
                      type: example
                      value: Cheeseburger
                    quantity:
                      unitOfMeasure: EA
                      unitOfMeasureLabel: example
                      value: 9.99
                    unitPrice: 9.99
      responses:
        '200':
          description: The updated order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                UpdateOrderById200Example:
                  summary: Default updateOrderById 200 response
                  x-microcks-default: true
                  value:
                    channel: Web
                    comments: Customer request
                    customer:
                      email: jsmith@example.com
                      firstName: Downtown Store
                      lastName: Downtown Store
                    orderLines:
                    - productId:
                        type: {}
                        value: {}
                      quantity:
                        unitOfMeasure: {}
                        unitOfMeasureLabel: {}
                        value: {}
                      unitPrice: 9.99
                    id: '500123'
                    status: ACTIVE
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /order/3/orders/1/find:
    post:
      tags:
      - Order
      summary: NCR Voyix Find Orders
      description: Search for orders by criteria such as customer email, with paging.
      operationId: findOrders
      parameters:
      - name: pageSize
        in: query
        schema:
          type: integer
        example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderSearch'
            examples:
              FindOrdersRequestExample:
                summary: Default findOrders request
                x-microcks-default: true
                value:
                  customerEmail: jsmith@example.com
                  returnFullOrders: true
      responses:
        '200':
          description: A page of matching orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageContent:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
              examples:
                FindOrders200Example:
                  summary: Default findOrders 200 response
                  x-microcks-default: true
                  value:
                    pageContent:
                    - channel: Web
                      comments: Customer request
                      customer:
                        email: {}
                        firstName: {}
                        lastName: {}
                      orderLines:
                      - {}
                      id: '500123'
                      status: ACTIVE
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ProductId:
      type: object
      properties:
        type:
          type: string
          example: example
        value:
          type: string
          example: Cheeseburger
    OrderLine:
      type: object
      properties:
        productId:
          $ref: '#/components/schemas/ProductId'
        quantity:
          $ref: '#/components/schemas/Quantity'
        unitPrice:
          type: number
          format: double
          example: 9.99
    Order:
      allOf:
      - $ref: '#/components/schemas/OrderInput'
      - type: object
        properties:
          id:
            type: string
          status:
            type: string
    Customer:
      type: object
      properties:
        email:
          type: string
          format: email
          example: jsmith@example.com
        firstName:
          type: string
          example: Downtown Store
        lastName:
          type: string
          example: Downtown Store
    OrderSearch:
      type: object
      properties:
        customerEmail:
          type: string
          format: email
          example: jsmith@example.com
        returnFullOrders:
          type: boolean
          example: true
    Error:
      type: object
      properties:
        code:
          type: string
          example: example
        message:
          type: string
          example: example
    Quantity:
      type: object
      properties:
        unitOfMeasure:
          type: string
          example: EA
        unitOfMeasureLabel:
          type: string
          example: example
        value:
          type: number
          example: 9.99
    OrderInput:
      type: object
      properties:
        channel:
          type: string
          example: Web
        comments:
          type: string
          example: Customer request
        customer:
          $ref: '#/components/schemas/Customer'
        orderLines:
          type: array
          items:
            $ref: '#/components/schemas/OrderLine'
      required:
      - orderLines
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    NepEnterpriseUnit:
      name: nep-enterprise-unit
      in: header
      required: true
      description: Identifier of the enterprise unit (site/location) the request applies to.
      schema:
        type: string
  securitySchemes:
    hmacAccessKey:
      type: apiKey
      in: header
      name: Authorization
      description: AccessKey (HMAC) authentication. The Authorization header carries "AccessKey {sharedKey}:{signature}", where the signature is a Base64 SHA-512 HMAC computed over the HTTP method, encoded request path and query string, Content-Type, optional Content-MD5, optional nep-application-key, and optional nep-correlation-id, keyed by the secret key concatenated with the ISO-8601 request date. A Date header must accompany the request. Access keys consist of a shared key and a secret key issued by NCR Voyix. See the ncr-bsp-hmac repository for reference implementations in Python, JavaScript, Java, Kotlin, Go, Dart, .NET, and PowerShell.