Skip to main content

Item Variants

Arcadier Support

Variants (e.g. Color, Size) represent purchasable configurations of an item while variant options refer to the specific attributes within a variant (e.g. Red, Blue, or Small, Large). Depending on your use case, variants may represent SKU options (for retail) or configurable attributes (for services, rentals, or subscriptions). Merchants can create parent items, variants and variant options within the seller portal UI, including their name and definitions.

Relationship between parent item and variants

  • The parent item (e.g., T-shirt) is what buyers see.
  • Variants (e.g., Color, Size) appear as dropdown options on the item page - See diagram above.
  • Variant options (e.g., Red, Blue) appear within those dropdowns - See diagram above.

System and API representation - For Developers

Each unique combination of variant options generates a distinct child item ID under the parent item. Each child item has its own unique GUID, can maintain its own stock quantity, and can maintain its own price override (if configured). Inventory is therefore managed at the child item level, not at the parent level.

Key Rules

  • Cart and Checkout APIs, must use child item IDs, not parent item IDs.
  • Submitting a parent item ID to Cart APIs returns a null response.
  • Inventory is managed at the child item level.

How variants map to child items

Each variant combination generates a unique child item ID. For example, a T-shirt with 3 sizes × 3 colors × 3 styles produces 27 child items, each with its own ID.

When a buyer selects a variant, the Cart API expects that variant's child item ID — not the parent.

JSON Structure - Item with variants

Child items are returned as an array nested inside the parent item response. Each child item is a full item object with its own ID, SKU, and pricing.

{
  "ID": "parent_item_ID",
  "SKU": "string",
  "Price": 0,
  "HasChildItems": true,
  "ChildItems": [
    {
      "ID": "child_item_ID",
      "SKU": "string",
      "Price": 1,
      "Variants": [{ "Name": "Black", "GroupName": "Color" }],
      "HasChildItems": false,
      "ChildItems": []
    },
    {
      "ID": "child_item_ID",
      "SKU": "string",
      "Price": 1,
      "Variants": [{ "Name": "White", "GroupName": "Color" }],
      "HasChildItems": false,
      "ChildItems": []
    }
  ]
}

JSON Structure - Adding an item to cart

POST /api/v2/buyers/{buyerID}/carts
{
  "ItemDetail": { "ID": "child_item_ID" },
  "Quantity": 1
}

See Item/Bookings API reference for more details.

 

Related to

Related articles