Tally UI

Connectors

Available Tally UI connectors for WooCommerce, MedusaJS, Shopify, and Vendure, with authentication, store sessions, replication, and custom connector setup.

Available Connectors

For what each app built on these connectors does today, see What works today.

WooCommerce

pnpm add @tallyui/connector-woocommerce

Connects to WooCommerce stores via the REST API. Supports WooCommerce v3 API and the WCPOS API extension.

Auth: Consumer Key + Consumer Secret (Basic Auth)

Built on it: tallyui-woocommerce · live demo

MedusaJS

pnpm add @tallyui/connector-medusa

Connects to MedusaJS v2 backends via the Admin API. Fetches products with variants, pricing, categories, and images.

Auth: Admin API Token (Bearer)

Built on it: Medusa POS · live demo

Shopify

pnpm add @tallyui/connector-shopify

Connects to Shopify stores via the Admin API. Fetches products with variants, images, and inventory data.

Auth: Admin API Access Token

Vendure

pnpm add @tallyui/connector-vendure

Connects to Vendure backends via the GraphQL Admin API. Supports products with variants, facets, and assets.

Auth: Bearer Token

Built on it: Vendure POS · live demo

Coming Soon

  • Square — Square APIs for retail
  • Vend/Lightspeed — Lightspeed Retail

One connector per store session

Build each connector with its factory, anew on each sign-in or store change, and never share one instance between two stores: an instance owns the reconcile feed that carries corrections into its own database.

import { useMemo, type ReactNode } from 'react';
import { ConnectorProvider } from '@tallyui/core';
import { createWooCommerceConnector } from '@tallyui/connector-woocommerce';
// Likewise createMedusaConnector() or createMedusaAdminUserConnector() from '@tallyui/connector-medusa',
// and createVendureConnector({ pricesIncludeTax }) from '@tallyui/connector-vendure'.

// `session` is a new object on each sign-in or store change, so each session gets its own connector.
function StoreSession({ session, children }: { session: object; children: ReactNode }) {
  const connector = useMemo(() => createWooCommerceConnector(), [session]);
  return <ConnectorProvider connector={connector}>{children}</ConnectorProvider>;
}

The static exports woocommerceConnector, medusaConnector, medusaAdminUserConnector and vendureConnector are deprecated, because one shared instance can leak queued reconcile work across stores; they are removed in 4.0.

Replication

All four connectors ship with pull-only product replication adapters. Each adapter knows how to pull changes from its API using checkpoint-based pagination. The POS never writes catalogue data back. See the Replication guide for setup and usage.

The TallyConnector contract

TallyConnector is exported from @tallyui/core; only the required members are needed to pull a catalogue, while the optional members switch features on.

MemberRequiredWhat it does
idyesUniquely identifies the connector.
nameyesGives the connector a human-readable name.
descriptionyesDescribes the backend the connector connects to.
iconnoProvides an icon or logo URL.
authyesConfigures authentication.
schemasyesProvides RxDB schemas for each collection.
traitsyesExtracts standard data from connector-specific documents.
syncyes (deprecated)Configures legacy pull-based sync for each collection; use replication instead.
replicationnoProvides per-collection adapters for the RxDB replication protocol.
reconcilenoPeriodically re-reads state that replication misses.
storeSettings(context, choice?)noReads the store's currency, tax inclusivity, tax rates and pricing context once after sign-in without writing to the store.
capabilities(context)noRe-reads contract capabilities for a restored session, returning undefined for an inconclusive read and potentially throwing when the store refuses it.
paymentMethods(context)noReads payment methods in display order; when absent, the till uses defaultPaymentMethods().
receiptTemplates(context, kind?)noReads renderable store print templates online in store order for a kind (default receipt), returning [] when none exist; when absent, the till keeps its built-in layouts.
searchCustomers(context, query, options?)noSearches customers online; an empty or whitespace query may list a first page, or returns [] if the connector cannot list customers.
searchCustomersPage(context, query, options?)noSearches customers online with a total match count and a 1-based page number that defaults to 1.
createCustomer(context, input)noCreates a customer online when the connector supports customers.
updateCustomer(context, id, patch)noEdits a customer online and returns the store's updated customer, rejecting credential failures with ConnectorUnauthorizedError and invalid, server or network failures with CustomerServiceError.
getCustomer(context, id)noLooks up a customer online when the connector supports customers.
emailReceipt(context, orderId, email, options?)noEmails an existing store order's receipt online once per call without automatic retries after timeouts, optionally saving the billing email where supported.
listOrders(context, query?)noReads store orders online, newest first and one page per call, rejecting unsupported filter fields with UnsupportedOrderFilterError.
orderFiltersnoDeclares the filter fields listOrders honours; when absent or empty, listOrders refuses every filter field.
getOrders(context, ids)noReads orders online by store ID in the requested order, omitting IDs the store does not have.
listRegisters(context)noReads the store's register directory online, rejecting credential failures with ConnectorUnauthorizedError and other failures with connector-specific errors.
cashier(context)noReads the signed-in cashier and neutral POS permissions mapped from platform roles or capabilities, returning null if there is no cashier; when absent, the till allows everything.
classifyFailure(error)noSynchronously and purely maps request failures to connectivity or update-required verdicts, returning null when unrelated to connectivity; when absent, neutralFailureClass applies.
displaySignallingnoProvides signalling for a customer display on a second device; when absent, the same-device display still works.

traits.product (ProductTraits) is required and traits.customer (CustomerTraits) is optional; both types are exported from @tallyui/core.

Building a Custom Connector

Implement the TallyConnector interface from @tallyui/core:

import type { TallyConnector } from '@tallyui/core';

export const myConnector: TallyConnector = {
  id: 'my-backend',
  name: 'My Backend',
  description: 'Custom connector for My Backend API',

  auth: { /* ... */ },
  schemas: { products: myProductSchema },
  traits: { product: myProductTraits },
  sync: { products: myProductSync }, // deprecated, still required
  replication: { products: myProductReplication },
};

See the Replication guide for how to implement a ReplicationAdapter, and the WooCommerce connector for a complete example.