Product Option Exceptions

Overview

You can use exceptions to make specific combinations of product options that the customers won't be able to select. For example, if you sell a T-shirt in various colors and sizes, you can make a certain color unavailable for a specific size.

Exceptions are somewhat similar to option combinations—they both include the combination object with variants of different options.

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

Understanding Option Exceptions

Only the options that have variants can be a part of an exception. This includes options of the following types: Checkbox, Select box, and Radiogroup.

Exception Types

There are two types of exceptions:

Forbidden — customers won't be able to select the combinations of option variants specified in the combination object.
Allowed — customers will be able to select ONLY the combinations of option variants specified in the combination object.

The type of the exception is determined by the product that the exception is associated with. A product has a field called exceptions_type, that can have either A (allowed) or F (forbidden) as its value.

Note: F (forbidden) is the default value of the exceptions_type field of the product.

API Endpoints

GET /api/2.0/products/{product_id}/exceptions

Retrieves all option exceptions for a specific product.

GET /api/2.0/products/{product_id}/exceptions/{exception_id}

Retrieves details for a specific option exception.

POST /api/2.0/products/{product_id}/exceptions

Creates a new option exception for a product.

PUT /api/2.0/products/{product_id}/exceptions/{exception_id}

Updates an existing option exception.

DELETE /api/2.0/products/{product_id}/exceptions/{exception_id}

Deletes an option exception.

Exception Structure

{
  "exception_id": "42",
  "product_id": "423",
  "combination": {
    "16": "43",  // option_id: variant_id (Color: White)
    "17": "52"   // option_id: variant_id (Size: XL)
  }
}

In this example, if the product's exceptions_type is:

F (forbidden) - Customers won't be able to select the "White" color in "XL" size
A (allowed) - Customers will only be able to select the "White" color in "XL" size, and no other combinations

Example: Creating a Forbidden Combination

// First, set the exceptions_type for the product (if needed)
PUT /api/2.0/products/423

{
  "exceptions_type": "F"  // F - forbidden, A - allowed
}

// Then create the exception
POST /api/2.0/products/423/exceptions

{
  "combination": {
    "16": "43",  // Color: White
    "17": "52"   // Size: XL
  }
}

Use Cases

Forbidden Exceptions

Use forbidden exceptions (exceptions_type="F") when most combinations are valid and you only need to exclude a few specific ones. Common use cases include:

Certain color/size combinations that are not manufactured
Option combinations that are temporarily out of stock
Incompatible feature combinations

Allowed Exceptions

Use allowed exceptions (exceptions_type="A") when only a few specific combinations are valid and most combinations should be unavailable. Common use cases include:

Products with strict manufacturing constraints
Products where only certain combinations make logical sense
When launching a new product with limited initial option combinations

Tip: For most products, forbidden exceptions are more practical as they require less maintenance. With allowed exceptions, you need to create an exception for every valid combination.

Best Practices

Use Sparingly - Too many exceptions can make product management complex
Keep Updated - Review exceptions regularly as inventory and manufacturing capabilities change
Communicate Clearly - Make sure your product descriptions explain why certain combinations are unavailable
Choose the Right Type - Select either "forbidden" or "allowed" exceptions based on which requires managing fewer combinations

Important: When working with option exceptions, ensure your frontend properly handles the user interface to prevent customers from selecting invalid combinations. This typically involves disabling or hiding option variants based on the customer's current selections.