Some products require user input before they can be added to a cart—such as selecting a player on a jersey, choosing engraving text, or configuring attributes.
Diddo supports these through a structured customizations object returned in the /products response.
Your application should:
- Render the customization fields in the UI
- Capture the user’s selections or inputs
- Send those selections back when calling
POST /cart/add
This guide explains how to interpret the customizations field and map it correctly to the cart request.
📘Dynamic Customization Schema
Customization schemas are returned directly with each product.
This allows clients to dynamically render configuration UI without hardcoding product-specific logic.
🧩 How Customizations Work
When a product supports customization, the /products endpoint returns a customizations array describing the required inputs.
Each customization object contains the information needed to render the UI and validate user input.
| Field | Description |
|---|---|
key | Unique identifier for the customization |
type | Input type (single_select, multi_select, text) |
label | Display label for the UI |
is_required | Whether the user must provide a value |
options | Allowed values for select inputs |
config | Validation rules for text inputs |
Example response from GET /products:
json🎯 Customization Types
Select Inputs
Used when the user must choose from predefined options.
| Type | Description |
|---|---|
single_select | Choose one option |
multi_select | Choose multiple options |
Each option contains:
| Field | Description |
|---|---|
value | The value sent back to the cart API |
label | Display text for the UI |
metadata | Optional additional data (e.g. jersey number) |
Example UI options:
| Label | Value |
|---|---|
| Jordan, Michael | 23 |
| Pippen, Scottie | 33 |
💡Important
Always send the
valuefield from the option object when submitting a cart request.
Text Inputs
Used when the user enters custom text (e.g. engraving or jersey name).
Text customizations include validation rules in the config object.
| Config Field | Description |
|---|---|
max_length | Maximum allowed characters |
pattern | Regex pattern used for validation |
Example:
jsonClient applications should validate these rules before submitting the cart request.
🔁 Mapping Customizations to Cart Requests
When adding a product to a cart, send the selected values inside the customizations array.
The structure depends on the customization type.
Product type | Cart field | Value source |
|---|---|---|
single_select / multi_select | value | One of options[].value |
text | text_value | Free string entered by the user |
Example POST /cart/add request for type text:
jsonExample POST /cart/add request for type single_select / multi_select:
javascript🧭 Implementation Flow
Typical client-side flow for customizable products:
1. Fetch products
plain2. Check for customizations
If present, render UI inputs based on the schema.
3. Collect user input
Store the selected values using each customization key.
4. Add to cart
Send the selections when calling:
plain⚠️ Important Notes
- Only the
valuefield should be sent to the cart API. configis only populated fortextcustomization types.optionsis only populated forsingle_select/multi_selectcustomization types.- Client-side validation should be applied for text fields before sending the request.