Microsoft Dynamics NAV

Microsoft Dynamics NAV Items API

Manage inventory items

GitHub OpenAPI

Documentation

📖
Documentation
https://learn.microsoft.com/en-us/dynamics-nav/microsoft-dynamics-nav-web-services-overview
📖
Authentication
https://learn.microsoft.com/en-us/dynamics-nav/web-services-authentication
📖
GettingStarted
https://learn.microsoft.com/en-us/dynamics-nav/walkthrough--creating-and-interacting-with-a-page-web-service--odata-
📖
Documentation
https://learn.microsoft.com/en-us/dynamics-nav/odata-web-services
📖
Documentation
https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/
📖
APIReference
https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/endpoints-apis-for-dynamics
📖
Authentication
https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/authenticate-web-services-using-oauth
📖
GettingStarted
https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-develop-connect-apps
📖
Documentation
https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/administration-center-api
📖
Authentication
https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/automation-apis-using-s2s-authentication
📖
GettingStarted
https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/
📖
Documentation
https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/itpro-introduction-to-automation-apis

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/navision/refs/heads/main/openapi/navision-items-api-openapi.yml

Other Resources

🔗
ChangeLog
https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/whatsnew/overview

OpenAPI Specification

navision-items-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Business Central Administration Center Accounts Items API
  description: REST API for programmatic administration of Dynamics 365 Business Central environments. Enables querying and managing production and sandbox environments, setting up administrative notifications, viewing tenant telemetry, managing apps, scheduling updates, and performing environment operations such as copy, rename, restore, and delete.
  version: '2.28'
  contact:
    name: Microsoft Dynamics Support
    email: bcsupport@microsoft.com
    url: https://dynamics.microsoft.com/support/
  license:
    name: Microsoft APIs Terms of Use
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  termsOfService: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
servers:
- url: https://api.businesscentral.dynamics.com/admin/v2.28
  description: Business Central Administration Center
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Items
  description: Manage inventory items
