# JSON data fields for receipt templates

Use this reference to map the receipt context JSON object to your receipt templates.

The receipt context is generated by the `buildReceiptContext` function. It contains all transaction data required to render a printable or digital receipt. You access fields in templates using their property paths (for example, `{{order_number}}`).

## Overview

Key concepts:

- Monetary values are represented by the Money type, including: `amount` (minor units, such as cents or pence), `currency`, and `precision`.
- Fields can be `null` when data is optional or undefined.
- `locale` controls formatting (dates, numbers, time) in the rendered receipt.

## Field reference

### Transaction metadata

| Field | Type | Description |
| --- | --- | --- |
| `timestamp` | Number | Unix timestamp in milliseconds. |
| `timestamp_formatted` | String | Localized date and time derived from the locale. |
| `order_number` | String | Unique transaction reference. |
| `workstation_id` | String | Identifier of the workstation where the transaction occurred. |
| `user_id` | String | Identifier of the user (associate) who processed the transaction. |
| `sequence_number` | String | Sequential transaction counter. |
| `locale` | String | Locale code (for example, `en-US`). |
| `reprint` | Boolean | Indicates a reprinted (duplicate) receipt. |
| `custom` | Object | Custom receipt-level attributes. |

When referencing these fields in your receipt template, use the exact path to the desired value, for example:

- `{{order_number}}`: transaction reference
- `{{location.location_name}}`: store name
- `{{line_items[0].description}}`: first line item description
- `{{payments[0].charge_card.last4}}`: last 4 digits of the first payment card

### Customer information

The `customer` object holds customer identification and personalization fields.

```json title="Customer object"
{
   "account_number": string | null,
  "salutation": string | null,
  "first_name": string | null,
  "middle_name": string | null,
  "last_name": string | null,
  "company": string | null,
  "paymentAccounts": string[],
  "custom": object
}
```

Template examples:

- `{{customer.first_name}}`
- `{{customer.account_number}}`
- `{{customer.company}}`

### Location information

The `location` object contains details about the store.

```json title="Location object"
{
  "location_id": string,
  "location_name": string,
  "description": string | null,
  "country": string | null,
  "address_line_1": string | null,
  "address_line_2": string | null,
  "city": string | null,
  "state": string | null,
  "postal_code": string | null,
  "telephone_number": string | null,
  "tax_id": string | null
}
```

### Line items

Each entry in `line_items` represents a purchased (or returned) item.

```json title="Line item example"
{
  "item_id": string,
  "description": string,
  "quantity": number,
  "price": {
    "amount": number,
    "currency": string,
    "precision": number
  },
  "extended_price": {
    "amount": number,
    "currency": string,
    "precision": number
  },
  "tax_code": string,
  "price_modifiers": [
    {
      "description": string,
      "amount": {
        "amount": number,
        "currency": string,
        "precision": number
      }
    }
  ],
  "attributes": [
    {
      "label": string,
      "value": string
    }
  ],
  "facets": [
    {
      "name": string,
      "value": string | null
    }
  ],
  "custom": object
}
```

### Totals

| Field | Type | Description |
| --- | --- | --- |
| `subtotal` | Money | Sum of line item net amounts before tax. |
| `tax` | Money | Total tax amount. |
| `total` | Money | Transaction total including tax. |
| `subtotal_gross` | Money | Subtotal including cart-level discounts. |
| `tax_id` | String | Tax identification number. |

Money object:

```json title="Attributes of a Money object"
{
  "amount": number,
  "currency": string,
  "precision": number
}
```

### Tax summary

`tax_summary` groups tax calculations by tax code.

```json title="Tax summary entry"
{
  "code": string,
  "total_net": Money,
  "total_gross": Money,
  "tax_rate": string,
  "total_tax": Money
}
```

### Payments and refunds

Use `payments` and `refunds` to list tender objects used to settle or refund the transaction.

#### Tender base

Every tender includes the following base fields:

```json title="Tender base"
{
  "type": string,
  "amount": Money,
  "custom": object | null
}
```

These can contain the following additional fields based on tender type:

#### Credit card fields

```json title="Credit card tender fields"
{
  "charge_card": {
    "processor": string,
    "processor_id": string,
    "last4": string,
    "brand": string,
    "account_type": string,
    "application_preferred_name": string | null,
    "dedicated_file_name": string | null,
    "authorization_response_code": string,
    "application_cryptogram": string | null,
    "terminal_verification_results": string | null,
    "transaction_status_information": string | null
  }
}
```

#### Voucher or return card tender fields

```json title="Voucher tender extension"
{
  "voucher": {
    "number": string,
    "last4": string,
    "type": string,
    "balance": Money
  }
}
```

### `carts`

`carts` lists nested transactions (for example, returns or exchanges) processed within the main transaction flow.

```json title="carts array"
{
  "type": string,
  "id": string,
  "line_items": Array<LineItem>,
  "total": Money,
  "gift_receipt": boolean,
  "custom": object | null
}
```

### Gift receipt items

`giftable_items` lists items eligible for dedicated gift receipts.

```json title="giftable_items array"
{
  "item_id": string,
  "description": string,
  "brand": string | null,
  "color": string | null,
  "gift_receipt": boolean,
  "custom": object | null
}
```

### Cart-level discounts

`cart_discounts` includes discounts applied at the transaction level.

```json title="cart_discounts array"
{
  "description": string,
  "amount": Money
}
```

### Cash management comments

You can print an optional comment on the receipt if the user provides one during cash management activities (except Bank Deposit). Wrap this in an `if` block to avoid printing empty comments.

| Template | Comment path |
| --- | --- |
| `Payout_Receipt_Template` | `{{payout.comment}}` |
| `Payin_Receipt_Template` | `{{payin.comment}}` |
| `Cash_Transfer_Out_Receipt_Template` | `{{transferOut.comment}}` |
| `Cash_Transfer_In_Receipt_Template` | `{{transferIn.comment}}` |
| `Safe_Deposit_Receipt_Template` | `{{safeDeposit.comment}}` |
| `Cash_Count_Receipt_Template` | `{{cashCount.comment}}` |

For example:

```
{{#if payout.comment}}
Comment: | {{payout.comment}}
{{/if}}
```

## Related pages

- [Area overview page with navigation](/instore.md)
- [Previous page: Send receipts by email or text message](/instore/implement-instore/receipts/email-receipt.md)
- [Next page: Sales receipt template](/instore/implement-instore/receipts/sales-receipt.md)
- [Search documentation and API specs](/search.md)