# Receipt Data Reference

WCPOS logicless HTML templates and thermal XML templates render from the same canonical receipt payload. Use Mustache dot paths such as `{{order.number}}`, `{{store.name}}`, and `{{totals.total_display}}`. Arrays are rendered with sections:

```
{{#lines}}

  {{name}} x {{qty}} — {{line_total_display}}

{{/lines}}
```

The canonical contract is produced by the WCPOS receipt data builder on the server and mirrored by the offline receipt renderer in the app. Receipts open immediately from local data, then upgrade to the server response when it is available, so custom templates should use the fields below rather than PHP order methods.

## Rendering rules[​](#rendering-rules "Direct link to Rendering rules")

### Currency fields[​](#currency-fields "Direct link to Currency fields")

Numeric money fields are preserved as numbers and the renderer adds locale-aware `_display` fields for template output:

| Numeric field              | Display field                      |
| -------------------------- | ---------------------------------- |
| `totals.total`             | `totals.total_display`             |
| `lines[].line_total`       | `lines[].line_total_display`       |
| `payments[].amount`        | `payments[].amount_display`        |
| `tax_summary[].tax_amount` | `tax_summary[].tax_amount_display` |

Prefer `_display` fields when printing receipts. Use numeric fields only for conditional sections or machine-readable output.

### Tax display-aware fields[​](#tax-display-aware-fields "Direct link to Tax display-aware fields")

Several fields have inclusive and exclusive variants plus a display-side convenience value. The convenience value follows the store's cart tax display setting.

| Convenience field       | Inclusive field              | Exclusive field              |
| ----------------------- | ---------------------------- | ---------------------------- |
| `lines[].unit_price`    | `lines[].unit_price_incl`    | `lines[].unit_price_excl`    |
| `lines[].unit_subtotal` | `lines[].unit_subtotal_incl` | `lines[].unit_subtotal_excl` |
| `lines[].line_subtotal` | `lines[].line_subtotal_incl` | `lines[].line_subtotal_excl` |
| `lines[].discounts`     | `lines[].discounts_incl`     | `lines[].discounts_excl`     |
| `lines[].line_total`    | `lines[].line_total_incl`    | `lines[].line_total_excl`    |
| `fees[].total`          | `fees[].total_incl`          | `fees[].total_excl`          |
| `shipping[].total`      | `shipping[].total_incl`      | `shipping[].total_excl`      |
| `discounts[].total`     | `discounts[].total_incl`     | `discounts[].total_excl`     |
| `totals.subtotal`       | `totals.subtotal_incl`       | `totals.subtotal_excl`       |
| `totals.discount_total` | `totals.discount_total_incl` | `totals.discount_total_excl` |
| `totals.total`          | `totals.total_incl`          | `totals.total_excl`          |

### Date objects[​](#date-objects "Direct link to Date objects")

Date fields are objects with multiple preformatted variants. This avoids doing date formatting inside Mustache.

| Field                                               | Description                    |
| --------------------------------------------------- | ------------------------------ |
| `datetime`, `date`, `time`                          | Default date/time strings      |
| `datetime_short`, `datetime_long`, `datetime_full`  | Locale-aware combined formats  |
| `date_short`, `date_long`, `date_full`              | Locale-aware date-only formats |
| `date_ymd`, `date_dmy`, `date_mdy`                  | Fixed-order date formats       |
| `weekday_short`, `weekday_long`                     | Day names                      |
| `day`, `month`, `month_short`, `month_long`, `year` | Individual date parts          |

Available date objects: `order.created`, `order.paid`, `order.completed`, `order.printed`, and `refunds[].date`. `order.printed` is refreshed at render time, which is useful for reprints.

## Top-level sections[​](#top-level-sections "Direct link to Top-level sections")

