To main website
  1. Help Center - Channable
  2. API's
  3. Mirakl API

Articles in this section

See more

Setting up a vtwonen API

Contents

Step 1: Create a new connection

  1. Navigate to [Your project] > APIs. 
  2. Click +Add new API. This will redirect you to your company's connections page.
  3. On the connections page, select +Add a new connection.
  4. Search for the "vtwonen" connection by clicking through the pages and select it by clicking on it.
  5. Add a label.
  6. Click Create. You will be redirected to vtwonen for the next step.
  7. Once redirected, log in using your vtwonen credentials.

vtwonen-api-step1.gif

After successfully logging in, the connection with vtwonen is ready. Next, you will be navigated back to the API setup.

Step 2: Create the API

Once you have created your connection, you need to select your new vtwonen connection and configure your API settings: 

  1. In the Name field, enter a name for your API. 
  2. Choose the Unique ID per item from the dropdown. We recommend the 'id' field.
  3. Select the Language for your API. 
  4. Click Continue to create your vtwonen API.

vtwonen-api-step2.gif

Step 3: Create your product listings

Note: We are gradually rolling out Marketplaces V2. If your API is on Marketplaces V1, these steps might be different. 

To set up your API, follow these steps. Click on each step to expand and view the detailed instructions which will guide you through the process.

1. Categorization

To set up your product data, your products need a category. Add categories to your products by using the generate categories feature, or create new categories from scratch.

  • Smart Categorization: This feature automatically assigns categories to your products based on predefined criteria, simplifying the categorization process.
  • Manual Categorization: Manually assign categories to your products by setting specific rules. You can create detailed filters to map each product to the correct category.
  • Uncategorized Items: Review and categorize any items that remain uncategorized to ensure all products are properly organized.

Read more about the Categorization in APIs.

2. Rules

Create different rules to optimize your product data. For examples, refer to our common rules support article for guidance.

  • Rules Setup: Set up various rules to refine your product data. This can include filtering, modifying, or enhancing data fields to meet marketplace requirements.

Read more about the Rules in APIs.

3. Build step

The Build step allows you to configure all necessary attributes for your items, ensuring your product data aligns with marketplace requirements. This step is crucial for successful product listings and avoiding errors.

3.1 Overview

  1. Access the Build step: Start by accessing the centralized interface of the Build step. This is where you will manage and map all product attributes.
  2. Identify mandatory and optional Fields: Mandatory fields are highlighted in pink, indicating they are essential for listing your products. Optional fields are marked in orange and can be filled based on specific needs.

3.2 Populate Shared Attributes

  1. Fill Shared Attributes: Enter common details that apply to all products, such as EAN, prices, and titles. This step ensures uniformity in basic product information across your listings.
    • Use static or dynamic Values:
      • Static Values: Directly input values that remain constant, like brand name or manufacturer.
      • Dynamic Values: Utilize fields that automatically update based on linked data, ideal for variables like stock levels or prices.

After you have filled in the desired values for the Shared attributes, continue to the Category specific attributes below.

3.3 Specify Category-Specific Attributes

  1. Select product category: Choose the relevant category for your product, such as clothing or furniture.
  2. Input Category - specific attributes: Fill in attributes that are specific to the selected category, such as size for clothing or dimensions for furniture. This step helps in fine-tuning your listings according to category requirements. Here you can again use static or dynamic values.

Read more about the Build step.

4. Quality step

The Quality step provides instant feedback on setup quality, highlighting mandatory and optional errors to ensure your product data meets the marketplaces' standards.

Actions

  • View items: See products with specific issues.
  • View in build: Redirects to the build step to map missing information.
  • Set categories: Directs to the categories step to categorize items.
  • Show source: Available for ID fields, directing to the settings step.

Read more about the Quality step.

5. Preview step

The Preview step displays mapped attributes for multiple items, highlighting errors before exporting to the marketplace.

Features

  • Search & filter: Find specific products or filter by error message/category.
  • Item overview: Shows all items to be exported; it can filter to show only items with errors.
  • Detailed product preview: Displays missing information and dynamic actions to correct errors.

