This article explains all the fields of PosTransactionDto, the canonical model for the transaction data ReceiptRoller handles. Transaction data from every POS vendor (Smaregi, Square, and others) is converted into this model and then used through the database, dashboards, the REST API, and MCP tools.
Use it as a reference when reading or writing transactions from an external system via the API, or when you want to understand how vendor-side fields appear on ReceiptRoller.
Overview
PosTransactionDto represents a single transaction (a single checkout). Line items (per product) are held as an array in LineItems, and internally persisted as JSON in LineItemsJson.
- Amounts are in the currency indicated by
Currency (default JPY) and, unless noted otherwise, are tax-inclusive
- All dates and times are stored in UTC and converted to JST for display
- Keys: it has two IDs —
TransactionId (ReceiptRoller internal ID) and ExternalTransactionId (the POS vendor-side ID)
- Payments support multiple tenders (split checkout), held in the
Payments array (the single-string PaymentMethod is kept for backward compatibility)
- It is extended to capture what vendors send, including refunds, external linkage IDs, card information, and raw data
Identifiers
| Field | Type | Description |
|---|
TransactionId | string | The ReceiptRoller internal transaction ID. In most cases the POS-side ID is adopted as-is (it becomes the key for the idempotent upsert) |
ExternalTransactionId | string | The POS vendor-side transaction ID. Smaregi: transactionHeadId, Square: Payment.Id |
OrganizationId | string (Guid) | The business account ID |
StoreId | string (Guid) | Store ID |
TerminalId | string (Guid) | The ID of the POS terminal (register) |
Dates and times
| Field | Type | Description |
|---|
TransactionDateTime | DateTime (UTC) | The time the checkout occurred. Converted from Square created_at, Smaregi transactionDateTime |
CreatedAt | DateTime (UTC) | The time the record was created on the ReceiptRoller side (for audit) |
UpdatedAt | DateTime (UTC) | The time the record was updated on the ReceiptRoller side (for audit) |
Amounts
| Field | Type | Description |
|---|
Currency | string | The currency code for all amounts (ISO-4217, default JPY). Square from money.currency, Smaregi fixed to JPY |
TotalAmount | decimal | Total amount (tax-inclusive) |
TaxAmount | decimal | Consumption tax amount |
SubtotalAmount | decimal | Subtotal (tax-excluded) = TotalAmount - TaxAmount |
DiscountAmount | decimal | Discount amount (held as a positive value, not a negative one) |
TipAmount | decimal? | Tip / service charge. Only when the source sends it separately (Square tip_money). null when not applicable |
Line items
| Field | Type | Description |
|---|
LineItems | List<PosTransactionLineItemDto> | The array of per-product line items (a computed property; the actual storage is LineItemsJson) |
LineItemsJson | string (JSON) | The JSON-persisted form of the line items. Don't read it directly — use LineItems |
ItemCount | int | The total line-item quantity (LineItems.Sum(li => li.Quantity)) |
PosTransactionLineItemDto
| Field | Type | Description |
|---|
ProductName | string | Product name. When there is a variation, in the form "Product name (variation name)" |
Quantity | int | Quantity sold |
UnitPrice | decimal | Unit price (tax-excluded) |
Subtotal | decimal | Subtotal (tax-inclusive) |
TaxRate | decimal | Effective tax rate (%). Square auto-computes it from the line item, Smaregi adopts taxRate |
TaxAmount | decimal? | Per-line tax amount. Square total_tax_money, Smaregi tax. null for sources / historical data that only carry a rate |
DiscountAmount | decimal? | Per-line discount amount. Square total_discount_money. null for sources that don't carry per-line discounts |
Category | string | Product category. Smaregi categoryName, Square currently empty |
Sku | string? | Vendor SKU / product code. Smaregi productCode. Used for matching against a PIM product |
CostPriceAtSale | decimal? | A snapshot of the PIM cost price (tax-excluded) at the time of sale. Used for gross-profit calculation. null if the cost price is not set |
ProductId | string? | The source product ID (when known) |
CatalogObjectId | string? | The vendor catalog object ID (Square catalog_object_id, Smaregi productId). For inter-system linkage |
Unit | string? | Sales unit ("pcs", "kg", etc.). Only when the source has it |
Note | string? | Per-line remarks |
Modifiers | List<PosLineItemModifierDto>? | Line-item options / modifiers (Square modifiers). Has Name and Amount |
Payments
A transaction can have multiple tenders (split checkout). The full breakdown is held in Payments (the actual storage is PaymentsJson), and the single-string PaymentMethod holds the "primary tender" for backward compatibility.
| Field | Type | Description |
|---|
PaymentMethod | string (enum) | Normalizes the primary payment method:
Cash / CreditCard / QR / IC / Other |
Payments | List<PosPaymentDto> | The full breakdown of tenders (a computed property; the actual storage is PaymentsJson) |
PaymentsJson | string (JSON) | The JSON-persisted form of the tender breakdown |
ReceiptNumber | string | Receipt number (the number issued on the POS side) |
PosPaymentDto
| Field | Type | Description |
|---|
Method | string | The normalized method (Cash / CreditCard / QR / IC / Other), or the source's raw name if not supported |
Amount | decimal | The amount of this tender |
TenderedAmount | decimal? | Amount tendered (when the source reports it) |
ChangeAmount | decimal? | Change (when the source reports it) |
Brand | string? | Card brand (VISA, Mastercard, etc.). Card payments only |
Last4 | string? | Last 4 digits of the card. Displayable (the PAN is not stored) |
ExternalId | string? | The source-side payment ID (when it differs from the transaction ID) |
Refunds
The refund breakdown for a (partially) refunded transaction. Held in Refund (the actual storage is RefundJson).
| Field | Type | Description |
|---|
Refund | PosRefundDto? | The refund breakdown (null if none) |
RefundJson | string (JSON) | The JSON-persisted form of the refund breakdown |
PosRefundDto
| Field | Type | Description |
|---|
Amount | decimal | Refund amount |
IsPartial | bool | Whether it is a partial refund |
Reason | string? | Refund reason |
OriginalTransactionId | string? | The original transaction being refunded |
RefundedAt | DateTime? | Refund date and time |
Note: the model and API shape are ready, and refund data is reflected if it exists. Because Square / Smaregi send refunds as a separate Webhook event, capturing refunds end-to-end is handled by a separate sync process.
External linkage and receipt URL
Holds the source POS's various IDs and receipt URL so a transaction can be reconciled back to its originating record.
| Field | Type | Description |
|---|
ReceiptUrl | string | The customer-facing receipt URL (Square receipt_url). It is a structured field (previously stored in Notes, now deprecated) |
ExternalIds | PosExternalIdsDto? | Cross-vendor IDs (a computed property; the actual storage is ExternalIdsJson) |
ExternalIdsJson | string (JSON) | The JSON-persisted form of the external IDs |
PosExternalIdsDto
| Field | Type | Description |
|---|
ProviderOrderId | string? | The vendor's order ID (Square order_id) |
LocationId | string? | The vendor's location ID (Square location_id) |
ProviderCustomerId | string? | The vendor's customer ID (Square customer_id, Smaregi customerId) |
Raw data
| Field | Type | Description |
|---|
RawJson | string (JSON) | The raw source payload at import time. Kept so that fields not modeled (card fingerprint, etc.) can be recovered. For server-internal use; not returned by the API |
Staff
| Field | Type | Description |
|---|
StaffName | string | The responsible staff name (empty if it could not be obtained) |
StaffId | string | The POS vendor-side staff ID (Square: team_member_id, Smaregi: staffId) |
Status and source
| Field | Type | Description |
|---|
Status | string (enum) | Completed / Voided / Refunded / Pending. For display, StatusDisplayName |
Source | string (enum) | API (auto-imported from the POS) / Webhook (pushed from the POS) / CSV (bulk import) / Manual (manual entry) |
Notes | string | Remarks / memo. The receipt URL moved to ReceiptUrl, so it is no longer stored here |
CRM linkage
When a transaction is linked to a customer (POS-side member information, a phone/email match, etc.), ReceiptRoller's ICrmCustomerResolver fills in the following fields.
| Field | Type | Description |
|---|
MembershipCode | string? | The ReceiptRoller membership number. null if it could not be linked |
CrmCustomerId | string? | The ID of the CRM customer record. null if it could not be linked |
The source-side raw customer ID can be referenced separately via ExternalIds.ProviderCustomerId.
Display helpers
Computed properties for use on the UI side. They are not stored directly in the DB.
PaymentMethodDisplayName — the localized name of the payment method (e.g. "Credit card")StatusDisplayName — the localized name of the status (e.g. "Completed", "Voided")StatusBadgeClass — the CSS class for a Bootstrap badgeSourceDisplayName — the display name of the sourceFormattedDateTime — the date/time in "yyyy/MM/dd HH:mm" formFormattedTotal — the total amount with thousands separators
Backward compatibility
All of the extension fields above are additive and nullable, and persisted as JSON columns. No Table Storage migration is needed, and existing rows and existing LineItemsJson remain valid as-is. New fields are populated from newly imported transactions onward (reflecting them in past data requires a re-sync).
Per-vendor mapping
For exactly which fields each POS vendor populates, see the per-vendor mapping articles below.
Related guides