收据数据参考

WCPOS 无逻辑 HTML 模板和热敏 XML 模板从相同的规范收据数据渲染。使用 Mustache 点路径，如 {{order.number}}、{{store.name}} 和 {{totals.total_display}}。数组通过区块渲染：

{{#lines}}
  {{name}} x {{qty}} — {{line_total_display}}
{{/lines}}

规范契约由服务器端的 WCPOS 收据数据构建器生成，并由应用中的离线收据渲染器镜像。收据会立即从本地数据打开，然后在服务器响应可用时升级为服务器数据，因此自定义模板应使用以下字段，而非 PHP 订单方法。

收据数据 v1.1 为每个商品行新增了已记录的原价、优惠券前售价以及节省金额字段。它还提供订单级的节省金额合计，其中包括一个 总计节省 值，该值将原价节省与 WooCommerce 折扣合并在一起，而不会改变订单合计或报表。

收据结构对照

打印收据的每个部分都来自数据契约中的某一节。悬停任意一侧可查看对应关系；点击可跳转到该节的字段。本页所有示例都使用同一个示例订单。

COFFEE MONSTER

12 Roast Lane, Portland OR

VAT: US-998877

---

收据 #10422026年7月13日

收银员：Ada客户：Nia

---

2 × 浓缩咖啡豆29.00

34.00 · 节省 −5.00

1 × 陶瓷马克杯18.00

1 × 可颂5.75

---

小计52.75

优惠券 SUMMER10−5.28

礼品包装2.50

运费10.00

合计59.97

总计节省10.28

---

刷卡59.97

---

感谢您的惠顾！

店铺抬头

store.name · store.address_lines · store.tax_ids · store.logo

订单与人员

order.number · order.created · cashier.name · customer.name

商品行项目

lines[] · line_savings · savings_in_discounts

合计区块

totals.* · discounts[] · fees[] · shipping[] · totals.total_saved

付款

payments[]

页脚

store.personal_notes · store.policies_and_conditions · i18n.thank_you_purchase

常用范例

大多数模板改动都属于以下三种之一。每张卡片先展示打印结果，然后给出确切的标记——可将其复制到任何无逻辑 HTML 或热敏 XML 模板中。第三张卡片展示的是 v1.9 之前的旧订单，而非上方的示例订单。

2 × 浓缩咖啡豆29.00

34.00 · 节省 −5.00

为原价添加删除线

{{#lines}}
{{#line_savings}}
  <s>{{line_regular_total_display}}</s>
  {{i18n.savings}}: -{{line_savings_display}}
{{/line_savings}}
{{/lines}}

区块条件判断会在没有记录价格历史的订单上隐藏全部内容。

合计59.97

总计节省10.28

添加一行总计节省

{{#totals.total_saved_complete}}
{{#totals.total_saved}}
  {{i18n.total_saved}}:
  {{totals.total_saved_display}}
{{/totals.total_saved}}
{{/totals.total_saved_complete}}

两重条件判断：当价格历史不完整或没有任何节省时，该行会消失。

1 × 浓缩咖啡豆14.50

17.00 折扣 −2.50

安全地重新打印 v1.9 之前的订单

{{#lines}}
{{#line_savings}}
  {{^savings_in_discounts}}
    {{i18n.savings}}: -{{line_savings_display}}
  {{/savings_in_discounts}}
{{/line_savings}}
{{/lines}}

旧订单把节省金额包含在折扣里——这样可避免重复打印。

渲染规则

货币字段

数值型金额字段保留为数字，渲染器会添加支持本地化的 _display 字段用于模板输出：

数值字段	显示字段
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

打印收据时优先使用 _display 字段。仅在条件判断或机器可读输出中使用数值字段。

税额显示感知字段

多个字段提供了含税和不含税变体，以及一个显示端的便捷值。该便捷值遵循店铺的购物车税额显示设置。

便捷字段	含税字段	不含税字段
lines[].regular_price	lines[].regular_price_incl	lines[].regular_price_excl
lines[].selling_price	lines[].selling_price_incl	lines[].selling_price_excl
lines[].unit_savings	lines[].unit_savings_incl	lines[].unit_savings_excl
lines[].line_regular_total	lines[].line_regular_total_incl	lines[].line_regular_total_excl
lines[].line_selling_total	lines[].line_selling_total_incl	lines[].line_selling_total_excl
lines[].line_savings	lines[].line_savings_incl	lines[].line_savings_excl
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.sale_savings_total	totals.sale_savings_total_incl	totals.sale_savings_total_excl
totals.total_saved	totals.total_saved_incl	totals.total_saved_excl
totals.total	totals.total_incl	totals.total_excl

日期对象

日期字段是包含多种预格式化变体的对象。这样可以避免在 Mustache 中进行日期格式化。

字段	说明
datetime、date、time	默认日期/时间字符串
datetime_short、datetime_long、datetime_full	本地化的组合格式
date_short、date_long、date_full	区域感知的纯日期格式
date_ymd、date_dmy、date_mdy	固定顺序的日期格式
weekday_short、weekday_long	星期名称
day、month、month_short、month_long、year	单独的日期部分

可用的日期对象：order.created、order.paid、order.completed、order.printed 和 refunds[].date。order.printed 在渲染时会刷新，适用于重新打印的场景。

顶级部分

部分	类型	描述
order	object	订单标识、状态、日期、备注和付款 URL 信息
store	object	店铺标识、地址、联系方式、税号、Logo、营业时间和页脚文本
cashier	object	处理订单的用户
customer	object	客户显示名称、地址和税号
lines	array	商品行项目
fees	array	费用行
shipping	array	运费行
discounts	array	优惠券/折扣行
totals	object	订单合计、支付合计、退款摘要及项目数量
tax	object	用于区块条件判断的税费显示模式标志
tax_summary	array	按税率汇总的税费行
has_tax_summary	boolean	tax_summary 的便捷判断标志
payments	array	支付行
refunds	array	应用于该订单的退款记录
fiscal	object	由财税集成填充的财税快照字段
presentation_hints	object	格式化与渲染器提示
i18n	object	内置和自定义模板的翻译标签

各种价格之间的关系

一个商品行会携带多个价格，一旦您在金额上看到它们，这些名称就很好理解了。下面是示例订单中的浓缩咖啡行——一件原价 $17.00 的商品，特价 $14.50，并在此基础上再叠加 10% 的优惠券：

浓缩咖啡豆 —— 单件（该订单有两件）

实付 13.05

1.45

2.50

0原价 17.00

顾客实际支付的金额unit_price → 13.05 · line_total → 26.10

优惠券折扣（SUMMER10）lines[].discounts → 2.90 on this line

相对原价的节省unit_savings → 2.50 · line_savings → 5.00

整个订单的特价节省totals.sale_savings_total = 5.00

整个订单的所有优惠券折扣totals.discount_total = 5.28

节省 + 折扣，并去除旧版重叠部分totals.total_saved = 10.28

特价节省和优惠券折扣是两回事：特价节省是把售价与已记录的原价进行比较，而 discounts 是 WooCommerce 自身的优惠券计算结果。WooCommerce 的订单合计和报表始终只包含优惠券部分——这正是 total_saved 存在的原因，它是把两者合并起来、面向顾客的唯一数字。

字段参考

完整的字段参考按部分分组如下。默认全部折叠——展开您需要的分组。

order — 标识、状态、日期

order

字段	类型	示例／说明
order.id	number	1042
order.number	string	面向用户的订单编号，例如 "1042"
order.currency	string	ISO 货币代码，例如 "USD"
order.customer_note	string	客户／订单备注
order.wc_status	string	WooCommerce 原始状态标识，例如 "processing"
order.status_label	string	本地化的状态标签，包含自定义状态
order.created_via	string	来源／渠道，例如 "woocommerce-pos"
order.needs_payment	boolean	是否应显示付款部分
order.payment_url	string	订单付款 URL（可用时）
order.created	date object	订单创建日期
order.paid	date object	付款日期，未付款时为空字符串
order.completed	date object	完成日期，未完成时为空字符串
order.printed	date object	渲染时的打印/重新打印时间戳

store — 标识、地址、联系方式、营业时间

store

字段	类型	示例／说明
store.id	number	店铺 ID，已删除店铺显示历史 ID
store.name	string	店铺显示名称
store.address.address_1	string	街道地址第 1 行
store.address.address_2	string	门牌号/单元行
store.address.city	string	城市/地区
store.address.state	string	州/省
store.address.postcode	string	邮政编码
store.address.country	string	ISO 国家代码
store.address_lines	array	预格式化的地址行；推荐在大多数模板中使用
store.tax_ids	array	结构化的企业税号；建议循环遍历此数组，而非使用单个税号
store.phone	string	店铺电话
store.email	string	店铺邮箱
store.logo	string/null	店铺 Logo URL 或 data URI
store.opening_hours	string/null	紧凑格式的营业时间文本
store.opening_hours_vertical	string/null	多行格式的营业时间
store.opening_hours_inline	string/null	逗号分隔的营业时间文本
store.opening_hours_notes	string/null	营业时间备注（自由文本）
store.personal_notes	string/null	小票页脚/个人备注
store.policies_and_conditions	string/null	退款、退货或条款文本
store.footer_imprint	string/null	法律页脚印记

税号对象

store.tax_ids 和 customer.tax_ids 包含具有相同结构的对象：

字段	类型	描述
type	string	标识符，例如 eu_vat、de_steuernummer、au_abn、br_cpf、us_ein 或 other
value	string	要打印的税号值
country	string/null	已知时的 ISO 国家代码
label	string/null	本地化显示标签，在渲染前解析

示例：

{{#store.tax_ids}}
  {{label}}: {{value}}
{{/store.tax_ids}}

cashier — 处理订单的用户

cashier

字段	类型	示例／说明
cashier.id	number	WordPress 用户 ID，未知时为 0
cashier.name	string	收银员显示名称

customer — 名称、地址、税号

customer

字段	类型	示例／说明
customer.id	number/null	客户 ID，访客时为 null
customer.name	string	客户显示名称，或访客标签
customer.billing_address.*	object	WooCommerce 账单地址字段
customer.shipping_address.*	object	WooCommerce 收货地址字段
customer.tax_ids	array	从订单快照中获取的客户税号结构化数据

常用地址键包括 first_name、last_name、company、address_1、address_2、city、state、postcode、country、email 和 phone。

lines — 商品行项目

lines

使用 {{#lines}}...{{/lines}} 进行循环。示例值取自示例订单中的浓缩咖啡行。

每个金额字段都成对提供：数字本身（用在 {{#…}} 条件判断中——零和 null 会隐藏该区块，而值为 null 的字段根本没有对应的 _display 孪生字段），以及它的 _display 字符串（用于打印）。标记为 incl/excl 的字段还提供 _incl 和 _excl 变体，每个变体都有各自的 _display。

keystring

稳定的行键/订单项 ID。

key"412"

skustring

产品 SKU。

sku"ESP-500"

namestring

产品或行项目显示名称。

name"Espresso Beans"

qtynumber

销售数量。

qty2

qty_refundednumber

该行项目的退款数量。

qty_refunded0

regular_pricenumbermoneynullableincl/excl

已记录的原始单价。在没有 POS 价格历史的订单上为 null——请将其包在一个区块中。

regular_price17

regular_price_display"$17.00"

selling_pricenumbermoneynullableincl/excl

优惠券前的售出单价——有记录时取 POS 记录的价格，否则由存储的行小计推导得出。

selling_price14.5

selling_price_display"$14.50"

unit_savingsnumbermoneynullableincl/excl

原价减去售价，最小值为零。零为假值，因此带条件判断的行会自行隐藏。

unit_savings2.5

unit_savings_display"$2.50"

line_regular_totalnumbermoneynullableincl/excl

已记录的原价乘以数量。

line_regular_total34

line_regular_total_display"$34.00"

line_selling_totalnumbermoneynullableincl/excl

优惠券前的售价乘以数量。

line_selling_total29

line_selling_total_display"$29.00"

line_savingsnumbermoneynullableincl/excl

该行从原价到售价的节省总额。

line_savings5

line_savings_display"$5.00"

savings_in_discountsboolean

在 v1.9.0 之前的订单上为 true，这些订单的节省金额已包含在 discounts 中——这是防重复计算的标志。

savings_in_discountsfalse

unit_subtotalnumbermoneyincl/excl

WooCommerce 折扣前的单件金额。请勿把它当作原价使用。

unit_subtotal14.5

unit_subtotal_display"$14.50"

unit_pricenumbermoneyincl/excl

WooCommerce 折扣后的最终单件金额。

unit_price13.05

unit_price_display"$13.05"

line_subtotalnumbermoneyincl/excl

WooCommerce 折扣前的行小计。

line_subtotal29

line_subtotal_display"$29.00"

discountsnumbermoneyincl/excl

WooCommerce 原生的行折扣，以正值表示——在当前订单上仅包含优惠券。

discounts2.9

discounts_display"$2.90"

line_totalnumbermoneyincl/excl

优惠券后的最终行合计——即金额列中打印的数值。

line_total26.1

line_total_display"$26.10"

total_refundednumbermoney

该行的退款总额，以正值表示。

total_refunded0

total_refunded_display"$0.00"

taxesarray

该行按税率分列的税额行。

—

metaarray

订单项元数据，以 {key, value} 键值对形式表示。

—

attributesarray

商品/变体属性，以 {key, value} 键值对形式表示。

—

显示原价与节省金额

对于按单价排布的版式，可以像这样显示已记录的原价、售价和节省金额：

{{#lines}}
  {{#unit_savings}}
    <span style="text-decoration: line-through;">{{regular_price_display}}</span>
    <span>{{selling_price_display}}</span>
    <span>{{i18n.savings}}: -{{unit_savings_display}}</span>
  {{/unit_savings}}
{{/lines}}

当数量重要时，请使用行合计字段：

{{#lines}}
  {{#line_savings}}
    <span style="text-decoration: line-through;">{{line_regular_total_display}}</span>
    <span>{{i18n.savings}}: -{{line_savings_display}}</span>
  {{/line_savings}}
{{/lines}}

selling_price 是优惠券之前的价格。WooCommerce 折扣之后的最终金额请使用 unit_price 或 line_total。

重新打印 v1.9.0 之前创建的订单

较早的 WCPOS 订单可能已经把从原价到售价的减免包含在 discounts 中。如果您的自定义模板同时打印行节省金额和行折扣，请使用 savings_in_discounts 以避免同一笔减免显示两次：

{{#lines}}
  {{#line_savings}}
    <span style="text-decoration: line-through;">{{line_regular_total_display}}</span>
    {{^savings_in_discounts}}
      <span>{{i18n.savings}}: -{{line_savings_display}}</span>
    {{/savings_in_discounts}}
  {{/line_savings}}
  {{#discounts}}
    <span>{{i18n.discount}}: -{{discounts_display}}</span>
  {{/discounts}}
{{/lines}}

如果模板不打印行级的 discounts 行，那么即使 savings_in_discounts 为 true，也应继续显示 line_savings。内置模板会自动处理这一区别。

fees 和 shipping

fees 和 shipping

使用 {{#fees}}...{{/fees}} 和 {{#shipping}}...{{/shipping}} 进行循环遍历。

字段	类型	描述
label	string	费用标签或配送方式名称
method_id	string	配送方式 ID（仅限配送）
total / _incl / _excl	number	显示端金额、含税金额和不含税金额
taxes	array	按税率分列的税额行
meta	array	{key, value} 元数据键值对

格式化变体：total_display、total_incl_display 和 total_excl_display。

discounts — 优惠券/折扣行

discounts

使用 {{#discounts}}...{{/discounts}} 进行循环。

字段	类型	描述
label	string	优惠券描述或代码回退值
code	string	优惠券代码
total / _incl / _excl	number	折扣金额，为正数值

格式化变体：total_display、total_incl_display 和 total_excl_display。如果需要将折扣显示为负数行，请在模板中自行添加负号。

totals — 订单、支付、退款及项目合计

totals

示例值取自示例订单，该订单随后收到了 $7.25 的部分退款。

金额字段遵循与商品行相同的成对规则：裸数字用于条件判断，_display 字符串用于打印，标记处还提供 _incl/_excl 变体。

subtotalnumbermoneyincl/excl

折扣前的订单小计。

subtotal52.75

subtotal_display"$52.75"

discount_totalnumbermoneyincl/excl

订单折扣总额，以正值表示——在当前订单上仅包含优惠券。

discount_total5.28

discount_total_display"$5.28"

sale_savings_totalnumbermoneynullableincl/excl

所有商品行上已记录的从原价到售价的节省总额，包含商品目录特价和收银台改价。

sale_savings_total5

sale_savings_total_display"$5.00"

total_savednumbermoneynullableincl/excl

WooCommerce 折扣与原价节省的合并值，并已去除旧版重叠部分。这是面向顾客、涵盖全部节省的唯一数字。

total_saved10.28

total_saved_display"$10.28"

total_saved_completeboolean

该收据是否有足够的已记录价格数据来计算完整的节省合计。

total_saved_completetrue

tax_totalnumbermoney

税额合计。

tax_total0

tax_total_display"$0.00"

totalnumbermoneyincl/excl

订单总计。

total59.97

total_display"$59.97"

paid_totalnumbermoney

已支付/已抵扣金额。

paid_total59.97

paid_total_display"$59.97"

change_totalnumbermoney

找零给顾客的金额。

change_total0

change_total_display"$0.00"

refund_totalnumbermoney

退款总额，以正值表示。

refund_total7.25

refund_total_display"$7.25"

net_totalnumbermoney

总计减去退款，最小值为零。

net_total52.72

net_total_display"$52.72"

total_qtynumber

商品行数量总和。

total_qty4

line_countnumber

商品行数。

line_count3

当您需要一个面向顾客、涵盖全部节省的数字时，请使用 total_saved。请勿在模板中把 discount_total 和 sale_savings_total 相加来自行计算：v1.9.0 之前创建的订单可能已经把 POS 价格节省包含在 WooCommerce 的折扣合计中。规范的 total_saved 字段会检测并去除这部分重叠。

当任一商品行缺少足够的已记录价格数据、无法得出可靠的汇总值时，节省合计为 null，且 total_saved_complete 为 false。请先用 total_saved_complete 判断该行，再用 total_saved 隐藏零值：

{{#totals.total_saved_complete}}
  {{#totals.total_saved}}
    <span>{{i18n.total_saved}}: {{totals.total_saved_display}}</span>
  {{/totals.total_saved}}
{{/totals.total_saved_complete}}

内置的含价模板使用同样的判断结构，配合含税变体（total_saved_incl 和 total_saved_incl_display），并且仅在完整值大于零时才显示 总计节省。

tax 和 tax_summary — 显示判断与按税率行

tax 和 tax_summary

使用 tax 进行显示模式判断，使用 tax_summary 显示分项税率行。

税费字段	类型	描述
tax.display	string	incl 或 excl
tax.display_incl	boolean	当价格显示为含税时为 true
tax.display_excl	boolean	当价格显示为不含税时为 true
tax.breakdown	string	hidden、single 或 itemized
tax.breakdown_hidden	boolean	当应隐藏税项行时为 true
tax.breakdown_single	boolean	当优先显示单一税额合计时为 true
tax.breakdown_itemized	boolean	当优先显示按税率逐项列出时为 true
has_tax_summary	boolean	当 tax_summary 包含行数据时为 true

使用 {{#tax_summary}}...{{/tax_summary}} 循环遍历 tax_summary。

字段	类型	描述
code	string	税率 ID/代码
rate	number/null	解析后的税率百分比
label	string	税率标签
compound	boolean	是否为复合税率
taxable_amount_excl	number/null	不含税应税基数
tax_amount	number	已征税额
taxable_amount_incl	number/null	含税应税基数

格式化变体：taxable_amount_excl_display、tax_amount_display 和 taxable_amount_incl_display。

payments — 支付行

payments

使用 {{#payments}}...{{/payments}} 进行循环。

字段	类型	描述
method_id	string	支付方式标识符
method_title	string	支付方式显示名称
amount	number	应用于订单的金额
transaction_id	string	支付网关交易 ID
tendered	number	存在时为收到的现金金额
change	number	存在时为找零金额

格式化变体：amount_display、tendered_display 和 change_display。

refunds — 退款记录

refunds

使用 {{#refunds}}...{{/refunds}} 进行循环。退款金额为正数绝对值；模板自行决定是否添加负号或渲染单独的退货商品区块。

字段	类型	描述
id	number	退款记录 ID
date	date object	退款创建日期
amount	number	退款总额
subtotal	number	退款行小计
tax_total	number	退款税额
shipping_total	number	退款运费金额
shipping_tax	number	退款运费税额
reason	string	退款原因
refunded_by_id	number/null	发起退款的用户 ID
refunded_by_name	string	发起退款的用户显示名称
refunded_payment	boolean	是否通过支付网关退款
destination	string	original_method、cash 或 manual
gateway_id	string	用于退款的支付网关 ID
gateway_title	string	支付网关显示名称
processing_mode	string	服务商/手动处理模式
lines	array	退款商品行
fees	array	退款费用行
shipping	array	退款运费行

退款行字段包括 name、sku、qty、total、total_incl、total_excl、line_total、unit_total 和 taxes。退款费用行和运费行使用 label、total、total_incl、total_excl 和 taxes。总计和税额会添加显示变体。

fiscal — 财税集成快照

fiscal

财务字段默认为空，由财务集成或 WCPOS Pro 快照增强功能填充。

字段	类型	描述
fiscal.immutable_id	string	不可变财务标识符
fiscal.receipt_number	string	财务收据编号
fiscal.sequence	number/null	序列计数器
fiscal.hash	string	哈希/签名值
fiscal.qr_payload	string	财务验证二维码数据
fiscal.tax_agency_code	string	税务机关代码
fiscal.signed_at	string	财务签名时间戳
fiscal.signature_excerpt	string	用于显示的截断签名
fiscal.document_label	string	单据标签，例如 Tax Invoice
fiscal.is_reprint	boolean	此次渲染是否为重新打印
fiscal.reprint_count	number	重新打印次数
fiscal.extra_fields	array/object	特定辖区的值

presentation_hints — 格式化与渲染器提示

presentation_hints

这些字段主要由渲染器和格式化器使用。需要时可在模板中使用。

字段	类型	描述
presentation_hints.display_tax	string	incl、excl、hidden、itemized 或 single
presentation_hints.prices_entered_with_tax	boolean	商品目录价格是否含税
presentation_hints.rounding_mode	string	WooCommerce 税额取整设置
presentation_hints.locale	string	用于格式化的区域设置
presentation_hints.timezone	string	收据时区
presentation_hints.currency_position	string	货币符号位置
presentation_hints.currency_symbol	string	货币符号
presentation_hints.price_thousand_separator	string	千位分隔符
presentation_hints.price_decimal_separator	string	小数分隔符
presentation_hints.price_num_decimals	number	小数位数
presentation_hints.price_display_suffix	string	WooCommerce 价格显示后缀
presentation_hints.order_barcode_type	string	图库模板使用的条形码类型

i18n — 翻译标签

i18n

尽可能使用 i18n 标签，而不是硬编码文本：

{{i18n.order}} #{{order.number}}
{{i18n.cashier}}: {{cashier.name}}
{{i18n.total}}: {{totals.total_display}}

常用键包括 order、date、cashier、customer、item、sku、qty、unit_price、regular_price、selling_price、savings、discount、subtotal、total_saved、total、tax、paid、tendered、change、tax_summary、refunded、net_total、customer_note、thank_you_purchase、opening_hours，以及税号标签键，如 store_tax_id_label_eu_vat 和 customer_tax_id_label_other。扩展可能会添加额外的键。