VTEX Sellers API

openapi: 3.2.0
info:
  title: VTex Marketplace Sellers API
  description: "The **Marketplace API** enables marketplaces and sellers hosted on VTEX to perform their collaborative operations.  \n\n>⚠️ The marketplace must [create an appKey and appToken](https://developers.vtex.com/docs/guides/getting-started-authentication) for each non-VTEX seller that will use this API.\n\n## Index\n\n### Notification\n\nEndpoints used by sellers to notify marketplaces that the price or inventory language has changed for one of their SKUs.\n\n`POST` [Notify marketplace of price update](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/price)\n\n`POST` [Notify marketplace of inventory update](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/inventory)\n\n\n### Suggestions\n\n#### Get Suggestions\n\nSearch and filter all suggestions using specific criteria.\n\n`GET` [Get all SKU Suggestions](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions)\n\n`GET` [Get SKU Suggestion by ID](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerSkuId-)\n\n\n#### Manage Suggestions\n\nSend or delete SKU suggestions from the seller to marketplace.\n\n`PUT` [Send SKU Suggestion](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/-sellerId-/-sellerSkuId-)\n\n`DELETE` [Delete SKU Suggestion](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#delete-/suggestions/-sellerId-/-sellerSkuId-)\n\n\n#### Get Versions\n\nSearch and filter all versions of suggestions, using specific criteria.\n\n`GET` [Get all versions](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerskuid-/versions)\n\n`GET` [Get version by ID](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerskuid-/versions/-version-)\n\n\n#### Match Received SKUs\n\nMatch SKU suggestions received in the marketplace.\n\n`PUT` [Match Received SKUs individually](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/-sellerId-/-sellerskuid-/versions/-version-/matches/-matchid-)\n\n`PUT` [Match Multiple Received SKUs](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/matches/action/-actionName-)\n\n\n#### SKU Approval Settings\n\nAllows marketplaces to configure rules for automatically and manually approving SKUs received from sellers.\n\n`GET`[Get autoApprove Status in Account Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration/autoapproval/toggle)  \n\n`PUT`[Activate autoApprove in Marketplace's Account](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/autoapproval/toggle)  \n\n`GET`[Get Account's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration)\n\n`PUT`[Save Account's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration)\n\n`GET`[Get Seller's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration/seller/-sellerId-)\n\n`PUT`[Save Seller's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/seller/-sellerId-)\n\n`PUT`[Activate autoApprove Setting for a Seller](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/autoapproval/toggle/seller/-sellerId-)   \n\n\n### Matched Offers\n\nOffers are seller products and SKUs that were sent to the marketplace, and already have their price and inventory level configured.\n\n`GET`[Get Matched Offers List](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/offers)\n\n`GET`[Get Matched Offer's Data by SKU ID](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/product/-productId-/sku/-skuId-)  \n\n`GET`[Get Matched Offer's Data by Product ID](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/product/-productId-)\n"
  version: '1.0'
servers:
- url: https://{accountName}.{environment}.com.br/api
  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: []
