Third Variation Tutorial

important

This is an upcoming feature. OpenAPI devs need to be ready by August 17th 2026, but Etsy will communicate the exact date of the General Audience launch closer to cutover.

The maximum number of listing properties to be used in a listing's inventory is now 3. Set the new query parameter max_variations_supported to 3 to write listing inventory with 3 variations.

The third variation can be one of the properties of the listing's taxonomy node and can use the property's predefined values("possible_values") or custom values. It can also be a custom variation. When using predefined properties and values, buyers can find your listings via search filters.

Developer Preview#

To facilitate development and testing prior to the General Audience launch, we are providing developers early access to these features via authorized test accounts starting on August 17th 2026.

To access the Third Variation feature prior to the General Audience launch, developers must use a seller account in developer mode.

Prerequisites#

  • An Etsy OpenAPI application account for development

How to Join the Developer Preview#

To join the developer preview for the Third Variation feature:

  1. Log in to Etsy with your account.
  2. Set your shop account to developer mode by going to https://www.etsy.com/developers/shop.
  • To restore your shop back to sales mode, follow the instructions in the above page.
  1. Register for the Third Variation developer preview by going to https://www.etsy.com/your/shops/me/dashboard?enroll-seller-third-variation-preview=true.

  • A green success toast appears after a successful registration.

    ✔︎You're in! You can try out the new third variation feature in Listings.⨉
    • A red failure toast appears after a failed registration.
    ⚠︎Looks like you don’t quite meet the eligibility requirements for the new third variation feature. This could be because the shop is not in Developer Mode, has no active app connections, or is otherwise ineligible.⨉
  1. To add listings with three variations, follow the rest of this tutorial.

Reading Listings with a Third Variation#

warning

Ensure you update your app to support reading all three variations before August 17th 2026. After that date, your app may incorrectly process listings with three variations and fail silently.

Endpoints that return inventory and variation data may now have up to three variations.

If a listing has three variations:

  • when calling getListingInventory, all the "products" > "property_values" arrays have three elements.
  • when calling getListing with the includes=Inventory query param, the "inventory" > "products" > "property_values" arrays have three elements.
  • when calling getShopReceiptTransaction for a transaction for the listing, the "variations" array has three elements.
  • when calling getShopReceipt for a receipt for the listing, the "transactions" > "product_data" arrays and the "transactions" > "variations" array have three elements.

Example Response for getListingInventory

{
"products": [
{
"product_id": 12345678979,
"sku": "",
"is_deleted": false,
"offerings": [
{
"offering_id": 34567891284,
"quantity": 9,
"is_enabled": true,
"is_deleted": false,
"price": { "amount": 100, "divisor": 100, "currency_code": "USD" },
"readiness_state_id": 1020304051823
}
],
"property_values": [
{
"property_id": 52047899318,
"property_name": "Size",
"scale_id": 30,
"scale_name": "US numeric",
"value_ids": [108450111039],
"values": ["Preemie"]
},
{
"property_id": 200,
"property_name": "Primary color",
"scale_id": null,
"scale_name": null,
"value_ids": [49928889192],
"values": ["Blue"]
},
{
"property_id": 52047899002,
"property_name": "Secondary color",
"scale_id": null,
"scale_name": null,
"value_ids": [52751447102],
"values": ["Black"]
}
]
},
// ...other products with three variations
],
"price_on_property": [52047899318, 200, 52047899002],
"quantity_on_property": [],
"sku_on_property": [],
"readiness_state_on_property": [],
"listing": {
"listing_id": 4444446484,
"taxonomy_id": 496,
// ...other listing fields
}
}

Writing Listings with a Third Variation#

The updateListingInventory endpoint accepts values for a third variation. If the query parameter max_variations_supported is set to 3, adding or updating the third variation is enabled. The *_on_property fields can have zero, one, or all the variation properties. For performance, the number of products allowed is limited to 2500 for listings with three variations and to 400 for listings where any *_on_property field has all variation properties.

  • Related endpoints: updateListingInventory
  • Structure changes: The request and response structures remain the same.
  • New parameters: Optional integer query parameter max_variations_supported with accepted values [2, 3].
    • If included and set to 3, the endpoint accepts requests with three variations and/or updates to listings with three variations.
    • If omitted or set to 2, the endpoint rejects requests with three variations and/or updates to listings with three variations and returns an appropriate error message.
    • Invalid values for this parameter return an appropriate error message.
    • For requests with two or less variations this parameter is not required.
  • Errors:
    • 400: Invalid value (X) for query parameter max_variations_supported.
    • 409: Could not update inventory for listing with unsupported number of variations. The maximum number of supported variations is X.
    • 409: Could not update inventory with unsupported number of variations. The maximum number of supported variations is X.
    • 400: X_on_property: unsupported number of property IDs. Supports only zero, one, or all Y variation properties.
    • 400: There was a problem with /inventory. Total products X exceeds maximum allowed 2500 for 3 variations.
    • 400: There was a problem with /inventory. Total products X exceeds maximum allowed 400 for listing that varies by all properties.

