Price per Variation

Figure 1: Family example with color variations and different prices

Key benefits

• Flexible pricing: Establish different prices per variation based on demand, cost, or market strategy.
• Independent listing types: Choose different exposure levels for each variation.
• Unified management: All variations share the same family_id for easy organization.
• Site-specific customization: Define specific prices and conditions for each marketplace.

How it works

In the traditional model, an item combined product information and sales terms. User Products separates these responsibilities: the UP defines the product, and the item defines the offer. Price per Variation arises naturally from this separation, allowing for multiple independent offers for related products.

• Each variation of color, size, or attribute is a separate User Product.
• All variations of the same product share the same family_id.
• Each User Product has its own item with independent price, listing_type, and shipping configuration.
• Product information (attributes, images, title) is managed at the UP Siteless level.
• Sales conditions (price, stock, shipping) are managed at the item level.

Seller validation

Sellers enabled for the User Products model have the user_product_seller tag. You can verify this by calling the users API:

Request:

curl -X GET 'https://api.mercadolibre.com/users/{user_id}' \
  --header 'Authorization: Bearer $TOKEN'

Response (200 OK):

{
  "user_type": "normal",
  "tags": [
    "user_product_seller",
    "normal"
  ]
}

Creating variations as User Products

Required fields:

Field	Required	Description
family_name	Yes	Generic description of the product family (e.g., "Apple iPhone 256GB").
sites_to_sell	Yes	Array of destination marketplaces with their sales conditions.
attributes	Yes	Product attributes including the variation attribute (e.g., COLOR).
pictures	Yes	Product images (sent only by ID).

Create UP Siteless with sales conditions

Create a UP Siteless for each variation (e.g., Red variation):

Request:

curl -X POST 'https://api.mercadolibre.com/global/items' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "sites_to_sell": [
    {
      "site_id": "MCO",
      "logistic_type": "remote"
    },
    {
      "site_id": "MLC",
      "logistic_type": "remote"
    },
    {
      "site_id": "MLB",
      "logistic_type": "remote"
    }
  ],
  "family_name": "Red T-shirt M logo",
  "category_id": "CBT416197",
  "global_net_proceeds": 25,
  "available_quantity": 100,
  "description": {
    "plain_text": "Sample item for E2E flow."
  },
  "pictures": [
    {
      "id": "655219-CBT82943741035_032025"
    }
  ],
  "attributes": [
    {
      "id": "ITEM_CONDITION",
      "values": [
        {
          "id": "2230284",
          "name": "New"
        }
      ]
    },
    {
      "id": "BRAND",
      "value_name": "FlowBrand"
    },
    {
      "id": "MODEL",
      "value_name": "FlowModel"
    },
    {
      "id": "PACKAGE_HEIGHT",
      "value_name": "10 cm"
    },
    {
      "id": "PACKAGE_LENGTH",
      "value_name": "20 cm"
    },
    {
      "id": "PACKAGE_WIDTH",
      "value_name": "15 cm"
    },
    {
      "id": "PACKAGE_WEIGHT",
      "value_name": "500 g"
    }
  ],
  "sale_terms": [
    {
      "id": "WARRANTY_TYPE",
      "value_id": "6150835",
      "value_name": "No warranty"
    }
  ]
}'

Response:

{
  "item_id": "CBT2826958659",
  "seller_id": 1305628788,
  "site_id": "CBT",
  "parent_user_product_id": "CBTU3687816070",
  "siteless_user_product_id": "U3687816070",
  "siteless_family_id": 4919667263731854,
  "site_items": [
    {
      "item_id": "MCO3419064200",
      "seller_id": 1305630918,
      "site_id": "MCO",
      "user_product_id": "MCOU3687816070",
      "logistic_type": "remote"
    },
    {
      "item_id": "MLB6068255422",
      "seller_id": 1305627900,
      "site_id": "MLB",
      "user_product_id": "MLBU3687816070",
      "logistic_type": "remote"
    },
    {
      "item_id": "MLC3437222586",
      "seller_id": 1305631715,
      "site_id": "MLC",
      "user_product_id": "MLCU3687816070",
      "logistic_type": "remote"
    }
  ]
}

Repeat the process for Blue and Green variations with their respective attributes and prices.

Adding new marketplaces

If you already have a UP Siteless and want to add a new marketplace:

Request:

curl -X POST 'https://api.mercadolibre.com/global/user-products/{siteless_user_product_id}' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "sites_to_sell": [
    {
      "site_id": "MLM",
      "logistic_type": "remote",
      "listing_type_id": "gold_pro",
      "net_proceeds": 200
    }
  ]
}'

Response (200 OK):

{
  "item_id": "CBT2827162121",
  "seller_id": 1305628788,
  "site_id": "CBT",
  "parent_user_product_id": "CBTU3689227954",
  "siteless_user_product_id": "U3689227954",
  "site_items": [
    {
      "item_id": "MLM4537463738",
      "seller_id": 1305634202,
      "site_id": "MLM",
      "user_product_id": "MLMU3689227954",
      "logistic_type": "remote"
    }
  ]
}

Identifying products from the same family

All User Products representing variations of the same product share the same family_id.

Get all User Products in a family:

Request:

curl -X GET 'https://api.mercadolibre.com/sites/{site_id}/user-products-families/{family_id}' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'X-API-Version: 2'

Response:

{
  "user_products_ids": [
    "U3687816070",
    "U3687816071",
    "U3687816072"
  ],
  "family_id": 4919667263731854,
  "user_id": 1305628788
}

Get UP Siteless information

Request:

curl -X GET 'https://api.mercadolibre.com/user-products/{siteless_user_product_id}' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'X-API-Version: 2'

Note: Use the header X-API-Version: 2 to obtain the locale field and full support for UP Siteless.

Site-specific attributes

With UP Siteless, you can provide site-specific values for the following item fields:

• Title (family_name): Marketplace-specific title.
• Description (description): Language/market-specific content.
• Price (net_proceeds): Marketplace-specific price.
• Status (status): Publication status (active, paused, closed).
• Listing type (listing_type): gold_special, gold_pro, etc.
• Official Store ID: Official store identifier.
• SALM: Site-specific logistics configuration.

Updating prices

To update the price of a specific variation in one or more marketplaces:

Request:

curl -X PUT 'https://api.mercadolibre.com/global/user-products/{siteless_user_product_id}' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "listing_sites": [
    {
      "listing_id": "MLM4529604428",
      "net_proceeds": 55.50
    }
  ]
}'

Response (200 OK):

{
  "id": "U3685216136",
  "errors": null,
  "listing_sites": [
    {
      "id": "MLM4529604428",
      "success": true,
      "errors": null
    }
  ]
}

Updating images

To update images for a UP Siteless (the thumbnail will be automatically recalculated):

Request:

curl -X PUT 'https://api.mercadolibre.com/user-products/{siteless_user_product_id}' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "pictures": [
    {
      "id": "790745-CBT77271594694_072024"
    }
  ]
}'

Response:

{
  "id": "U3685216136",
  "success": true,
  "errors": null
}

Best practices

• Once enabled for User Products (tag user_product_seller), create all new items under this model.
• Use family_name for a generic product description that applies to all variations.
• The variations array cannot be sent - it will return an error.
• Each variation must be created as a separate UP Siteless with its own attributes.
• Keep all variations of the same product grouped by using consistent family_name values.
• Stock is managed centrally at the UP Siteless level.