Data Model

In a nutshell

This page documents the internal tables and model relationships used by the billing engine. Use this section for implementation, demo, and handoff context.

Tables

Table	Model	Purpose
`tenants`	Tenant	Business account, API key, webhook URL, Nomba account mapping.
`plans`	Plan	Current plan definition used for new subscriptions.
`plan_versions`	PlanVersion	Versioned plan snapshots used by subscriptions.
`customers`	Customer	Merchant end customer.
`subscriptions`	Subscription	Recurring billing relationship between customer and plan.
`payment_sources`	PaymentSource	Saved card token or bank mandate reference.
`invoices`	Invoice	Amount due for a billing cycle.
`payment_intents`	PaymentIntent	Attempt to collect payment for a subscription/invoice.
`webhook_deliveries`	WebhookDelivery	Outgoing merchant webhook delivery record.
`webhook_delivery_attempts`	WebhookDeliveryAttempt	Individual webhook delivery attempt result.
`nomba_webhook_events`	NombaWebhookEvent	Incoming provider webhook event log model.
`nomba_initiations`	NombaInitiation	Nomba checkout/charge initiation and metadata mapping.
`settlements`	Settlement	Pending/completed/failed settlement record.
`email_deliveries`	EmailDelivery	Queued customer lifecycle emails.

Code prefixes

Object	Generated code prefix
Plan	`PLN_`
Customer	`CUST_`
Subscription	`SUB_`
Invoice	`INV_`
Payment intent	`PAY_`

Core relationships

Tenant
  -> Plans
  -> Customers
       -> PaymentSources
       -> Subscriptions
            -> Invoices
            -> PaymentIntents
  -> WebhookDeliveries
  -> EmailDeliveries

Hidden tenant fields

Most resource JSON responses omit tenantId because the API resolves tenant ownership from the API key. Internal records still store tenant IDs for isolation.

Production Checklist

Billing Lifecycle

⌘I

​Data Model

​In a nutshell

​Tables

​Code prefixes

​Core relationships

​Hidden tenant fields