Products registered in Square Catalog are automatically converted into Receipt Roller's product master (ProductDto) after connecting Square to Receipt Roller. This article summarizes the field-by-field correspondence and the quirks specific to Square.

Square Catalog structure

In Square Catalog, products are represented in the following three layers. Receipt Roller maps a single ITEM to a single product, taking the SKU and price from the first ITEM_VARIATION.

• ITEM — the product itself (name, description, category)
• ITEM_VARIATION — individual products differing by size or color (SKU, price)
• CATEGORY — classification (category name)

Field mapping table

Fixed and default values

• TaxRate = 0.10 (Japan's standard 10%) is set uniformly. Per-product tax rates are not imported in the current version.
• Status = "Active". Products deleted on the Square side (is_deleted = true) are excluded from the sync.

Fields that are not imported

The following fields in Square Catalog are not imported into Receipt Roller in the current version.

• The 2nd and subsequent ITEM_VARIATION entries — Square's size and color variants are not yet mapped to Receipt Roller's variant feature (HasVariants / Variants). Only the first one is used as the SKU/price.
• Product images (image_ids) — fetching images requires a separate call to the Square Images API, which is currently excluded from the sync.
• Modifiers (modifier_list_info) — add-on items such as toppings and options are not supported.
• Cost information — Square also has no standard field for this, so BaseCostPrice remains 0. Register this separately on the Receipt Roller side.
• Receipt Roller–specific fields (JanCode / Brand / Supplier / ModelNumber, etc.) — there is no corresponding concept in Square, so these are never overwritten on re-sync. Content registered manually on the Receipt Roller side is preserved.

Sync timing

• Square → Receipt Roller (product master import): Triggered manually with the "Sync from Square" button on the Product Management screen. ITEMs and CATEGORYs are fetched together from the Square Catalog API (ListCatalog) and matched by SquareCatalogObjectId to add or update records.
• Behavior on re-sync: For existing products (matched by the same SquareCatalogObjectId), ProductName / Description / SKU / Category / BasePrice / SquareVariationId are overwritten. JanCode / Brand / BaseCostPrice, etc. added on the Receipt Roller side are preserved.
• Receipt Roller → Square: Not supported in the current version. Products registered on the Receipt Roller side are not automatically reflected back to Square Catalog.

Matching and new registrations

When products are imported from Square Catalog, matching against existing products is done solely by an exact match on SquareCatalogObjectId. If there is no match, the product is added to PIM as new. No automatic matching by product name or category is performed (since identical names could still be different products). If you want to merge duplicates, do so manually from the Product Management screen.

Points to note

• If a product is physically deleted on the Square side, matching by that product's SquareCatalogObjectId stops working; if re-added, it will be registered as a separate product. On Square, we recommend "deactivating" rather than deleting.
• If you use Square's size or color variants (multiple Variations), only the first Variation is imported. If you want to register each size as a separate product, register them as separate ITEMs on the Square side as well.
• Currencies other than JPY are converted automatically (smallest currency unit ÷ 100). Mixing multiple currencies in one operation is not recommended.
• Registering BaseCostPrice (cost) on the Receipt Roller side is reflected in profit calculations in sales analysis. Since Square has no cost field, be sure to enter this separately on the Receipt Roller side.

Related guides

• ProductDto reference (for developers) — full field specification of the canonical model
• Square transaction data mapping
• Square customer data mapping
• Square POS integration setup