Personalized products
General
Use cases
Customers often appreciate the option to add a personal touch to their purchases, such as adding a custom message to a gift, or a name on towels and blankets. SCAYLE refers to these offerings as personalized or customizable products.
Personalized products
At their core, personalized products follow SCAYLE's standard product data structure. This means they are created through either the Admin API or the SCAYLE Panel, complete with a master, product, and variant structure. Here's a breakdown:
Product entity | Description | Example | Comment |
---|---|---|---|
Master | Product style | “Towel with embroidered name 50x100 cm” | |
Product | Color level | red | |
Variant | Size level | 50x100 cm | If only one size is available, label as “one size”. |
Personalizing a product often requires input fields in the shop frontend. This information is then integrated into order details and passed to the order management system.
You don't need a separate variant just for personalization. SCAYLE simply provides additional info to the order management system.
Storefront API
Transfer custom data to the basket
When selling personalized products, you'll need to transfer custom text from the shop frontend to the basket. This is where the customData
parameter becomes essential.
Details about customData
and the relevant add-to-basket
endpoint of the Storefront API can be accessed in the Storefront API Documentation.
Example add-to-basket
request with personalization:
{
"customData": {
"message": "Hello"
},
"displayData": {},
"quantity": 1,
"shopId": 10001,
"variantId": 45
}
The customData
parameter can be defined freely. While message
serves as one example, you can introduce multiple data fields as required. For a more complex use case, consider structuring it as an array that pairs parameters with their respective values:
{
"variantId": 7,
"quantity": 1,
"customData": {
"services": [
{
"key": "gift_wrapping",
"value": true
}
]
}
}
Admin API
Custom data in the order
All the custom data is automatically available in order details via the Admin API.
To retrieve this information in the response of the getOrder
endpoint, include the parameter?with=items.legacyCustomData
in your request.
Further details on the order endpoint can be found in the Admin API Specification.
Example
Below is a snippet from the Admin API response showcasing how custom data appears.
For example, gift_wrapping
in the legacyCustomData
section:
{
"packageId": 1,
"price": {
"withTax": 80,
"withoutTax": 67,
"appliedReductions": [
{
"category": "sale",
"type": "relative",
"amount": {
"relative": 0.2,
"absoluteWithTax": 20
}
}
],
"tax": {
"vat": {
"amount": 13,
"rate": 0.19
}
}
},
"status": "available",
"key": "1ff1de774005f8da13f42943881c655f",
"product": {
"id": 7,
"name": "ARC'TERYX JAS ZWART NL"
},
"id": 24,
"warehouseId": 1,
"variant": {
"id": 7,
"referenceKey": "13243187M"
},
"reservationKey": "1718",
"legacyCustomData": {
"services": [
{
"key": "gift_wrapping",
"value": true
}
]
},
"itemGroup": null
}