ProductDto reference

PIM Product Data Model Reference POS Integration

Who this article is for
This is for developers working with ReceiptRoller's product master (PIM) via the API, MCP, or Webhook. It explains the structure, including product information imported from a POS, per-store pricing, variants, and cost price.

ProductDto is the canonical model for ReceiptRoller's product master (PIM). Products registered on the product management screen of the store dashboard, products synced from Square Catalog, and products imported via CSV — all of them are consolidated into this single type.

The product master is managed per business account and can be shared across the stores under it. When you want per-store prices, use StorePricesJson, described below.

Main fields

Identifiers and basic information

Field	Type	Description
`OrganizationId`	string	Business account ID. PartitionKey.
`ProductId`	string	RR internal product ID (GUID). RowKey.
`ProductName`	string	Product name.
`SKU`	string	Stock keeping unit (SKU code). For Square integration, the Variation's SKU goes here.
`JanCode`	string	JAN code (barcode).
`Category`	string	Category name (string). A flat classification, not a hierarchy.
`Brand` / `Supplier` / `Description` / `Unit`	string	Brand, supplier, description, unit (pcs, bottles, kg, etc.).

Product specifications

ModelNumber / Series / Color / Size / Weight / ContentVolume / Material / Specification / CountryOfOrigin. All string and optional. Intended for use in a retail-goods product master.

B2B, logistics, and customs

CasePackSize (case pack quantity), MinimumOrderQuantity, LeadTimeDays, HsCode (HS code), StorageRequirements, Certifications. Extension fields for businesses that do wholesale / import-export.

Price and cost

Field	Type	Description
`BasePrice`	decimal	Tax-excluded selling price (the base price).
`BaseCostPrice`	decimal	Cost price (base). The foundational data for profit analysis.
`TaxRate`	decimal	Tax rate. Default `0.10` (Japan standard).
`StorePricesJson`	string (JSON)	Per-store price / cost overrides. Accessible as an array via the `StorePrices` property. Has `GetPriceForStore(storeId)` / `GetCostPriceForStore(storeId)` helpers.

Calculation helpers: TaxIncludedPrice (tax-inclusive price), ProfitMargin (gross margin %), MinVariantPrice / MaxVariantPrice (the price range when there are variants).

Images

ImageUrl (cover image URL) and ImageUrlsJson (a JSON array of the whole gallery). Readable as an array via the ImageUrls property. For backward compatibility with single-image legacy products, when ImageUrlsJson is empty it falls back to a single-element array containing ImageUrl.

Variants

HasVariants (whether it has variants), VariantOptionsJson (the option definitions such as color and size), Variants (an array of ProductVariantDto). Used when handling color and size differences as a single product.

Fields for POS integration

Field	Description
`SquareCatalogObjectId`	The Item object ID of Square Catalog (in `#XXXX` form). Set at sync time.
`SquareVariationId`	The Variation object ID of Square Catalog. Stores the first variation.

Pre-order, status, and audit

IsPreOrder, PreOrderReleaseDate, PreOrderNote (the release date / note for a pre-order product). Status (Active / Discontinued / Draft), SortOrder, InternalMemo, CreatedAt, UpdatedAt.

Mapping from the POS

Which fields of each POS's product data map to which fields of ProductDto is documented in the individual store-help articles. Note that the items each POS can handle differ significantly.

Mapping Square product data to ReceiptRoller product data — full bidirectional sync via the Catalog API
Mapping Smaregi product data to ReceiptRoller product data — in the current version, only via transaction line items

Notes

The combination of OrganizationId and ProductId is the unique key. Even with the same product name, a different business account is a different product.
BaseCostPrice is used directly in the profit calculation of sales analysis. Since updating the value does not keep history, a separate design is needed if you need a snapshot at the time of a cost change (under consideration in the t-e9a2f447 cost-data extension series).
StorePricesJson is a per-store override; for stores where it is not set, BasePrice / BaseCostPrice apply as-is.
Products imported from Square Catalog have SquareCatalogObjectId set, and are reconciled by this ID on re-sync. Do not overwrite it manually.

Related guides

PosTransactionDto reference — the canonical model for POS transactions
CrmCustomerDto reference — the canonical model for the customer master
Back to the Developer Help top

Published: 2026-05-29 Updated: 2026-07-05

Back to help list