Order Line Types

This guide will go through the different types of line items that can be passed through our carts and how they behave

Gift Cards

Gift cards are handled as a dedicated productType in the cart, allowing full control and clarity in both session creation and order management. Unlike standard order lines, they follow specific rules for VAT, amount handling, and lifecycle events like capture and refund.

Gift card order lines

Gift cards are represented as separate order lines with productType: "gift_card". They are different from regular order lines in the sense that they don't include unitPrice, taxRate, or discountPercentage. Instead, a giftCardAmount is used to indicate the value.

• Positive amount = buying a gift card
• Negative amount = redeeming a gift card

Example 1: Using a gift card

"cart": [
  {
    "productType": "gift_card",
    "reference": "giftcard-123",
    "name": "Gift Card",
    "giftCardAmount": -1200
  }
]

Example 2: Buying a gift card

"cart": [
  {
    "productType": "gift_card",
    "reference": "giftcard-456",
    "name": "Gift Card",
    "giftCardAmount": 1500
  }
]

Order totals and tax behavior

Gift cards are always exempt from tax and never affect the orders amountExVat. This allows you to maintain correct taxable totals even when gift cards are applied.

Important notes:

• amountIncVat includes the giftCardAmount.
• amountExVat does not include any gift card lines.
• This means amountIncVat can be lower than amountExVat, or even zero, in cases where a gift card is used.

Order Management with gift cards

Gift card line items should be included when performing order management functionality like captures and refunds, as the most important part is that the correct amount is captured/refunded.

However, different payment providers handle gift cards in different ways, so if you use gift cards in your business you need to make sure to inform your payment providers of this in case any special requirements are needed.

For example some providers do not support partial captures if a gift card is involved, and in those cases it's recommended to either use full captures, or hide the payment method for orders containing a gift card.

And when it comes to partial refunds, gift card line items cannot be partially refunded, so instead an adjustment refund should be used.

Sales Tax Line Item

In some markets such as the United States, sales tax must be presented as a separate line item rather than being included in the product price. To support this, you can include a dedicated sales_tax line item in the cart array.

This line item represents the total tax charged on the order. It should reflect the full sales tax amount for the order, as calculated externally (e.g., using a tax engine).

Line Item Structure

{
  "productType": "sales_tax",
  "name": "Sales tax",
  "reference": "sales_tax",
  "totalTaxAmount": 1200
}

Field Descriptions

Field	Type	Required	Description	Example
productType	string	yes	Must be set to "sales_tax"	"sales_tax"
name	string	yes	Display name for the line item	"Sales tax"
reference	string	no	Optional internal reference	"sales_tax"
totalTaxAmount	integer	yes	Total sales tax amount in minor units (e.g., 1 USD = 100)	1200

Notes

• sales_tax items do not have unitPrice, taxRate, or discountPercentage.
• This line item is only used for tax systems where tax must be shown separately (e.g., U.S.).
• totalTaxAmount should reflect the final tax for the full order.
• This item is optional and should only be used in relevant regions.

Example Cart with Sales Tax

"cart": [
  {
    "productType": "physical",
    "reference": "shirt123",
    "name": "T-shirt",
    "quantity": 1,
    "unitPrice": 2000,
    "taxRate": 0,
    "discountPercentage": 0
  },
  {
    "productType": "sales_tax",
    "name": "Sales tax",
    "reference": "sales_tax",
    "totalTaxAmount": 160
  }
]

In this example, the physical item does not include tax, and the tax is reported separately using a sales_tax line item.