Skip to main content

Personalizations on lines

Some things are not in the catalog: a name to engrave on a ring, a message for a card, a colour the customer types in. They do not change the variant, the price or the stock, but they must travel with what is bought. For this, every line of the cart and of the order can carry additionalData: pairs of text and text.

{ "name": "Anna", "font": "serif" }

The store does not read what is inside: it keeps it, compares it and brings it to the order. What it means is up to your site and to your checkout hooks.

A line is the variant and its data​

A line is a variant together with its data:

  • the same variant with the same data is one line, and the quantity adds up (the order of the keys does not matter);
  • the same variant with other data is another line: two rings with two names are two lines;
  • no data, null and {} are the same thing: a line with no data, exactly as every line was before.

Stock, instead, is the stock of the variant: the quantities of all its lines add up, and if together they are more than what is in stock, every one of those lines is shown as not available. The same goes for what sells best: the best sellers are counted per variant, whatever the data.

Limits​

WhatLimit
Keysup to 20
A key1 to 64 characters
A valuetext, up to 500 characters

Anything that is not text, or goes over a limit, is refused with a 400 and nothing is saved.

Where the data goes​

  1. The cart. The guest's cart (kept in the browser) and the customer's cart keep it with the line. When a guest signs in, the lines are merged into the customer's cart with their data: a line the customer already has, with the same data, is added to; another one is a new line.
  2. The checkout. The quote and the payment take the lines with their data, and the checkout hooks receive additionalData on every line (null when it has none). An operation of a hook that targets a line names it by variant and data when the variant is in the cart with different data; the same variant twice with the same data is refused with CART_DUPLICATE_ITEMS.
  3. Stripe. The line on the payment page of Stripe shows the data after the options, as key: value, so the customer can read what they are paying for.
  4. The order. Every order line keeps the data it was bought with. Two lines of the same variant with different data stay two lines of the order. You can read them in the API and in the order events, and the admin shows them in the Details column of the items of an order, also for the orders that come from Stripe.

From the SDK​

With the commerce SDK the data goes in the line you add, and the same pair of variant and data names the line when you change or remove it:

await commerce.cart.add({
variantId,
priceId,
quantity: 1,
additionalData: { name: "Anna", font: "serif" },
});

// the line of that variant with that data
await commerce.cart.setQuantity({ variantId, additionalData: { name: "Anna", font: "serif" } }, 2);
await commerce.cart.remove({ variantId, additionalData: { name: "Anna", font: "serif" } });

A text instead of an object (cart.remove(variantId)) means the line of that variant with no data, as it always did. The React hook (useCart, see React) takes and gives the same data.

Through the API​

POST /cart, POST /cart/merge and POST /cart/total take additionalData on every line, and the cart answers with it. PATCH and DELETE of /cart/{id} act on the line with that id, which is the one with its data. The quote and the payment of the checkout API take it on the lines, as the pages of the API reference say.