Product Lines, Fees, and Shipping
An order can contain three different kinds of monetary charge. Choosing the right one keeps fulfilment, invoicing, discounts, and tax behaviour predictable.
| Use | Model | Examples |
|---|---|---|
| What the customer chose to buy | Order line | Goods, digital products, services |
| A cost caused by that purchase | Fee | Handling, assembly, restocking, per-line surcharge |
| The chosen terms for moving goods | fulfillment shipping | Standard freight, express delivery, carrier option |
Use a fee for a derivative charge
A fee exists because another item is being bought. Attach it to the scope that owns the cost:
- fulfillment fee for a fulfillment-wide cost such as handling or a return surcharge.
- Order-line fee for a cost caused by one line, such as assembly or engraving.
Fees are taxable and discountable in their own right. They have a stable feeId, a type key, an amount or percentage value, optional tax information, and optional tax classifications. They do not have a native line number and cannot be released to invoicing independently: a fulfillment fee invoices when its fulfillment is released (releaseFulfillmentToInvoicing — one release covers native shipping and fulfillment-scoped fees), and an order-line fee invoices when its line is released.
Entity-scoped discounts (a line discount, a shipping discount, or a fee's own discount) apply only to that entity. A static order discount, by contrast, is order-wide: it distributes across every active cost-bearing entity — order lines, native shipping, and fees — so a 100% order discount reduces the active order total to zero, regardless of fees.
Use addFulfillmentFee or addOrderLineFee to create one. Use setFeeTaxClassifications when an integration owns its tax classification.
Keep ordinary shipping on the fulfillment
Shipping is not a fee type. It is a native property of the fulfillment because it represents the customer's selected shipping option and the fulfilment act that moves the order's goods.
Use the fulfillment's shipping product number, description, price, discounts, and tax fields for ordinary freight. A shipping provider can use its carrier option as the shipping product number without turning it into an order line or a fee.