Contents

  • What are custom variations?
  • How to use custom variations
  • How to list items with custom variations
  • How to update custom variations
  • How to delete custom variations

What are custom variations?

When users do not find the attributes they need for a certain variation, they will be able to create a “custom variation” that better fits or describe their products.

For example, a cell-phones covers seller need to add the “design” attribute for a variation. Doing so, he will be able to create 1 listing with the different design variations.

Sellers will also be able to add custom values to existing standard variations.

Using custom variations

When using custom variations, make sure the category in which you want to list products has attributes. Also, attributes and existing values in that category are different to which you are intending to add. Take into account that only is possible to add one type of variation per product.

Listing products with custom variations

First of all, you need to check on the Categories API if the selected category accepts the type of variation you are intending to add:

Call:

curl -X GET https://api.mercadolibre.com/categories/{Category_id}

Example:

curl -X GET https://api.mercadolibre.com/categories/MLA70400

Response:

The next step is to perform a call to the attributes resource to find out if the category has fixed attributes.

curl -X GET https://api.mercadolibre.com/categories/{Category_id}/attributes

Example:

curl -X GET https://api.mercadolibre.com/categories/MLA90105/attributes

In this case, the category does not have attributes, therefore the variation will be added under no restrictions. You can encode your Json as the following example.

Example:

Response:

Awesome! You have just listed a product with custom variation. Go to the listing through the permalink to check how your product with design variation is shown in our Marketplace.

How to update custom variations

You have already learned to publish with custom variations and, most probably, you will need to update them when updating prices, adding variations or modifying the values of some published attribute.
For example, let’s suppose you listed.

To perform changes on a product with variations or a particular variation, you will have to get the variation_id by looking the product variations up as follows:

Call:

curl -X GET https://api.mercadolibre.com/items/{Item_id}/variations

Example:

curl -X GET https://api.mercadolibre.com/items/MLA601053403/variations

Response:

{
    "id": 10541993184,
    "attribute_combinations": [
      {
        "id": null,
        "name": "Diseño",
        "value_id": null,
        "value_name": "Bulldog"
      }
    ],
    "price": 1000,
    "available_quantity": 3,
    "sold_quantity": 0,
    "picture_ids": [
      "21150-MLA20204290696_112014"
    ],
    "seller_custom_field": null
  },
  {
    "id": 10541993186,
    "attribute_combinations": [
      {
        "id": null,
        "name": "Diseño",
        "value_id": null,
        "value_name": "Búho"
      }
    ],
    "price": 1000,
    "available_quantity": 3,
    "sold_quantity": 0,
    "picture_ids": [
      "21124-MLA20204291671_112014"
    ],
    "seller_custom_field": null
  }

Once you have the Ids for each variation, you can look up for each of them by adding the variaton_id at the end of the GET.

Call:

curl -X GET https://api.mercadolibre.com/items/{Item_id}/variations/{Variation_id}

Example:

curl -X GET https://api.mercadolibre.com/items/MLA601053403/variations/10541993184

Response:

{
  "id": 10541993184,
  "attribute_combinations": [
    {
      "id": null,
      "name": "Diseño",
      "value_id": null,
      "value_name": "Bulldog"
    }
  ],
  "price": 1000,
  "available_quantity": 3,
  "sold_quantity": 0,
  "picture_ids": [
    "21150-MLA20204290696_112014"
  ],
  "seller_custom_field": null,
  "attributes": [
  ]
}

Different types of changes can be performed on a listing with variations. The following guideline shows how to work in each particular case.

If you need to add an image to an existing variation, the image URL will have to be added to the product general pictures array and to the variation’s, as well. Also, since the update will be performed on the items resource, it is necessary to add the Ids for each existing variation on the Json, otherwise, the API will interpret you do not want to keep them on the product listing.

Example:

curl -XPUT -H "Content-type: application/json" -d '{
  "pictures":[  
    { "id":"21124-MLA20204291671_112014" },
    { "id":"21150-MLA20204290696_112014" },
    { "source": "http://mla-s1-p.mlstatic.com/funda-marc-jacobs-3d-iphone-5-5s-5c-bulldog-cebra-buho-732301-MLA20299187840_052015-F.jpg" }
  ],
  "variations":[  
    { "id":10541993184},
    { "id":10541993186,
       "picture_ids":[  
          "21124-MLA20204291671_112014",
          "http://mla-s1-p.mlstatic.com/funda-marc-jacobs-3d-iphone-5-5s-5c-bulldog-cebra-buho-732301-MLA20299187840_052015-F.jpg"
       ]
    }
  ]
}' https://api.mercadolibre.com/items/MLA601053403?access_token=$ACCESS_TOKEN

If you do not want to keep the previous images, do not add them to the Json and they will be automatically detached.

Let’s say now it is available a new design for your product. You can add a new variation on the same listing.

Example:

curl -X POST -d '{
	"attribute_combinations": [{
		"name": "Diseño",
		"value_name": "Cebra"
	}],
	"price": 1000,
	"available_quantity": 3,
	"picture_ids": ["209411-MLA20552996931_012016"]
}' https://api.mercadolibre.com/items/MLA601053403/variations?access_token=$ACCESS_TOKEN

OK. Now the listing has three design variations: Bulldog, Búho and Cebra.

If you want to modify a non-attibute type variation field, you will have to do something similar. In this case, you will have to replace the value of “seller_custom_field” field, which previously was set to null, with a String with the product SKU:

Example:

curl -X PUT -d '{"seller_custom_field": "123456789000"}' https://api.mercadolibre.com/items/MLA601053403/variations/10541993184?access_token=$ACCESS_TOKEN

If you need to change other listing aspects non-related to variations, follow the tutorials for Synchronizing listings (Link).

Relisting custom variations

If your listing is closed but yet there are some variations with stock, you can relist it by setting the variations you wish to keep, the available quantity and the price for each.

Example:

curl -X POST -H "Content-Type: application/json" -d'{
    "listing_type_id": "bronze",
    "variations": [
        {
            "id": 10541993184,
            "price": 1000,
            "quantity": 2
        },
        {
            "id": 10541993186,
            "price": 1000,
            "quantity": 2
        },
                {
            "id": 10542199553,
            "price": 1000,
            "quantity": 1
        }
    ] }' https://api.mercadolibre.com/items/MLA601053403/relist?access_token=$ACCESS_TOKEN

As you can see, when an item is relisted, a new listing is created, therefore there will be created a new “Item_id” and a new variation “Id”, as well.

Deleting custom variations

Now that you know how get the Id of each variation, deleting one or more variations of an item will be a simple task.

Example:

curl -X DELETE 'https://api.mercadolibre.com/items/MLA601053403/variations/10542199553?access_token=$ACCESS_TOKEN'

Well done! You have already learned how to delete variations for an item.

Please, rate this article