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.
This page is written for AI assistants and coding agents. If you are a human reader, the core concepts guide 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:
- Customer created — Customer record is set up; becomes the hub all other records reference.
- 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.
- Subscription activated — Signed proposal converts to an active subscription linked to a bundle pricing. ARR/MRR values are stamped here and updated on changes.
- Product assignment — The bundle defines which products and pricing tiers are included. The junction table maps the full product-pricing configuration.
- 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.
- 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.
- 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.
- 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.