Parameter Conditionals#

  • Query parameter max_variations_supported is omitted or set to 2.
ListingRequest PayloadResult
Has up to two variationsHas up to two variationsRequest succeeds, listing has request variations
Has up to three variationsHas three variationsRequest fails with a 400 error, listing has original variations
Has three variationsHas up to three variationsRequest fails with a 400 error, listing has original variations
  • Query parameter max_variations_supported is set to 3.
ListingRequest PayloadResult
Has up to three variationsHas up to three variationsRequest succeeds, listing has request variations

Notes:

  • If the max_variations_supported query parameter is set to a different value than 2 or 3 the request returns a 400 error.
  • If the listing has three variations and the request payload has less than three variations, the missing variations are deleted.

Writing a Third Variation#

Use the endpoint getPropertiesByTaxonomyId to get the list of properties that can be used for variations ("supports_variations": true). The third variation can also be a custom variation.

Examples#

  • Context:
    • Request for listing with two or less variations, request adds a third variation.
    • Query parameter max_variations_supported is set to 3. (max_variations_supported=3)
  • Response changes:
    • All products[].property_values have three elements.
    • The *_on_property fields may have zero, one, or all three properties.

Example Payload

{
"products": [
{
"offerings": [
{
"price": 10.0,
"quantity": 1,
"is_enabled": true,
"readiness_state_id": 1020304051823
}
],
"property_values": [
{
"property_id": 513,
"property_name": "My custom variation",
"value_ids": [],
"values": ["Custom value 1"],
"scale_id": null
},
{
"property_id": 200,
"property_name": "Primary color",
"value_ids": [9],
"values": ["Red"],
"scale_id": null
},
{
"property_id": 102868018123,
"property_name": "Gemstone type",
"value_ids": [4535],
"values": ["Agate"],
"scale_id": null
}
],
"sku": ""
}
// ...other products with three variations
],
"price_on_property": [],
"quantity_on_property": [],
"readiness_state_on_property": [],
"sku_on_property": []
}

Example Response

{
"products": [
{
"product_id": 30328811353,
"sku": "",
"is_deleted": false,
"offerings": [
{
"offering_id": 123456284729,
"quantity": 1,
"is_enabled": true,
"is_deleted": false,
"price": { "amount": 1000, "divisor": 100, "currency_code": "USD" },
"readiness_state_id": 1020304051823
}
],
"property_values": [
{
"property_id": 513,
"property_name": "My custom variation",
"scale_id": null,
"scale_name": null,
"value_ids": [1474406756737],
"values": ["Custom value 1"]
},
{
"property_id": 200,
"property_name": "Primary color",
"scale_id": null,
"scale_name": null,
"value_ids": [52041479599],
"values": ["Red"]
},
{
"property_id": 102868018123,
"property_name": "Gemstone",
"scale_id": null,
"scale_name": null,
"value_ids": [1014715895892],
"values": ["Agate"]
}
]
},
// ...other products with three variations
],
"price_on_property": [],
"quantity_on_property": [],
"sku_on_property": [],
"readiness_state_on_property": []
}

Writing a Third Variation: On Property#

For listings with a third variation, you can use the *_on_property fields as follows:

  • Leave all of them empty, OR
  • Add one property to any of them, OR
  • Add all three properties to any of them.

When the listing has three variations, adding only two properties to any of these fields returns an error.

Examples#

  • Context:
    • Payload has a third variation and empty *_on_property fields.
    • Query parameter max_variations_supported is set to 3. (max_variations_supported=3)
  • Response changes:
    • All products[].property_values have three elements.
    • The *_on_property fields are empty.

Example Payload

{
"products": [
{
"offerings": [
{
"price": 10.0,
"quantity": 1,
"is_enabled": true,
"readiness_state_id": 1020304051823
}
],
"property_values": [
{
"property_id": 513,
"property_name": "My custom variation",
"value_ids": [1474406756737],
"values": ["Custom value 1"],
"scale_id": null
},
{
"property_id": 200,
"property_name": "Primary color",
"value_ids": [52041479599],
"values": ["Red"],
"scale_id": null
},
{
"property_id": 102868018123,
"property_name": "Gemstone type",
"value_ids": [1014715895892],
"values": ["Agate"],
"scale_id": null
}
],
"sku": ""
}
// ...other products with three variations
],
"price_on_property": [],
"quantity_on_property": [],
"readiness_state_on_property": [],
"sku_on_property": []
}

