> ## Documentation Index
> Fetch the complete documentation index at: https://nombasub.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Model

> Internal tables and domain objects used by the billing engine.

# 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

```txt theme={null}
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.