| Section              | Type    | Description                                                                     |
| -------------------- | ------- | ------------------------------------------------------------------------------- |
| `order`              | object  | Order identity, status, dates, note, and payment URL information                |
| `store`              | object  | Store identity, address, contact details, tax IDs, logo, hours, and footer text |
| `cashier`            | object  | User who processed the order                                                    |
| `customer`           | object  | Customer display name, addresses, and tax IDs                                   |
| `lines`              | array   | Product line items                                                              |
| `fees`               | array   | Fee rows                                                                        |
| `shipping`           | array   | Shipping rows                                                                   |
| `discounts`          | array   | Coupon/discount rows                                                            |
| `totals`             | object  | Order totals, payment totals, refund summary, and item counts                   |
| `tax`                | object  | Tax display mode flags for section guards                                       |
| `tax_summary`        | array   | Per-rate tax summary rows                                                       |
| `has_tax_summary`    | boolean | Convenience guard for `tax_summary`                                             |
| `payments`           | array   | Payment rows                                                                    |
| `refunds`            | array   | Refund records applied to the order                                             |
| `fiscal`             | object  | Fiscal snapshot fields populated by fiscal integrations                         |
| `presentation_hints` | object  | Formatting and renderer hints                                                   |
| `i18n`               | object  | Translated labels for bundled and custom templates                              |

## Field reference[​](#field-reference "Direct link to Field reference")

The full field reference is grouped by section below. Everything is collapsed by default — expand the group you need.

order — identity, status, dates

### order[​](#order "Direct link to order")

| Field                 | Type        | Example / description                             |
| --------------------- | ----------- | ------------------------------------------------- |
| `order.id`            | number      | `1234`                                            |
| `order.number`        | string      | Human-facing order number, e.g. `"10045"`         |
| `order.currency`      | string      | ISO currency code, e.g. `"USD"`                   |
| `order.customer_note` | string      | Customer/order note                               |
| `order.wc_status`     | string      | Raw WooCommerce status slug, e.g. `"processing"`  |
| `order.status_label`  | string      | Localised status label, including custom statuses |
| `order.created_via`   | string      | Source/channel, e.g. `"woocommerce-pos"`          |
| `order.needs_payment` | boolean     | Whether a payment section should be shown         |
| `order.payment_url`   | string      | Order payment URL when available                  |
| `order.created`       | date object | Order creation date                               |
| `order.paid`          | date object | Paid date, empty strings when not paid            |
| `order.completed`     | date object | Completed date, empty strings when incomplete     |
| `order.printed`       | date object | Render-time print/reprint timestamp               |

store — identity, address, contact, hours

### store[​](#store "Direct link to store")

| Field                           | Type        | Example / description                                                   |
| ------------------------------- | ----------- | ----------------------------------------------------------------------- |
| `store.id`                      | number      | Store ID, or historical ID for deleted stores                           |
| `store.name`                    | string      | Store display name                                                      |
| `store.address.address_1`       | string      | Street address line 1                                                   |
| `store.address.address_2`       | string      | Suite/unit line                                                         |
| `store.address.city`            | string      | City/locality                                                           |
| `store.address.state`           | string      | State/region                                                            |
| `store.address.postcode`        | string      | Postal code                                                             |
| `store.address.country`         | string      | ISO country code                                                        |
| `store.address_lines`           | array       | Preformatted address lines; recommended for most templates              |
| `store.tax_ids`                 | array       | Structured business tax IDs; loop this instead of using a single tax ID |
| `store.phone`                   | string      | Store phone                                                             |
| `store.email`                   | string      | Store email                                                             |
| `store.logo`                    | string/null | Store logo URL or data URI                                              |
| `store.opening_hours`           | string/null | Compact opening-hours text                                              |
| `store.opening_hours_vertical`  | string/null | Multi-line opening-hours block                                          |
| `store.opening_hours_inline`    | string/null | Comma-separated opening-hours text                                      |
| `store.opening_hours_notes`     | string/null | Free-text opening-hours notes                                           |
| `store.personal_notes`          | string/null | Receipt footer/personal note                                            |
| `store.policies_and_conditions` | string/null | Refund, returns, or terms text                                          |
| `store.footer_imprint`          | string/null | Legal footer imprint                                                    |

### Tax ID objects[​](#tax-id-objects "Direct link to Tax ID objects")

`store.tax_ids` and `customer.tax_ids` contain objects with the same shape:

| Field     | Type        | Description                                                                              |
| --------- | ----------- | ---------------------------------------------------------------------------------------- |
| `type`    | string      | Identifier such as `eu_vat`, `de_steuernummer`, `au_abn`, `br_cpf`, `us_ein`, or `other` |
| `value`   | string      | Tax ID value to print                                                                    |
| `country` | string/null | ISO country code when known                                                              |
| `label`   | string/null | Localised display label, resolved before rendering                                       |

