VTex Orders API — Orders

naftiko: 1.0.0-alpha2
info:
  label: VTex Orders API — Orders
  description: 'VTex Orders API — Orders. 6 operations. Lead operation: VTex List orders. Self-contained Naftiko capability
    covering one Vtex business surface.'
  tags:
  - Vtex
  - Orders
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    VTEX_API_KEY: VTEX_API_KEY
capability:
  consumes:
  - type: http
    namespace: orders-orders
    baseUri: https://{accountName}.{environment}.com.br
    description: VTex Orders API — Orders business capability. Self-contained, no shared references.
    resources:
    - name: api-oms-pvt-orders
      path: /api/oms/pvt/orders
      operations:
      - name: listorders
        method: GET
        description: VTex List orders
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
          required: true
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: orderBy
          in: query
          type: string
          description: 'You can retrieve orders lists filtering by an `OrderField` combined with an `OrderType`. To do so,
            you have to concatenate them: `orderBy={{OrderField}},{{Order'
        - name: page
          in: query
          type: integer
          description: Define the number of pages you wish to retrieve, restricted to the limit of 30 pages.
        - name: per_page
          in: query
          type: integer
          description: Quantity of orders for each page, the default value is 15 and it goes up to 100 orders per page. Be
            aware that the limit of retrieval ofthis endpoint is 30 page
        - name: f_hasInputInvoice
          in: query
          type: boolean
          description: Filters list to return only orders with non `null` values for the `invoiceInput` field.
        - name: q
          in: query
          type: string
          description: "This parameter filters using Fulltext and accepts the values below. Be aware that the `+` caracter\
            \ is not allowed in Fulltext Search. \r"
        - name: f_shippingEstimate
          in: query
          type: string
          description: "You can filter orders by shipping estimate time in days by concatenating the desired number of days\
            \ with the sufix `.days`. For example: \r"
        - name: f_invoicedDate
          in: query
          type: string
          description: "You can filter orders by invoiced date by concatenating the sufix `invoicedDate:` with the range date\
            \ in Timestamp format. For example: \r"
        - name: f_creationDate
          in: query
          type: string
          description: "You can filter orders by creation date by concatenating the sufix `creationDate:` with the range date\
            \ in Timestamp format. For example: \r"
        - name: f_authorizedDate
          in: query
          type: string
          description: "You can filter orders by creation date by concatenating the sufix `authorizedDate:` with the range\
            \ date in Timestamp format. For example: \r"
        - name: f_UtmSource
          in: query
          type: string
          description: You can filter orders by Urchin Tracking Module (UTM) source.
        - name: f_sellerNames
          in: query
          type: string
          description: You can filter orders by using a seller's name.
        - name: f_callCenterOperatorName
          in: query
          type: string
          description: You can filter orders by using a Call Center Operator's identification.
        - name: f_salesChannel
          in: query
          type: string
          description: You can filter orders by sales channel's ([or trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV))
            name.
        - name: salesChannelId
          in: query
          type: string
          description: You can filter orders by sales channel's ([or trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV))
            ID.
        - name: f_affiliateId
          in: query
          type: string
          description: You can filter orders by affiliate ID.
        - name: f_status
          in: query
          type: string
          description: "You can filter orders by the following [order status](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196):\
            \ \r"
        - name: incompleteOrders
          in: query
          type: boolean
          description: When set as `true`, you retrieve [incomplete orders](https://help.vtex.com/en/tutorial/understanding-incomplete-orders),
            when set as `false`, you retrieve order
        - name: f_paymentNames
          in: query
          type: string
          description: You can filter orders by payment type.
        - name: f_RnB
          in: query
          type: string
          description: You can filter orders by rates and benefits (promotions).
        - name: searchField
          in: query
          type: string
          description: "You can search orders by using one of the following criterias: \r"
        - name: f_isInstore
          in: query
          type: boolean
          description: When set as `true`, this parameter filters orders made via [inStore](https://help.vtex.com/en/tracks/what-is-instore--zav76TFEZlAjnyBVL5tRc),
            and when set as `f
    - name: api-oms-pvt-orders-orderId
      path: /api/oms/pvt/orders/{orderId}
      operations:
      - name: getorder
        method: GET
        description: VTex Get order
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
          required: true
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: orderId
          in: path
          type: string
          description: Order ID is a unique code that identifies an order. Instead of using `orderId`, you can also make the
            request using the sequence, a six-digit string that follow
          required: true
    - name: api-oms-pvt-orders-orderId-cancel
      path: /api/oms/pvt/orders/{orderId}/cancel
      operations:
      - name: cancelorder
        method: POST
        description: VTex Cancel order
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: Content-Type
          in: header
          type: string
          description: Describes the type of the content being sent.
          required: true
        - name: orderId
          in: path
          type: string
          description: ID that identifies the order in the seller.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-oms-pvt-orders-orderId-changes
      path: /api/oms/pvt/orders/{orderId}/changes
      operations:
      - name: registerchange
        method: POST
        description: VTex Register change on order
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
          required: true
        - name: orderId
          in: path
          type: string
          description: ID that identifies the order in the seller.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-oms-pvt-orders-orderId-interactions
      path: /api/oms/pvt/orders/{orderId}/interactions
      operations:
      - name: addlog
        method: POST
        description: VTex Add log in orders
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
          required: true
        - name: orderId
          in: path
          type: string
          description: Unique code that identifies an order.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-oms-pvt-orders-orderId-start-handling
      path: /api/oms/pvt/orders/{orderId}/start-handling
      operations:
      - name: starthandling
        method: POST
        description: VTex Start handling order
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
          required: true
        - name: Content-Type
          in: header
          type: string
          description: Type of the content being sent.
          required: true
        - name: orderId
          in: path
          type: string
          description: Order ID is a unique code that identifies an order.
          required: true
    authentication:
      type: apikey
      key: X-VTEX-API-AppKey
      value: '{{env.VTEX_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: orders-orders-rest
    port: 8080
    description: REST adapter for VTex Orders API — Orders. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/api/oms/pvt/orders
      name: api-oms-pvt-orders
      description: REST surface for api-oms-pvt-orders.
      operations:
      - method: GET
        name: listorders
        description: VTex List orders
        call: orders-orders.listorders
        with:
          Accept: rest.Accept
          Content-Type: rest.Content-Type
          orderBy: rest.orderBy
          page: rest.page
          per_page: rest.per_page
          f_hasInputInvoice: rest.f_hasInputInvoice
          q: rest.q
          f_shippingEstimate: rest.f_shippingEstimate
          f_invoicedDate: rest.f_invoicedDate
          f_creationDate: rest.f_creationDate
          f_authorizedDate: rest.f_authorizedDate
          f_UtmSource: rest.f_UtmSource
          f_sellerNames: rest.f_sellerNames
          f_callCenterOperatorName: rest.f_callCenterOperatorName
          f_salesChannel: rest.f_salesChannel
          salesChannelId: rest.salesChannelId
          f_affiliateId: rest.f_affiliateId
          f_status: rest.f_status
          incompleteOrders: rest.incompleteOrders
          f_paymentNames: rest.f_paymentNames
          f_RnB: rest.f_RnB
          searchField: rest.searchField
          f_isInstore: rest.f_isInstore
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/oms/pvt/orders/{orderid}
      name: api-oms-pvt-orders-orderid
      description: REST surface for api-oms-pvt-orders-orderId.
      operations:
      - method: GET
        name: getorder
        description: VTex Get order
        call: orders-orders.getorder
        with:
          Accept: rest.Accept
          Content-Type: rest.Content-Type
          orderId: rest.orderId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/oms/pvt/orders/{orderid}/cancel
      name: api-oms-pvt-orders-orderid-cancel
      description: REST surface for api-oms-pvt-orders-orderId-cancel.
      operations:
      - method: POST
        name: cancelorder
        description: VTex Cancel order
        call: orders-orders.cancelorder
        with:
          Accept: rest.Accept
          Content-Type: rest.Content-Type
          orderId: rest.orderId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/oms/pvt/orders/{orderid}/changes
      name: api-oms-pvt-orders-orderid-changes
      description: REST surface for api-oms-pvt-orders-orderId-changes.
      operations:
      - method: POST
        name: registerchange
        description: VTex Register change on order
        call: orders-orders.registerchange
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          orderId: rest.orderId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/oms/pvt/orders/{orderid}/interactions
      name: api-oms-pvt-orders-orderid-interactions
      description: REST surface for api-oms-pvt-orders-orderId-interactions.
      operations:
      - method: POST
        name: addlog
        description: VTex Add log in orders
        call: orders-orders.addlog
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          orderId: rest.orderId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/oms/pvt/orders/{orderid}/start-handling
      name: api-oms-pvt-orders-orderid-start-handling
      description: REST surface for api-oms-pvt-orders-orderId-start-handling.
      operations:
      - method: POST
        name: starthandling
        description: VTex Start handling order
        call: orders-orders.starthandling
        with:
          Accept: rest.Accept
          Content-Type: rest.Content-Type
          orderId: rest.orderId
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: orders-orders-mcp
    port: 9090
    transport: http
    description: MCP adapter for VTex Orders API — Orders. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: vtex-list-orders
      description: VTex List orders
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: orders-orders.listorders
      with:
        Accept: tools.Accept
        Content-Type: tools.Content-Type
        orderBy: tools.orderBy
        page: tools.page
        per_page: tools.per_page
        f_hasInputInvoice: tools.f_hasInputInvoice
        q: tools.q
        f_shippingEstimate: tools.f_shippingEstimate
        f_invoicedDate: tools.f_invoicedDate
        f_creationDate: tools.f_creationDate
        f_authorizedDate: tools.f_authorizedDate
        f_UtmSource: tools.f_UtmSource
        f_sellerNames: tools.f_sellerNames
        f_callCenterOperatorName: tools.f_callCenterOperatorName
        f_salesChannel: tools.f_salesChannel
        salesChannelId: tools.salesChannelId
        f_affiliateId: tools.f_affiliateId
        f_status: tools.f_status
        incompleteOrders: tools.incompleteOrders
        f_paymentNames: tools.f_paymentNames
        f_RnB: tools.f_RnB
        searchField: tools.searchField
        f_isInstore: tools.f_isInstore
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-order
      description: VTex Get order
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: orders-orders.getorder
      with:
        Accept: tools.Accept
        Content-Type: tools.Content-Type
        orderId: tools.orderId
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-cancel-order
      description: VTex Cancel order
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: orders-orders.cancelorder
      with:
        Accept: tools.Accept
        Content-Type: tools.Content-Type
        orderId: tools.orderId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-register-change-order
      description: VTex Register change on order
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: orders-orders.registerchange
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        orderId: tools.orderId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-add-log-orders
      description: VTex Add log in orders
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: orders-orders.addlog
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        orderId: tools.orderId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-start-handling-order
      description: VTex Start handling order
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: orders-orders.starthandling
      with:
        Accept: tools.Accept
        Content-Type: tools.Content-Type
        orderId: tools.orderId
      outputParameters:
      - type: object
        mapping: $.