> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Order costs

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

The relevant [meta fields](/docs/orchestration/payment-acceptance/meta-fields) in the `order` object are:

| Field | Description |
| :- | :- |
| `total` | Total cost of the order, including discounts, shipping, and taxes. |
| `shipping` | Total shipping costs of the order. |
| `totalDiscount` | Total discounts of the order. Can be a single order-level field, or as the sum of discounts per line. |
| `totalTax` | Total 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:

```json theme={null}
{
  "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"
  }
}
```

<Callout>
  * 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.
</Callout>


## Related topics

- [Payment Options](/docs/overview/payment-options.md)
- [Dynamic Routing](/docs/overview/routing.md)
- [Orders Report](/docs/analytics-and-reporting/upload-files/orders-report.md)