Example:

```
{{#store.tax_ids}}

  {{label}}: {{value}}

{{/store.tax_ids}}
```

cashier — user who processed the order

### cashier[​](#cashier "Direct link to cashier")

| Field          | Type   | Example / description               |
| -------------- | ------ | ----------------------------------- |
| `cashier.id`   | number | WordPress user ID, `0` when unknown |
| `cashier.name` | string | Cashier display name                |

customer — name, addresses, tax IDs

### customer[​](#customer "Direct link to customer")

| Field                         | Type        | Example / description                                  |
| ----------------------------- | ----------- | ------------------------------------------------------ |
| `customer.id`                 | number/null | Customer ID, or `null` for guests                      |
| `customer.name`               | string      | Customer display name, or guest label                  |
| `customer.billing_address.*`  | object      | WooCommerce billing address fields                     |
| `customer.shipping_address.*` | object      | WooCommerce shipping address fields                    |
| `customer.tax_ids`            | array       | Structured customer tax IDs snapshotted from the order |

Common address keys include `first_name`, `last_name`, `company`, `address_1`, `address_2`, `city`, `state`, `postcode`, `country`, `email`, and `phone`.

lines — product line items

### lines[​](#lines "Direct link to lines")

Loop with `{{#lines}}...{{/lines}}`.

| Field                               | Type   | Description                                          |
| ----------------------------------- | ------ | ---------------------------------------------------- |
| `key`                               | string | Stable line key/order item ID                        |
| `sku`                               | string | Product SKU                                          |
| `name`                              | string | Product or line display name                         |
| `qty`                               | number | Quantity sold                                        |
| `qty_refunded`                      | number | Quantity refunded for this line                      |
| `unit_subtotal` / `_incl` / `_excl` | number | Pre-discount unit price                              |
| `unit_price` / `_incl` / `_excl`    | number | Post-discount unit price                             |
| `line_subtotal` / `_incl` / `_excl` | number | Pre-discount line subtotal                           |
| `discounts` / `_incl` / `_excl`     | number | Discount amount as a positive value                  |
| `line_total` / `_incl` / `_excl`    | number | Final line total                                     |
| `total_refunded`                    | number | Total refunded for this line as a positive value     |
| `taxes`                             | array  | Per-rate tax rows for this line                      |
| `meta`                              | array  | Order item meta as `{key, value}` pairs              |
| `attributes`                        | array  | Product/variation attributes as `{key, value}` pairs |

Formatted variants include `unit_subtotal_display`, `unit_price_display`, `line_subtotal_display`, `discounts_display`, `line_total_display`, and inclusive/exclusive `_display` variants.

fees and shipping

### fees and shipping[​](#fees-and-shipping "Direct link to fees and shipping")

Loop with `{{#fees}}...{{/fees}}` and `{{#shipping}}...{{/shipping}}`.

| Field                       | Type   | Description                                   |
| --------------------------- | ------ | --------------------------------------------- |
| `label`                     | string | Fee label or shipping method name             |
| `method_id`                 | string | Shipping method ID (shipping only)            |
| `total` / `_incl` / `_excl` | number | Display-side, inclusive, and exclusive totals |
| `taxes`                     | array  | Per-rate tax rows                             |
| `meta`                      | array  | `{key, value}` meta pairs                     |

Formatted variants: `total_display`, `total_incl_display`, and `total_excl_display`.

discounts — coupon/discount rows

### discounts[​](#discounts "Direct link to discounts")

Loop with `{{#discounts}}...{{/discounts}}`.

| Field                       | Type   | Description                              |
| --------------------------- | ------ | ---------------------------------------- |
| `label`                     | string | Coupon description or code fallback      |
| `code`                      | string | Coupon code                              |
| `codes`                     | string | Legacy/display fallback for joined codes |
| `total` / `_incl` / `_excl` | number | Discount amount as a positive value      |

Formatted variants: `total_display`, `total_incl_display`, and `total_excl_display`. Add your own minus sign in the template if you want discounts shown as negative rows.

totals — order, payment, refund, and item totals

### totals[​](#totals "Direct link to totals")

