Order costs

This guide presents examples of how to send the different costs associated with an order.

The relevant meta fields in the order object are:

FieldDescription
totalTotal cost of the order, including discounts, shipping, and taxes.
shippingTotal shipping costs of the order.
totalDiscountTotal discounts of the order. Can be a single order-level field, or as the sum of discounts per line.
totalTaxTotal tax of the order. Can be a single order-level field, or as the sum of taxes per line.

If you have the breakdown per order line, you can send it in each object on the order.lines list:

Field

Description

type

The type of line, useful if you allow applying many discounts or taxes to your order.
Possible values:

  • lineItem: (default) regular order line item
  • discount: discount line, e.g. voucher, promo code, etc.
  • tax: tax line, e.g. VAT, IVA, etc.

quantity

Count of items per line. Should be "1" if type is not lineItem.

unitPrice

Unit price of the item.

totalDiscount

Discount on the item.

taxAmount

Tax cost applied to the item.

taxPercentage

Tax percentage that applies to the item.

total

Total cost of the item, including discount and taxes.

Example

Let's say you have:

  • Item 1, which costs $10, but has a discount of $1
  • Item 2, which costs $3 per unit, and you order 2 units
  • The cost of shipping for the order is $4
  • A discount of $2 on the shipping (e.g. after a certain amount, your shipping cost is reduced)
  • A "Voucher 1" of $3 that applies a discount on the entire order
  • The total tax of $1 that applies to the entire order
  • The total amount of your order (after including taxes, shipping, and applying discounts) is $15

So what you send as the order meta field to Payrails looks like:

{
  "lines": [
    {
      "type": "lineItem",
      "name": "Item 1",
      "quantity": 1,
      "unitPrice": {
        "currency": "EUR",
        "value": "10"
      },
      "totalDiscount": {
        "currency": "EUR",
        "value": "1"
      }
    },
    {
      "type":"lineItem",
      "name":"Item 2",
      "quantity": 2,
      "unitPrice": {
        "currency": "EUR",
        "value": "3"
      }
    },
    {
      "type":"discount",
      "name":"Voucher 1",
      "quantity": 1,
      "unitPrice": {
        "currency": "EUR",
        "value": "3"
      }
    },
    {
      "type":"discount",
      "name":"Shipping discount",
      "quantity": 1,
      "unitPrice": {
        "currency": "EUR",
        "value": "2"
      }
    }
  ],
  "shipping": {
    "currency": "EUR",
    "value": "4"
  },
  "totalTax": {
    "currency": "EUR",
    "value": "1"
  }
}

📘

  • If you don't need to specify different taxes or discounts as lines, you can use the totalTax or totalDiscount fields on the order level.
  • If you have the breakdown of items, you don't need to specify the order.total and lines[*].total, we will calculate it for you.