Example Response

{
"products": [
{
"product_id": 30328811353,
"sku": "",
"is_deleted": false,
"offerings": [
{
"offering_id": 123456284729,
"quantity": 1,
"is_enabled": true,
"is_deleted": false,
"price": { "amount": 1000, "divisor": 100, "currency_code": "USD" },
"readiness_state_id": 1020304051823
}
],
"property_values": [
{
"property_id": 513,
"property_name": "My custom variation",
"scale_id": null,
"scale_name": null,
"value_ids": [1474406756737],
"values": ["Custom value 1"]
},
{
"property_id": 200,
"property_name": "Primary color",
"scale_id": null,
"scale_name": null,
"value_ids": [52041479599],
"values": ["Red"]
},
{
"property_id": 102868018123,
"property_name": "Gemstone",
"scale_id": null,
"scale_name": null,
"value_ids": [1014715895892],
"values": ["Agate"]
}
]
}
// ...other products with three variations
],
"price_on_property": [],
"quantity_on_property": [],
"sku_on_property": [],
"readiness_state_on_property": []
}

Writing a Third Variation: Product Limits#

For more complex listings, the number of products allowed is limited for performance:

  • For listings with three variations, the maximum number of products is 2500.
  • For listings with two or three variations where any *_on_property field has all properties, then the maximum number of products is 400.

Adding more products than allowed returns an error.

Examples#

  • Context:
    • Payload has a third variation, more than 2500 products, and no *_on_property fields with all properties.
    • Query parameter max_variations_supported is set to 3. (max_variations_supported=3)
  • Response changes:
    • Returns a 400 error.

Example Payload

{
"products": [
{
"offerings": [
{
"price": 10.0,
"quantity": 1,
"is_enabled": true,
"readiness_state_id": 1020304051823
}
],
"property_values": [
{
"property_id": 513,
"property_name": "My custom variation",
"value_ids": [1474406756737],
"values": ["Custom value 1"],
"scale_id": null
},
{
"property_id": 200,
"property_name": "Primary color",
"value_ids": [52041479599],
"values": ["Red"],
"scale_id": null
},
{
"property_id": 102868018123,
"property_name": "Gemstone type",
"value_ids": [1014715895892],
"values": ["Agate"],
"scale_id": null
}
],
"sku": ""
}
// ...other more than 2500 products with three variations
],
"price_on_property": [],
"quantity_on_property": [513],
"readiness_state_on_property": [],
"sku_on_property": [102868018123]
}

Example Response

{
"error": "There was a problem with /inventory. Total products 2501 exceeds maximum allowed 2500 for 3 variations."
}

Removing the Third Variation#

To remove the third variation, use the updateListingInventory endpoint. Set the query parameter max_variations_supported to 3 and remove the variation property from property_values. Ensure that *_on_property fields only have properties used in the new inventory.

Examples#

  • Context:
    • Request for listing with three variations, payload removes a variation
    • Query parameter max_variations_supported is set to 3. (max_variations_supported=3)
  • Response changes:
    • All products[].property_values have two elements.
    • The *_on_property fields may have zero, one, or all two properties.

Example Payload

{
"products": [
{
"offerings": [
{
"price": 10.0,
"quantity": 1,
"is_enabled": true,
"readiness_state_id": 1020304051823
}
],
"property_values": [
{
"property_id": 513,
"property_name": "My custom variation",
"value_ids": [1474406756737],
"values": ["Custom value 1"],
"scale_id": null
},
{
"property_id": 102868018123,
"property_name": "Gemstone",
"value_ids": [1014715895892],
"values": ["Agate"],
"scale_id": null
}
],
"sku": ""
}
// ...other products with two variations
],
"price_on_property": [],
"quantity_on_property": [],
"readiness_state_on_property": [],
"sku_on_property": []
}

Example Response

{
"products": [
{
"product_id": 30328811353,
"sku": "",
"is_deleted": false,
"offerings": [
{
"offering_id": 123456284729,
"quantity": 1,
"is_enabled": true,
"is_deleted": false,
"price": { "amount": 1000, "divisor": 100, "currency_code": "USD" },
"readiness_state_id": 1020304051823
}
],
"property_values": [
{
"property_id": 513,
"property_name": "My custom variation",
"scale_id": null,
"scale_name": null,
"value_ids": [1474406756737],
"values": ["Custom value 1"]
},
{
"property_id": 102868018123,
"property_name": "Gemstone",
"scale_id": null,
"scale_name": null,
"value_ids": [1014715895892],
"values": ["Agate"]
}
]
}
// ...other products with two variations
],
"price_on_property": [],
"quantity_on_property": [],
"sku_on_property": [],
"readiness_state_on_property": []
}