Checklist for finalizing attributes

  • Review shared attributes: Ensure all mandatory shared attributes are filled.
  • Review category-specific attributes: Ensure all mandatory category-specific attributes are filled.
  • Check for errors: Correct any red-marked fields.

Read more about the Preview step.

6. Result step

The Result step provides an overview of your API setup outcomes, including successful uploads, errors, and a preview of the products to be listed. This tab ensures your product data is correctly processed and identifies any issues that need resolution.

  • Overview: The result tab shows the status of your product listings, highlighting errors and issues for detailed insights.
  • Preview products: Displays an overview of products to be sent to the marketplace, allowing verification of correctly filled attributes.
  • Successful: Lists products successfully processed and ready for listing, confirming compliance with marketplace requirements.
  • Errors: Identifies errors during processing, providing detailed information to troubleshoot and resolve issues.

Optional tabs like repricer errors, repricer event history, stock updates, and fulfillment updates appear only if relevant to the API you are using. 

Read more about the Result step.

Additional requirements for vtwonen

These attribute requirements are specific to vtwonen and apply to the attributes in the Build step. 

Shared attributes tab

  • Shipping class (logistic class): The logistic classes determine the respective shipping costs for your items. Enter the logistic class of your product.
  • Lead time to ship: The shipping lead time indicates the time required until the package is handed over to the shipping, Indicate the shipping time in days.

Title requirements

Product titles should consist of the following: 

Brand The brand name as it is registered
Product type The product category, for example, "sofa". This must be written in lower case
Series/product name The series or product name that helps to identify the variant of the product. Each word must be written with a capital letter
Attributes The distinguishing features of the product, for example, color, dimensions or material
  • Structure: Brand Product type Name - Attributes
  • Example: vtwonen pendant lamp Titan - black.

Product description

The product descriptions for your vtwonen API should:  

  • address the customer (“you” and “your”)
  • be written in a friendly, helpful and respectful tone
  • avoid jargon or technical terms, if relevant to the target group
  • describe the product features and the benefits and experience
  • use relevant keywords
  • not contain abbreviations

Product descriptions should consist of the following: 

Short description

 An overview of the product to highlight the most important features. HTML is not allowed
Bullet points The key features and benefits of the product. Minimum 3 and maximum 5 points
Long description

Detailed information about the product's features, specifications, materials and usage. Also, styling and maintenance tips. HTML is allowed (bold and lists)


Image requirements

Minimum resolution 800 x 800 px
Maximum resolution 4472 x 4472 px
Supported formats JPEG, PNG, WebP, GIF
Style No watermarks, logos or text components


Video requirements

Duration Between 30 sec. and 2 min
Resolution 1080p or higher
Supported formats .mp4, .mov, .avi, .flv
Style No borders, sketches, watermarks, logos,
labels or prices

Best practices

Adding multiple attribute values: When adding multiple values in an attribute field for Mirakl Marketplaces, separate each value with a pipe symbol "|" to ensure proper detection and processing. 

Seller's Product ID for Single/simple products: Please note that there are two attributes named 'SellerArticleId' and 'SellerProductId,' respectively. 'SellerProductId' refers to the Parent ID, while 'SellerArticleId' refers to the variant items. For single products, both attributes must be filled with the same value.

For more information on Mirakl Marketplace errors, how-to's, and best practices, check out our dedicated guide. 

 

Step 4: Send your product listings to vtwonen

Once your product listings are ready, you need to send them to vtwonen: 

  1. If you have not activated your project, go to [Your project] > Settings and click Activate project. 
  2. In [Your project] > APIs, go to [Your vtwonenAPI] > Settings.
  3. Click Activate API.
  4. Once you have activated the API, navigate back to APIs.
  5. Click on the Run now button in the 'Status' column to send your product listings to vtwonen.

Step 5: Check your product listings for errors

  1. To check for errors, navigate to the Result > Errors tab. Here there is a list of the product listings that have errors. 
  2. Click on the specific error to display more information about what is causing the error.