VTEX Order Hook API

openapi: 3.2.0
info:
  title: VTex Orders Order Hook API
  description: 'Each purchase a customer makes in your store generates an [order](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196) on VTEX. With the Orders API, you can view orders statuses and manage multiple aspects involved in order fulfillment, such as financial transactions, invoicing, shipping, and subscriptions. You can also [change orders](https://help.vtex.com/en/tutorial/changing-items-from-a-complete-order--tutorials_190) and make configurations to allow or forbid marketplaces and sellers to change or cancel orders.


    ### Order integration


    To automate actions related to order processing, you can [integrate orders](https://developers.vtex.com/docs/guides/erp-integration-guide) with systems like ERP (Enterprise Resource Planning) and WMS (Warehouse Management System) using [Feed and Hook](https://developers.vtex.com/docs/guides/orders-feed).


    ## Orders API Index


    ### Orders


    - `GET` [Get order](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders/-orderId-)

    - `GET` [List orders](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders)

    - `POST` [Start handling order](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/start-handling)

    - `POST` [Cancel order](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/cancel)

    - `POST` [Register change on order](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/changes)


    ### Invoice


    - `POST` [Order invoice notification](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/invoice)

    - `PATCH` [Update order''s partial invoice (send tracking number)](https://developers.vtex.com/docs/api-reference/orders-api#patch-/api/oms/pvt/orders/-orderId-/invoice/-invoiceNumber-)


    ### Tracking


    - `PUT` [Update order tracking status](https://developers.vtex.com/docs/api-reference/orders-api#put-/api/oms/pvt/orders/-orderId-/invoice/-invoiceNumber-/tracking)


    ### Conversation


    - `GET` [Retrieve order conversation](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders/-orderId-/conversation-message)


    ### Payment


    - `GET` [Retrieve payment transaction](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/orders/-orderId-/payment-transaction)

    - `POST` [Send payment notification](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/oms/pvt/orders/-orderId-/payments/-paymentId-/payment-notification)


    ### Feed v2 (deprecated)


    - `GET` [Get feed order status](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/pvt/feed/orders/status)


    ### Feed v3


    - `GET` [Get feed configuration](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/orders/feed/config)

    - `POST` [Create or update feed configuration](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/feed/config)

    - `DELETE` [Delete feed configuration](https://developers.vtex.com/docs/api-reference/orders-api#delete-/api/orders/feed/config)

    - `GET` [Retrieve feed items](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/orders/feed)

    - `POST` [Commit feed items](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/feed)

    - `POST` [Test JSONata expression](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/expressions/jsonata)


    ### Order hook


    - `GET` [Get hook configuration](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/orders/hook/config)

    - `POST` [Create or update hook configuration](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/hook/config)

    - `DELETE` [Delete hook configuration](https://developers.vtex.com/docs/api-reference/orders-api#delete-/api/orders/hook/config)


    ### User orders


    - `GET` [Retrieve user''s orders](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/user/orders)

    - `GET` [Retrieve user order details](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/oms/user/orders/-orderId-)


    ### Change seller


    - `GET` [Get window to change seller](https://developers.vtex.com/docs/api-reference/orders-api#get-/api/checkout/pvt/configuration/window-to-change-seller)

    - `POST` [Update window to change seller](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/checkout/pvt/configuration/window-to-change-seller)'
  contact: {}
  version: '1.0'
servers:
- url: https://{accountName}.{environment}.com.br
  description: VTEX server URL.
  variables:
    accountName:
      description: Name of the VTEX account. Used as part of the URL.
      default: apiexamples
    environment:
      description: Environment to use. Used as part of the URL.
      enum:
      - vtexcommercestable
      default: vtexcommercestable
security:
- appKey:
  - '{{appKey}}'
  appToken:
  - '{{appToken}}'
tags:
- name: Order Hook
paths:
  /api/orders/hook/config:
    get:
      tags:
      - Order Hook
      summary: VTex Get hook configuration
      description: "Retrieves a given hook's configuration details. Learn more with the [orders hook guide](https://developers.vtex.com/vtex-rest-api/docs/orders-feed#hook). \n\n> \U0001F4D8 Onboarding guide \n>\n> Check the new [Orders onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/orders-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Orders and is organized by focusing on the developer's journey.\n\n"
      operationId: GetHookConfiguration
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: Accept
        in: header
        description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: clientEmail
        in: query
        description: Customer email.
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: customer@mail.com
      - name: page
        in: query
        description: Page number for result pagination.
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: '10'
      - name: per_page
        in: query
        description: Page quantity for result pagination.
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: '15'
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
    post:
      tags:
      - Order Hook
      summary: VTex Create or update hook configuration
      description: "Configures filtering rules applied to orders hook. Learn more with the [orders hook guide](https://developers.vtex.com/vtex-rest-api/docs/orders-feed#hook).\n\nThere are two types of filtering that can be used: \n\n - `FromWorkflow`: filters orders by status.\n\n - `FromOrders`: uses JSONata expressions to filter orders according to any property in the orders JSON document.\n\n This enables stores to filter delivered orders and orders in which products have been added or removed, for example.\n\nTo learn more, access the [JSONata documentation](https://docs.jsonata.org/overview.html) and test filtering JSONata expressions with our [expressions API](https://developers.vtex.com/docs/api-reference/orders-api#post-/api/orders/expressions/jsonata)."
      operationId: HookConfiguration
      parameters:
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: Accept
        in: header
        description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HookConfigurationRequest'
            example:
              filter:
                type: FromOrders
                expression: value > 100
                disableSingleFire: false
              hook:
                url: https://endpoint.example/path
                headers:
                  key: value
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HookConfiguration'
              example:
                Domain: Fulfillment
                OrderId: v52277740atmc-01
                State: ready-for-handling
                LastState: window-to-cancel
                LastChange: '2019-08-14T17:11:39.2550122Z'
                CurrentChange: '2019-08-14T17:12:48.0965893Z'
                Origin:
                  Account: automacaoqa
                  Key: vtexappkey-appvtex
      deprecated: false
    delete:
      tags:
      - Order Hook
      summary: VTex Delete hook configuration
      description: 'Deletes a given hook configuration.


        Learn more with the [orders hook guide](https://developers.vtex.com/vtex-rest-api/docs/orders-feed#hook).'
      operationId: DeleteHookConfiguration
      parameters:
      - name: Accept
        in: header
        description: HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: Content-Type
        in: header
        description: Type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      responses:
        '200':
          description: Success
        '403':
          description: The credentials are not enabled to access the service
        '404':
          description: Value not found
        '429':
          description: Too many requests
      deprecated: false
components:
  schemas:
    Headers:
      title: Headers
      required:
      - key
      type: object
      properties:
        key:
          type: string
      example:
        key: value
    HookFilter:
      title: Filter
      required:
      - type
      type: object
      properties:
        type:
          type: string
          description: "Determines what orders appear in the hook and how they are filtered. As shown in the examples above, there are two ways:\n\n - `FromWorkflow`: the hook will receive order updates only when there is a change or update in the [order status](https://help.vtex.com/en/tutorial/order-flow-and-status--tutorials_196). You must send at least one value for the `status` field to determine by which status the orders will be filtered.\n\n - `FromOrders`: the hook will receive order updates when there is a change in the order. In this case, orders can be filtered by any property, according to JSONata expressions passed in the `expression` field. You must send the request with values for the `expression` and `disableSingleFire` fields."
          example: FromWorkflow
        status:
          type: array
          items:
            type: string
          description: List of order statuses that should be included in the hook. This should only be used in case `type` is `FromWorkflow`.
        expression:
          type: string
          description: JSONata query expression that defines what conditions must be met for an order to be included in the hook. This should only be used in case `type` is `FromOrders`.
        disableSingleFire:
          type: boolean
          description: Sets a limit to how many times a specific order shows on the hook, after it first meets filtering conditions. Using the `FromOrders` type configuration with JSONata filtering expressions might cause orders to appear more than once on a feed, whenever changes are made to that order. If this field is `false` orders will appear in the hook only once. Send this field if you want to filter `FromOrders`.
          example: false
    HookConfiguration:
      title: HookConfiguration
      required:
      - Domain
      - OrderId
      - State
      - LastState
      - LastChange
      - CurrentChange
      - Origin
      type: object
      properties:
        Domain:
          type: string
        OrderId:
          type: string
        State:
          type: string
        LastState:
          type: string
        LastChange:
          type: string
        CurrentChange:
          type: string
        Origin:
          $ref: '#/components/schemas/Origin2'
      example:
        Domain: Fulfillment
        OrderId: v52277740atmc-01
        State: ready-for-handling
        LastState: window-to-cancel
        LastChange: '2019-08-14T17:11:39.2550122Z'
        CurrentChange: '2019-08-14T17:12:48.0965893Z'
        Origin:
          Account: automacaoqa
          Key: vtexappkey-appvtex
    HookConfigurationRequest:
      title: HookConfigurationRequest
      required:
      - filter
      - hook
      type: object
      properties:
        filter:
          $ref: '#/components/schemas/HookFilter'
        hook:
          $ref: '#/components/schemas/Hook'
      example:
        filter:
          type: FromWorkflow
          status:
          - order-completed
          - handling
          - ready-for-handling
          - waiting-ffmt-authorization
          - cancel
        hook:
          url: https://endpoint.example/path
          headers:
            key: value
    Hook:
      title: Hook
      required:
      - url
      - headers
      type: object
      properties:
        url:
          type: string
        headers:
          $ref: '#/components/schemas/Headers'
      example:
        url: https://endpoint.example/path
        headers:
          key: value
    Origin2:
      title: Origin2
      required:
      - Account
      - Key
      type: object
      properties:
        Account:
          type: string
        Key:
          type: string
      example:
        Account: automacaoqa
        Key: vtexappkey-appvtex
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken