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:

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.

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:

json

Copy

{
  "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:

json

Copy

{
  "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:

json

Copy

{
  "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
}