NCR Voyix Commerce Platform APIs

openapi: 3.0.3
info:
  title: NCR Voyix Commerce Platform APIs
  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: Catalog
  description: Item, item-price, and item-attribute management plus item-details search.
- name: Category
  description: Catalog category-node hierarchy and group management.
- name: Selling
  description: Selling Service shopping carts and cart line items.
- name: Order
  description: Order creation, lookup, update, and search.
- name: Site
  description: Site (location) provisioning, lookup, and geospatial search.
- name: Security
  description: Authentication, authorization, and user password management.
- name: Provisioning
  description: Platform user creation and user profile management.
paths:
  /catalog/items:
    get:
      tags: [Catalog]
      summary: NCR Voyix List Catalog Items
      description: List catalog items, optionally filtered by status and paged/sorted.
      operationId: listCatalogItems
      parameters:
      - name: itemStatus
        in: query
        description: Filter by item status.
        schema:
          type: string
          enum: [ACTIVE, INACTIVE]
        example: ACTIVE
      - name: pageSize
        in: query
        schema:
          type: integer
        example: 1
      - name: sortField
        in: query
        schema:
          type: string
        example: example
      - name: sortDirection
        in: query
        schema:
          type: string
          enum: [ASC, DESC]
        example: ASC
      responses:
        '200':
          description: A page of catalog items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemPage'
              examples:
                ListCatalogItems200Example:
                  summary: Default listCatalogItems 200 response
                  x-microcks-default: true
                  value:
                    pageContent:
                    - version: 1
                      itemId: {}
                      shortDescription:
                        values: {}
                      longDescription:
                        values: {}
                      status: ACTIVE
                      merchandiseCategory: example
                      departmentId: example
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags: [Catalog]
      summary: NCR Voyix Create Catalog Items
      description: Bulk create or update catalog items. There is no delete; mark INACTIVE to retire.
      operationId: createCatalogItems
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemInput'
            examples:
              CreateCatalogItemsRequestExample:
                summary: Default createCatalogItems request
                x-microcks-default: true
                value:
                  version: 1
                  itemId: {}
                  shortDescription:
                    values:
                    - locale: en-US
                      value: Cheeseburger
                  longDescription:
                    values:
                    - locale: en-US
                      value: Cheeseburger
                  status: ACTIVE
                  merchandiseCategory: example
                  departmentId: example
      responses:
        '200':
          description: The created or updated catalog items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
              examples:
                CreateCatalogItems200Example:
                  summary: Default createCatalogItems 200 response
                  x-microcks-default: true
                  value:
                    version: 1
                    itemId: {}
                    shortDescription:
                      values:
                      - locale: {}
                        value: {}
                    longDescription:
                      values:
                      - locale: {}
                        value: {}
                    status: ACTIVE
                    merchandiseCategory: example
                    departmentId: example
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalog/items/{itemCode}:
    parameters:
    - $ref: '#/components/parameters/ItemCode'
    get:
      tags: [Catalog]
      summary: NCR Voyix Get Catalog Item
      description: Retrieve the details of a single catalog item by its item code.
      operationId: getCatalogItem
      responses:
        '200':
          description: The catalog item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
              examples:
                GetCatalogItem200Example:
                  summary: Default getCatalogItem 200 response
                  x-microcks-default: true
                  value:
                    version: 1
                    itemId: {}
                    shortDescription:
                      values:
                      - locale: {}
                        value: {}
                    longDescription:
                      values:
                      - locale: {}
                        value: {}
                    status: ACTIVE
                    merchandiseCategory: example
                    departmentId: example
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags: [Catalog]
      summary: NCR Voyix Create or Update Catalog Item
      description: Create or update a catalog item. The version must increase on each update.
      operationId: putCatalogItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemInput'
            examples:
              PutCatalogItemRequestExample:
                summary: Default putCatalogItem request
                x-microcks-default: true
                value:
                  version: 1
                  itemId: {}
                  shortDescription:
                    values:
                    - locale: en-US
                      value: Cheeseburger
                  longDescription:
                    values:
                    - locale: en-US
                      value: Cheeseburger
                  status: ACTIVE
                  merchandiseCategory: example
                  departmentId: example
      responses:
        '200':
          description: The created or updated catalog item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
              examples:
                PutCatalogItem200Example:
                  summary: Default putCatalogItem 200 response
                  x-microcks-default: true
                  value:
                    version: 1
                    itemId: {}
                    shortDescription:
                      values:
                      - locale: {}
                        value: {}
                    longDescription:
                      values:
                      - locale: {}
                        value: {}
                    status: ACTIVE
                    merchandiseCategory: example
                    departmentId: example
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalog/item-prices:
    put:
      tags: [Catalog]
      summary: NCR Voyix Create or Update Item Prices
      description: Bulk create or update item prices for catalog items.
      operationId: createCatalogItemPrices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemPriceInput'
            examples:
              CreateCatalogItemPricesRequestExample:
                summary: Default createCatalogItemPrices request
                x-microcks-default: true
                value:
                  version: 1
                  price: 9.99
                  currency: USD
                  effectiveDate: '2026-06-02T14:30:00Z'
                  status: ACTIVE
      responses:
        '200':
          description: The created or updated item prices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemPrice'
              examples:
                CreateCatalogItemPrices200Example:
                  summary: Default createCatalogItemPrices 200 response
                  x-microcks-default: true
                  value:
                    version: 1
                    price: 9.99
                    currency: USD
                    effectiveDate: '2026-06-02T14:30:00Z'
                    status: ACTIVE
                    priceId:
                      itemCode: BURGER-001
                      priceCode: BASE
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalog/item-prices/{itemCode}/{priceCode}:
    parameters:
    - $ref: '#/components/parameters/ItemCode'
    - name: priceCode
      in: path
      required: true
      description: Unique identifier for the item price.
      schema:
        type: string
    put:
      tags: [Catalog]
      summary: NCR Voyix Update Item Price by Item Code
      description: Create or update the price for a catalog item at a site. The version must increase on each update.
      operationId: updateItemPriceByItemCode
      parameters:
      - $ref: '#/components/parameters/NepEnterpriseUnit'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemPriceInput'
            examples:
              UpdateItemPriceByItemCodeRequestExample:
                summary: Default updateItemPriceByItemCode request
                x-microcks-default: true
                value:
                  version: 1
                  price: 9.99
                  currency: USD
                  effectiveDate: '2026-06-02T14:30:00Z'
                  status: ACTIVE
      responses:
        '200':
          description: The updated item price.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemPrice'
              examples:
                UpdateItemPriceByItemCode200Example:
                  summary: Default updateItemPriceByItemCode 200 response
                  x-microcks-default: true
                  value:
                    version: 1
                    price: 9.99
                    currency: USD
                    effectiveDate: '2026-06-02T14:30:00Z'
                    status: ACTIVE
                    priceId:
                      itemCode: BURGER-001
                      priceCode: BASE
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalog/item-prices/get-multiple:
    post:
      tags: [Catalog]
      summary: NCR Voyix Get Multiple Item Prices
      description: Retrieve prices for a list of catalog items in a single request, scoped to a site.
      operationId: getMultipleItemPrices
      parameters:
      - $ref: '#/components/parameters/NepEnterpriseUnit'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemCodeList'
            examples:
              GetMultipleItemPricesRequestExample:
                summary: Default getMultipleItemPrices request
                x-microcks-default: true
                value:
                  itemIds:
                  - itemCode: BURGER-001
      responses:
        '200':
          description: The requested item prices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  itemPrices:
                    type: array
                    items:
                      $ref: '#/components/schemas/ItemPrice'
              examples:
                GetMultipleItemPrices200Example:
                  summary: Default getMultipleItemPrices 200 response
                  x-microcks-default: true
                  value:
                    itemPrices:
                    - version: 1
                      price: 9.99
                      currency: USD
                      effectiveDate: '2026-06-02T14:30:00Z'
                      status: ACTIVE
                      priceId:
                        itemCode: {}
                        priceCode: {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalog/item-attributes/get-multiple:
    post:
      tags: [Catalog]
      summary: NCR Voyix Get Multiple Item Attributes
      description: Retrieve attributes for a list of catalog items in a single request, scoped to a site.
      operationId: getMultipleItemAttributes
      parameters:
      - $ref: '#/components/parameters/NepEnterpriseUnit'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemCodeList'
            examples:
              GetMultipleItemAttributesRequestExample:
                summary: Default getMultipleItemAttributes request
                x-microcks-default: true
                value:
                  itemIds:
                  - itemCode: BURGER-001
      responses:
        '200':
          description: The requested item attributes.
          content:
            application/json:
              schema:
                type: object
              examples:
                GetMultipleItemAttributes200Example:
                  summary: Default getMultipleItemAttributes 200 response
                  x-microcks-default: true
                  value: {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalog/item-attributes/{itemCode}:
    parameters:
    - $ref: '#/components/parameters/ItemCode'
    put:
      tags: [Catalog]
      summary: NCR Voyix Update Item Attributes by Item Code
      description: Create or update attributes for a catalog item at a site.
      operationId: updateItemAttributesByItemCode
      parameters:
      - $ref: '#/components/parameters/NepEnterpriseUnit'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            examples:
              UpdateItemAttributesByItemCodeRequestExample:
                summary: Default updateItemAttributesByItemCode request
                x-microcks-default: true
                value: {}
      responses:
        '200':
          description: The updated item attributes.
          content:
            application/json:
              schema:
                type: object
              examples:
                UpdateItemAttributesByItemCode200Example:
                  summary: Default updateItemAttributesByItemCode 200 response
                  x-microcks-default: true
                  value: {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalog/item-details/{itemCode}:
    parameters:
    - $ref: '#/components/parameters/ItemCode'
    get:
      tags: [Catalog]
      summary: NCR Voyix Get Item Details by Item Code
      description: Retrieve the consolidated item details (item, price, attributes) for a single item at a site.
      operationId: getItemDetailsByItemCode
      parameters:
      - $ref: '#/components/parameters/NepEnterpriseUnit'
      responses:
        '200':
          description: The item details.
          content:
            application/json:
              schema:
                type: object
              examples:
                GetItemDetailsByItemCode200Example:
                  summary: Default getItemDetailsByItemCode 200 response
                  x-microcks-default: true
                  value: {}
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalog/item-details/search:
    get:
      tags: [Catalog]
      summary: NCR Voyix Search Item Details
      description: Search consolidated item details at a site by description pattern, merchandise category, group, and status, with sorting.
      operationId: searchItemDetails
      parameters:
      - $ref: '#/components/parameters/NepEnterpriseUnit'
      - name: shortDescriptionPattern
        in: query
        description: Wildcard pattern matched against the item short description.
        schema:
          type: string
        example: example
      - name: merchandiseCategoryId
        in: query
        schema:
          type: string
        example: example
      - name: groupCode
        in: query
        schema:
          type: string
        example: example
      - name: itemStatus
        in: query
        schema:
          type: string
          enum: [ACTIVE, INACTIVE]
        example: ACTIVE
      - name: sortField
        in: query
        schema:
          type: string
        example: example
      - name: sortDirection
        in: query
        schema:
          type: string
          enum: [ASC, DESC]
        example: ASC
      responses:
        '200':
          description: A page of matching item details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageContent:
                    type: array
                    items:
                      type: object
              examples:
                SearchItemDetails200Example:
                  summary: Default searchItemDetails 200 response
                  x-microcks-default: true
                  value:
                    pageContent:
                    - {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalog/v2/category-nodes:
    get:
      tags: [Category]
      summary: NCR Voyix List Category Nodes
      description: List catalog category nodes, optionally filtered by parent node.
      operationId: listCategoryNodes
      parameters:
      - name: parentId
        in: query
        description: Filter to children of the supplied parent category node.
        schema:
          type: string
        example: example
      responses:
        '200':
          description: The category nodes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  categoryNodes:
                    type: array
                    items:
                      $ref: '#/components/schemas/CategoryNode'
              examples:
                ListCategoryNodes200Example:
                  summary: Default listCategoryNodes 200 response
                  x-microcks-default: true
                  value:
                    categoryNodes:
                    - id: '500123'
                      version: 1
                      name:
                        values:
                        - {}
                      parentId: example
                      nodeType: CATEGORY
                      status: ACTIVE
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags: [Category]
      summary: NCR Voyix Create or Update Category Node
      description: Create or update a catalog category node in the category hierarchy.
      operationId: putCategoryNode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryNode'
            examples:
              PutCategoryNodeRequestExample:
                summary: Default putCategoryNode request
                x-microcks-default: true
                value:
                  id: '500123'
                  version: 1
                  name:
                    values:
                    - locale: en-US
                      value: Cheeseburger
                  parentId: example
                  nodeType: CATEGORY
                  status: ACTIVE
      responses:
        '200':
          description: The created or updated category node.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryNode'
              examples:
                PutCategoryNode200Example:
                  summary: Default putCategoryNode 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    version: 1
                    name:
                      values:
                      - locale: en-US
                        value: Cheeseburger
                    parentId: example
                    nodeType: CATEGORY
                    status: ACTIVE
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalog/v2/category-nodes/{nodeId}:
    parameters:
    - name: nodeId
      in: path
      required: true
      description: The category node identifier.
      schema:
        type: string
    get:
      tags: [Category]
      summary: NCR Voyix Get Category Node
      description: Retrieve a single category node by its identifier.
      operationId: getCategoryNode
      responses:
        '200':
          description: The category node.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryNode'
              examples:
                GetCategoryNode200Example:
                  summary: Default getCategoryNode 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    version: 1
                    name:
                      values:
                      - locale: en-US
                        value: Cheeseburger
                    parentId: example
                    nodeType: CATEGORY
                    status: ACTIVE
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalog/v2/category-nodes/{nodeId}/ancestors:
    parameters:
    - name: nodeId
      in: path
      required: true
      description: The category node identifier.
      schema:
        type: string
    get:
      tags: [Category]
      summary: NCR Voyix Get Category Node Ancestors
      description: Retrieve the ancestor chain for a category node up to the root.
      operationId: getCategoryNodeAncestors
      responses:
        '200':
          description: The ancestor category nodes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ancestors:
                    type: array
                    items:
                      $ref: '#/components/schemas/CategoryNode'
              examples:
                GetCategoryNodeAncestors200Example:
                  summary: Default getCategoryNodeAncestors 200 response
                  x-microcks-default: true
                  value:
                    ancestors:
                    - id: '500123'
                      version: 1
                      name:
                        values:
                        - {}
                      parentId: example
                      nodeType: CATEGORY
                      status: ACTIVE
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalog/v2/groups:
    get:
      tags: [Category]
      summary: NCR Voyix List Groups
      description: List catalog groups, optionally paged and filtered by title pattern.
      operationId: listGroups
      parameters:
      - name: pageSize
        in: query
        schema:
          type: integer
        example: 1
      - name: titlePattern
        in: query
        schema:
          type: string
        example: example
      responses:
        '200':
          description: The catalog groups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageContent:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
              examples:
                ListGroups200Example:
                  summary: Default listGroups 200 response
                  x-microcks-default: true
                  value:
                    pageContent:
                    - id: '500123'
                      version: 1
                      title:
                        values:
                        - {}
                      itemCodes:
                      - example
                      status: ACTIVE
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags: [Category]
      summary: NCR Voyix Create or Update Group
      description: Create or update a catalog group used to merchandise items together.
      operationId: putGroup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
            examples:
              PutGroupRequestExample:
                summary: Default putGroup request
                x-microcks-default: true
                value:
                  id: '500123'
                  version: 1
                  title:
                    values:
                    - locale: en-US
                      value: Cheeseburger
                  itemCodes:
                  - example
                  status: ACTIVE
      responses:
        '200':
          description: The created or updated group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              examples:
                PutGroup200Example:
                  summary: Default putGroup 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    version: 1
                    title:
                      values:
                      - locale: en-US
                        value: Cheeseburger
                    itemCodes:
                    - example
                    status: ACTIVE
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /catalog/v2/groups/{groupId}:
    parameters:
    - name: groupId
      in: path
      required: true
      description: The group identifier.
      schema:
        type: string
    get:
      tags: [Category]
      summary: NCR Voyix Get Group
      description: Retrieve a single catalog group by its identifier.
      operationId: getGroup
      responses:
        '200':
          description: The group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              examples:
                GetGroup200Example:
                  summary: Default getGroup 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    version: 1
                    title:
                      values:
                      - locale: en-US
                        value: Cheeseburger
                    itemCodes:
                    - example
                    status: ACTIVE
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /emerald/selling-service/cart/v1/carts:
    post:
      tags: [Selling]
      summary: NCR Voyix Create Cart
      description: Create a new shopping cart at a site via the Selling Service.
      operationId: createCart
      parameters:
      - $ref: '#/components/parameters/NepEnterpriseUnit'
      responses:
        '201':
          description: The created cart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
              examples:
                CreateCart201Example:
                  summary: Default createCart 201 response
                  x-microcks-default: true
                  value:
                    cartId: cart-a1b2c3d4
                    status: ACTIVE
                    items:
                    - productId:
                        type: {}
                        value: {}
                      quantity:
                        unitOfMeasure: {}
                        unitOfMeasureLabel: {}
                        value: {}
                      voidReason: Customer request
                      lineId: line-001
                      unitPrice: 9.99
                    totals:
                      total: 9.99
                      currency: USD
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /emerald/selling-service/cart/v1/carts/{cartId}:
    parameters:
    - $ref: '#/components/parameters/CartId'
    get:
      tags: [Selling]
      summary: NCR Voyix Get Cart by Id
      description: Retrieve a shopping cart by its identifier.
      operationId: getCartById
      parameters:
      - $ref: '#/components/parameters/NepEnterpriseUnit'
      responses:
        '200':
          description: The cart.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
              examples:
                GetCartById200Example:
                  summary: Default getCartById 200 response
                  x-microcks-default: true
                  value:
                    cartId: cart-a1b2c3d4
                    status: ACTIVE
                    items:
                    - productId:
                        type: {}
                        value: {}
                      quantity:
                        unitOfMeasure: {}
                        unitOfMeasureLabel: {}
                        value: {}
                      voidReason: Customer request
                      lineId: line-001
                      unitPrice: 9.99
                    totals:
                      total: 9.99
                      currency: USD
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      tags: [Selling]
      summary: NCR Voyix Update Cart Status
      description: Update mutable cart fields such as status.
      operationId: updateCart
      parameters:
      - $ref: '#/components/parameters/NepEnterpriseUnit'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
            examples:
              UpdateCartRequestExample:
                summary: Default updateCart request
                x-microcks-default: true
                value:
                  statu

# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ncr/refs/heads/main/openapi/ncr-voyix-commerce-platform-openapi.yml