Product customisations and add-ons with custom order line attributes

It is possible to create custom attributes on the level of an order line (or selection line), making it easy to implement additional checkout features like paid add-ons (engravings, gift messages) or save other meta-data for each item in your basket. These are later visible on the orders in the AMS backend, as well as in Integration API, so that your post-sale integrations can make use of those attributes as well.

Overview

Basket and order line custom attributes let you attach structured metadata to a specific line item. Values are set on basket lines in the storefront and carried over to order lines after checkout, making them available in Centra AMS and in downstream integrations (ERP/WMS/ESP).

This is commonly used for product customisations, but it also supports broader operational use cases such as fulfillment routing, packing instructions, lead-time messaging, and status tracking.

Use cases

While custom attributes are highly flexible, they generally fall into two strategic areas

Paid product customisations and add-ons

This is the most common use case. By creating "Service Product" or "Add-on Product" in Centra, you can represent customizations that carry their own price.

How it works

Create a separate product (e.g., “Engraving Service” or “Gift wrapping”) and use line attributes to store the specific value (e.g., engraving text or wrapping type). You can also use variants to charge for different options—such as engraving length or premium gift wrap types.

Benefits

Enables charging for customisations and add-ons while keeping the data clean and transferable to downstream systems.

info

Read more about how to set up paid product customisations in the second article.

Unpaid product customisations and operational metadata

This area covers data that doesn’t represent a physical “add-on,” but still affects how an order is fulfilled or handled (think: a non-paid add-on).

How it works:

No separate product is needed — simply attach values directly to the main product line(s) in the storefront.

Benefits:

Enables operational flexibility and supports more personalised customer experiences without altering the product catalogue.

Examples include:

• Gift messaging: storing item-specific notes.
• Fulfillment routing: Tagging lines for different warehouse locations or processing steps (e.g., a “monogramming” station).
• Extended warranties: Linking a warranty ID or warranty terms to a high-value item.

How to set up custom order line attributes

Whether you’re supporting paid or unpaid add-ons, the initial setup steps are the same.

Step 1: Create order line attribute in Centra

To enable order line attributes, you must first create an attribute within the Centra configuration.

• Navigate to System → Configuration in Centra
• Click the Create attribute type button.
• Define your custom attribute following the Centra Developer Documentation.
• Set the attribute group to order_line.

info

Note that line attributes are restricted to the following types: select, textarea, input, boolean.

Step 2: Configuring order line attributes visibility on the order view

To ensure your customer service and fulfillment teams can see line attributes efficiently, you can configure the attribute visibility by toggling the showOnLine property on specific elements.

Value	Visibility Behavior
true	The attribute is displayed immediately in the main Order View.
false (default behaviour)	The attribute is hidden in the main view; it is only accessible by clicking the "Details" button on the order line.

Step 3: Enable attributes in the Storefront API plugin

After configuring the attributes in the configuration view, you must explicitly enable them within the Storefront API plugin to allow attributes to be set via API calls.

1. Open your Centra AMS and navigate to the Storefront API plugin settings.
2. Locate the Line attributes settings section.
3. Enable the specific order line attributes you wish to expose to your frontend.

info

Note: If an attribute is not enabled within the plugin, the Storefront API will ignore any attempts to pass data for that field, even if it is correctly configured in the attribute types.

Check which attributes are available to be updated via Storefront API

Once your attributes are configured and enabled in the plugin, you can programmatically retrieve them via the Storefront API. This ensures your frontend always knows which attributes are valid to send back in the mutations described in Step 4.

Query: availableLineAttributes

Step 4: Set attributes on order lines via the Storefront API

The Storefront API supports attribute assignment through several mutations. You can define attributes using dynamicAttributes for custom values or mappedAttributes for predefined attributes.

1. How to assign attributes to lines when adding products to a basket?

To attach data to a product line, pass the attribute values when adding the item to the basket

Mutation: addItem

Mutation: addFlexibleBundle

2. How to update order line attributes on existing order lines?

You can update or remove attributes for items already in the cart using setLineAttributes and unsetLineAttributes.

tip

There’s line splitting logic: Without specifying quantity, the entire line is updated. When using quantity parameter, the line is split. One part remains unchanged, while a new line is created for the specified quantity with the updated attributes.

Mutation: setLineAttributes

Mutation: unsetLineAttributes

Assigning attributes to only some products in the order line:

• You can assign attributes to any quantity of a product.
• Assigning different attributes to the same SKU (e.g., two identical shirts with different monograms) will automatically create separate lines in the basket. For example
  • Basic T-shirt, Red, Size S - Qty 1 - Embroidery “Moody“
  • Basic T-shirt, Red, Size S - Qty 1 - Embroidery “Grumpy“
• Essentially, if there are any differences in attributes for the same product, it will always be split into multiple lines. But if the attributes are the same, it will remain as one line on the basket and later the order.

Step 5: Order management and export

Once the order is placed, line attributes are displayed in Centra according to your visibility settings.

info

Attribute elements with showOnLine: true are included in line product name.

Integration API export

When fetching orders via the Integration API, all line attributes are included on the order line objects so downstream systems (ERP/WMS) can consume the customisation/operational metadata.

query orderAttributes($number: Int) {
    order(number: $number) {
        lines {
            attributes {
                ... on MappedAttribute {
                    id
                }
                type {
                    name
                    isMulti
                }
                elements {
                    key
                    description
                    kind
                    ... on AttributeStringElement {
                        value
                    }
                    ... on AttributeChoiceElement {
                        selectedValue
                        selectedValueName
                        isMulti
                    }
                }
            }
        }
    }
}

Step 6: Updating attributes post-purchase

Currently, updating order line attributes after an order is placed is only possible via the Integration API, and not possible in the Centra order view.

Supported patterns:

• Full line updates: Update all attributes on a line.
• Partial updates by quantity: If a line has quantity 5 but only 1 unit needs a change, the API can support splitting the line or targeting a partial quantity.

Mutation: assignAttributes

Mutation: unassignAttributes

How to modify attributes for only a fraction of a line item?

When you need to modify attributes for only a fraction of a line item (e.g., changing the customization for 1 unit out of an existing 5), the system utilizes an atomic Cancel-and-Add workflow via the updateDirectToConsumerOrder mutation.

Instead of "editing" the existing line, you are essentially splitting it: removing the target quantity from the original line and instantly replacing it with a new, correctly configured line.

Mutation: updateDirectToConsumerOrder

Core Principles for Success

Because this operation creates a brand new line, keep these technical requirements in mind:

• No Attribute Inheritance: The system will not copy attributes from the original line. You must explicitly provide the full set of required attributes in the addLines block.
• Data Consistency: To maintain order integrity, you must manually ensure the displayId, sizeId, unitPrice and any other custom field match the original line exactly.
• Status: Orders can only be modified until they have been shipped.
• Allocation: Following a split, each new line requires an independent allocation.

Allocation

Once a new line with updated attributes is added, it must be allocated from the same warehouse as the cancelled line.

Mutation: allocateOrder