| Field                                       | Type   | Description                              |
| ------------------------------------------- | ------ | ---------------------------------------- |
| `totals.subtotal` / `_incl` / `_excl`       | number | Order subtotal before discounts          |
| `totals.discount_total` / `_incl` / `_excl` | number | Order discount total as a positive value |
| `totals.tax_total`                          | number | Total tax amount                         |
| `totals.total` / `_incl` / `_excl`          | number | Order grand total                        |
| `totals.paid_total`                         | number | Amount paid/applied                      |
| `totals.change_total`                       | number | Change returned to the customer          |
| `totals.refund_total`                       | number | Total refunded as a positive value       |
| `totals.net_total`                          | number | `total - refund_total`, clamped to zero  |
| `totals.total_qty`                          | number | Sum of line item quantities              |
| `totals.line_count`                         | number | Count of product line rows               |

Formatted variants include `subtotal_display`, `discount_total_display`, `tax_total_display`, `total_display`, `paid_total_display`, `change_total_display`, `refund_total_display`, and `net_total_display`, plus inclusive/exclusive variants where applicable.

tax and tax\_summary — display guards and per-rate rows

### tax and tax\_summary[​](#tax-and-tax_summary "Direct link to tax and tax_summary")

Use `tax` for display-mode guards and `tax_summary` for itemized rate rows.

| Tax field                | Type    | Description                               |
| ------------------------ | ------- | ----------------------------------------- |
| `tax.display`            | string  | `incl` or `excl`                          |
| `tax.display_incl`       | boolean | True when prices display inclusive of tax |
| `tax.display_excl`       | boolean | True when prices display exclusive of tax |
| `tax.breakdown`          | string  | `hidden`, `single`, or `itemized`         |
| `tax.breakdown_hidden`   | boolean | True when tax rows should be hidden       |
| `tax.breakdown_single`   | boolean | True when a single tax total is preferred |
| `tax.breakdown_itemized` | boolean | True when per-rate rows are preferred     |
| `has_tax_summary`        | boolean | True when `tax_summary` contains rows     |

Loop `tax_summary` with `{{#tax_summary}}...{{/tax_summary}}`.

| Field                 | Type        | Description                    |
| --------------------- | ----------- | ------------------------------ |
| `code`                | string      | Tax rate ID/code               |
| `rate`                | number/null | Rate percentage when resolved  |
| `label`               | string      | Tax rate label                 |
| `compound`            | boolean     | Whether the rate is compounded |
| `taxable_amount_excl` | number/null | Taxable base excluding tax     |
| `tax_amount`          | number      | Tax collected                  |
| `taxable_amount_incl` | number/null | Taxable base including tax     |

Formatted variants: `taxable_amount_excl_display`, `tax_amount_display`, and `taxable_amount_incl_display`.

payments — payment rows

### payments[​](#payments "Direct link to payments")

Loop with `{{#payments}}...{{/payments}}`.

| Field            | Type   | Description                       |
| ---------------- | ------ | --------------------------------- |
| `method_id`      | string | Payment method identifier         |
| `method_title`   | string | Payment method display title      |
| `amount`         | number | Amount applied to the order       |
| `transaction_id` | string | Gateway transaction ID            |
| `tendered`       | number | Cash amount tendered when present |
| `change`         | number | Cash change returned when present |

Formatted variants: `amount_display`, `tendered_display`, and `change_display`.

refunds — refund records

### refunds[​](#refunds "Direct link to refunds")

Loop with `{{#refunds}}...{{/refunds}}`. Refund amounts are positive magnitudes; templates decide whether to prepend a minus sign or render a separate returned-items block.

| Field              | Type        | Description                                          |
| ------------------ | ----------- | ---------------------------------------------------- |
| `id`               | number      | Refund record ID                                     |
| `date`             | date object | Refund creation date                                 |
| `amount`           | number      | Refund total                                         |
| `subtotal`         | number      | Refunded line subtotal                               |
| `tax_total`        | number      | Tax refunded                                         |
| `shipping_total`   | number      | Shipping amount refunded                             |
| `shipping_tax`     | number      | Shipping tax refunded                                |
| `reason`           | string      | Refund reason                                        |
| `refunded_by_id`   | number/null | User ID that issued the refund                       |
| `refunded_by_name` | string      | User display name that issued the refund             |
| `refunded_payment` | boolean     | Whether the payment was refunded through the gateway |
| `destination`      | string      | `original_method`, `cash`, or `manual`               |
| `gateway_id`       | string      | Gateway ID used for the refund                       |
| `gateway_title`    | string      | Gateway display title                                |
| `processing_mode`  | string      | Provider/manual processing mode                      |
| `lines`            | array       | Refunded product rows                                |
| `fees`             | array       | Refunded fee rows                                    |
| `shipping`         | array       | Refunded shipping rows                               |

