Order costs

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:

FieldDescription
typeThe 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.
quantityCount of items per line. Should be "1" if type is not lineItem.
unitPriceUnit price of the item.
totalDiscountDiscount on the item.
taxAmountTax cost applied to the item.
taxPercentageTax percentage that applies to the item.
totalTotal 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.