AI Context

​

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

​

Domain 2: Product Catalog

​

Domain 3: Usage and Metering

​

Domain 4: Invoicing and Payments

​

Domain 5: Credits and Discounts

---

​

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: ⚠️ 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.