paths:
  /companies({company_id})/items:
    get:
      summary: List Items
      description: Returns a list of item objects from the specified company.
      operationId: listItems
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/select'
      responses:
        '200':
          description: Successfully retrieved items
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/Item'
              examples:
                Listitems200Example:
                  summary: Default listItems 200 response
                  x-microcks-default: true
                  value:
                    value:
                    - '@odata.etag': example_value
                      id: abc123
                      number: example_value
                      displayName: example_value
                      displayName2: example_value
                      type: Inventory
                      itemCategoryId: '500123'
                      itemCategoryCode: example_value
                      blocked: true
                      gtin: example_value
                      inventory: 42.5
                      unitPrice: 42.5
                      priceIncludesTax: true
                      unitCost: 42.5
                      taxGroupId: '500123'
                      taxGroupCode: example_value
                      baseUnitOfMeasureId: '500123'
                      baseUnitOfMeasureCode: example_value
                      generalProductPostingGroupId: '500123'
                      generalProductPostingGroupCode: example_value
                      inventoryPostingGroupId: '500123'
                      inventoryPostingGroupCode: example_value
                      lastModifiedDateTime: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: Create an Item
      description: Creates a new item object in the specified company.
      operationId: createItem
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/company_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemCreate'
            examples:
              CreateitemRequestExample:
                summary: Default createItem request
                x-microcks-default: true
                value:
                  number: example_value
                  displayName: example_value
                  type: Inventory
                  itemCategoryCode: example_value
                  blocked: true
                  gtin: example_value
                  unitPrice: 42.5
                  unitCost: 42.5
                  taxGroupCode: example_value
                  baseUnitOfMeasureCode: example_value
      responses:
        '201':
          description: Item created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
              examples:
                Createitem201Example:
                  summary: Default createItem 201 response
                  x-microcks-default: true
                  value:
                    '@odata.etag': example_value
                    id: abc123
                    number: example_value
                    displayName: example_value
                    displayName2: example_value
                    type: Inventory
                    itemCategoryId: '500123'
                    itemCategoryCode: example_value
                    blocked: true
                    gtin: example_value
                    inventory: 42.5
                    unitPrice: 42.5
                    priceIncludesTax: true
                    unitCost: 42.5
                    taxGroupId: '500123'
                    taxGroupCode: example_value
                    baseUnitOfMeasureId: '500123'
                    baseUnitOfMeasureCode: example_value
                    generalProductPostingGroupId: '500123'
                    generalProductPostingGroupCode: example_value
                    inventoryPostingGroupId: '500123'
                    inventoryPostingGroupCode: example_value
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /companies({company_id})/items({item_id}):
    get:
      summary: Get an Item
      description: Retrieves a specific item by ID.
      operationId: getItem
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/item_id'
      - $ref: '#/components/parameters/select'
      responses:
        '200':
          description: Successfully retrieved item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
              examples:
                Getitem200Example:
                  summary: Default getItem 200 response
                  x-microcks-default: true
                  value:
                    '@odata.etag': example_value
                    id: abc123
                    number: example_value
                    displayName: example_value
                    displayName2: example_value
                    type: Inventory
                    itemCategoryId: '500123'
                    itemCategoryCode: example_value
                    blocked: true
                    gtin: example_value
                    inventory: 42.5
                    unitPrice: 42.5
                    priceIncludesTax: true
                    unitCost: 42.5
                    taxGroupId: '500123'
                    taxGroupCode: example_value
                    baseUnitOfMeasureId: '500123'
                    baseUnitOfMeasureCode: example_value
                    generalProductPostingGroupId: '500123'
                    generalProductPostingGroupCode: example_value
                    inventoryPostingGroupId: '500123'
                    inventoryPostingGroupCode: example_value
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      summary: Update an Item
      description: Updates an existing item object.
      operationId: updateItem
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/item_id'
      - $ref: '#/components/parameters/ifMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemUpdate'
            examples:
              UpdateitemRequestExample:
                summary: Default updateItem request
                x-microcks-default: true
                value:
                  displayName: example_value
                  type: Inventory
                  itemCategoryCode: example_value
                  blocked: true
                  gtin: example_value
                  unitPrice: 42.5
                  unitCost: 42.5
                  taxGroupCode: example_value
                  baseUnitOfMeasureCode: example_value
      responses:
        '200':
          description: Item updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
              examples:
                Updateitem200Example:
                  summary: Default updateItem 200 response
                  x-microcks-default: true
                  value:
                    '@odata.etag': example_value
                    id: abc123
                    number: example_value
                    displayName: example_value
                    displayName2: example_value
                    type: Inventory
                    itemCategoryId: '500123'
                    itemCategoryCode: example_value
                    blocked: true
                    gtin: example_value
                    inventory: 42.5
                    unitPrice: 42.5
                    priceIncludesTax: true
                    unitCost: 42.5
                    taxGroupId: '500123'
                    taxGroupCode: example_value
                    baseUnitOfMeasureId: '500123'
                    baseUnitOfMeasureCode: example_value
                    generalProductPostingGroupId: '500123'
                    generalProductPostingGroupCode: example_value
                    inventoryPostingGroupId: '500123'
                    inventoryPostingGroupCode: example_value
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: Delete an Item
      description: Deletes an item by ID.
      operationId: deleteItem
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/item_id'
      responses:
        '204':
          description: Item deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ItemCreate:
      type: object
      required:
      - displayName
      properties:
        number:
          type: string
          maxLength: 20
          example: example_value
        displayName:
          type: string
          maxLength: 100
          example: example_value
        type:
          type: string
          enum:
          - Inventory
          - Service
          - Non-Inventory
          example: Inventory
        itemCategoryCode:
          type: string
          maxLength: 20
          example: example_value
        blocked:
          type: boolean
          example: true
        gtin:
          type: string
          maxLength: 14
          example: example_value
        unitPrice:
          type: number
          format: decimal
          example: 42.5
        unitCost:
          type: number
          format: decimal
          example: 42.5
        taxGroupCode:
          type: string
          maxLength: 20
          example: example_value
        baseUnitOfMeasureCode:
          type: string
          maxLength: 10
          example: example_value
    Item:
      type: object
      properties:
        '@odata.etag':
          type: string
          example: example_value
        id:
          type: string
          format: uuid
          description: The unique identifier of the item
          example: abc123
        number:
          type: string
          description: The item number
          maxLength: 20
          example: example_value
        displayName:
          type: string
          description: The item display name
          maxLength: 100
          example: example_value
        displayName2:
          type: string
          description: The item display name 2
          maxLength: 50
          example: example_value
        type:
          type: string
          description: The item type
          enum:
          - Inventory
          - Service
          - Non-Inventory
          example: Inventory
        itemCategoryId:
          type: string
          format: uuid
          description: The item category ID
          example: '500123'
        itemCategoryCode:
          type: string
          description: The item category code
          maxLength: 20
          example: example_value
        blocked:
          type: boolean
          description: Whether the item is blocked
          example: true
        gtin:
          type: string
          description: The Global Trade Item Number
          maxLength: 14
          example: example_value
        inventory:
          type: number
          format: decimal
          description: The current inventory quantity
          readOnly: true
          example: 42.5
        unitPrice:
          type: number
          format: decimal
          description: The unit price
          example: 42.5
        priceIncludesTax:
          type: boolean
          description: Whether the price includes tax
          example: true
        unitCost:
          type: number
          format: decimal
          description: The unit cost
          example: 42.5
        taxGroupId:
          type: string
          format: uuid
          description: The tax group ID
          example: '500123'
        taxGroupCode:
          type: string
          description: The tax group code
          maxLength: 20
          example: example_value
        baseUnitOfMeasureId:
          type: string
          format: uuid
          description: The base unit of measure ID
          example: '500123'
        baseUnitOfMeasureCode:
          type: string
          description: The base unit of measure code
          maxLength: 10
          example: example_value
        generalProductPostingGroupId:
          type: string
          format: uuid
          example: '500123'
        generalProductPostingGroupCode:
          type: string
          maxLength: 20
          example: example_value
        inventoryPostingGroupId:
          type: string
          format: uuid
          example: '500123'
        inventoryPostingGroupCode:
          type: string
          maxLength: 20
          example: example_value
        lastModifiedDateTime:
          type: string
          format: date-time
          readOnly: true
          example: '2026-01-15T10:30:00Z'
    ItemUpdate:
      type: object
      properties:
        displayName:
          type: string
          maxLength: 100
          example: example_value
        type:
          type: string
          enum:
          - Inventory
          - Service
          - Non-Inventory
          example: Inventory
        itemCategoryCode:
          type: string
          maxLength: 20
          example: example_value
        blocked:
          type: boolean
          example: true
        gtin:
          type: string
          maxLength: 14
          example: example_value
        unitPrice:
          type: number
          format: decimal
          example: 42.5
        unitCost:
          type: number
          format: decimal
          example: 42.5
        taxGroupCode:
          type: string
          maxLength: 20
          example: example_value
        baseUnitOfMeasureCode:
          type: string
          maxLength: 10
          example: example_value
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: A stable error code
            message:
              type: string
              description: A human-readable error message
          example: example_value
  parameters:
    ifMatch:
      name: If-Match
      in: header
      required: true
      description: ETag value for optimistic concurrency control
      schema:
        type: string
    filter:
      name: $filter
      in: query
      description: OData filter expression
      schema:
        type: string
    orderby:
      name: $orderby
      in: query
      description: OData order by expression
      schema:
        type: string
    company_id:
      name: company_id
      in: path
      required: true
      description: The unique identifier of the company
      schema:
        type: string
        format: uuid
    item_id:
      name: item_id
      in: path
      required: true
      description: The unique identifier of the item
      schema:
        type: string
        format: uuid
    skip:
      name: $skip
      in: query
      description: Number of items to skip
      schema:
        type: integer
        minimum: 0
    select:
      name: $select
      in: query
      description: Comma-separated list of properties to include in the response
      schema:
        type: string
    top:
      name: $top
      in: query
      description: Maximum number of items to return
      schema:
        type: integer
        minimum: 0
  responses:
    Unauthorized:
      description: Unauthorized - authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication via Microsoft Entra ID
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
          scopes:
            https://api.businesscentral.dynamics.com/.default: Access Business Central Admin APIs
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
          scopes:
            https://api.businesscentral.dynamics.com/.default: Access Business Central Admin APIs
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Administration Center API Documentation
  url: https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/administration-center-api