Product Option Combinations

Overview

Product options in Venddor can be grouped in option combinations—this is useful for tracking products with multiple customizable attributes. For example, clothes come in various colors and sizes. It's convenient to track separately how many blue XL T-shirts and white M T-shirts you have. Option combinations also allow you to assign unique SKUs, prices, and images for each specific combination.

Base URL: https://www.venddor.com.br/api/2.0/products/{product_id}/options/combinations

Important: A product option must have the Inventory checkbox ticked (inventory=Y) to be a part of the combination. Only the options of the Checkbox, Select box, and Radiogroup type have that checkbox.

Option Combination Structure

{
  "combination_id": "251",
  "product_id": "423",
  "product_code": "TSHIRT-BL-XL",
  "combination_hash": "16_42_17_53",  // format: option_id_variant_id_option_id_variant_id
  "combination": {
    "16": "42",  // option_id: variant_id (Color: Black)
    "17": "53"   // option_id: variant_id (Size: XL)
  },
  "amount": "25",
  "position": 10,
  "image_pairs": {
    "pair_id": "156",
    "image_id": "421",
    "detailed_id": "422",
    "position": "0",
    "detailed": {
      "object_id": "421",
      "object_type": "product_option",
      "image_path": "/var/www/html/images/detailed/422/black_xl_tshirt.jpg",
      "alt": "",
      "image_x": "800",
      "image_y": "800",
      "http_image_path": "https://www.venddor.com.br/images/detailed/422/black_xl_tshirt.jpg",
      "https_image_path": "https://www.venddor.com.br/images/detailed/422/black_xl_tshirt.jpg",
      "absolute_path": "/var/www/html/images/detailed/422/black_xl_tshirt.jpg",
      "relative_path": "images/detailed/422/black_xl_tshirt.jpg"
    }
  }
}

API Endpoints

GET /api/2.0/products/{product_id}/options/combinations

Retrieves all option combinations for a specific product.

GET /api/2.0/products/{product_id}/options/combinations/{combination_id}

Retrieves details for a specific option combination.

POST /api/2.0/products/{product_id}/options/combinations

Creates a new option combination for a product.

PUT /api/2.0/products/{product_id}/options/combinations/{combination_id}

Updates an existing option combination.

DELETE /api/2.0/products/{product_id}/options/combinations/{combination_id}

Deletes an option combination.

Key Fields Explained

product_code - A unique SKU/product code for this specific combination
combination_hash - A system-generated string that uniquely identifies the combination of option variants
combination - An object mapping option IDs to variant IDs
amount - The inventory quantity available for this specific combination
position - The display order of this combination in lists
image_pairs - Images specific to this option combination

Example: Creating an Option Combination

POST /api/2.0/products/423/options/combinations

{
  "product_code": "TSHIRT-RED-M",
  "combination": {
    "16": "44",  // Color: Red
    "17": "52"   // Size: M
  },
  "amount": "15",
  "position": 20
}

Important: When creating option combinations, make sure all the options referenced have inventory=Y. Otherwise, the API will return an error.

Bulk Operations

For products with many option combinations, it may be more efficient to use bulk operations:

POST /api/2.0/products/{product_id}/options/combinations/batch

Creates multiple option combinations in a single API call.

POST /api/2.0/products/423/options/combinations/batch

{
  "combinations": [
    {
      "product_code": "TSHIRT-RED-S",
      "combination": {
        "16": "44",  // Color: Red
        "17": "51"   // Size: S
      },
      "amount": "10",
      "position": 30
    },
    {
      "product_code": "TSHIRT-RED-L",
      "combination": {
        "16": "44",  // Color: Red
        "17": "53"   // Size: L
      },
      "amount": "12",
      "position": 40
    }
  ]
}

Use Cases

Inventory Management

Option combinations are essential for accurate inventory tracking when products have multiple variants. Each combination can have its own inventory level, allowing for precise stock management.

Custom Pricing

Different combinations can have different pricing. For example, larger sizes might cost more, or premium colors might have a surcharge.

Combination-Specific Images

Each combination can have its own image, showing customers exactly what they'll receive when selecting specific options.

Custom SKUs

Unique product codes for each combination make warehouse management and order fulfillment more efficient.

Tip: Use a consistent naming convention for your product_code values to make inventory management easier. For example, PRODUCTNAME-COLOR-SIZE is a common pattern.

Best Practices

Plan Your Option Structure - Before creating combinations, carefully plan which options will need inventory tracking
Use Batch Operations - For products with many combinations, use batch operations to create them all at once
Maintain Consistency - Use consistent naming and coding conventions across all products
Include Images - Where possible, provide combination-specific images to improve the customer experience
Regular Updates - Keep combination inventory levels updated to prevent overselling