Line-items

The line-items action is designed to facilitate straightforward and efficient management of individual products or services within a transaction. This action is crucial in scenarios like adding, modifying, or removing items from a shopping cart or an order list. It enables merchants to streamline operations and provide customers with the flexibility to adjust their purchases as needed, such as changing quantities, selecting specific variants, or applying special instructions. This functionality not only simplifies the purchasing process for both the merchant and the customer but also enhances the overall efficiency of the transaction handling, allowing for a smoother and more responsive shopping experience.

Related Actions

This action pairs well with the following actions:

State

The final selection of items and all the details for each when the user accepted it.

Union

The target action is expected to be the next step after configuring the line items to the desired state. So this is likely a payment, but could be a payout or signature depending on the use case.

Macro level details for how union attribute behaves can be found within the Union documentation.

Features

Name	Type	Description	Rules
currency	string	Currency of the payout (ISO 3 Digit Currency Code). Optional when 'union' is not defined; not allowed when 'union' is defined. Examples: "USD".	MaxLength: 3 MinLength: 3 Pattern: ^([A-Z]*)$
variant	string	Line-item variant to define layout on GUI. Examples: "invoice", "cart".	Possible values: `invoice`, `cart`.

Context (required)

Name	Type	Description	Rules
items	array	(required) Items in the line items payload.	See items
modifiers	array	Modifiers show up at the end of the invoice display to modify the totals. Modifiers are displayed and calculated in the order presented.	See modifiers

items

Name	Type	Description	Rules
name	string	(required) A unique id (within this instance) for this line item. Examples: "ref-x1234".	MaxLength: 256 MinLength: 1
unit	string	The label for the units of this item. Examples: "kg", "Job".	MaxLength: 32 MinLength: 1
label	string	A customer friendly title or name of this option. Examples: "Item Label".	MaxLength: 128 MinLength: 1
description	string	A detailed description of the option, can include a light level of markdown like titles, bullet points and paragraphs. Examples: "Item Description".	MaxLength: 65536 MinLength: 1
sku	string	The sku from the inventory system for this option. Examples: "SKU12345".	MaxLength: 512 MinLength: 1
quantity	number	Quantity of the item.
amountPer	number	(required) Amount in cents per item.
features	object	Features of the option.

modifiers

Name	Type	Description	Rules
name	string	(required) Layman friendly name of this modifier.	MaxLength: 128 MinLength: 1
amount	number	(required) A negative or positive modifier. If an integer is used it is presumed to be an amount in cents. If a decimal is used, then it is presume to be a percentage.

Example

Below is an example payload for adding an Line-items action to a business process or blueprint.

{
    "type": "line-items",
    "union": 1,
    "context": {
        "modifiers": [
            {
                "name": "VAT",
                "amount": 0.2
            }
        ],
        "items": [
            {
                "features": {
                    "noDelete": true,
                    "noQuantity": false,
                    "color": "HexValue",
                    "image": "<image-path>",
                    "icon": "material-design-icon-name"
                },
                "quantity": 1,
                "unit": "kg",
                "name": "Annual hospital association dues.",
                "amountPer": 20000,
                "description": "Choose the amount of dues you owe.",
                "label": "Annual hospital association dues.",
                "sku": "Annual hospital association dues."
            }
        ]
    },
    "features": {
        "variant": "invoice",
        "currency": "CAD"
    }
}