StateSet iCommerce Language Bindings

Language bindings for the embedded iCommerce engine, their coverage levels, and the money-precision contract.

StateSet iCommerce Language Bindings

StateSet iCommerce ships language bindings so you can run the embedded engine in your stack without changing how your team builds. The Rust core is the source of truth; each binding wraps the same embedded accessors.

Coverage

Bindings are not all at the same maturity. Pick with that in mind.

Binding	Status
Rust	The core itself — full surface
Node.js	Full parity. Every embedded accessor is bound; the binding-parity CI gate has an empty exception list, so a future unbound accessor fails the build
Python	Full parity with Node across all domains, with typed .pyi stubs and package re-exports
Go, Java, .NET, Ruby, PHP, Swift, Kotlin, WASM	Available, but not at Node/Python parity — verify the domains you need before committing

Node and Python are the primary consumer surfaces and are held to a parity gate in CI. The remaining bindings are generated from the same definitions but cover less of the surface.

Domain coverage

The Node and Python bindings reach the complete accessor surface, including domains that were previously core-only:

Customer balances — gift cards, loyalty (programs, accounts, points, rewards), store credits.

Storefront — product reviews (with getSummary returning average, total, and per-star distribution), wishlists (nested items with product, variant, quantity, priority, note), customer segments (rules and memberships).

Commerce core — customers with address books, products with variants and lifecycle (activate/archive), and the full RMA return workflow: mark received, complete, cancel, add tracking, and list by order, customer, or pending.

Finance and operations — see Finance & Accounting for the GL, AP, AR, fixed-asset, and revenue-recognition surface.

Infrastructure — activity logs, channels, companies, units of measure, shipping zones, stock snapshots, print stations, integration and field mappings, payment obligations, purgatory, topology snapshots, vendor returns, fraud, search config, EDI documents, prepayments, vendor credits, price schedules and levels, transfer orders, production batches, supplier SKUs, inbound shipments, and ERC-8004 (identity, reputation, validation).

update_return is intentionally not exposed as a single tool — its UpdateReturn input is complex and unbound. The status-transition methods cover the practical paths.

Money precision

The Rust core represents every monetary amount as an exact base-10 decimal (rust_decimal::Decimal). The engine, the HTTP DTOs, and the newer binding domains preserve that: money crosses the FFI boundary as an exact decimal string such as "30.01".

// correct — exact decimal string
const balance = await commerce.storeCredits.get(id); // balance: "-10.00"

Known defect — older binding output structs convert Decimal to f64. Roughly 50 money fields on both the Node and Python surfaces are affected, including PaymentOutput.amount, OrderResponse.total_amount, InvoiceOutput subtotal/tax/paid, cart and line-item amounts, and refund amounts.

f64 cannot represent most decimal cents exactly, so these fields can carry sub-cent drift, and values beyond 2^53 minor units lose integer precision outright.

This is tracked as an open decision because fixing it is a breaking change to the binding surface. Until it lands: for exact settlement, read money from the HTTP DTOs or the newer decimal-string domains rather than from the affected binding fields, and never accumulate across many f64 money values.

Domains added in and after the gift-card/loyalty cycle use exact decimal strings throughout. Points are integers; reward values and store-credit balances are decimal strings (an applied credit is recorded as a negative debit, e.g. "-10.00").

Validation at the boundary

Bindings validate before crossing into the core, so errors surface in your language rather than as opaque FFI failures — review ratings are checked 1–5, segment rule operators are checked against the known set, and negative store-credit balances are rejected.

Related

• Embedded engine
• Finance & Accounting
• API Hardening