> ## Documentation Index > Fetch the complete documentation index at: https://docs.getmeasure.com/llms.txt > Use this file to discover all available pages before exploring further. # AI Context This page is written for AI assistants and coding agents. If you are a human reader, the [core concepts guide](/pages/guides/core-concepts) is a friendlier starting point. ## Data model Measure separates **what you sell** from **how you price it** from **who buys it**. * **What you sell** is defined by Products and BillableItems. * **How you price it** is defined by BillableItemPricings, ProductPricings, and BundlePricings. * **Who buys it** is defined by Customers and Subscriptions. *** ## Billing lifecycle Every billable event in Measure flows through these stages: 1. **Customer created** — Customer record is set up; becomes the hub all other records reference. 2. **Proposal / quote** — Sales sends a CPQ proposal with TCV/ACV. Proposals can include one-time charges. The subscription link is populated once a proposal converts. 3. **Subscription activated** — Signed proposal converts to an active subscription linked to a bundle pricing. ARR/MRR values are stamped here and updated on changes. 4. **Product assignment** — The bundle defines which products and pricing tiers are included. The junction table maps the full product-pricing configuration. 5. **Usage metering** — Each billing period, usage is recorded for metered products. Billable metrics define how consumption is aggregated; pricing rules define how it is charged. 6. **Invoice generated** — At billing cycle end, Measure creates an invoice. Each product/charge becomes a line item. Discounts and credits are applied and reflected in line items and totals. 7. **Discounts and credits applied** — Active discounts (% or fixed) are applied at invoice time. Credits are drawn down from a balance. Both have ledger tables tracking exactly when and how much was applied per invoice. 8. **Payment captured** — Stripe (or other provider) processes payment. Each transaction records gross, net, and fee breakdown. Joins to invoices via UUID (not id). *** ## Schema domains The schema is organized into five domains. ### Domain 1: Core Entities | Table | Description | | --------------- | ------------------------------------------------------------------------------------------------ | | `customers` | Primary billing entity. Nearly every other table has a `customer_id → customers.id` foreign key. | | `subscriptions` | Recurring billing agreements. Tracks ARR/MRR, billing cycles, trial status, and renewal config. | | `proposals` | Sales quotes/CPQ proposals that convert into subscriptions. Tracks TCV/ACV and deal lifecycle. | ### Domain 2: Product Catalog | Table | Description | | ------------------------- | ----------------------------------------------------------------------------------------------- | | `products` | Top-level sellable products. Foundation of the product catalog. | | `product_pricings` | Multiple pricing plans per product — supports different tiers per currency, region, or package. | | `bundle_pricings` | Packaged groups of products. Referenced by `subscriptions.bundle_pricing_id`. | | `bundle_product_pricings` | Junction table: maps bundle → product → pricing tier (three-way mapping). | | `entitlements` | Feature flag definitions associated with products and pricing tiers. | ### Domain 3: Usage and Metering | Table | Description | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `billable_items` | Measurable units of consumption. Foundation of usage-based billing. | | `billable_item_pricings` | Pricing rules — supports volume, step, gradient, credit, and custom models. | | `billable_metrics` | Metric definitions that meter billable items. Defines how consumption is aggregated. | | `product_metric_pricings` | Central junction table (5 FKs) tying products, pricing tiers, billable items, item pricing, and metrics together. The most connected table in the schema. | | `subscription_metric_pricing_records` | Per-period metering records for each subscription. Highest-volume table in the schema. | ### Domain 4: Invoicing and Payments | Table | Description | | ---------------------- | ------------------------------------------------------------------------------------- | | `invoices` | Billing documents issued to customers. Has both `id` and `uuid` fields (see gotchas). | | `invoice_line_items` | Individual charges on an invoice, broken down by product/metric. | | `payment_transactions` | Payment records (charges, refunds) synced from Stripe or other providers. | | `one_time_billables` | One-off charges tied to proposals or customers. Non-recurring line items. | ### Domain 5: Credits and Discounts | Table | Description | | --------------- | ----------------------------------------------------------------------------- | | `credits` | Credit balances issued to customers or subscriptions. | | `credit_logs` | Ledger of credit applications and adjustments per invoice. | | `discounts` | Discount rules (% or fixed) applied to customers, subscriptions, or products. | | `discount_logs` | Ledger of discount applications per invoice. | *** ## Object reference ### Customers Primary billing entity. Nearly every other table has a `customer_id → customers.id` foreign key. Key fields: * `id` — Primary key. Referenced by nearly every table. * `identifier` — Your external ID. Accepted in most API calls as an alternative to the Measure-assigned `id`. * `name`, `org_name` — Display names. * `status` — `ACTIVE` or `ARCHIVED`. * `parent_customer_id` — Self-referencing FK for customer hierarchy (parent billing). * `exclude_from_metrics` — Filter flag for test or internal accounts; exclude from ARR/MRR calculations. * `billing_emails` — JSON array of billing contact emails. * `tags`, `metadata` — JSON fields for flexible categorization and custom attributes. * `mrr` / `arr` — Computed fields derived from active subscriptions. Do not set directly. * `computed_entitlements` — Aggregated feature access derived from all active subscriptions. This is a JSON object where each key is an entitlement key and the value is the resolved entitlement value across all active subscriptions. Use this field to check what a customer currently has access to without traversing the full subscription → bundle → product → entitlement chain. Do not set directly; it is recomputed whenever subscriptions change. ### Subscriptions Recurring billing agreements. Tracks ARR/MRR, billing cycles, trial status, and renewal config. Key fields: * `customer_id` — FK to `customers`. * `bundle_pricing_id` — FK to `bundle_pricings`. Defines what is being billed. * `status` — `ACTIVE`, `CANCELLED`, `UNPAID`, or `PENDING_PAYMENT`. * `start_date`, `end_date`, `renewal_date`, `cancel_date` — Lifecycle dates (stored as TEXT; see gotchas). * `next_invoice_date` — The upcoming invoice date. * `billing_anchor_date` — Anchor date that controls billing cycle alignment. * `arr_value_in_cents`, `mrr_value_in_cents` — Monetary values in cents (divide by 100 for dollars). * `minimum_spend_value_in_cents` — Contractual minimum spend. * `auto_renews` — Whether subscription renews automatically at term end. * `auto_charges` — Whether invoices are auto-charged to the default payment method. * `trial` — Whether this is a trial subscription. * `trial_conversion_date` — When trial converted to paid. * `config_items` — Per-subscription overrides. Most commonly used to set `num_licenses` (seat count) for LICENSE\_ITEM pricing. * `computed_entitlements` — Derived feature access based on active pricing. **Cancel timings**: `IMMEDIATE`, `PERIOD_END`, `RENEWAL`, `CUSTOM`. **Change timings** (plan upgrade/downgrade): `IMMEDIATE`, `PERIOD_END`, `RENEWAL`, `CUSTOM`, `RELATIVE`. **Proration types** (for mid-cycle changes): `NONE`, `NEXT` (credit on next invoice), `IMMEDIATE` (charge or credit now). ### Proposals Sales quotes/CPQ proposals that convert into subscriptions. Tracks TCV/ACV and deal lifecycle. Key fields: * `customer_id` — FK to `customers`. * `subscription_id` — FK to `subscriptions` (may be `NULL` if not yet converted). * `bundle_pricing_id` — FK to `bundle_pricings`. * `status` — Proposal lifecycle state. * `tcv_value_in_cents` — Total contract value. * `acv_value_in_cents` — Annual contract value. * `signed_date` — When the deal was signed. * `start_date`, `expiration_date`, `finalized_date`, `completed_date` — Deal timeline dates. * `auto_charges`, `auto_renew`, `trial` — Flags carried forward to the subscription on conversion. ### Products Top-level sellable products. Foundation of the product catalog. Key fields: * `id` — Primary key. * `name` / `external_name` — Internal and customer-facing names. * `state` — `ACTIVE` or `ARCHIVED`. * `entitlements` — Feature flags this product grants (JSON). * `tags`, `metadata` — Flexible categorization (JSON). ### Product Pricings Multiple pricing plans per product — supports different tiers per currency, region, or package. Key fields: * `product_id` — FK to `products`. * `name` / `external_name` — Internal and customer-facing names. * `currency` — Each ProductPricing is for a single currency. To sell in multiple currencies, create multiple ProductPricings. * `state` — `ACTIVE` or `ARCHIVED`. Archived pricings cannot be assigned to new subscriptions. * `num_subs` — Count of subscriptions currently on this pricing. * `entitlements` — Tier-specific feature grants (JSON). ### Bundle Pricings Packaged groups of products. Referenced by `subscriptions.bundle_pricing_id`. Key fields: * `name` / `key` — Identity fields. * `currency` — Pricing currency. * `default_term_count` / `default_term_frequency` — Default billing cycle. * `state` — `ACTIVE` or `ARCHIVED`. * `num_subs` — Count of active subscriptions using this bundle. Most companies create one bundle per tier (e.g., Starter, Growth, Enterprise). ### Bundle Product Pricings Junction table: maps bundle → product → pricing tier (three-way mapping). Key fields: * `bundle_pricing_id` — FK to `bundle_pricings`. * `product_id` — FK to `products`. * `product_pricing_id` — FK to `product_pricings`. ### Billable Items Measurable units of consumption. Foundation of usage-based billing. Key fields: * `name` / `external_name` — Internal and customer-facing names. * `state` — `ACTIVE` or `ARCHIVED`. * `standard` — Whether this is a standard vs. custom item. Item types: * `LICENSE_ITEM` — Seat or license based. Quantity set on the subscription via `config_items.num_licenses`. * `CUSTOM_USAGE` — Event-driven. Customers send events via the ingest API; Measure aggregates at billing time. * `CUSTOM_OBJ` — Object-based. Customers sync objects (e.g., active accounts); Measure counts or sums them. * `ONETIME_ITEM` — One-time charge not tied to a recurring billing period. ### Billable Metrics Metric definitions that meter billable items. Defines how consumption is aggregated. Key fields: * `item_id` — FK to `billable_items`. * `name` / `external_name` — Identity fields. * `metering_rule` — JSON: aggregation logic and filter rules. * `standard` — Whether this is a standard vs. custom metric. Aggregator types: `COUNT`, `SUM`, `MAX`, `AVG`, `UNIQUE`, `UNIQUE_DAILY`, `OBJ_COUNT`, `OBJ_SUM`, `OBJ_MAX`, `OBJ_UNIQUE`, `OBJ_PRORATED_COUNT`, `CUSTOMER_FIXED`, `CUSTOMER_LAST_EVER`, `CUSTOMER_LAST_PERIOD`, `LAST_EVER_SUM`. ### Billable Item Pricings Pricing rules — supports volume, step, gradient, credit, and custom models. Key fields: * `item_id` — FK to `billable_items`. * `charge_type` — `FIXED`, `STEP`, `GRADIENT`, `VOLUME`, `CUSTOM`, or `SCHEDULED`. * `frequency` — Billing frequency: `HOUR`, `DAY`, `WEEK`, `BI_MONTH`, `MONTH`, `QUARTER`, `BI_ANNUAL`, `YEAR`, or `ONETIME`. * `term_count` — How many frequency periods make one billing cycle. * `base_price_value_in_cents`, `volume_price`, `step_price`, `gradient_price`, `custom_price` — Pricing model data (JSON for tiered models). * `true_up_frequency` — How often usage is reconciled if it differs from billing frequency. * `carry_over` — Whether unused units roll over to the next period. * `base_units` — Included units before charges begin. * `proration_type` — How proration is calculated on mid-cycle changes. ### Product Metric Pricings Central junction table (5 FKs) tying products, pricing tiers, billable items, item pricing, and metrics together. The most connected table in the schema. Key fields: * `product_id` — FK to `products`. * `product_pricing_id` — FK to `product_pricings`. * `item_id` — FK to `billable_items`. * `item_pricing_id` — FK to `billable_item_pricings`. * `metric_id` — FK to `billable_metrics`. ### Subscription Metric Pricing Records Per-period metering records for each subscription. Highest-volume table in the schema. Key fields: * `subscription_id` — FK to `subscriptions`. * `customer_id` — FK to `customers` (denormalized for query performance). * `product_metric_pricing_id` — FK to `product_metric_pricings`. * `item_pricing_id` — The pricing rule used for this period. * `metric_id` — Which metric was measured. * `period_start_date`, `period_end_date` — Billing period boundaries (stored as TEXT). * `pre_charged_amount_value_in_cents` — Pre-computed charge amount. * `metric_meter` — JSON: meter reading for this period. * `state` — Record state. ### Invoices Billing documents issued to customers. Has both `id` and `uuid` fields (see gotchas). Key fields: * `id` — Primary key. * `uuid` — UUID field. **Payment transactions join on this field, not `id`.** * `customer_id` — FK to `customers`. * `billed_customer_id` — The customer actually billed (differs from `customer_id` in parent billing scenarios where a child's invoice rolls up to the parent). * `subscription_id` — FK to `subscriptions` (may be `NULL` for one-time invoices). * `proposal_id` — FK to `proposals` (optional). * `number` — Human-readable invoice number. * `status` — Lifecycle: `DRAFT` → `OPEN` → `PAID` / `VOID` / `UNCOLLECTIBLE`. * `invoice_date`, `due_date`, `paid_date` — Timeline dates (stored as TEXT). * `subtotal_value_in_cents` — Pre-tax subtotal. * `total_value_in_cents`, `paid_value_in_cents`, `due_value_in_cents` — Monetary totals. * `prorated_amount_value_in_cents` — Prorated portion of the invoice. * `pre_payment_credit_amount_value_in_cents`, `post_payment_credit_amount_value_in_cents` — Credits applied before and after payment. ### Invoice Line Items Individual charges on an invoice, broken down by product/metric. Key fields: * `invoice_id` — FK to `invoices`. * `subscription_id`, `product_id`, `product_metric_pricing_id` — Context FKs. * `description` — Line item description. * `quantity` — Units billed. * `amount_value_in_cents` — Total line charge. * `unit_price_value_in_cents` — Per-unit price. * `discount_applied_value_in_cents`, `tax_applied_value_in_cents` — Adjustments applied to this line. * `period_start_date`, `period_end_date` — Billing period for this line. * `proration` — Whether this is a prorated charge. * `taxable` — Whether this line is subject to tax. ### Payment Transactions Payment records (charges, refunds) synced from Stripe or other providers. Key fields: * `customer_id` — FK to `customers`. * `invoice_uuid` — **Joins to `invoices.uuid`, not `invoices.id`.** * `invoice_number` — Invoice number (denormalized). * `status` — Transaction state. * `transaction_type` — `CHARGE`, `REFUND`, etc. * `total_amount_value_in_cents` — Gross transaction amount. * `net_amount_value_in_cents` — Net after fees. * `total_fee_amount_value_in_cents` — Total fees. * `stripe_fee_amount_value_in_cents` — Stripe processing fee. * `tax_fee_amount_value_in_cents` — Tax fee component. * `provider_type` — Payment provider (Stripe, etc.). * `provider_transaction_id` — External transaction reference for reconciliation. * `captured_at` — When payment was captured (stored as TEXT). ### One Time Billables One-off charges tied to proposals or customers. Non-recurring line items. Key fields: * `customer_id` — FK to `customers`. * `proposal_id` — FK to `proposals`. * `product_pricing_id` — Associated pricing. * `name` — Charge description. * `state` — `ACTIVE` or `ARCHIVED`. * `aggregate` — Whether this charge is aggregated with other charges on the invoice. ### Credits Credit balances issued to customers or subscriptions. Key fields: * `customer_id` — FK to `customers`. * `subscription_id` — FK to `subscriptions` (may be `NULL` for customer-level credits). * `amount_value_in_cents` — Remaining monetary balance. * `issued_amount_value_in_cents` — Original issued amount. * `issued_units` / `units` — Unit-based credit issued and remaining. * `state` — `ACTIVE`, `EXPIRED`, or `CONSUMED`. * `expiration_date` — When the credit expires. * `coupon_id` — The originating coupon, if applicable. ### Credit Logs Ledger of credit applications and adjustments per invoice. Key fields: * `credit_id` — FK to `credits`. * `customer_id` — FK to `customers` (denormalized). * `invoice_id` — FK to `invoices` (which invoice consumed this credit). * `action_type` — What happened (applied, reversed, etc.). * `amount_applied_value_in_cents` — Monetary amount used. * `units_applied` — Units consumed (for unit-based credits). * `note` — Free-text note on the adjustment. ### Discounts Discount rules (% or fixed) applied to customers, subscriptions, or products. Key fields: * `customer_id` — FK to `customers`. * `subscription_id` — FK to `subscriptions` (may be `NULL`). * `product_id` — FK to `products` (for product-specific discounts). * `amount_value_in_cents` — Fixed discount amount. * `percent` — Percentage discount. * `cap_value_in_cents` — Maximum discount cap. * `state` — `ACTIVE` or `EXPIRED`. * `expiration_date` — When discount expires. * `coupon_id` — The originating coupon, if applicable. * `proposal_id` — The proposal this discount was created from, if applicable. ### Discount Logs Ledger of discount applications per invoice. Key fields: * `discount_id` — FK to `discounts`. * `customer_id` — FK to `customers` (denormalized). * `invoice_id` — FK to `invoices`. * `subscription_id` — FK to `subscriptions`. * `amount_applied_value_in_cents` — Fixed amount applied. * `cap_applied_value_in_cents` — Cap that was enforced. * `percent_applied` — Percentage applied. ### Entitlements Feature flag definitions associated with products and pricing tiers. Key fields: * `key` — Feature identifier. * `name` — Display name. * `possible_values` — JSON: allowed values. * `aggregator_type` — How values combine across products. Entitlements are inherited by customers via their active subscriptions. Values can be boolean, numeric, or string. *** ## Foreign key map All 39 relationships in the schema: | From | Field | To | | ------------------------------------- | --------------------------- | ---------------------------- | | `subscriptions` | `customer_id` | `customers.id` | | `proposals` | `customer_id` | `customers.id` | | `proposals` | `subscription_id` | `subscriptions.id` | | `invoices` | `customer_id` | `customers.id` | | `invoices` | `subscription_id` | `subscriptions.id` | | `invoices` | `proposal_id` | `proposals.id` | | `invoice_line_items` | `invoice_id` | `invoices.id` | | `invoice_line_items` | `subscription_id` | `subscriptions.id` | | `invoice_line_items` | `product_id` | `products.id` | | `invoice_line_items` | `product_metric_pricing_id` | `product_metric_pricings.id` | | `payment_transactions` | `customer_id` | `customers.id` | | `payment_transactions` | `invoice_uuid` | `invoices.uuid` ⚠️ | | `credits` | `customer_id` | `customers.id` | | `credits` | `subscription_id` | `subscriptions.id` | | `credit_logs` | `credit_id` | `credits.id` | | `credit_logs` | `customer_id` | `customers.id` | | `credit_logs` | `invoice_id` | `invoices.id` | | `discounts` | `customer_id` | `customers.id` | | `discounts` | `subscription_id` | `subscriptions.id` | | `discounts` | `product_id` | `products.id` | | `discount_logs` | `discount_id` | `discounts.id` | | `discount_logs` | `customer_id` | `customers.id` | | `discount_logs` | `invoice_id` | `invoices.id` | | `product_pricings` | `product_id` | `products.id` | | `bundle_product_pricings` | `bundle_pricing_id` | `bundle_pricings.id` | | `bundle_product_pricings` | `product_id` | `products.id` | | `bundle_product_pricings` | `product_pricing_id` | `product_pricings.id` | | `billable_item_pricings` | `item_id` | `billable_items.id` | | `billable_metrics` | `item_id` | `billable_items.id` | | `product_metric_pricings` | `product_id` | `products.id` | | `product_metric_pricings` | `product_pricing_id` | `product_pricings.id` | | `product_metric_pricings` | `item_id` | `billable_items.id` | | `product_metric_pricings` | `item_pricing_id` | `billable_item_pricings.id` | | `product_metric_pricings` | `metric_id` | `billable_metrics.id` | | `subscription_metric_pricing_records` | `subscription_id` | `subscriptions.id` | | `subscription_metric_pricing_records` | `customer_id` | `customers.id` | | `subscription_metric_pricing_records` | `product_metric_pricing_id` | `product_metric_pricings.id` | | `one_time_billables` | `customer_id` | `customers.id` | | `one_time_billables` | `proposal_id` | `proposals.id` | ⚠️ `payment_transactions.invoice_uuid` joins to `invoices.uuid`, not `invoices.id`. *** ## Common patterns **Look up a customer**: Use `identifier` (your external ID) or the Measure-assigned `id`. Both are accepted in GET `/customers` endpoints. **Find a customer's current plan**: Fetch the customer's active subscriptions, then follow `bundle_pricing_id` to the BundlePricing. Use `GET /bundle_pricings/{id}` to see the products inside. **Understand what a subscription costs**: Fetch the BundlePricing, then its BundleProductPricings, then each ProductPricing's ProductMetricPricings to see the items and BillableItemPricings. **Preview an upcoming invoice**: Use the `next_invoice` tool or endpoint. It supports simulating a plan change or cancellation. **Change a subscription's plan**: `PATCH /subscriptions/{id}` with a `change_config` specifying the new `bundle_pricing_id`, change `timing`, and `proration_type`. **Cancel a subscription**: `PATCH /subscriptions/{id}` with a `cancel_config` specifying `timing` and `refund_type`. **Apply a credit**: `POST /credits` with the customer ID, amount, and currency. Credits are applied automatically to the next invoice. **Get payment history for an invoice**: Join `payment_transactions.invoice_uuid = invoices.uuid` — not `invoices.id`.