Skip to content

Enrollment sync

Every Zev product owes ZevID a sync of the user's per-product state: their enrollment status, their per-product tier, and a small metadata blob describing the entities they own at that product (businesses for ZevPay, stores for ZevCommerce, projects for ZevCloud, orgs for ZevWorkspace, etc.).

This sync is the mechanism by which ZevID becomes the source of truth for cross-product user state. The DPO concern: every Zev product knows about the user via ZevID instead of duplicating data; we have one place to read what a user is enrolled in and at what tier.

Contract

Each product is responsible for calling PUT /v1/internal/users/{accountId}/enrollments/{productClientId} whenever:

  • The user is created on that product (initial enrollment).
  • The user's tier changes (e.g. ZevPay KYC level moves from 1 to 2).
  • The user gains/loses a sub-entity (new business, store, project, org).
  • The user is removed (account closed on that product).

The PUT carries: tier (opaque to ZevID; product-defined), metadata (JSON blob with the product's sub-entities), isActive (bool).

Spec detail: zevid-backend/docs/product-integration/PROTOCOL.md §7.3 (internal URL).

What goes in metadata

Each product publishes its metadata shape in its own product section and in PUBLISHING_GUIDE.md (internal). Examples:

// ZevPay
{
  "personalKycLevel": 2,
  "businesses": [
    { "id": "<uuid>", "name": "Acme Ltd", "kycLevel": 1 }
  ]
}

// ZevCommerce
{
  "stores": [
    { "id": "<uuid>", "name": "Acme Shop", "slug": "acme" }
  ]
}

Data minimisation in metadata

NDPA §31 — data minimisation. Products should NOT put authorization data (KYC tier as a hard gate, fraud flags, suspension reasons) in metadata; those stay as eligibility-check capability responses. Metadata is for display + identification of sub-entities — names, slugs, ids, image URLs. Not approval state.

Each product's data-flows.md records exactly what it syncs.

Lawful basis

  • Lawful basis: contract performance (NDPA §25(1)(b)) — providing the cross-product Zev experience requires knowing what products a user uses and at what tier. The user enters this contract by signing up to any Zev product.
  • Consent layer: when one product reads detailed data from another (beyond the enrollment-sync minimum), it goes through ZPIP consent.