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
}