tags:
- name: Sellers
paths:
  /seller-register/pvt/sellers:
    post:
      tags:
      - Sellers
      summary: VTex Configure Seller Account
      description: "This endpoint is used by marketplace operators to configure the accounts of sellers that have already accepted the invitation to join their marketplaces. \n\nFor marketplaces to [add sellers](https://help.vtex.com/en/tutorial/adding-a-seller--tutorials_392) without the [Seller Invite](https://help.vtex.com/en/tutorial/marketplace-invited-sellers--6rb2FkcslmDueJ689Ulb9A) feature, call this endpoint directly. \n\nThis call includes all the information a seller needs to activate their account."
      operationId: UpsertSellerRequest
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/contentType'
      requestBody:
        description: Request to upsert seller information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertSellerRequest'
        required: true
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
    get:
      tags:
      - Sellers
      summary: VTex List Sellers
      description: This endpoint lists all Sellers. This call's results can be filtered by [trade policies](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data) through the `sc` query param.
      operationId: GetListSellers
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/from'
      - $ref: '#/components/parameters/to'
      - $ref: '#/components/parameters/keyword'
      - $ref: '#/components/parameters/integration'
      - $ref: '#/components/parameters/group'
      - $ref: '#/components/parameters/isActive'
      - $ref: '#/components/parameters/isBetterScope'
      - $ref: '#/components/parameters/isVtex'
      - $ref: '#/components/parameters/sc'
      - $ref: '#/components/parameters/sellerType'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/contentType'
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
  /seller-register/pvt/sellers/{sellerId}:
    patch:
      tags:
      - Sellers
      summary: VTex Update Seller by Seller ID
      description: This endpoint allows marketplace operators to update the information of sellers connected to their account. You can replace a path's value with another value in order to update that single information. There is no need to fill all the body params available, only the one you wish to update.
      operationId: UpdateSeller
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/contentType'
      - $ref: '#/components/parameters/sellerId'
      requestBody:
        description: array of objects
        content:
          application/json:
            schema:
              type: array
              description: array of objects
              title: Request body
              items:
                type: object
                required:
                - operation
                - path
                - value
                properties:
                  operation:
                    type: string
                    description: The action being performed, which is always going to be `replace`.
                    default: replace
                  path:
                    type: string
                    default: /field
                    description: The path in which the value is being updated. It follows the standardized format `/{field}`, where `{field}` is the path's name.
                  value:
                    type: boolean
                    default: false
                    description: The value that is being updated. Notice that the type will depend on the path that is being updated.
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
    get:
      tags:
      - Sellers
      summary: VTex Get Seller data by ID
      operationId: GetRetrieveSeller
      description: Marketplace operator may call this endpoint to retrieve information about a specific seller by filtering by ID. It is also possible to filter results by sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) through the `sc` query param.
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/sc'
      - $ref: '#/components/parameters/sellerId'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/contentType'
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
components:
  parameters:
    environment:
      name: environment
      in: path
      required: true
      description: Environment to use. Used as part of the URL.
      schema:
        type: string
        default: vtexcommercestable
    isVtex:
      name: isVtex
      in: query
      description: When set as `true`, the list returned will be of sellers who have a VTEX store configured. When set as `false`, the list will be of sellers who do not have a VTEX store configured.
      required: false
      schema:
        type: boolean
        default: false
    sellerId:
      name: sellerId
      in: path
      description: A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.
      required: true
      style: simple
      schema:
        type: string
        example: seller123
    accountName:
      name: accountName
      in: path
      required: true
      description: Name of the VTEX account that belongs to the marketplace. The notification will be posted into this account.
      schema:
        type: string
        example: apiexamples
    keyword:
      name: keyword
      in: query
      description: Search sellers by a keyword in `sellerId` or `sellerName`.
      required: false
      schema:
        type: string
        default: keyword
    isActive:
      name: isActive
      in: query
      description: Enables to filter sellers that are active (`true`) or unactive (`false`) in the marketplace.
      required: false
      schema:
        type: boolean
        default: false
    sellerType:
      name: sellerType
      in: query
      description: Filters sellers by their type, which can be regular seller (`1`) or whitelabel seller (`2`).
      required: false
      schema:
        type: integer
        default: 1
    sort:
      name: sort
      in: query
      description: "Criteria used to sort the list of offers. For sorting values in ascending order, use `asc`, while for descending order, use `desc`. To fill in the field, insert the sorting criteria, followed by 'asc', or 'desc', separated by a comma. You can sort by the following criteria: \n\n- **price:** sorts offers by price. *Ascending* goes from lowest to highest price, while *Descending* goes from highest to lowest price. \n\n- **name:** sorts offers by *productName*, in alphabetical order. *Ascending* goes from *A* to *Z*, while *Descending* goes from *Z* to *A*. \n\n- **availability:** availability in the sales channel (sc). The default value is 1. \n\nEx. sort=availability,desc \n\nEx. sort=name,asc \n\nEx. price,desc"
      required: false
      style: form
      explode: true
      schema:
        type: string
        example: availability,desc
    sc:
      name: sc
      in: query
      description: Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) associated to the seller account created.
      required: false
      style: form
      explode: true
      schema:
        type: string
        default: '1'
    contentType:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
    to:
      name: to
      in: query
      description: The end number of pagination, being `100` the default value.
      required: false
      schema:
        type: number
        default: 100
    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
    from:
      name: from
      in: query
      description: The start number of pagination, being `0` the default value.
      required: false
      schema:
        type: number
        default: 0
    group:
      name: 'group '
      in: query
      description: Groups are defined by keywords that group sellers into categories defined by the marketplace.
      required: false
      schema:
        type: string
        default: Group
    integration:
      name: integration
      in: query
      description: 'Filters sellers by the name of who made the integration, if VTEX or an external hub. The possible values for VTEX integrations are: `vtex-sellerportal`, `vtex-seller` and `vtex-franchise`.'
      required: false
      schema:
        type: string
        default: vtex-seller
    isBetterScope:
      name: isBetterScope
      in: query
      description: The flag `isBetterScope` is used by the VTEX Checkout to simulate shopping carts, products, and shipping only in sellers with the field set as `true`, avoiding performance issues. When used as a query param, `isBetterScope` filters sellers that have the flag set as `true` or `false`.
      required: false
      schema:
        type: boolean
        default: false
  schemas:
    UpsertSellerRequest:
      title: Configure Seller Account
      required:
      - id
      - name
      - isActive
      - fulfillmentEndpoint
      - allowHybridPayments
      - taxCode
      - email
      - description
      - sellerCommissionConfiguration
      - isBetterScope
      - sellerType
      - availableSalesChannels
      - CSCIdentification
      - account
      - channel
      - salesChannel
      - isVtex
      - score
      - exchangeReturnPolicy
      - deliveryPolicy
      - securityPrivacyPolicy
      - fulfillmentSellerId
      - user
      - password
      - catalogSystemEndpoint
      - trustPolicy
      type: object
      properties:
        id:
          type: string
          description: Seller ID assigned by the marketplace. We recommend filling it in with the seller's account name.
          default: seller123
        name:
          type: string
          description: Name of the seller's store, configured in the seller's environment.
          default: Seller Name
        isActive:
          type: boolean
          description: Whether the seller is active on the marketplace or not.
          default: true
        fulfillmentEndpoint:
          type: string
          description: "URL of the endpoint for fulfillment of seller's orders, which the marketplace will use to communicate with the seller. \n\nFor **external sellers**, please include the URL of the seller's endpoint. External sellers have different endpoint standards. The seller must inform this endpoint to the marketplace so that the marketplace can complete the configuration process. \n\nFor **VTEX Stores**, the field format will be as follows: `https://{SellerName}.vtexcommercestable.com.br/api/fulfillment?&sc={TradePolicyID}`. \n\nThe value `SellerName` corresponds to the store name if the seller is a VTEX store. \n\nThe value `TradePolicyID` corresponds to the [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV#master-data) created by the seller in their own VTEX environment. The seller must inform this ID to the marketplace so that the marketplace can complete the configuration process. \n\nThe value `AffiliateID` corresponds to the 3-digit affiliate identification code created by the seller. The seller must inform this ID to the marketplace so that the marketplace can complete the configuration process. \n\nTo configure the [Multilevel Omnichannel Inventory](https://developers.vtex.com/vtex-rest-api/docs/multilevel-omnichannel-inventory) feature, fill in this field with the checkout endpoint following this example: `https://{{sellerAccount}}.vtexcommercestable.com.br/api/checkout?affiliateid={{affiliateId}}&sc={{salesChannel`"
          default: http://{SellerName}.vtexcommercestable.com.br/api/fulfillment?&sc={TradePolicyID}
        allowHybridPayments:
          type: boolean
          description: Flag that allows customers to use gift cards from the seller to buy their products on the marketplace. It identifies purchases made with a gift card so that only the final price (with discounts applied) is paid to the seller.
          default: false
        taxCode:
          type: string
          description: This code is the Identity Number for the legal entity and is linked to information in its base country.
          default: '34444'
        email:
          type: string
          description: email of the admin responsible for the seller.
          default: seller@email.com
        description:
          type: string
          description: String describing the seller
          default: Seller A, from the B industry.
        sellerCommissionConfiguration:
          type: object
          items:
            $ref: '#/components/schemas/SellerCommissionConfiguration'
        isBetterScope:
          type: boolean
          description: Flag used by the VTEX Checkout to simmulate shopping carts, products and shipping only in sellers with the boolean set as `true`, avoiding performance issues.
          default: true
        sellerType:
          type: integer
          description: "Type of seller, including: \n\n`1`: regular seller \n\n`2`: whitelabel seller"
          default: 1
        availableSalesChannels:
          type: array
          items:
            $ref: '#/components/schemas/AvailableSalesChannel'
          description: Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) available.
          default: []
        CSCIdentification:
          type: string
          description: SKU Seller Identification
          default: cscidentification 123
        account:
          type: string
          description: Seller's account name
          default: partner01
        channel:
          type: string
          description: Channel's name.
          default: channel name
        salesChannel:
          type: string
          description: Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) associated to the seller account created. If no value is specified, the system will automatically use the sales channel configured in the seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) ID.
          default: '1'
        isVtex:
          type: boolean
          description: Flag determining whether the seller configured is a VTEX store or not.
          default: true
        exchangeReturnPolicy:
          type: string
          description: Text describing the exchange and return policy previously agreed between the marketplace and the seller.
          default: Describe exchange and returns policy
        deliveryPolicy:
          type: string
          description: Text describing the delivery policy previously agreed between the marketplace and the seller.
          default: Describe delivery policy
        securityPrivacyPolicy:
          type:
          - string
          - 'null'
          description: ' Text describing the security policy previously agreed between the marketplace and the seller.'
          default: Describe privacy and security policy
        fulfillmentSellerId:
          type: string
          description: ' Identification code of the seller responsible for fulfilling the order. This is an optional field used when a seller sells SKUs from another seller. If the seller sells their own SKUs, it must be nulled.'
          default: seller1
        groups:
          type: array
          items:
            $ref: '#/components/schemas/Groups'
          description: Array of groups attached to the seller. Groups are defined by key-words that group sellers into categories defined by the marketplace when adding a new seller through the [Configure Seller Account](https://developers.vtex.com/vtex-rest-api/reference/sellers#putupsertseller) endpoint. It is possible to filter sellers by group in the Seller Management page in your VTEX Admin. Know more about groups through our [Seller Management](https://help.vtex.com/en/tutorial/gerenciamento-de-sellers-beta--6eEiOISwxuAWJ8w6MtK7iv#groups) documentation.
        user:
          type:
          - string
          - 'null'
          title: user
          description: Username, if you are using a hub to integrate with the external seller.
          default: integrationHubUserName
        password:
          type:
          - string
          - 'null'
          title: password
          description: User password, if you are using a hub to integrate with the external seller.
          default: integrationHubPassword
        catalogSystemEndpoint:
          type: string
          title: Catalog System Endpoint schema
          description: 'URL of the endpoint of the seller''s catalog. This field will only be displayed if the seller type is VTEX Store. The field format will be as follows: `https://{sellerName}.vtexcommercestable.com.br/api/catalog_system/.`'
          default: https://pedrostore.vtexcommercestable.com.br/api/catalog_system/
        trustPolicy:
          type: string
          title: Trust Policy
          description: ' the marketplace must first allow VTEX to share clients’ email addresses with the seller. To do so, it is necessary to set ''AllowEmailSharing'' as the value for the TrustPolicy field'
          default: AllowEmailSharing
        score:
          type: number
          title: Score
          description: Score attributed to this seller.
          default: 0
      example:
        id: testeMARCUS123
        name: qamarketplace
        isActive: true
        fulfillmentEndpoint: http://fulfillment.vtexcommerce.com.br/api/fulfillment?an=parceiro01
        allowHybridPayments: false
        trustPolicy: AllowEmailSharing
        user: integrationHubUserName
        password: integrationHubPassword
        taxCode: '34444'
        email: vtexqa1@vtex.com.br
        description: Seller A, from the B industry.
        sellerCommissionConfiguration:
          productCommissionPercentage: 3
          freightCommissionPercentage: 4
          categoriesCommissionConfiguration: []
        isBetterScope: false
        sellerType: 1
        availableSalesChannels:
        - isSelected: true
          id: 1
          name: Loja Principal
        - isSelected: true
          id: 2
          name: Terceira
        - isSelected: true
          id: 3
          name: Marketplaces
        CSCIdentification: SampleCSCIdentification123
        account: parceiro01
        channel: SampleChannel
        salesChannel: SampleSalesChannel
        isVtex: true
        score: 0
        exchangeReturnPolicy: '1'
        deliveryPolicy: '3'
        securityPrivacyPolicy: null
        catalogSystemEndpoint: https://pedrostore.vtexcommercestable.com.br/api/catalog_system/
        fulfillmentSellerId: seller1
        groups:
        - groups:
          - id: 8d845239bf1448dc8bc3ed3121837511
            name: long tail
          - id: b9bcd348ab9c4cec8285ff9485c27a72
            name: franchise accounts
    AvailableSalesChannel:
      title: Available Sales Channel
      required:
      - isSelected
      - id
      - name
      type: object
      properties:
        isSelected:
          type: boolean
          description: Flag defining if the sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) is selected or not.
          default: true
        id:
          type: integer
          description: Sales Channel's ID.
          default: 1
        name:
          type: string
          description: Name of the Sales Channel.
          default: Main Store
      example:
        isSelected: true
        id: 1
        name: Loja Principal
    SellerCommissionConfiguration:
      title: Seller Commission Configuration
      required:
      - productCommissionPercentage
      - freightCommissionPercentage
      - categoriesCommissionConfiguration
      type: object
      properties:
        productCommissionPercentage:
          type: number
          description: Percentage of the comission applied to the product in decimals.
          default: 9.85
        freightCommissionPercentage:
          type: number
          description: Percentage of the comission applied to the freight in decimals.
          default: 2.43
        categoriesCommissionConfiguration:
          type: array
          items:
            type: string
          description: Array with percentage of the comission applied to categories in decimals.
          default: []
      example:
        productCommissionPercentage: 3
        freightCommissionPercentage: 4
        categoriesCommissionConfiguration: []
    Groups:
      title: groups
      description: Array of groups attached to the seller. Groups are defined by key-words that group sellers into categories defined by the marketplace when adding a new seller through the [Configure Seller Account](https://developers.vtex.com/vtex-rest-api/reference/sellers#putupsertseller) endpoint. It is possible to filter sellers by group in the Seller Management page in your VTEX Admin. Know more about groups through our [Seller Management](https://help.vtex.com/en/tutorial/gerenciamento-de-sellers-beta--6eEiOISwxuAWJ8w6MtK7iv#groups) documentation.
      required:
      - groups
      type: object
      properties:
        id:
          type: string
          description: Group's unique identifier code.
          default: 8d845239bf1448dc8bc3ed3121837511
        name:
          type: string
          description: Name of the tag chosen to identify the group.
          default: franchise Accounts
      example:
        groups:
        - id: 8d845239bf1448dc8bc3ed3121837511
          name: long tail
        - id: b9bcd348ab9c4cec8285ff9485c27a72
          name: franchise accounts
  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.'