v50

latestOpenAPI 3.0.0raw.githubusercontent.com2025-08-282624202.6 KB

Sellers

Configure seller account

This endpoint is used by marketplace operators to configure the accounts of sellers that have already accepted the invitation to join their marketplaces.

For marketplaces to add sellers without the Seller Invite feature, call this endpoint directly.

This call includes all the information a seller needs to activate their account.

Permissions

Any user or API 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
Seller Register	Seller Administration	Save Seller

You can create a custom role with that resource or use one of the following predefined roles:

Role	Resource
Seller manager	Save Seller

❗ Assigning a predefined role to users or application keys usually grants permission to multiple License Manager resources. 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.

post/seller-register/pvt/sellers

Path parameters

accountNamestring required

Example:apiexamples

Name of the VTEX account that belongs to the marketplace. The notification will be posted into this account.

environmentstring required

Environment to use. Used as part of the URL.

Headers

Acceptstring required

HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.

Content-Typestring required

Type of the content being sent.

Request body

idstring required

Seller ID assigned by the marketplace. We recommend filling it in with the seller's account name.

namestring required

Name of the seller's store, configured in the seller's environment.

isActiveboolean required

Whether the seller is active on the marketplace or not.

fulfillmentEndpointstring required

URL of the endpoint for fulfillment of seller's orders, which the marketplace will use to communicate with the seller.

For 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.

For VTEX Stores, the field format will be as follows: https://{SellerName}.vtexcommercestable.com.br/api/fulfillment?&sc={TradePolicyID}.

The value SellerName corresponds to the store name if the seller is a VTEX store.

The value TradePolicyID corresponds to the trade policy 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.

The 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.

To configure the 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}}.

allowHybridPaymentsboolean required

Indicates if customers can use gift cards from the seller to buy their products on the marketplace (true) or not (false). If true, it identifies purchases made with a gift card so that only the final price (with discounts applied) is paid to the seller.

taxCodestring required

Identity number of the legal entity, which is linked to information in its base country.

emailstring required

Email of the administrative user responsible for the seller.

descriptionstring required

Description of the seller.

sellerCommissionConfigurationobject required

Details of the seller's commission configuration, including the product commission percentage, freight commission percentage, and categories commission configuration.

isBetterScopeboolean required

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.

sellerTypeinteger required

Type of seller, including:

1: Regular seller

2: White label seller.

CSCIdentificationstring required

SKU Seller Identification.

accountstring required

Seller's account name.

channelstring required

Channel's name.

salesChannelstring required

Sales channel (or trade policy) 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 ID.

isVtexboolean required

Indicates whether the seller configured is a VTEX store or not.

exchangeReturnPolicystring required

Text describing the exchange and return policy previously agreed between the marketplace and the seller.

deliveryPolicystring required

Text describing the delivery policy previously agreed between the marketplace and the seller.

securityPrivacyPolicystring nullable required

Text describing the security policy previously agreed between the marketplace and the seller.

fulfillmentSellerIdstring nullable required

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.

userstring nullable required

Username, if you are using a hub to integrate with the external seller.

passwordstring nullable required

User password, if you are using a hub to integrate with the external seller.

catalogSystemEndpointstring required

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/.

trustPolicystring required

Specifies the trust policy agreed between the marketplace and the seller, such as permissions related to data sharing.

scorenumber required

Score attributed to this seller.

Example request

{
  "id": "seller123",
  "name": "Seller Name",
  "isActive": true,
  "fulfillmentEndpoint": "http://{SellerName}.vtexcommercestable.com.br/api/fulfillment?&sc={TradePolicyID}",
  "taxCode": "34444",
  "email": "seller@email.com",
  "description": "Seller A, from the B industry.",
  "sellerCommissionConfiguration": {
    "productCommissionPercentage": 3,
    "freightCommissionPercentage": 4,
    "categoriesCommissionConfiguration": []
  },
  "isBetterScope": true,
  "sellerType": 1,
  "availableSalesChannels": [
    {
      "isSelected": true,
      "id": 1,
      "name": "Principal store"
    },
    {
      "isSelected": true,
      "id": 2,
      "name": "Third"
    },
    {
      "isSelected": true,
      "id": 3,
      "name": "Marketplaces"
    }
  ],
  "CSCIdentification": "cscidentification 123",
  "account": "partner01",
  "channel": "channel name",
  "salesChannel": "1",
  "isVtex": true,
  "exchangeReturnPolicy": "Describe exchange and returns policy",
  "deliveryPolicy": "Describe delivery policy",
  "securityPrivacyPolicy": "Our marketplace ensures that all transactions are encrypted with SSL technology, and we adhere to strict privacy standards to protect both sellers and buyers. Personal data is only shared with authorized parties to facilitate order processing and delivery, and we do not sell or disclose personal information to third parties without consent.",
  "fulfillmentSellerId": "seller1",
  "groups": [
    {
      "groups": [
        {
          "id": "8d845239bf1448dc8bc3ed3121837511",
          "name": "long tail"
        },
        {
          "id": "b9bcd348ab9c4cec8285ff9485c27a72",
          "name": "franchise accounts"
        }
      ]
    }
  ],
  "user": "integrationHubUserName",
  "password": "integrationHubPassword",
  "catalogSystemEndpoint": "https://apiexamples.vtexcommercestable.com.br/api/catalog_system/",
  "trustPolicy": "AllowEmailSharing"
}

v50