Refund line fields include `name`, `sku`, `qty`, `total`, `total_incl`, `total_excl`, `line_total`, `unit_total`, and `taxes`. Refund fee and shipping rows use `label`, `total`, `total_incl`, `total_excl`, and `taxes`. Display variants are added for totals and tax amounts.

fiscal — fiscal integration snapshot

### fiscal[​](#fiscal "Direct link to fiscal")

Fiscal fields are empty by default and populated by fiscal integrations or WCPOS Pro snapshot enrichment.

| Field                      | Type         | Description                        |
| -------------------------- | ------------ | ---------------------------------- |
| `fiscal.immutable_id`      | string       | Immutable fiscal identifier        |
| `fiscal.receipt_number`    | string       | Fiscal receipt number              |
| `fiscal.sequence`          | number/null  | Sequence counter                   |
| `fiscal.hash`              | string       | Hash/signature value               |
| `fiscal.qr_payload`        | string       | QR payload for fiscal verification |
| `fiscal.tax_agency_code`   | string       | Tax authority code                 |
| `fiscal.signed_at`         | string       | Fiscal signing timestamp           |
| `fiscal.signature_excerpt` | string       | Truncated signature for display    |
| `fiscal.document_label`    | string       | Document label, e.g. Tax Invoice   |
| `fiscal.is_reprint`        | boolean      | Whether this render is a reprint   |
| `fiscal.reprint_count`     | number       | Reprint count                      |
| `fiscal.extra_fields`      | array/object | Jurisdiction-specific values       |

presentation\_hints — formatting and renderer hints

### presentation\_hints[​](#presentation_hints "Direct link to presentation_hints")

These fields are mainly consumed by the renderer and formatter. They are available to templates when needed.

| Field                                         | Type    | Description                                       |
| --------------------------------------------- | ------- | ------------------------------------------------- |
| `presentation_hints.display_tax`              | string  | `incl`, `excl`, `hidden`, `itemized`, or `single` |
| `presentation_hints.prices_entered_with_tax`  | boolean | Whether catalogue prices include tax              |
| `presentation_hints.rounding_mode`            | string  | WooCommerce tax rounding setting                  |
| `presentation_hints.locale`                   | string  | Locale used for formatting                        |
| `presentation_hints.timezone`                 | string  | Receipt timezone                                  |
| `presentation_hints.currency_position`        | string  | Currency symbol position                          |
| `presentation_hints.currency_symbol`          | string  | Currency symbol                                   |
| `presentation_hints.price_thousand_separator` | string  | Thousands separator                               |
| `presentation_hints.price_decimal_separator`  | string  | Decimal separator                                 |
| `presentation_hints.price_num_decimals`       | number  | Decimal places                                    |
| `presentation_hints.price_display_suffix`     | string  | WooCommerce price display suffix                  |
| `presentation_hints.order_barcode_type`       | string  | Barcode type used by gallery templates            |

i18n — translated labels

### i18n[​](#i18n "Direct link to i18n")

Use `i18n` labels instead of hardcoding text where possible:

```
{{i18n.order}} #{{order.number}}

{{i18n.cashier}}: {{cashier.name}}

{{i18n.total}}: {{totals.total_display}}
```

Common keys include `order`, `date`, `cashier`, `customer`, `item`, `sku`, `qty`, `unit_price`, `discount`, `subtotal`, `total`, `tax`, `paid`, `tendered`, `change`, `tax_summary`, `refunded`, `net_total`, `customer_note`, `thank_you_purchase`, `opening_hours`, and the tax-ID label keys such as `store_tax_id_label_eu_vat` and `customer_tax_id_label_other`. Extra keys may be added by extensions.