Venddor API - Option Combination Details

Product Option Combinations

Option combinations allow you to manage product variations based on different option selections. For example, a T-shirt might have combinations of size and color options (e.g., "Small/Red", "Medium/Blue"). This documentation describes the fields and properties of option combinations in the Venddor API.

Note: The Venddor REST API always accepts and returns data as strings and arrays/objects. The data types shown in the "Values" column below indicate the logical data type of each field, not the format in which they are transmitted.

Option Combination Fields

The following table provides a comprehensive list of all fields available for product option combinations:

Parameter	Values	Description
product_id	integer	The unique identifier of the product that the option combination is associated with.
product_code	string	The product code of the option combination. This can be used as a SKU (Stock Keeping Unit) for inventory management.
combination_hash	string	The hash of the option combination, which serves as a unique identifier for the specific combination of option variants.
combination	object	The options and variants that comprise the combination. This object contains key-value pairs where the key is the option_id and the value is the variant_id.
amount	integer	Determines how many items of this combination are in stock. This field is used for inventory tracking.
position	integer	The lower this number, the higher the option combination appears on the list in the Administration panel.
image_pairs	object	The information about the images associated with the option combination. This allows for different product images based on the selected combination (e.g., different images for different color variants).

Tip: Using unique product_code values for each combination makes inventory management and order fulfillment much easier, especially for products with many variations.

Example Option Combination Object

{
  "product_id": "101",
  "product_code": "TSH-BLK-M",
  "combination_hash": "842135592",
  "combination": {
    "12": "35",  // Size (option_id: 12) = Medium (variant_id: 35)
    "14": "41"   // Color (option_id: 14) = Black (variant_id: 41)
  },
  "amount": "25",
  "position": "20",
  "image_pairs": {
    "pair_id": "123",
    "image_id": "456",
    "detailed_id": "789",
    "position": "0",
    "detailed": {
      "image_path": "http://example.com/images/detailed/0/tshirt_black_m.jpg",
      "alt": "Black T-shirt Medium Size",
      "image_x": "800",
      "image_y": "1200",
      "http_image_path": "http://example.com/images/detailed/0/tshirt_black_m.jpg",
      "https_image_path": "https://example.com/images/detailed/0/tshirt_black_m.jpg"
    },
    "icon": {
      "image_path": "http://example.com/images/thumbnails/0/tshirt_black_m_thumb.jpg",
      "alt": "Black T-shirt Medium Size",
      "image_x": "200",
      "image_y": "300",
      "http_image_path": "http://example.com/images/thumbnails/0/tshirt_black_m_thumb.jpg",
      "https_image_path": "https://example.com/images/thumbnails/0/tshirt_black_m_thumb.jpg"
    }
  }
}

Working with Inventory and Option Combinations

Option combinations are particularly important for inventory management. When a product has multiple options (like size and color), each unique combination can have its own inventory level.

Inventory Management:

For inventory tracking to work with option combinations, you need to ensure:

The product has the inventory tracking feature enabled
The relevant options have the inventory="Y" setting
Each desired combination has a specified amount value

API Endpoints for Option Combinations

GET /products/{product_id}/option_combinations

Retrieves all option combinations for a specific product.

Path Parameters

Parameter	Type	Required	Description
product_id*	integer	Yes	The unique identifier of the product

GET /option_combinations/{combination_hash}

Retrieves details of a specific option combination.

Path Parameters

Parameter	Type	Required	Description
combination_hash*	string	Yes	The unique hash of the option combination

POST /products/{product_id}/option_combinations

Creates a new option combination for a product.

Path Parameters

Parameter	Type	Required	Description
product_id*	integer	Yes	The unique identifier of the product

Request Body Parameters

Parameter	Type	Required	Description
product_code	string	No	The product code for this specific combination
combination*	object	Yes	The options and variants that comprise the combination
amount	integer	No	The quantity in stock for this combination
position	integer	No	The position of this combination in the list

Important: When creating option combinations, ensure that all option IDs and variant IDs specified in the combination object exist and are associated with the specified product. Using invalid option or variant IDs will result in an error.