This document aims to help integrate the information in the catalog of a VTEX store with some external service.

Among the most common use cases for this integration, we have:

1. Integrate the VTEX Store catalog with external marketplaces.
2. Send catalog data to BI tools.
3. Generate external reports using the information in the catalog.

Follow the steps below to perform the integration.

The affiliate acts as a webhook that will notify the external service about changes made to an SKU's information, changes in inventory or changes in pricing.

1. On the admin side menu, click Order Management.
2. Click Settings.
3. Click the Affiliates tab.
4. Click the New Affiliate button.
5. Fill in the fields as described below.
6. Click Save.

• Name: Fill in the name of the affiliate system.
• ID: Affiliate identification code with 3 digits. The ID must contain only consonants.
• Trade Policy: Id of the trade policy whose information will be sent to the affiliate.
• Follow Up E-mail: E-mail address that will receive information when the affiliate is notified.
• Search Endpoint: URL of the application that will receive notifications about the SKUs, their prices and their stocks. This URL must be developed by the external system so that VTEX can notify the changes through this route.
• Search Endpoint Version: Keep this field populated with the value 1.x.x.
• Use my payment method: If it makes sense for your integration that the external service receives the payment information of your store, check this flag.

After you have created the Endpoint that will receive product information and have successfully configured the affiliate, you must first load the Catalog data and save it to your external service database. To do this, follow the instructions below.

Do a GET in the path http://{accountName}.vtexcommercestable.com.br/api/catalog_system/pvt/sku/stockkeepingunitids?page={page}&pagesize={page_size} to get an array with the IDs of the SKUs in your store.

API Parameters:

{accountName}: Your store account name in VTEX.

{page}: The page where the request is being made. You must go through all the pages until the request response is an empty array ([]).

{page_size}: The amount of SKU IDs to be returned per page. We recommend returning a maximum of 1000 ids per page.

Example of response:

Using the IDs of the SKUs obtained in the previous request, you should do a GET on the route http://{{accountName}}.vtexcommercestable.com.br/api/catalog_system/pvt/sku/stockkeepingunitbyid/{{skuId}} to get information about the properties of the SKUs. The response of this request will return the information that characterizes the SKU, such as __Name __, Brand, Category, Collections, Image, if the SKU is Active or Inactive and Trade Policies, for example. Pricing and inventory information are not yet available in this step.

API Parameters:

{accountName}: Your store account name in VTEX.

{{skuId}}: ID of the SKU to be queried.

Example of answer:

Still using the IDs obtained in the first request, you should do a POST on the route https://{accountName}.vtexcommercestable.com.br/api/fulfillment/pvt/orderForms/simulation?sc={salesChannel}&affiliateId={affiliateId} to get the price, inventory, and delivery SLA data from the SKUs. This call simulates a cart in VTEX Checkout, returning the most up-to-date price, inventory, and delivery SLA information.

API Parameters:

{accountName}: Your store account name in VTEX.

{salesChannel}: Trade Policy to be considered in the simulation.

{affiliateId}: Affiliate ID to be considered in the context of the simulation.

Example of BODY to fill in POST:

Example of response:

By combining the three request types shown above, you will be able to perform the first load of data from the VTEX Catalog to write to the database of an external service.

In the event of any product changes, VTEX will notify the Affiliate Endpoint of the information on all SKUs of the changed product even if one of the SKUs has not changed, performing a POST. Here is an example of the payload sent by VTEX to the Endpoint:

Receiving this payload, the integrator must use this information to decide which calls to make to update the SKU information:

• If there has been a price or stock change, the integrator should call the https://{accountName}.vtexcommercestable.com.br/api/fulfillment/pvt/orderForms/simulation?sc={salesChannel}&affiliateId={affiliateId}, as described in the section Obtain SKU price and inventory data.
• If there has been a change in the SKU other than price or inventory, the integrator should call the http://{{accountName}}.vtexcommercestable.com.br/api/catalog_system/pvt/sku/stockkeepingunitbyid/{{skuId}}, as described in the section Get the data about SKU properties.

If a new SKU is inserted into the catalog, it will be notified at the endpoint of each affiliate. Because it is a new SKU, it's necessary to fill in the data of this new SKU in the database of the external service. The integrator shall verify that the notified SKU does not yet exist in the external service database. If it's a new SKU, the integrator must follow the same steps described in the Perform the first load with SKU data section. If it's an existing SKU, the integrator must follow the steps in the section Update SKUs data

If you want to integrate the payment methods of a VTEX seller with an external marketplace, go to our documentation.