Skip to main content

Sync Contract

:::info Source Sourced from services/billing-service/SYNC_CONTRACT.md in the documentation repo. :::

1. Applicability​

Limited offline replication. Invoices and payment methods are viewable offline for continuity; payments never processed offline.

2. Registration​

{ service: 'billing', entityType: 'Invoice', conflictPolicy: 'server_authoritative', deltaProjector: 'invoices_by_tenant', pushHandler: 'none', versionField: 'updatedAt', schemaRef: 'schemas://billing/invoice/v1' }
{ service: 'billing', entityType: 'Subscription', conflictPolicy: 'server_authoritative', deltaProjector: 'subs_by_tenant', pushHandler: 'none', versionField: 'updatedAt', schemaRef: 'schemas://billing/subscription/v1' }
{ service: 'billing', entityType: 'PaymentMethod', conflictPolicy: 'server_authoritative', deltaProjector: 'pms_by_customer', pushHandler: 'none', versionField: 'updatedAt', schemaRef: 'schemas://billing/payment_method/v1' }

3. Delta Format​

Server → device upserts only on viewable data. No card numbers cached (tokenized refs + metadata only).

4. Conflict Resolution​

All server-authoritative. Client strictly read-only.

5. Cursor​

Scope: billing:tenant:{tid}.

6. LocalStore​

invoices_view: (id PK, number, total, currency, status, dueAt, pdfUrl?)
subscriptions_view: (id PK, planId, state, currentPeriod, trialEnd?)
payment_methods_view: (id PK, last4, brand, type, isDefault)

PDF URLs cached for offline viewing (signed, may expire; refresh when online).

7. Offline Capability​

  • View invoices offline.
  • View subscription state offline.
  • View saved payment methods offline.
  • Cannot pay, change subscription, or add payment methods offline.

8. Security​

  • No raw card data in client store.
  • PII minimized.
  • Payment methods encrypted with tenant key at rest.

9. Data Classes​

  • Invoice data: Confidential.
  • Payment methods: Restricted (but only tokens offline).