<!-- SKILL-VERSION: library/receipt-v1 3a76850@2026-10-04T07:41:12+10:00 -->
> **Skill version:** `3a76850@2026-10-04T07:41:12+10:00` (`library/receipt-v1`).
> If you have a cached copy of this skill with a different version token,
> discard it and use this copy. Re-fetch this URL at the start of each
> session to detect updates.

# makesPDF — Receipt skill `receipt-v1`

> Version: `receipt-v1`. **Immutable** — this file never changes after
> release. Fixes land in `receipt-v2`, served alongside this file. If a
> newer version exists, it is noted at the top of this file; this URL
> keeps serving regardless.

> **Note to AI agents:** this document is served over HTTP at
> `https://makespdf.com/skills/library/receipt-v1.md` (or
> `http://localhost:8788/skills/library/receipt-v1.md` in dev). It is
> **not a local file.** Re-fetch it with a web fetch / HTTP tool — do
> **not** call your filesystem `Read` tool with `/skills/...`. Paths
> that begin with `/api/v1/` or `/skills/` below are URL paths relative
> to the makespdf origin, not filesystem paths.

Read [`/skills/pdf-template-author.md`](https://makespdf.com/skills/pdf-template-author.md)
first for the builder DSL, style properties, and the preview/render loop.
This file is the receipt-specific companion: which fields to use, which
library template to start from, and a worked fetch, fill, render example.

A receipt is proof of payment already received (money-in). For a bill
for goods/services delivered, use the invoice skill instead.

## Canonical fields (field registry)

Source: `docs/field-registry.md` and
`apps/web/src/utils/field-registry.ts` (`documentTypes` containing
`"receipt"`). Use these canonical ids when naming data keys. The
`Aliases` column lists common incoming names the registry already
recognises — prefer the canonical id for new data.

### Document identity

| Canonical id        | Label             | Type / format | Common aliases                          |
| ------------------- | ----------------- | ------------- | --------------------------------------- |
| `receipt-number`    | Receipt Number    | string        | receiptno, receiptid, transactionnumber |
| `document-date`     | Date              | date          | date, receiptdate, issuedate            |
| `reference-invoice` | Reference Invoice | string        | originalinvoice, relatedinvoice         |

### Store (seller side)

| Canonical id     | Label           | Type / format | Common aliases                     |
| ---------------- | --------------- | ------------- | ---------------------------------- |
| `store-name`     | Store Name      | string        | storename, shopname, branchname    |
| `store-address`  | Store Address   | string        | storeaddress, shopaddress          |
| `cashier`        | Cashier         | string        | cashier, clerk, servedby, operator |
| `register`       | Register        | string        | register, terminal, pos, till      |
| `seller-name`    | Company Name    | string        | companyname, vendorname            |
| `seller-address` | Company Address | string        | companyaddress, vendoraddress      |
| `seller-phone`   | Phone           | phone         | phone, mobile, tel                 |
| `seller-tax-id`  | Tax ID          | tax-id        | gstin, vat, ein, abn               |
| `seller-logo`    | Logo            | url           | logo, companylogo                  |

### Transaction

| Canonical id       | Label          | Type / format | Common aliases                   |
| ------------------ | -------------- | ------------- | -------------------------------- |
| `transaction-id`   | Transaction ID | string        | transid, txnid                   |
| `transaction-time` | Time           | datetime      | time, transactiontime, saletime  |
| `payment-method`   | Payment Method | string        | paymentmethod, payvia            |
| `card-last-four`   | Card Last Four | string        | lastfour, cardnumber, maskedcard |
| `buyer-name`       | Client Name    | string        | customername, client             |

### Line items

| Canonical id       | Label       | Type / format | Common aliases                 |
| ------------------ | ----------- | ------------- | ------------------------------ |
| `item-description` | Description | string        | description, itemname, product |
| `item-quantity`    | Quantity    | integer       | qty, quantity, count           |
| `item-unit-price`  | Unit Price  | currency      | unitprice, price, rate         |
| `item-discount`    | Discount    | currency      | discount, rebate               |
| `item-line-total`  | Line Total  | currency      | linetotal, amount, total       |

### Totals

| Canonical id     | Label        | Type / format | Common aliases               |
| ---------------- | ------------ | ------------- | ---------------------------- |
| `subtotal`       | Subtotal     | currency      | subtotal, netamount          |
| `discount-total` | Discount     | currency      | discounttotal, totaldiscount |
| `tax-amount`     | Tax Amount   | currency      | tax, vat, gst, salestax      |
| `total`          | Total        | currency      | grandtotal, totaldue         |
| `amount-paid`    | Amount Paid  | currency      | paid, totalpaid              |
| `change-given`   | Change Given | currency      | change, changedue            |

### Notes

| Canonical id    | Label         | Type / format | Common aliases        |
| --------------- | ------------- | ------------- | --------------------- |
| `notes`         | Notes         | string        | notes, memo, remarks  |
| `return-policy` | Return Policy | string        | returns, refundpolicy |

## Library template

Start from **`receipt-retail`** (centred store header, receipt meta,
member/loyalty panel, itemised table, totals, payment block). Thermal
and minimal variations exist (`receipt-thermal`, `receipt-minimal`) —
list them with
`GET /api/v1/templates?owner=library&category=receipt`.

## Worked example: fetch, fill, render

All calls need `Authorization: Bearer $MAKESPDF_API_KEY`.

**1. Fetch the template's DSL and sample data.**

```sh
curl -s -H "Authorization: Bearer $MAKESPDF_API_KEY" \
  "https://makespdf.com/api/v1/templates/receipt-retail"
# -> { templateId, name, dsl, sampleData, ... }
```

**2. Fill.** Start from the returned `sampleData`, keep its keys, replace
the values with the real sale. Map incoming names to the canonical ids
above (`transid` -> Transaction ID, `lastfour` -> Card Last Four).
Minimal override shape:

```json
{
  "receiptNumber": "R-2026-00931",
  "date": "2026-09-11",
  "time": "14:32",
  "transactionId": "TXN-88124",
  "cashier": "J. Rivera",
  "register": "POS-03",
  "store": { "name": "Corner Grocer No. 4" },
  "items": [{ "description": "Sourdough loaf", "qty": 2, "total": 11.0 }],
  "total": 11.83,
  "amountPaid": 20.0,
  "changeGiven": 8.17
}
```

**3. Render.** Production path is the stored template (billed, 1 credit
per 10 pages):

```sh
curl -s -X POST https://makespdf.com/api/v1/render \
  -H "Authorization: Bearer $MAKESPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId": "receipt-retail", "data": {...}}' -o receipt.pdf
```

Iterating on a customised fork? Draft it free with
`POST /api/v1/preview { dsl, data }`, pre-flight with
`POST /api/v1/preview/validate`, then save via
`POST /api/v1/templates { dsl, name }` and render your copy.

## Traps

- Cash sales must show `amount-paid` tendered and `change-given`;
  card sales show `payment-method` plus `card-last-four`, never a full
  PAN.
- `reference-invoice` links the receipt back to the original invoice
  when one exists — keep both numbers visible.
- Numeric table columns stay `auto`/`1fr`, never fixed `%` widths on
  Qty / Price / Total.