VTEX Region API

openapi: 3.2.0
info:
  title: VTex Checkout Region API
  description: '>ℹ️ Check the new Checkout onboarding guide.'
  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: Region
paths:
  /api/checkout/pub/regions/{regionId}:
    get:
      tags:
      - Region
      summary: VTex Get sellers by region or address
      description: 'Retrieves a list of sellers that cater to a specific region or address, according to your setup of our regionalization feature. Learn more about Region v2.


        To access the list of sellers, you must choose one of the following methods:


        1. Send the identification of the list of sellers (`regionId`) as a path parameter through the URL. Or;

        2. Send the `country` (3-digit ISO code) and at least one of the two values (`postal Code` or `geo Coordinates`) as query parameters through the URL. For this method, it is also allowed to send both values (`postalCode` or `geoCoordinates`) in the same request.


        > The `regionId` and `country` parameters are indicated as required in this documentation. However, only one of them should be sent in the request according to one of the methods mentioned above.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:


        | **Product** | **Category** | **Resource** |

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

        | Checkout | CheckoutResources | **Shopping Cart Full Access** |


        There are no applicable predefined roles for this resource list. You must create a custom role and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see Authentication overview.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      operationId: GetSellersByRegion
      security: []
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: regionId
        in: path
        description: ID of the region corresponding to the shopper's location.
        required: true
        style: simple
        schema:
          type: string
          example: v2.1BB18CE648B5111D0933734ED83EC783
      - name: country
        in: query
        description: Three letter country code refering to the `postalCode` field.
        required: true
        style: form
        schema:
          type: string
          example: BRA
      - name: postalCode
        in: query
        description: Postal code corresponding to the shopper's location.
        required: false
        style: form
        schema:
          type: string
          example: '1234000'
      - name: geoCoordinates
        in: query
        description: Geocoordinates (first longitude, semicolon, then latitude) corresponding to the shopper's location.
        required: false
        style: form
        schema:
          type: array
          example:
          - -47.924747467041016
          - -15.832582473754883
          items:
            description: Geocoordinates.
            type: number
            example: -47.924747467041016
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Region ID.
                  sellers:
                    type: array
                    description: Array with information on each seller retrieved for the given region.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Seller ID.
                        name:
                          type: string
                          description: Seller name.
                        logo:
                          type:
                          - string
                          - 'null'
                          description: Seller logo.
              example:
                id: v2.1BB18CE648B5111D0933734ED83EC783
                sellers:
                - id: abacaba
                  name: Abacaba Store
                  logo: null
                - id: abacaba2
                  name: Abacaba VTEX Outlet
                  logo: null
                - id: abacaba3
                  name: Abacaba VTEX Mall
                  logo: null
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.'