VTEX Fulfillment API

openapi: 3.2.0
info:
  title: VTex Checkout Fulfillment API
  description: '>ℹ️ Check the new [Checkout onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/checkout-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about the Checkout and is organized by focusing on the developer''s journey.


    The Checkout API allows you to obtain and configure information about the shopping cart and its attachments, personalization of custom fields, orderForm structure, fulfillment data, order management, and identification of the sellers delivery region.


    >ℹ️ Data modification operations (`POST`, `PATCH`, `PUT` or `DELETE` endpoints) shall not be performed in parallel in the Checkout APIs. They need to be enqueued by the client/requester. Otherwise, old values ​​can be overwritten incorrectly or competition errors may occur.


    >⚠️ All endpoints that consult or edit the orderForm can change the authentication depending on the customer context. If you are handling information from a customer with a complete profile on the store, authentication will be required. You can only access or modify the customer data for these profiles with an authenticated request.


    ## Shopping cart


    Allows merchants to simulate, configure and customize shopping cart information.


    - [POST - Cart Simulation](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForms/simulation): simulate a cart in VTEX Checkout.

    - [GET - Get current or create a new cart](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orderForm): get your current shopping cart information or to create a new cart.

    - [GET - Get cart information by ID](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orderForm/-orderFormId-): get all information associated to a given shopping cart.

    - [POST - Add cart items](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/items): add a new item to the shopping cart.

    - [POST - Update cart items](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/items/update): change the quantity of one or more items in a specific cart or remove an item from the cart.

    - [PATCH - Handle cart items](https://developers.vtex.com/docs/api-reference/checkout-api#patch-/api/checkout/pub/orderForm/-orderFormId-/items): change the quantity or price of one or more items to the shopping cart or add a new item to the shopping cart.

    - [POST - Remove all items](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/items/removeAll): removes all items from a given cart, leaving it empty.

    - [PUT - Change price](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orderForm/-orderFormId-/items/-itemIndex-/price): changes the price of an SKU in a cart.

    - [GET - Cart installments](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orderForm/-orderFormId-/installments): retrieves possible amount of installments and respective values for a given cart with a given payment method.


    ## Cart attachments


    Allows merchants to obtain client profiles and add information to a given shopping cart.


    - [GET - Get client profile by email](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/profiles): retrieve a client''s profile information by providing an email address.

    - [POST - Add client profile](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/clientProfileData): include client profile information to a given shopping cart.

    - [Patch - Ignore profile data](https://developers.vtex.com/docs/api-reference/checkout-api#patch-/api/checkout/pub/orderForm/-orderFormId-/profile): disable the automatic inclusion of profile information in a shopping cart when a shopper provides an email address at checkout.

    - [GET - Remove all personal data](https://developers.vtex.com/docs/api-reference/checkout-api#get-/checkout/changeToAnonymousUser/-orderFormId-): removes all user information, making a cart anonymous while leaving the items.

    - [POST - Add client preferences](https://developers.vtex.com/docs/api-reference/checkout-api#patch-/api/checkout/pub/orderForm/-orderFormId-/items): include client preferences information to a given shopping cart.

    - [POST - Add shipping address and select delivery option](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/shippingData): include shipping information and/or selected delivery option to a given shopping cart.

    - [POST - Add marketing data](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/marketingData): include marketing information to a given shopping cart.

    - [POST - Add payment data](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/paymentData): include payment information to a given shopping cart.

    - [POST - Add merchant context data](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/merchantContextData): add to the cart any relevant information that is related to the context of a specific order.

    - [POST - Add coupons to the cart](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/coupons): add coupons to a given shopping cart.


    ## Custom data


    Allows merchants to manage custom fields that were created by an app in their account.


    - [PUT - Set multiple custom field values](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/coupons): allows you to update the values of custom fields created in your account''s apps.

    - [PUT - Set single custom field value](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orderForm/-orderFormId-/customData/-appId-/-appFieldName-): allows you to update the value of a specific custom field created in your account''s apps.

    - [DELETE - Remove single custom field value](https://developers.vtex.com/docs/api-reference/checkout-api#delete-/api/checkout/pub/orderForm/-orderFormId-/customData/-appId-/-appFieldName-): allows you to remove the value of a specific custom field created in your account''s apps.


    ## Configuration


    Allows merchants to configure orderForm in the account and seller exchange on a given order.


    - [GET - Get orderForm configuration](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pvt/configuration/orderForm): retrieves the settings that are currently applied to every [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) in the account.

    - [POST - Update orderForm configuration](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pvt/configuration/orderForm): determines settings that will apply to every [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) in the account.

    - [GET - Get window to change seller](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pvt/configuration/window-to-change-seller): retrieves a marketplace’s window to change seller.

    - [POST - Update window to change seller](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pvt/configuration/window-to-change-seller): updates a marketplace’s window to change seller.

    - [POST - Clear orderForm messages](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/messages/clear): removes all messages from the `messages` field of the [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields).


    ## Fulfillment


    Allows merchants to obtain pickup points and address information.


    - [GET - List pickup points by location](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/pickup-points): retrieves information on pickup points close to a given location determined by geocoordinates or postal code.

    - [GET - Get address by postal code](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/postal-code/-countryCode-/-postalCode-): retrieves address information for a given postal code and country.


    ## Order placement


    Allows merchants to place and process orders by creating a new cart or using an existing cart.


    - [POST - Place order from an existing cart](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/transaction): places an order from an existing [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) object, meaning an existing cart.

    - [PUT - Place order](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orders): places order without having any prior cart information.

    - [POST - Process order](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/gatewayCallback/-orderGroup-): order processing callback request, which is made after an order''s payment is approved.


    ## Region


    Allows merchants to obtain a list of sellers serving a specific delivery region.


    - [GET - Get sellers by region or address](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/regions/-regionId-)": retrieves a list of sellers that cater to a specific region or address.


    ## Common parameters in the documentation


    | Parameter name            | Description                                                                             |

    |---------------------------|-----------------------------------------------------------------------------------------|

    | `{{accountName}}`         | Store account name                                                                      |

    | `{{environment}}`         | The environment that will be called. Change for vtexcommercestable or vtexcommmercebeta |

    | `{{X-VTEX-API-AppKey}}`   | Located in the headers of the requests, user authentication key                         |

    | `{{X-VTEX-API-AppToken}}` | Located in the headers of the requests, authentication password                         |

    '
  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: []
  appToken: []
- VtexIdclientAutCookie: []
tags:
- name: Fulfillment
paths:
  /api/checkout/pub/pickup-points:
    get:
      tags:
      - Fulfillment
      summary: VTex List pickup points by location
      description: 'Retrieves information on pickup points close to a given location determined by geocoordinates or postal code.


        The pickup points returned are not necessarily all active ones. Make sure to validate the information consumed by integrations.


        ## Permissions


        This endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).'
      operationId: ListPickupPpointsByLocation
      security: []
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: geoCoordinates
        in: query
        description: Geocoordinates (first longitude, then latitude) around which to search for pickup points. If you use this type of search, do not pass postal and country codes.
        required: false
        style: form
        schema:
          type: array
          example:
          - -47.924747467041016
          - -15.832582473754883
          items:
            description: Geocoordinate.
            type: number
            example: -47.924747467041016
      - name: postalCode
        in: query
        description: Postal code around which to search for pickup points. If you use this type of search, make sure to pass a `countryCode` and do not pass `geoCoordinates`.
        required: false
        style: form
        schema:
          type: string
          example: '1234000'
      - name: countryCode
        in: query
        description: Three letter country code refering to the `postalCode` field. Pass the country code only if you are searching pickup points by postal code.
        required: false
        style: form
        schema:
          type: string
          example: BRA
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                paging:
                  page: 1
                  pageSize: 30
                  total: 1
                  pages: 1
                items:
                - distance: 0.8469786518616546
                  pickupPoint:
                    friendlyName: physical-store-02
                    address:
                      addressType: pickup
                      receiverName: null
                      addressId: physical-store-02
                      isDisposable: true
                      postalCode: 23450-070
                      city: Rio de Janeiro
                      state: RJ
                      country: BRA
                      street: Praia de Botafogo
                      number: '132'
                      neighborhood: Botafogo
                      complement: Apto 101
                      reference: null
                      geoCoordinates:
                      - -47.924747467041016
                      - -15.832582473754883
                    additionalInfo: null
                    id: 02_Physical
                    businessHours:
                    - DayOfWeek: 0
                      OpeningTime: 00:00:00
                      ClosingTime: '23:59:00'
                    - DayOfWeek: 1
                      OpeningTime: 00:00:00
                      ClosingTime: '23:59:00'
                    - DayOfWeek: 2
                      OpeningTime: 00:00:00
                      ClosingTime: '23:59:00'
                    - DayOfWeek: 3
                      OpeningTime: 00:00:00
                      ClosingTime: '23:59:00'
                    - DayOfWeek: 4
                      OpeningTime: 00:00:00
                      ClosingTime: '23:50:00'
                    - DayOfWeek: 5
                      OpeningTime: 00:00:00
                      ClosingTime: '23:59:00'
                    - DayOfWeek: 6
                      OpeningTime: 00:00:00
                      ClosingTime: '23:59:00'
              schema:
                type: object
                properties:
                  paging:
                    description: Paging.
                    type: object
                    properties:
                      page:
                        description: Page number.
                        type: integer
                      pageSize:
                        description: Page size.
                        type: integer
                      total:
                        description: Total pages.
                        type: integer
                      pages:
                        description: Pages.
                        type: integer
                  items:
                    description: Items.
                    type: array
                    items:
                      description: Item information.
                      type: object
                      properties:
                        distance:
                          description: Distance.
                          type: integer
                        pickupPoint:
                          description: Pickup point.
                          type: object
                          properties:
                            friendlyName:
                              description: Friendly name.
                              type: string
                            address:
                              description: Address.
                              type: object
                              properties:
                                addressType:
                                  description: Address type.
                                  type: string
                                receiverName:
                                  description: Receiver name.
                                  type: string
                                addressId:
                                  description: Address ID.
                                  type:
                                  - string
                                  - 'null'
                                isDisposable:
                                  description: Is disposable.
                                  type: boolean
                                postalCode:
                                  description: Postal code.
                                  type: string
                                city:
                                  description: City.
                                  type: string
                                state:
                                  description: State.
                                  type: string
                                country:
                                  description: Country.
                                  type: string
                                street:
                                  description: Street.
                                  type: string
                                number:
                                  description: Number.
                                  type: string
                                neighborhood:
                                  description: Neighborhood.
                                  type: string
                                complement:
                                  description: Complement.
                                  type: string
                                reference:
                                  description: Racao.
                                  type: string
                                geoCoordinates:
                                  description: Geo coordinates.
                                  type: array
                                  items:
                                    description: Geo coordinate.
                                    type: integer
                            additionalInfo:
                              description: Additional info.
                              type: string
                            id:
                              description: ID.
                              type: string
                            businessHours:
                              description: Array with business hours.
                              type: array
                              items:
                                description: Business hours.
                                type: object
                                properties:
                                  DayOfWeek:
                                    description: Day of week.
                                    type: integer
                                  OpeningTime:
                                    description: Opening time.
                                    type: string
                                  ClosingTime:
                                    description: Closing time.
                                    type: string
  /api/checkout/pub/postal-code/{countryCode}/{postalCode}:
    get:
      tags:
      - Fulfillment
      summary: VTex Get address by postal code
      description: 'Retrieves address information for a given postal code and country.


        This request can be used to implement auto complete functionality when a customer needs to fill in an address.


        ## Permissions


        This endpoint does not require [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).'
      operationId: GetAddressByPostalCode
      security: []
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: countryCode
        in: path
        description: Three letter country code refering to the `postalCode` field.
        required: true
        style: simple
        schema:
          type: string
          example: BRA
      - name: postalCode
        in: path
        description: Postal code.
        required: true
        style: simple
        schema:
          type: string
          example: '1234000'
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                postalCode: '12345000'
                city: Rio de Janeiro
                state: RJ
                country: BRA
                street: My street
                number: '34'
                neighborhood: My neighborhood
                complement: Apto 101
                reference: Reference
                geoCoordinates: []
              schema:
                description: Address.
                type: object
                properties:
                  postalCode:
                    description: Postal code.
                    type: string
                  city:
                    description: City.
                    type: string
                  state:
                    description: State.
                    type: string
                  country:
                    description: Country.
                    type: string
                  street:
                    description: Street.
                    type: string
                  number:
                    description: Number.
                    type: string
                  neighborhood:
                    description: Neighborhood.
                    type: string
                  complement:
                    description: Complement.
                    type: string
                  reference:
                    description: Reference.
                    type: string
                  geoCoordinates:
                    description: Geo coordinates.
                    type: array
                    items:
                      description: Geo coordinate.
                      type: integer
components:
  parameters:
    Accept:
      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
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
      description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
      description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    VtexIdclientAutCookie:
      type: apiKey
      in: header
      name: VtexIdclientAutCookie
      description: '[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.'