VTEX Seller Commissions API

openapi: 3.2.0
info:
  title: VTex Marketplace Seller Commissions 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: Seller Commissions
paths:
  /seller-register/pvt/sellers/{sellerId}/commissions:
    get:
      tags:
      - Seller Commissions
      summary: VTex List Seller Commissions by seller ID
      description: "This endpoint retrieves all comissions configured for a specific seller. It is not necessary to send a request body.\n\n## Permissions\n\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) 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:\n\n| **Product** | **Category** | **Resource** | **Role** |\n|---|---|---|---|\n| Seller Register | Seller adminstration | View Seller | View all sellers linked to the Marketplace account described on the sellers management page, including recovering seller data, either from the sellers listing, or a specific seller. |\n| Seller Register | Seller administration | Save Seller | Create new sellers and edit data from all sellers linked to Marketplace account from the sellers management page. |\n\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with this feature or use one of the predefined roles from the list above.\n\n >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
      operationId: ListSellerCommissions
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/sellerId'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/contentType'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: Array with objects containing information about the category, seller and percentage of commission applied.
                items:
                  $ref: '#/components/schemas/responseSellerCommissionsID'
      deprecated: false
    put:
      tags:
      - Seller Commissions
      summary: VTex Upsert Seller Commissions in bulk
      description: "This endpoint is used by marketplace operators to define comissions for multiple categories, sending an array with multiple objects in the same call.\n\n## Permissions\n\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) 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:\n\n| **Product** | **Category** | **Resource** | **Role** |\n|----|----|----|----|\n| Seller Register | Seller administration | Save Seller | Create new sellers and edit data from all sellers linked to Marketplace account from the sellers management page. |\n\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with this feature or use one of the predefined roles from the list above.\n\n >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
      operationId: BulkUpsertSellerCommissions
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/contentType'
      - $ref: '#/components/parameters/sellerId'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              description: Array with objects containing information about the category, seller and commission percentage to be applied.
              items:
                $ref: '#/components/schemas/BulkUpsertSellerCommissionsRequest'
        required: true
      responses:
        '204':
          description: No Content
      deprecated: false
  /seller-register/pvt/sellers/{sellerId}/commissions/{categoryId}:
    delete:
      tags:
      - Seller Commissions
      summary: VTex Remove Seller Commissions by Category ID
      operationId: RemoveSellerCommissions
      description: "This endpoint removes a seller comission on the selected category.\n\n >❗This action cannot be undone, to reconfigure the commission it is necessary to use the [Upsert Seller Commissions in Bulk endpoint](https://developers.vtex.com/docs/api-reference/marketplace-apis#put-/seller-register/pvt/sellers/-sellerId-/commissions/categories?endpoint=put-/seller-register/pvt/sellers/-sellerId-/commissions/categories). \n\n## Permissions\n\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) 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:\n\n| **Product** | **Category** | **Resource** | **Role** |\n|----|----|----|----|\n| Seller Register | Seller administration | Save Seller | Create new sellers and edit data from all sellers linked to Marketplace account from the sellers management page. |\n\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with this feature or use one of the predefined roles from the list above.\n\n >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
      parameters:
      - $ref: '#/components/parameters/accountName'
      - $ref: '#/components/parameters/environment'
      - $ref: '#/components/parameters/accept'
      - $ref: '#/components/parameters/contentType'
      - $ref: '#/components/parameters/sellerId'
      - $ref: '#/components/parameters/categoryId'
      responses:
        '204':
          description: No Content
      deprecated: false
    get:
      tags:
      - Seller Commissions
      summary: VTex Get Seller Commissions by Category ID
      operationId: RetrieveSellerCommissions
      description: "This endpoint retrieves seller comissions applied to the selected category. It is not necessary to send a request body.\n\n## Permissions\n\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) 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:\n\n| **Product** | **Category** | **Resource** | **Role** |\n|---|---|---|---|\n| Seller Register | Seller adminstration | View Seller | View all sellers linked to the Marketplace account described on the sellers management page, including recovering seller data, either from the sellers listing, or a specific seller. |\n| Seller Register | Seller administration | Save Seller | Create new sellers and edit data from all sellers linked to Marketplace account from the sellers management page. |\n\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with this feature or use one of the predefined roles from the list above.\n\n >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm). To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
      parameters:
      - name: accountName
        in: path
        description: Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.
        required: true
        schema:
          type: string
          default: apiexamples
      - name: environment
        in: path
        required: true
        description: Environment to use. Used as part of the URL.
        schema:
          type: string
          default: vtexcommercestable
      - 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: Describes the type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: sellerId
        in: path
        description: A string that identifies the seller in the marketplace. This ID must be created by the marketplace.
        required: true
        style: simple
        schema:
          type: string
          default: seller123
      - name: categoryId
        in: path
        description: ID of the category in which the comission was applied
        required: true
        style: simple
        schema:
          type: string
          default: '6'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseSellerCommissionsID'
      deprecated: false
components:
  parameters:
    contentType:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
    categoryId:
      name: categoryId
      in: path
      description: ID of the category in which the comission was applied
      required: true
      style: simple
      schema:
        type: string
        default: '6'
    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
    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
    environment:
      name: environment
      in: path
      required: true
      description: Environment to use. Used as part of the URL.
      schema:
        type: string
        default: vtexcommercestable
    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
  schemas:
    responseSellerCommissionsID:
      type: object
      description: Object with the category properties and the commission percentage applied to it.
      properties:
        categoryId:
          type: string
          description: Marketplace's Category ID that the product belongs to, configured in the Catalog.
          example: '51'
        categoryName:
          type: string
          description: Category name with applied commission.
          example: Clothes
        categoryFullPath:
          type: array
          description: Full path to the SKU's category.
          items:
            type: string
            example: '2.0'
          example:
          - '2.0'
          - Boys
          - Clothes
        productCommissionPercentage:
          type: number
          description: Percentage of the comission applied to the product in decimals.
          example: 7.75
        freightCommissionPercentage:
          type: number
          description: Percentage of the comission applied to the freight in decimals.
          example: 2.33
      example:
        categoryId: '51'
        categoryName: Clothes
        categoryFullPath:
        - '2.0'
        - Boys
        - Clothes
        productCommissionPercentage: 7.75
        freightCommissionPercentage: 2.33
    BulkUpsertSellerCommissionsRequest:
      required:
      - categoryId
      - categoryFullPath
      - productCommissionPercentage
      - freightCommissionPercentage
      type: object
      properties:
        categoryId:
          type: string
          description: Marketplace's Category ID that the product belongs to, configured in the Catalog.
          example: '6'
        categoryFullPath:
          type:
          - string
          - 'null'
          description: 'Full path to the SKU''s category. It should be written as {department}/{category}. For example: if the department is **Appliances** and the category is **Oven**, the full path should be ''Appliances/Oven''.'
          example: Appliances/Oven
        productCommissionPercentage:
          type: number
          description: Percentage of the comission applied to the product in decimals.
          example: 9.85
        freightCommissionPercentage:
          type: number
          description: Percentage of the comission applied to the freight in decimals.
          example: 2.43
      example:
      - categoryId: '6'
        categoryFullPath: null
        productCommissionPercentage: 9.85
        freightCommissionPercentage: 2.43
      - categoryId: '51'
        categoryFullPath: Appliances/Oven
        productCommissionPercentage: 7.85
        freightCommissionPercentage: 3.43
  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.'