Price List Elements

Additional charges a price list carries on top of its unit amount, how they are calculated, and how they appear in the API, imports, exports and approvals.

Overview​

A price list element is an additional charge attached to a price list: a tariff, a surcharge, a duty, a levy or a handling fee. The product UI calls them additional charges.

Elements let you keep the base unit_amount as the price of the goods and declare the extra charges separately, so buyers can see what makes up the price they pay, and buyers' approvers can see exactly which charges changed.

Key points:

• Elements are additive. The resolved price a buyer pays is the unit amount plus every element on the price list.
• Elements belong to one price list. They are created with the price list and, like the price list itself, they cannot be edited afterwards. Changing a charge means creating a new price list.
• A price list carries up to 5 elements.
• Elements are accepted on the standard, volume and graduated billing schemes, for products, product variants and services. They are rejected on quote and external price lists, which carry no price of their own.
• An element change is a price change. A new price list that only changes its elements still needs the buyer's approval, and it is never auto-approved.

Element Fields​

Types​

The type is a label for the buyer, it does not change the calculation. Use other for a charge none of the named types describe, and give it a description.

Amount types and apply per​

apply_per is required whenever amount_type is fixed. For percentage elements it may be omitted; the platform stores and returns it as unit.

How Elements Are Calculated​

Elements are applied in the pricing pipeline after promotions and field price modifiers, and before tax and shipping.

The rules:

1. All figures are per unit. The per-unit price after tiers, promotions and modifiers is the base every element is applied to.
2. Percentage elements never compound. Every percentage element takes its share of the same base price, so two 10% elements add 20%, not 21%.
3. Fixed per-unit elements are added as they are.
4. Fixed per-line elements are charged once for the order line and spread over the quantity being priced, in the same way a volume tier's flat_amount is folded into the unit price. At a quantity of 1 the whole amount lands on that unit.
5. Tax follows the price list. Elements are added before tax, so tax is calculated on goods plus elements. When the price list is tax_behaviour: inclusive, element amounts are treated as tax inclusive too, consistent with the price they are added to.
6. Currency follows the price list. Fixed amounts are in the price list currency. If the platform falls back to another currency at resolution time, the element amounts are converted together with the price.

Worked example​

A standard price list with unit_amount 100.00 CHF and these elements, resolved for a quantity of 4:

The additional charges total 19.50 CHF per unit, so the resolved unit price is 119.50 CHF and the line comes to 478.00 CHF before tax. Had the quantity been 1, the handling fee would have added the full 20.00 CHF to that single unit.

Creating Elements​

Supplier API​

Add an elements array to the Create Price List request. The same array is accepted on each entry of prices when creating a product through the Create Product endpoint.

curl --location --request POST 'https://api.axiomdata.io/api/suppliers/price-lists' \
--header 'Content-Type: application/json' \
--data-raw '{
    "priceable_type": "product",
    "priceable_identifier": "testproduct",
    "billing_scheme": "standard",
    "unit_amount": "100.00",
    "public_price": "120.00",
    "currency_code": "CHF",
    "country_code": "CH",
    "tax_behaviour": "exclusive",
    "store_id": 1,
    "elements": [
        {
            "type": "tariff",
            "amount_type": "percentage",
            "amount": 12.5,
            "description": "EU import tariff"
        },
        {
            "type": "handling",
            "amount_type": "fixed",
            "apply_per": "line",
            "amount": 20,
            "description": "Handling fee"
        }
    ]
}'

Validation:

Price lists are validated as a whole, so a rejected element rejects the price list: no price is created without its charges.

Price list and product CSV imports​

Each element is a group of five columns, numbered 1 to 5:

In the prices CSV the columns are named exactly as above. In the products CSV, where price columns carry the price. prefix, they are price.element_1_type, price.element_1_amount_type and so on.

type,identifier,billing_scheme,tax_behaviour,price,currency,store_id,country,public_price,element_1_type,element_1_amount_type,element_1_amount,element_1_apply_per,element_1_description,element_2_type,element_2_amount_type,element_2_amount,element_2_apply_per,element_2_description
product,testproduct,standard,exclusive,100,CHF,1,CH,120,tariff,percentage,12.5,,EU import tariff,handling,fixed,20,line,Handling fee

Import behaviour:

• An element counts as filled in when any of its type, amount_type or amount cells has a value. A half-filled element fails validation for the row rather than being dropped, so a price is never imported without a charge you declared.
• A description or apply_per on its own does not declare an element.
• Column numbering does not have to be contiguous. A file with element_1_* and element_3_* columns imports both.
• The column number sets the display order (sort_order).

Where Elements Appear​

Supplier API responses​

Show Price List, List Price Lists and the product price list endpoints include an elements array on any price list that has them, ordered by sort_order. The key is omitted from price lists without elements.

"elements": [
    {
        "type": "tariff",
        "amount_type": "percentage",
        "apply_per": "unit",
        "amount": 12.5,
        "description": "EU import tariff",
        "sort_order": 0
    },
    {
        "type": "handling",
        "amount_type": "fixed",
        "apply_per": "line",
        "amount": 20,
        "description": "Handling fee",
        "sort_order": 1
    }
]

Resolved prices​

Wherever the platform resolves a price for a buyer, the response carries:

include_price_elements is accepted as a query parameter by the supplier Price Resolver endpoint and the buyer product price and service price endpoints, and as a body field on the buyer bulk price endpoint. Cart responses always itemise the elements on each cart item and total them per currency under price_elements in the cart summary.

"resolved_price": {
    "currency_code": "CHF",
    "base_price": 100,
    "modified_price": 119.5,
    "price_elements": 19.5,
    "price_element_details": [
        {
            "type": "tariff",
            "amount_type": "percentage",
            "apply_per": "unit",
            "amount": 12.5,
            "description": "EU import tariff",
            "applied_amount": 12.5
        },
        {
            "type": "surcharge",
            "amount_type": "percentage",
            "apply_per": "unit",
            "amount": 2,
            "description": null,
            "applied_amount": 2
        },
        {
            "type": "handling",
            "amount_type": "fixed",
            "apply_per": "line",
            "amount": 20,
            "description": "Handling fee",
            "applied_amount": 5
        }
    ]
}

Supplier and buyer UI​

• In the supplier portal, a price with charges shows a N charges pill in the product and service price tables and on the Approvals page. Expanding the row opens an Additional charges table listing each charge, its description, its amount and whether it applies per unit, per order line or to the unit price.
• Buyers see the same pill and breakdown on their Offer Approvals page when reviewing your offers.

Exports​

The Offer Approval export on the supplier side, and the Price Approval and Price Change Report exports on the buyer side, carry the elements of each price list in element_1_type, element_1_amount_type, element_1_amount and element_1_apply_per through to element_5_*. Descriptions are not exported. This is why a price list is capped at five elements: every charge stays visible to whoever approves the change.

Approval Behaviour​

price, price_change and price_change_percentage in approvals and exports describe the unit amount only. They do not include additional charges.

To stop an element-only change slipping past a price-based rule, auto-approval rules approve a pending price list only when its elements are identical to those of the currently approved price list for the same product, store and country (or when neither has any). "Identical" compares each element's type, amount_type, apply_per and amount; a changed description or order does not count as a change. Any other difference sends the price list to manual review, whatever the rule says about the unit amount.

Constraints Summary​