AIFilterParseRequest
page_idPage the filters apply to (e.g. customers, invoices)
queryNatural-language filter query (max 500 chars)
ActivePromotion
effect_typeKind of effect the promotion applies (e.g. a percentage or fixed discount).
nameDisplay name of the promotion.
promotion_idThe applied promotion.
discount_valueEffect magnitude as a decimal string; empty when not applicable.
expires_atInstant this promotion stops applying to the subscription; null for open-ended.
Actor
typeemailkey_idkey_prefixlabelnamepictureuser_idAddInvoiceLineRequest
amount^-?\d+(\.\d+)?$MAJOR units, in the addressed invoice's currency. Convenience alias for unit_price when quantity is 1.
currencyOptional echo-guard: must equal the invoice's currency when set.
descriptionLine description; required unless product_id is set, in which case the product name is used.
line_typeManual line type: EXPENSE_PASSTHROUGH, MILESTONE, ADJUSTMENT, or CREDIT; defaults to ADD_ON when omitted.
markup_percent^-?\d+(\.\d+)?$Optional markup applied on top of a product-resolved price, as a percentage (0-1000); ignored when product_id is not set.
Arbitrary caller-supplied key/value pairs.
period_endOptional end of the service period this line covers; must be on or after period_start.
period_startOptional start of the service period this line covers.
product_idOptional catalog product; when set, the service resolves the active price and description and unit_price may be omitted.
quantity^-?\d+(\.\d+)?$Billed quantity; defaults to 1 when omitted. Must be positive.
tax_category_codeEN16931 VAT category (S/Z/E/AE/K/G/O); when set, overrides tax resolution for this line.
tax_exemption_reasonBT-120 exemption reason text; required when tax_category_code is a non-standard (Z/E/AE/K/G/O) category.
tax_rate^-?\d+(\.\d+)?$Optional tax rate override for this line, as a fraction between 0 and 1 (0.19 = 19%).
unit_price^-?\d+(\.\d+)?$MAJOR units, in the addressed invoice's currency.
AddItemRequest
auto_renewWhether the committed term auto-renews at term end; only meaningful with a term.
effective_atWhen the new item starts being billed: null adds it now, a future instant queues it at that boundary; past is rejected.
price_keyKey-set entry to bill under; set only for keyed products.
product_idProduct to add as a billable item.
proration_modeHow the mid-period addition is charged: pro_rata, pay_in_full or do_not_charge; defaults to pro_rata.
quantityNumber of units to bill for the new item; must be at least 1.
term_countNumber of term units the item is committed for; set together with term_unit.
term_unitCommitment term unit (week/month/year); set with term_count to bill the whole term upfront, or leave both nil to follow the subscription cadence.
AddProductRequest
credit_unit_value^-?\d+(\.\d+)?$Money value of one POOL unit, MAJOR units in currency; POOL only.
currencyISO 4217 currency for a POOL's money-denominated knobs (credit_unit_value, spend_limit).
included_quantity^-?\d+(\.\d+)?$Quantity bundled into the base price before per-unit billing applies (the included allowance/seat floor); null means none.
kindEntitlement kind: REFRESHING (per-period allowance, the empty-string default) or POOL (durable credit that never resets).
Free-form operator key/value metadata for this membership.
product_idProduct to attach to the plan.
product_track_modeHow this membership tracks the product version: latest (auto-follow head) or pinned; omitted seeds from the org default.
refresh_countPlan-level default allowance-refresh cadence count; null (with refresh_unit) means one whole-period pool.
refresh_unitUnit for the refresh cadence: day, week, month, year or billing_cycle.
rollover_enabledWhen true, unused included allowance carries forward into later periods.
rollover_expiry_periodsNumber of periods after which rolled-over allowance expires; null means it never expires.
rollover_max^-?\d+(\.\d+)?$Cap on accumulated rolled-over allowance; null means uncapped.
spend_limit^-?\d+(\.\d+)?$Ceiling on a POOL's money spend, MAJOR units in currency; POOL only.
unit_limit^-?\d+(\.\d+)?$Ceiling on a POOL's unit balance; POOL only.
AdjustRequest
amount^-?\d+(\.\d+)?$Signed adjustment, MAJOR units, in the addressed wallet's currency.
currencyOptional echo-guard: must equal the wallet's currency when set.
reasonOptional free-text explanation stored on the ledger entry.
referenceOptional external reference; a repeated (source, reference) is treated as an idempotent replay.
sourceWhat originates the adjustment: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER.
AllowanceRolledOverPayload
expires_atWhen the rolled-over allowance expires (RFC3339), when capped.
invoice_idThe invoice the roll-over was computed against.
organization_idperiod_endThe end of the billing period the allowance carried into (RFC3339).
period_startThe start of the billing period the allowance carried into (RFC3339).
product_idThe metered product the allowance belongs to.
quantityThe unused allowance quantity carried forward, as a decimal string.
subscription_idThe subscription whose allowance rolled over.
workspace_idThe workspace that owns the subscription.
AllowanceStateResponse
current_period_endEnd of the billing period the snapshot covers (RFC-3339).
current_period_startStart of the billing period the snapshot covers (RFC-3339).
Per-product allowance state for the subscription.
subscription_idThe subscription this allowance snapshot is for.
AppliedReserveDiscount
amount^-?\d+(\.\d+)?$Amount of the up-front reduction, MAJOR units in the hold's currency.
promotion_idPromotion that reduced this hold up-front.
ApplyCreditNoteRequest
amount^-?\d+(\.\d+)?$MAJOR units, in the addressed credit note's currency.
currencyOptional echo-guard: must equal the credit note's currency when set.
invoice_idInvoice to apply the credit against, or refund from (required).
ApprovalDecision
approval_request_iddecided_atdecided_bydecisionidstep_numbercommentApprovalRequest
created_atcurrent_stepentity_identity_typeidinitiated_byorganization_idstatusstep_started_attrigger_actionupdated_atworkflow_template_idpayloadprevious_stateresolved_atworkspace_idApprovalRequestApprovedPayload
entity_idThe id of the entity that was approved.
entity_typeThe kind of entity that was approved (e.g. INVOICE, PLAN).
request_idThe approval request that was fully approved.
ApprovalRequestAutoRejectedPayload
organization_idrequest_idThe approval request that was auto-rejected.
step_numberThe step at which the request was auto-rejected.
ApprovalRequestCancelledPayload
cancelled_byThe actor who cancelled the request.
request_idThe approval request that was cancelled.
ApprovalRequestCreatedPayload
entity_idThe id of the entity awaiting approval.
entity_typeThe kind of entity awaiting approval (e.g. INVOICE, PLAN).
initiated_byThe actor who initiated the request.
organization_idrequest_idThe approval request that was created.
step_countThe number of approval steps in the workflow.
trigger_actionThe action that required approval.
workspace_idThe workspace that owns the approval request.
ApprovalRequestRejectedPayload
decided_byThe actor who rejected the request.
entity_idThe id of the entity that was rejected.
entity_typeThe kind of entity that was rejected (e.g. INVOICE, PLAN).
request_idThe approval request that was rejected.
step_numberThe step at which the request was rejected.
ApprovalStepApprovedPayload
decided_byThe actor who approved the step.
request_idThe approval request the step belongs to.
step_numberThe 1-based number of the approved step.
ApprovalStepAutoApprovedPayload
organization_idrequest_idThe approval request the step belongs to.
step_numberThe 1-based number of the auto-approved step.
ApprovalStepEscalatedPayload
organization_idrequest_idThe approval request the escalated step belongs to.
step_numberThe step that was escalated.
ApprovalStepStartedPayload
approver_rolesThe roles allowed to decide this step.
request_idThe approval request the step belongs to.
step_numberThe 1-based number of the started step.
AttachIDPRequest
aliasdisplay_nameenabledhide_on_loginprovider_idAudienceMatch
customer_idcustomer_typeemailnamecountryredemption_statusAudiencePreviewResponse
all_customerstotalAuditEvent
event_typeidoccurred_atorganization_idactor_emailactor_key_idactor_key_prefixactor_labelactor_nameactor_pictureactor_typeactor_user_idcausation_idcorrelation_idcustomer_iddiffdomainentityentity_identity_typepayloadplan_idproduct_idrequest_idseveritysubscription_idsummarytrace_idverbvisibilityAuditEventRetentionPolicy
created_atevent_typeidorganization_idretention_daysupdated_atBatchIngestRequest
Usage events to ingest in one call; 1-1000 per batch, one external_cost_currency per (subscription, metric) group.
Branding
company_nameCompany name shown alongside or in place of the logo.
logo_heightRendered logo height in millimeters (mm).
logo_urlURL of the logo image to render in the document header.
logo_widthRendered logo width in millimeters (mm).
BrandingUpsertRequest
accent_colorcustom_cssdisplay_namefavicon_urllogo_urlprimary_colorprivacy_urlsupport_emailsupport_urlterms_urlBreakdown
applied_to_invoice_linesdirect_subscriptionspinned_by_planspinned_by_pricessubscription_historysubscription_itemsused_in_invoice_atomsused_in_invoice_linesBreakdownAdjustment
Signed amount this adjustment contributes to the effective price.
labelHuman-readable description of the adjustment.
typeKind of adjustment: override, tier, formula, promotion, or conversion.
BulkArchiveResponse
archived_countblocked_countBulkEnrollResponse
cap_reachedenrolledfailedrequestedskippedBulkUpgradeRequest
forceWhen true, upgrade even subscriptions pinned to their current version.
scheduled_atReserved for future scheduling; rejected with a validation error when set (per-sub scheduling parity is a pending followup).
strategyMoney policy for each upgrade: immediate_prorate, next_period or at_phase_change.
subscription_idsSubscriptions to upgrade; at least one, at most 500.
target_plan_versionPlan version to move plan-based subscriptions to; null leaves plan-based subs untouched.
target_product_versionProduct version to move product-based subscriptions to; null leaves product-based subs untouched.
BulkUpgradeResponse
Subscriptions that were skipped or failed, each with a reason.
Subscriptions that were upgraded.
BulkUpgradeSkippedRow
reasonWhy the subscription was skipped or failed.
sub_idThe subscription that was not upgraded.
BulkUpgradeUpgradedRow
new_versionVersion the subscription now sits on.
sub_idThe upgraded subscription.
CaptureHoldRequest
amount^-?\d+(\.\d+)?$Partial-capture amount, MAJOR units, in the hold's currency. Omitted: captures the full held amount.
referenceOptional external reference recorded on the capture's ledger entry.
ChangeCustomerModeRequest
modeTarget wallet settlement mode: PREPAID or POSTPAID.
reasonOptional audit-trail reason for the mode change.
ChangeCustomerTypeRequest
customer_typeTarget buyer classification: BUSINESS, CONSUMER, or UNKNOWN.
reasonAudit-trail reason for the type change. Required.
ChangeQuantityRequest
effective_atWhen the change takes effect: null applies now, a future instant queues it at that boundary; past is rejected.
new_quantityNew quantity to bill for the item; must be at least 1.
subscription_item_idThe subscription item to restate the quantity on.
ChangeSubscriptionVersionRequest
effective_atEffective instant for an immediate-strategy bump; null stamps the server's current time. Ignored by the deferred strategies.
scheduled_atSchedule the bump at an explicit future instant instead of a billing boundary; pair with strategy=immediate_prorate. null = not date-scheduled.
strategyHow the change is realized in money: immediate_prorate, next_period or at_phase_change; required.
target_latestWhen true, resolve to the plan/product head version. Mutually exclusive with target_version.
target_versionConcrete version to pin to; null uses target_latest instead. Mutually exclusive with target_latest.
update_track_modeOptionally flip the track mode (pinned↔latest) as part of the change; null leaves it unchanged.
ChargeInvoiceResponse
attempt_idThe payment attempt row created for this charge.
attempt_numberOne-based sequence number of this attempt for the invoice.
invoice_idThe invoice being charged.
providerPayment provider resolved for the charge (e.g. stripe, gocardless).
scheduled_forWhen the retry worker will execute the attempt; set to now for immediate execution.
checkout_urlProvider hosted-checkout URL to redirect the customer to; empty for providers without a hosted flow.
CheckoutLink
collect_addresscollect_phonecollect_vat_idcreated_atidmetadataorganization_idplan_idslugstatusupdated_atcurrencydefault_billing_timingdefault_payment_terms_daysdefault_preferred_providerdefault_wallet_modenamesuccess_urltax_inclusivetrial_daysvat_id_collectionCheckoutLinkCreateRequest
collect_addresscollect_phonecollect_vat_idcurrencydefault_billing_timingdefault_payment_terms_daysdefault_preferred_providerdefault_wallet_modemetadatanameplan_idslugsuccess_urltax_inclusivetrial_daysvat_id_collectionCheckoutLinkUpdateRequest
collect_addresscollect_phonecollect_vat_idcurrencydefault_billing_timingdefault_payment_terms_daysdefault_preferred_providerdefault_wallet_modemetadatanamestatussuccess_urltax_inclusivetrial_daysvat_id_collectionChildSetDiff
addedchangedremovedChurnResponse
churned_countNumber of customers who churned this month.
current_rateThis month's churn rate as a fraction between 0 and 1.
previous_ratePrior month's churn rate as a fraction between 0 and 1.
total_customersNumber of currently active customers.
ClawbackComponent
amount^-?\d+(\.\d+)?$ · requiredDecimal number encoded as a string to preserve precision.
currencysourceClawbackResult
already_clawed_backredemption_idclawed_back_atComputePriceRequest
debugWhen true, the response includes a step-by-step evaluation trace.
expressionAd-hoc expression to evaluate; either this or formula_id is required.
formula_idA stored formula to evaluate; either this or expression is required.
Variable bindings supplied to the evaluation, keyed by variable name.
ComputePriceResponse
expressionThe expression that was evaluated.
resultThe evaluated result as a decimal string.
The variable bindings used in the evaluation, as decimal strings.
debug_traceStep-by-step evaluation trace, present only when debug was requested.
formula_idThe formula that was evaluated, when formula_id was supplied.
formula_versionThe formula version that was evaluated, when a stored formula was used.
Condition
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · kind="minimum_spend" | |
| type = object · kind="subscription_plan" | |
| type = object · kind="external_verification" | |
| type = object · kind="product_combination" | |
| type = object · kind="quantity_threshold" | |
| type = object · kind="first_purchase" | |
| type = object · kind="usage_threshold" |
kindUnion discriminator.
amount^-?\d+(\.\d+)?$Minimum spend the customer must reach for the condition to pass, MAJOR units in the currency field.
currencyISO 4217 currency the amount / max_amount thresholds are denominated in.
max_amount^-?\d+(\.\d+)?$Optional upper bound (MAJOR units); when set the spend must fall within [amount, max_amount] rather than merely meeting the minimum.
scopeWhich spend total the threshold measures: per_invoice (current invoice subtotal, default), period (spend in the current billing period), or lifetime (total spend ever).
ConditionDetail
passedWhether this individual condition passed.
reasonHuman-readable explanation of why the condition passed or failed.
typeThe condition kind that was evaluated (e.g. minimum_spend, product_combination).
ConditionMeta
applies_atWhen the condition is evaluated: REDEEM_TIME, INVOICE_TIME, or BOTH.
summaryOne-line human-readable description of the condition.
typeThe condition kind (e.g. minimum_spend, product_combination).
ConditionPreview
applies_atWhen the condition is evaluated: REDEEM_TIME, INVOICE_TIME, or BOTH.
passedWhether this condition currently passes for the customer.
summaryHuman-readable description of the condition.
typeThe condition kind (e.g. minimum_spend, product_combination).
ConditionSet
conditionsThe conditions to evaluate; each is a discriminated {kind, ...params} object. An empty set is always eligible.
modeHow the conditions combine: ALL (every condition must pass, default) or ANY (at least one).
ConsentItem
audiencekeykindrequiredtypeversionCopyAsDraftRequest
effective_fromEffective-from timestamp for the new draft version.
effective_toOptional effective-to timestamp for the new draft version.
noteOptional note for the new draft version.
CopyProductAsDraftRequest
external_idExternal identifier for the new draft copy.
nameName for the new draft copy; defaults to a derived copy name when omitted.
CopyPromotionAsDraftRequest
codeCoupon code for the new draft; only valid when the promotion's distribution is COUPON.
nameName for the new draft; defaults to the source promotion's name suffixed as a copy when omitted.
valid_fromFirst calendar day (UTC) the new draft is valid; required.
valid_toLast calendar day (UTC) the new draft is valid, inclusive; null = open-ended.
CorrectiveInvoiceReviewRequiredPayload
currencyThe invoice currency, ISO-4217.
customer_idThe customer whose corrective invoice needs review.
flagged_atWhen the invoice was flagged for review (RFC3339).
from_typeThe customer type the invoice was issued under.
invoice_idThe invoice flagged for corrective review.
issued_atWhen the invoice was issued (RFC3339).
organization_idto_typeThe customer type the change moves to.
The invoice grand total, as a money object.
trigger_eventThe event that triggered the corrective-review flag.
workspace_idThe workspace that owns the invoice.
Cost
created_atidkeyFormula-reference key for this cost (e.g. icann_fee, referenced in formulas as cost.icann_fee).
organization_idrequires_continuous_coverageWhen true a subscription referencing this cost must keep it continuously covered (no coverage gaps).
scopeCost scope: PRODUCT (per-product, requires product_id) or ORG (org-wide, feeds price formulas across the whole org).
statusCost lifecycle status (e.g. active or archived).
updated_atStatic money value of the cost; set for amount-form costs, null when the cost is a formula.
archived_atTimestamp the cost was archived, if it has been.
descriptionOperator-facing description of what this cost represents.
Formula that computes the cost from other costs; set for formula-form costs, null when the cost is a static amount.
Free-form operator key/value metadata.
product_idOwning product for a PRODUCT-scoped cost; null for ORG-scoped costs.
Locale-keyed overrides for the cost's description.
CostExpression
currencyISO 4217 result currency the expression evaluates to; must match every referenced cost's currency.
sourcePrice-formula expression source referencing other costs by key (e.g. "cost.buy_com + cost.icann_fee").
CostSummaryEntry
cost_countNumber of static costs contributing to total_amount.
currencyISO 4217 currency this rollup is denominated in.
total_amount^-?\d+(\.\d+)?$ · requiredSum of the static (amount-form) costs in this currency, MAJOR units; formula-form costs are excluded.
CreateAPIKeyRequest
allowed_ipsexpires_atkey_typenamescopesCreateAPIKeyResponse
allowed_ipscreated_atidkeykey_prefixkey_typenamescopesexpires_atCreateBracketEntry
range_max^-?\d+(\.\d+)?$Exclusive upper bound of the bracket; it matches values where value < range_max. Null means unbounded above.
range_min^-?\d+(\.\d+)?$Inclusive lower bound of the bracket; it matches values where range_min <= value.
value^-?\d+(\.\d+)?$The value returned when a value falls in this bracket.
CreateCostRequest
Static money value; set exactly one of amount or expression.
descriptionOperator-facing description of what this cost represents.
Formula referencing other costs by key; set exactly one of amount or expression.
keyFormula-reference key for the new cost; 1-64 chars matching [a-zA-Z0-9._-].
Free-form operator key/value metadata.
product_idOwning product for a PRODUCT-scoped cost, stamped from the URL path; null creates an ORG-scoped cost.
Locale-keyed overrides for the cost's description.
CreateCreditNoteLineRequest
descriptionLine description shown on the document (required).
invoice_line_idSource invoice line this credits; omit for an ad-hoc credit line.
line_typeFree-form line classification, typically carried over from the credited source line.
Arbitrary caller-supplied key/value pairs.
period_endEnd of the service period this credited line covers.
period_startStart of the service period this credited line covers.
product_idCatalog product associated with the credited line; omit for manual lines.
quantity^-?\d+(\.\d+)?$Credited quantity; must be positive.
tax_rate^-?\d+(\.\d+)?$Tax rate applied to this line, as a fraction (0.19 = 19%).
tax_typeTax type label (e.g. VAT, GST); null when the line is untaxed.
unit_price^-?\d+(\.\d+)?$MAJOR units, in the credit note's currency (the request's currency field).
CreateCreditNoteRequest
currencyISO 4217 currency for the note and all its lines (required).
customer_idCustomer to issue the credit note to (required).
fx_snapshot_idFX snapshot to pin the note to (the original invoice's rate); populated by refund builders, rarely set by API callers.
invoice_idInvoice this note reverses or credits; omit for a standalone customer credit.
Credit-note line items; at least one is required.
Arbitrary caller-supplied key/value pairs.
reasonFree-text reason shown on the document.
reason_codeStructured reason: VOID, REFUND, PROMOTIONAL_CREDIT, CANCELLATION, WITHDRAWAL, DOWNGRADE, ITEM_REMOVAL, OVERPAYMENT, BILLING_ERROR, GOODWILL, or OTHER.
template_idTemplate to render the note's document with; omit to inherit the org default.
CreateCustomFieldDefinitionRequest
auditabledefault_valuedescriptiondisplay_nameentity_typesfield_groupfield_typekeyshow_in_tablesort_ordervisibilitywrite_accessCreateCustomerRequest
auto_validate_vatPer-request hint: null = auto-validate VAT after creation when eligible, false = skip the auto-trigger. Still gated by the workspace and per-customer VAT disable flags.
Postal billing address; when provided, line1, city, postal_code and country are required and it is used for tax determination.
Values for the organization's configured custom-field definitions.
customer_typeBuyer classification: BUSINESS, CONSUMER, or UNKNOWN; defaults to UNKNOWN when omitted.
Default auto-topup amount as {value, currency}, MAJOR units. Currency should match preferred_currency.
default_auto_topup_enabledWhether the auto-provisioned wallet enables automatic top-up.
Default wallet credit limit as {value, currency}, MAJOR units. Currency should match the customer's preferred_currency; it is echoed from preferred_currency on read.
Default low-balance threshold as {value, currency}, MAJOR units. Currency should match preferred_currency.
Default wallet max balance as {value, currency}, MAJOR units. Currency should match preferred_currency.
Default wallet max single-credit as {value, currency}, MAJOR units. Currency should match preferred_currency.
disabled_providersPayment provider ids that must not be used to charge this customer; each must be a known provider and unique.
einvoice_emailOverride email address for e-invoice delivery; null = fall back to email.
emailPrimary contact email; the default recipient for invoices and portal links. Required.
external_idCaller-assigned external identifier for cross-referencing in your own systems; must be unique per organization when set.
localeBCP-47-style locale (one of en, de, fr, es, it, pt, nl, ja) for invoice and communication language.
Free-form key/value metadata for caller use; not interpreted by billing.
modeWallet settlement mode for the auto-provisioned wallet: PREPAID or POSTPAID.
nameCustomer's display / legal name as it appears on invoices. Required.
payment_terms_daysNet payment terms in days for invoice due dates (0-365); null = inherit the customer-type default, then the organization setting.
peppol_idPeppol participant identifier in scheme:value form used as the buyer endpoint for e-invoice delivery.
prefer_einvoicePer-customer master switch for structured e-invoicing; null = inherit the workspace setting.
preferred_currencyISO 4217 currency the customer is billed in; seeds the auto-provisioned wallet.
preferred_providerPreferred payment provider id tried first when charging; must be a known provider and must not also appear in disabled_providers.
Tax identifiers keyed by scheme (e.g. "vat"); required for BUSINESS customers in EU countries.
vat_validation_disabledWhen true, automatic VAT-ID validation is skipped for this customer; requires vat_validation_disabled_reason.
vat_validation_disabled_reasonReason recorded when vat_validation_disabled is true; required in that case.
CreateCustomerResponse
The newly created customer.
The wallet auto-provisioned for the customer in its preferred currency.
CreateFXOverrideRequest
rateManual conversion rate (decimal string, 1 source = rate target). Mutually exclusive with snapshot_date.
reasonOptional free-text note explaining the override.
snapshot_datePin the pair to the ECB snapshot of this calendar day. Mutually exclusive with rate.
source_currencyISO 4217 currency being converted from (normalized to uppercase).
target_currencyISO 4217 currency being converted to; must differ from source_currency.
valid_fromInstant the override begins applying; null means now.
valid_toInstant the override stops applying; null means open-ended.
CreateFlowRequest
descriptionOptional longer description of what the flow does.
Dependency edges between steps (the DAG arcs).
failure_policyHow the flow reacts to a step failure; defaults to continue_independent.
nameOperator-facing name of the flow.
priorityScheduling priority; higher-priority flows are advanced first when several are due.
The flow's step nodes (the DAG vertices).
target_bindingWhen bulk-step targets are resolved — snapshot at activation or live at fire time; defaults to snapshot_at_activate.
trigger_localWall-clock local time the flow should fire, paired with trigger_tz; both nil means run immediately on activation.
trigger_tzIANA timezone for trigger_local (e.g. Europe/Berlin); must be set together with it.
CreateInvoiceTemplateRequest
descriptionFree-text description of the template.
document_typesDocument types this template can render (subset of {invoice, credit_note}); defaults to [invoice] when omitted.
nameTemplate name (required).
The template document: ordered blocks plus theme, branding, and footer.
CreateKeySetRequest
descriptionOptional description of the set.
Optional keys to seed the set with in the same call; validated like UpsertEntries.
nameDisplay name for the new key set.
slugURL-safe unique identifier for the new key set, matching ^[a-z0-9][a-z0-9_-]{0,63}$.
CreateLookupEntry
keyExact-match key for this lookup entry.
value^-?\d+(\.\d+)?$The value returned for this key: money in the table's currency or a unitless multiplier.
CreateManualInvoiceRequest
billing_period_endEnd of the service period the invoice covers.
billing_period_startStart of the service period the invoice covers.
buyer_referenceBuyer's routing reference (Leitweg-ID / PO number).
currencyISO 4217 currency; defaults to the customer's preferred currency when omitted.
customer_idCustomer to bill (required).
delivery_dateDate of supply (Leistungsdatum).
due_datePayment due date.
Manual line items applied inline, each validated as an AddInvoiceLineRequest.
localeRendering locale (en, de, fr, es, it, pt, nl, ja); null inherits the org default.
Arbitrary caller-supplied key/value pairs.
CreateMeterRequest
When set, defines this as a derived meter computed from other meters via a formula.
dedup_key_pathJSON-path to the event field used for deduplication; default uses the event's idempotency_key.
dimensionsEvent metadata fields exposed for group-by.
event_schemaJSON-Schema document validating ingested events; null disables validation.
Predicate tree restricting which events the meter includes.
functionAggregation applied over the window: SUM, COUNT, MAX, MIN, AVG, UNIQUE_COUNT, LAST, or P95.
keyOrg-unique slug identifying the meter; lowercase letter then [a-z0-9_-], 1-64 chars.
late_event_policyHow events arriving after period close are handled: DROP, CLAMP_TO_PERIOD, or REBILL_PRIOR.
metric_keyEvent ingestion key this meter aggregates over.
nameHuman-readable label for the meter.
negative_allowedWhether the aggregated value may go negative (e.g. for credits/reversals).
Alert conditions evaluated against the meter's output.
unique_by_fieldEvent field whose distinct values are counted; required for UNIQUE_COUNT.
unit_currency_fieldEvent field carrying the currency when the metric measures money.
unit_labelDisplay label for one metric unit (e.g. "calls").
value_fieldEvent field aggregated; required for SUM/MAX/MIN/AVG/P95/LAST, forbidden for COUNT/UNIQUE_COUNT.
Time window over which to aggregate; null uses the default window.
CreateOrganizationRequest
billing_emaildefault_currencydefault_localenameslugCreatePaymentGatewayConfigRequest
Provider-specific credential document. Stripe: api_key (required), stripe_account_id, webhook_secret, api_base. GoCardless: access_token, webhook_secret. PATCH merges shallowly - send only the keys to change; omitted keys keep their stored value (so a masked read never needs to be resent).
display_namemodeprovidersupported_currenciessupported_methodsCreatePaymentMethodRequest
customer_idCustomer to attach the payment method to. Required.
is_defaultWhen true, make this the customer's default payment method, demoting any prior default.
Free-form key/value metadata for caller use; not interpreted by billing.
providerPayment provider holding this method, e.g. "stripe" or "gocardless". Required.
provider_idProvider's own identifier for the stored method; omit when not tracked externally.
typeMethod type: CREDIT_CARD, BANK_ACCOUNT, SEPA_DIRECT_DEBIT, SEPA_DIRECT_DEBIT_B2B, ACH_BUSINESS, PAYPAL, or EXTERNAL. Required; the B2B/ACH types require a BUSINESS customer.
CreatePhaseInput
Conditions required to enter this phase from the one below.
allow_regressionWhether a redemption may regress out of this phase to the one below.
effectsEffects applied while a redemption is in this phase.
Conditions required to remain in this phase.
idClient-supplied phase ID; canonical once created. Omit to have the server assign one.
is_terminalWhether this is a terminal phase the redemption cannot advance beyond.
min_dwell_daysMinimum days a redemption must dwell in this phase before any exit (advance or regress) is allowed.
nameOperator-facing phase name.
Max-bound triggers that drop a redemption out of this phase to the one below.
transition_timingWhen a phase transition takes effect relative to the billing cycle.
CreatePhaseRequest
auto_transitionWhether reaching this phase's end automatically starts the next pending phase.
duration_unitUnit of duration_value: day, week, month or billing_cycle; required when end_kind is duration.
duration_valueLength of the phase in duration_unit units; required when end_kind is duration.
end_atAbsolute instant the phase ends; used when end_kind is date.
end_kindEnd policy: manual, duration or date; determines how the phase's end is computed.
phase_kindBilling mode for this phase: setup, trial, standard, paused or dunning.
start_atAbsolute instant this phase should start; null starts it when the prior phase ends.
CreatePlanRequest
Org-defined custom field values for this plan.
descriptionInternal operator-facing description; not shown to buyers.
external_idCaller-supplied external identifier for reconciliation with an upstream system.
Free-form operator key/value metadata.
nameInternal operator-facing plan name.
public_descriptionBuyer-facing description shown in checkout and the customer portal.
Locale-keyed overrides for name, description and public_description.
CreatePriceFormulaRequest
expressionThe expression to evaluate for a tier rate; may reference declared variables, cost.
nameDisplay name for the formula.
Variables the expression references, each with a name, type, and optional default.
CreatePriceRequest
country_codeCountry to scope this price to; omit to match any country.
currencyISO 4217 currency for the list price and tier amounts.
Arbitrary dimension key/values that further scope the price.
customer_idCustomer to scope a CUSTOMER_OVERRIDE to; required for kind=CUSTOMER_OVERRIDE, forbidden otherwise.
display_nameCustomer-facing label for this price / price_key.
effective_fromOptional explicit publish timestamp; defaults to now.
effective_toOptional timestamp at which this price version stops being effective.
is_set_priceMarks this as the set price covering every effective key of the product's key set; requires a keyed product and a null price_key.
kindResolution scope: BASE, PLAN_OVERRIDE, or CUSTOMER_OVERRIDE. Defaults to the most specific scope implied by the ids present.
list_price^-?\d+(\.\d+)?$List price, MAJOR units, in the currency field.
Free-form key/value metadata to attach to the price.
plan_idPlan to scope a PLAN_OVERRIDE to; required (with plan_version) for kind=PLAN_OVERRIDE, forbidden otherwise.
plan_versionThe exact plan version the PLAN_OVERRIDE pins to; required for kind=PLAN_OVERRIDE.
price_keyKeyed variant this price covers on a keyed product; 1-64 chars matching [a-zA-Z0-9._-].
product_idThe product to attach this price to.
The tier ladder in ascending up_to order; at least one tier is required.
valid_fromCustomer-facing start of the price's applicability window; distinct from effective_from.
valid_toCustomer-facing end of the price's applicability window; distinct from effective_to.
CreatePriceTierRequest
flat_amount^-?\d+(\.\d+)?$Flat amount, MAJOR units, in the price's currency.
Per-tier numeric overrides of the formula's declared variable defaults.
formula_idOptional reference to a price_formulas row whose expression computes the tier rate; wins over rate_expression and unit_amount.
rate_expressionOptional ad-hoc arithmetic expression for the tier rate; overrides unit_amount when present.
unit_amount^-?\d+(\.\d+)?$Per-unit amount, MAJOR units, in the price's currency.
up_to^-?\d+(\.\d+)?$Inclusive upper quantity bound; the tier covers (previous tier's up_to, up_to]. Null (last tier only) means infinity.
CreateProductMeterBindingRequest
meter_idMeter to bind to the product.
Additional filter tree AND-ed onto the meter's own filters for this product only.
pricing_var_nameFormula variable name to expose the meter result as (slug); required for BILLABLE_QUANTITY and PRICING_VAR, optional for INFORMATIONAL.
roleHow the pipeline consumes the result: BILLABLE_QUANTITY, PRICING_VAR or INFORMATIONAL.
CreateProductRequest
Org-defined custom field values for this product.
descriptionInternal operator-facing description; not shown to buyers.
external_idCaller-supplied external identifier for reconciliation with an upstream system.
invoiceable_standaloneWhether the product may appear in the manual-invoice picker; absent defaults to true, explicit false marks it subscription-only.
key_set_excluded_keysKeys subtracted from the linked key set's active entries (subtract-only).
key_set_idOpts the product into keyed pricing by linking it to an org-global key set.
Free-form operator key/value metadata.
nameInternal operator-facing product name.
pricing_modelPricing model applied to this product; defaults to VOLUME when omitted.
public_descriptionBuyer-facing description shown in checkout and the customer portal.
quantity_adjustableWhen true the buyer picks the quantity (seats/licenses); defaults to false (flat charge) and is rejected on METERED products.
quantity_sourceWhere the billed quantity comes from: DECLARED (set on the subscription item) or METERED (from the meter evaluator); defaults to DECLARED.
requires_product_idsProducts that must also be present for this product to be sold (dependency set).
tax_categoryProduct tax category: DEFAULT, REDUCED, ZERO or EXEMPT; defaults to DEFAULT.
Locale-keyed overrides for name, description and public_description.
unit_labelSingular noun one billed unit is called; defaults to unit.
CreatePromotionRequest
application_timingWhen a redeemed promotion first takes effect: NEXT_CYCLE, RETROACTIVE, or IMMEDIATE.
archetypeFrontend-only preset hint; not persisted as rule logic.
Live targeting set (who sees / auto-enrolls into the promotion); omit for all customers.
budget_behaviorWhat happens when a redemption would exceed max_budget: SKIP or PARTIAL.
budget_currencyISO 4217 currency the budget is denominated in; required when max_budget is set.
codeCoupon code; required when distribution is COUPON and must be omitted otherwise.
descriptionInternal description of the promotion (not shown to customers).
distributionHow a customer comes to hold the promotion: AUTO_APPLY, AUTO_ENROLL, COUPON, or DIRECT. Required.
effectsSingle-phase shorthand: the effects to apply. Mutually exclusive with phases.
Single-phase shorthand: the eligibility condition set. Mutually exclusive with phases.
evaluation_scopeWhere the engine evaluates the promotion: invoice (default), subscription, usage_event, or reserve.
max_budget^-?\d+(\.\d+)?$MAJOR units, denominated in budget_currency (required when max_budget is set).
max_redemptionsCap on total redemptions across all customers; omit for unlimited.
max_redemptions_per_customerCap on redemptions by any single customer; omit for unlimited.
nameOperator-facing promotion name.
Phased-ladder rule shape: ordered phases with per-phase conditions and effects. Mutually exclusive with eligibility/effects.
priorityOrdering priority on the invoice pass; higher applies first and wins within a stacking group.
public_descriptionCustomer-facing description of the promotion.
stacking_groupNamed mutual-exclusion group for stacking_mode=stack; promotions sharing a group never combine with each other.
stacking_modeHow the promotion combines with others on the invoice pass: stack (default) or exclusive (applies alone).
Localized overrides for customer-facing text, keyed by locale.
valid_fromFirst calendar day (UTC) the promotion is valid; required.
valid_toLast calendar day (UTC) the promotion is valid, inclusive; null = open-ended.
CreateRateTableRequest
currencyISO 4217 currency for the entry values; defaults to the org's preferred currency when omitted.
default_valueDecimal value returned on a miss; required when on_missing_key=default_value.
descriptionOptional description of the table's purpose.
nameDisplay name for the table.
on_missing_keyBehaviour when no entry matches: 'error', 'zero', or 'default_value'.
requires_continuous_coverageWhen true, published versions may not leave a gap in the effective-date timeline.
slugURL-safe unique identifier formulas reference this table by.
table_typeMatching mode: 'lookup' (exact key match) or 'bracket' (numeric range match).
CreateScheduledChangeRequest
change_payloadEntity-type-specific change body applied by the release hook at fire time; validated only for non-emptiness at authoring.
change_typeDiscriminator routing the release hook (e.g. UPDATE, version_bump); the payload shape is interpreted per this value only at fire time.
created_byUser who scheduled the change.
depends_on_change_idOptional predecessor change that must be released before this one.
entity_idId of the entity the change targets.
entity_typeKind of entity the change targets (PROMOTION/PLAN/SUBSCRIPTION/PRODUCT).
entity_version_at_scheduleThe entity version observed when scheduling; a mismatch at release is logged as a staleness warning.
immediateRelease now instead of at scheduled_at (skips the future-date check).
Free-form metadata map carried on the change.
notification_configOptional notification configuration carried alongside the change.
release_strategyAUTOMATIC (the ticker releases at scheduled_at) or MANUAL; defaults to AUTOMATIC.
rollback_windowOptional Postgres interval string bounding how long after release the change may be rolled back.
scheduled_atWhen the change should be released; must be in the future unless immediate is set.
CreateSubscriptionItemOverrideRequest
currencyISO 4217 currency the list_price is denominated in.
display_nameOptional override display name shown on invoices.
list_priceList price, MAJOR units, denominated in this request's currency.
valid_fromDate the override starts applying (RFC-3339 date); null starts it immediately.
valid_toDate the override stops applying (RFC-3339 date); null for open-ended.
CreateSubscriptionRequest
auto_renewWhether the subscription renews automatically at period end; false lets it expire when the current period closes.
billing_anchor_dayDay of the month (1-28) each billing period starts on; derived from the activation date when omitted.
billing_interval_countNumber of interval units per billing cycle; defaults to 1.
billing_interval_unitUnit of the billing cycle length: week, month or year; defaults to month.
billing_timingWhen invoices fire relative to the period: in_advance (at period start) or in_arrears (at period end); defaults to in_arrears.
currencyISO 4217 currency the subscription bills in; defaults to the customer/org currency.
Values for the org's configured custom fields.
customer_idCustomer the subscription bills; required.
descriptionInternal operator-facing description; not shown to buyers.
Products, quantities and prices billed by this subscription; defaults from the plan-version snapshot for plan-based subs when omitted.
Arbitrary caller-supplied key/value pairs.
nameInternal operator-facing subscription name.
payment_terms_daysNet payment window in days for this subscription's invoices (0-365); null inherits the org default.
pending_checkout_session_idProvider checkout session to bind an on_checkout_complete DRAFT to; set by the public-checkout finalizer only.
Billing-mode phases; must contain at least one entry (the initial ACTIVE phase), later entries are pre-planned PENDING phases.
plan_idPlan to base the subscription on; mutually exclusive with product_id (plan-or-product XOR).
product_idProduct to bill directly; mutually exclusive with plan_id (plan-or-product XOR).
product_versionProduct version to pin; null follows the product head version.
public_descriptionBuyer-facing description shown in checkout and the customer portal.
Per-subscription billing setting overrides; unset keys inherit from customer, then org, then default.
start_atActivation instant; required when start_trigger is start_date, rejected otherwise.
start_triggerWhat activates the DRAFT subscription: immediate, on_checkout_complete, manual or start_date; defaults to immediate.
Locale-keyed overrides for name, description and public_description.
version_change_strategyMoney policy for auto-upgrades: immediate_prorate, next_period or at_phase_change; required when version_track_mode is latest.
version_track_modeHow the subscription follows plan/product versions: pinned or latest; defaults to pinned (no auto upgrades).
CreateTagRequest
colorOptional display color as a #RRGGBB hex string.
descriptionOptional free-text description of the tag's purpose.
entity_typeEntity kind the tag applies to: CUSTOMER, SUBSCRIPTION, PRODUCT, PLAN, INVOICE, or CREDIT_NOTE.
nameDisplay name; normalized (NFKC, trimmed, collapsed whitespace) and unique per (organization, entity_type).
CreateTaxRuleRequest
applies_to_customer_typesapplies_to_product_categoriesapplies_to_supply_typesapply_orderinclusiveis_compoundjurisdiction_countryjurisdiction_regionrate^-?\d+(\.\d+)?$Decimal number encoded as a string to preserve precision.
requires_continuous_coveragetax_typevalid_fromvalid_toCreateVerificationRequest
check_typeCategory of check: VAT, IDENTITY, KYC, or SANCTIONS; may be omitted.
customer_idCustomer to create the verification record for. Required.
providerName of the verification provider to record. Required.
verification_typeProvider-specific verification subtype label. Required.
CreateVersionRequest
Bracket entries to create for the version.
clone_from_version_idOptional existing version to seed the new version's entries from.
effective_fromWhen the new version starts being effective on the billing timeline.
effective_toOptional timestamp at which the new version stops being effective.
Raw entry rows (lookup or bracket) for the version.
Lookup entries to create for the version.
noteOptional note describing the version.
CreateWalletRequest
auto_topup_amount^-?\d+(\.\d+)?$MAJOR units, in this request's currency.
auto_topup_enabledWhether the wallet auto-tops-up when its balance drops below low_balance_threshold.
credit_limit^-?\d+(\.\d+)?$MAJOR units, in this request's currency.
currencyISO 4217 currency the wallet is denominated in.
customer_idCustomer the new wallet belongs to.
low_balance_threshold^-?\d+(\.\d+)?$MAJOR units, in this request's currency.
max_balance^-?\d+(\.\d+)?$MAJOR units, in this request's currency.
max_single_credit^-?\d+(\.\d+)?$MAJOR units, in this request's currency.
CreateWebhookEndpointRequest
descriptionevent_typessecret_idurlCreateWebhookSecretRequest
descriptionentity_identity_typesigning_methodCreateWorkspaceCurrencyRequest
billing_enabledEnable billing/invoicing in this currency; at least one of billing_enabled or catalog_enabled must be true.
catalog_enabledEnable price/cost authoring in this currency; at least one of billing_enabled or catalog_enabled must be true.
currency_codeISO 4217 currency code to enable (normalized to uppercase).
CreditApplicationsEnvelopeBody
Credit-note applications that have reduced this invoice's amount due.
Pagination block; this collection is returned unpaginated with a total count.
Invoice-level credit rollup so the UI can render totals without recomputing.
CreditGrant
quantity^-?\d+(\.\d+)?$ · requiredAmount of usage credit granted, in metered units.
sourceOrigin of the credit: the granting promotion's name, or a top-up.
expires_atInstant the credit expires; null for non-expiring credit.
CreditNote
created_atcurrencycustomer_ididorganization_idreasonreason_codestatusupdated_atcredit_note_numberdeleted_atinvoice_idissued_atvoided_atCreditNoteApplication
amount^-?\d+(\.\d+)?$ · requiredMAJOR units, in the credit note's currency.
applied_atTimestamp the credit was applied.
created_atcredit_note_idThe credit note that was applied.
idinvoice_idThe invoice the credit was applied against (or refunded from).
organization_idCreditNoteApplicationForInvoice
applied_atcreated_atcredit_note_idcredit_note_statusidreason_codecredit_note_numberCreditNoteAppliedPayload
The amount applied, as a money object.
applied_atWhen the credit note was applied (RFC3339).
credit_note_idThe credit note that was applied.
customer_idThe customer the credit note belongs to.
invoice_idThe invoice the credit note was applied to.
organization_idworkspace_idThe workspace that owns the credit note.
CreditNoteCreatedPayload
created_atcredit_note_idThe credit note that was created.
customer_emailThe customer's email at creation time, when known.
customer_idThe customer the credit note is issued to.
invoice_idThe invoice the credit note references.
numberThe human-readable credit note number, when already assigned.
organization_idreasonThe reason the credit note was created.
statusThe credit note status at creation.
The credit note total, as a money object.
workspace_idThe workspace that owns the credit note.
CreditNoteIssuedPayload
credit_note_idThe credit note that was issued.
credit_note_numberThe human-readable credit note number.
customer_emailThe customer's email at issue time, when known.
customer_idThe customer the credit note is issued to.
invoice_idThe invoice the credit note references.
issued_atWhen the credit note was issued (RFC3339).
organization_idreason_codeThe coded reason the credit note was issued.
The credit note total, as a money object.
workspace_idThe workspace that owns the credit note.
CreditNoteLine
created_atcredit_note_iddescriptionidline_typeorganization_idquantity^-?\d+(\.\d+)?$ · requiredDecimal number encoded as a string to preserve precision.
tax_rate^-?\d+(\.\d+)?$ · requiredDecimal number encoded as a string to preserve precision.
invoice_line_idperiod_endperiod_startproduct_idtax_category_codetax_exemption_reasontax_typeCreditNotePDFRegenerationQueued
credit_note_idThe credit note whose PDF regeneration was queued.
messageHuman-readable acknowledgement that the regeneration job was enqueued.
CreditNoteReasonCode
CreditNoteVoidedPayload
credit_note_idThe credit note that was voided.
customer_idThe customer the credit note belongs to.
invoice_idThe invoice the credit note references.
organization_idreasonThe reason the credit note was voided.
voided_atWhen the credit note was voided (RFC3339).
workspace_idThe workspace that owns the credit note.
CreditRequest
amount^-?\d+(\.\d+)?$MAJOR units, in the addressed wallet's currency.
currencyOptional echo-guard: must equal the wallet's currency when set.
expires_atFor PROMOTION credits, when the granted promotional balance expires; null = never.
reasonOptional free-text explanation stored on the ledger entry.
referenceOptional external reference; a repeated (source, reference) is treated as an idempotent replay.
sourceWhat originates the credit: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER.
CurrencyReferences
costsCost entries authored in this currency.
credit_notesCredit notes issued in this currency.
customersCustomers whose preferred currency is this code.
invoicesInvoices issued in this currency.
pricesCatalog prices authored in this currency.
subscriptionsSubscriptions priced in this currency.
totalSum of all reference counts; when greater than zero the currency cannot be removed.
walletsWallets denominated in this currency.
CustomFieldDefinition
auditablecreated_atdisplay_nameentity_typesfield_typeidkeyorganization_idshow_in_tablesort_orderstatusupdated_atversionvisibilitywrite_accessdefault_valuedeleted_atdeprecated_atdescriptionfield_groupCustomer
created_atcustomer_typeBuyer classification driving tax treatment and invoicing: BUSINESS, CONSUMER, or UNKNOWN.
emailPrimary contact email; the default recipient for invoices and portal links.
idlocaleBCP-47-style locale (one of en, de, fr, es, it, pt, nl, ja) driving invoice and communication language.
modeWallet settlement mode: PREPAID (spend limited to funded balance) or POSTPAID (spend allowed against credit).
nameCustomer's display / legal name as it appears on invoices.
organization_idpreferred_currencyISO 4217 currency the customer is billed in; seeds the auto-provisioned wallet and is echoed as the currency of the wallet-default amounts on read.
statusLifecycle status: active, suspended (billing paused), or churned; only active customers can be billed.
updated_atvat_validation_disabledWhen true, automatic VAT-ID validation is skipped for this customer.
vat_validation_statusOutcome of the last VAT-ID validation: UNVALIDATED, PENDING, VALID, INVALID, ERROR, MANUAL (operator override), or MAINTENANCE (VIES unavailable).
Postal billing address used for tax determination and invoice rendering; null when no address is on file.
Values for the organization's configured custom-field definitions.
Default auto-topup amount as {value, currency}, MAJOR units. Currency echoes preferred_currency on read.
default_auto_topup_enabledWhether new wallets seeded from this customer enable automatic top-up; null = leave the wallet default.
Default wallet credit limit as {value, currency}, MAJOR units. Currency echoes preferred_currency on read.
Default low-balance threshold as {value, currency}, MAJOR units. Currency echoes preferred_currency on read.
Default wallet max balance as {value, currency}, MAJOR units. Currency echoes preferred_currency on read.
Default wallet max single-credit as {value, currency}, MAJOR units. Currency echoes preferred_currency on read.
deleted_atSoft-delete timestamp (RFC3339); null for live customers, set once the customer has been soft-deleted.
disabled_providersPayment provider ids that must not be used to charge this customer.
einvoice_emailOverride email address for e-invoice delivery; null = fall back to email.
external_idCaller-assigned external identifier for cross-referencing the customer in your own systems; unique per organization when set, null when unused.
Free-form key/value metadata for caller use; not interpreted by billing.
payment_terms_daysNet payment terms in days used to compute invoice due dates; null = inherit the customer-type default, then the organization's payment_terms_days setting (default 30).
peppol_idPeppol participant identifier in scheme:value form used as the buyer endpoint for e-invoice delivery; null when the customer is not on Peppol.
prefer_einvoicePer-customer master switch for structured e-invoicing; null = inherit the workspace e-invoicing setting, false = never auto-generate e-invoices.
preferred_providerPreferred payment provider id (e.g. "stripe", "gocardless") tried first when charging this customer; null = organization default routing.
Organization-defined tags attached to the customer for segmentation and filtering.
Tax identifiers keyed by scheme (e.g. "vat"); the VAT entry is the buyer VAT ID used for reverse-charge and e-invoicing.
vat_validation_disabled_reasonOperator-supplied reason recorded when vat_validation_disabled is true; null otherwise.
CustomerAuditEvent
event_typeidoccurred_atdomainentityentity_identity_typepayloadverbCustomerCreatedPayload
created_atcustomer_idThe customer that was created.
emailThe customer's email address.
external_idThe caller-supplied external id, when provided.
organization_idpreferred_currencyThe customer's preferred billing currency, ISO-4217.
wallet_idThe default wallet provisioned for the customer.
workspace_idThe workspace that owns the customer.
CustomerGroup
entity_typeEntity type this group previews (e.g. invoice, subscription).
has_moreTrue when the customer has more records of this type than the preview shows.
Recency-ordered preview of the customer's records of this type.
CustomerModeChangedPayload
actor_idThe actor who performed the mode change, when known.
changed_atWhen the wallet mode changed (RFC3339).
customer_idThe customer whose wallet mode changed.
fromThe wallet mode before the change (e.g. PREPAID, POSTPAID).
organization_idreasonWhy the wallet mode was changed.
toThe wallet mode after the change (e.g. PREPAID, POSTPAID).
Per-wallet balance snapshots captured at the moment of the change.
workspace_idThe workspace that owns the customer.
CustomerOverview
One preview group per customer-owned entity type that has records.
The customer's own profile hit; null when the profile was not requested or not found.
CustomerTypeChangedPayload
actor_idThe actor who performed the type change, when known.
changed_atWhen the customer type changed (RFC3339).
customer_idThe customer whose type changed.
fromThe customer type before the change (e.g. INDIVIDUAL, BUSINESS).
organization_idreasonWhy the customer type was changed.
toThe customer type after the change (e.g. INDIVIDUAL, BUSINESS).
workspace_idThe workspace that owns the customer.
CustomerVerification
check_typeCategory of check performed: VAT, IDENTITY, KYC, or SANCTIONS.
created_atcustomer_idCustomer this verification record belongs to.
idorganization_idproviderSource that produced the result, e.g. an external provider name or one of the internal markers MANUAL_OVERRIDE, MAINTENANCE_DEFERRED, DOMESTIC_SKIP.
statusCurrent verification status: pending, verified, expired, failed, manual, or maintenance.
updated_atverification_typeProvider-specific verification subtype label carried through to the provider call and expiry handling.
actor_idUser who set the current status via a manual override; null for automated results.
expires_atWhen the verified result expires and must be re-checked; null when it does not expire.
last_checked_atWhen the check was last run against the provider; null if never run.
provider_referenceProvider's own reference identifier for this check; null when the provider returned none.
reasonHuman-readable explanation for the current status, e.g. a manual-override or failure reason.
result_payloadRaw provider response payload retained for audit; null when none was stored.
verified_atWhen the verification last succeeded; null while not yet verified.
DataEnvelopeAnalyticsMRRData
Outcome-dependent: with segment=customer_type the MRRByTypeResponse (B2B/B2C-segmented series), otherwise the plain MRRResponse.
DataEnvelopeAnalyticsRevenueData
Outcome-dependent: with segment=customer_type the RevenueByCustomerTypeResponse, otherwise the plain RevenueResponse breakdown.
DataEnvelopeFinalizeInvoiceData
Outcome-dependent: on 200 the finalized InvoiceDTO; on 202 the ApprovalRequest that intercepted finalization (poll GET /approvals/{id}).
DataEnvelopeIngestUsageEventData
Outcome-dependent: on 201 the created UsageEvent (single-event body) or the BatchIngestResult (batch body); on 202 the UsageEventQueuedResponse when the event settles a reservation and is processed asynchronously (the hold's state is observable at GET /wallets/{id}/holds).
DataEnvelopeRateTableUpdateData
Outcome-dependent: with effective_at the PATCH publishes the latest draft and returns the RateTableVersion; a plain display-field update returns the RateTable root row.
DataEnvelopeRefundInvoiceData
Outcome-dependent: on 200 the VoidInvoiceResponseDTO (voided invoice + credit note); on 202 the RefundInvoiceResponse with status=refund_pending while the gateway refund settles (observe completion via GET /invoices/{id}/payments).
DebitRequest
amount^-?\d+(\.\d+)?$MAJOR units, in the addressed wallet's currency.
currencyOptional echo-guard: must equal the wallet's currency when set.
reasonOptional free-text explanation stored on the ledger entry.
referenceOptional external reference; a repeated (source, reference) is treated as an idempotent replay.
sourceWhat originates the debit: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER.
DependentPlan
plan_idplan_nameplan_statusstaletrack_modecurrent_versionpinned_versionDerivationFX
The amount in the price's own currency before conversion.
original_currencyISO 4217 currency the price was denominated in before conversion.
exchange_rateThe exchange rate applied, as a decimal string.
DerivationTier
Flat amount for this tier.
Per-unit amount for this tier.
formulaThe inline rate expression when the tier rate is computed (e.g. "cost.icann_fee * 1.15"); empty for static tiers.
has_formula_refTrue when the tier is bound to a structured price_formulas row rather than an inline expression.
up_to^-?\d+(\.\d+)?$Inclusive upper quantity bound of the tier; null is the open-ended final tier (infinity).
DerivationTierStep
Amount contributed by this segment (quantity times unit_price).
quantity^-?\d+(\.\d+)?$ · requiredQuantity billed within this segment.
tier_indexIndex of the contributing tier in the price's tier ladder.
Per-unit rate applied within this segment.
lower_bound^-?\d+(\.\d+)?$Exclusive lower quantity bound of the segment this step covers (nil for the first tier, which starts at 0).
upper_bound^-?\d+(\.\d+)?$Inclusive upper quantity bound of the segment (nil for the open-ended final tier).
DisputeChangedPayload
dispute_idThe dispute that was upserted and needs re-indexing.
organization_idDocumentFailedPayload
delivery_attemptsThe number of delivery attempts before quarantine.
error_messageThe failure detail that sent the request to the DLQ.
idempotency_keyThe de-duplication key of the failed request, when known.
kindThe document kind that failed to render, when known.
organization_idThe organization that owns the source record, when known.
profileThe rendering profile requested, when known.
quarantine_idThe document-quarantine record id for operator inspection.
quarantined_atWhen the request was quarantined (RFC3339).
source_idThe id of the source record, when known.
source_kindThe kind of source record, when known.
workspace_idThe workspace that owns the source record, when known.
DocumentGeneratedPayload
archive_record_idThe archival record id for the written artifact.
byte_sizeThe artifact size in bytes.
chain_hashThe archival hash-chain value at this artifact.
chain_seqThe artifact's position in the tamper-evident archival hash chain.
content_hashHex-encoded sha256 over the artifact bytes.
content_typeThe artifact MIME type.
generated_atWhen the artifact was generated (RFC3339).
jurisdictionThe jurisdiction the document was rendered for.
kindThe document kind that was rendered.
organization_idprofileThe rendering profile used, when profile-specific.
source_idThe id of the source record.
source_kindThe kind of source record the document was rendered from.
storage_bucketThe object-storage bucket the artifact was written to.
storage_keyThe object-storage key of the artifact.
workspace_idThe workspace that owns the source record.
DocumentRequestedPayload
idempotency_keyThe consumer-side de-duplication key for this render request.
jurisdictionThe jurisdiction the document is rendered for, when applicable.
kindThe document kind to render.
organization_idprofileThe rendering profile, when profile-specific.
requested_atWhen the document was requested (RFC3339).
source_idThe id of the source record.
source_kindThe kind of source record the document is rendered from (e.g. INVOICE, CREDIT_NOTE).
workspace_idThe workspace that owns the source record.
DriftCandidateVersion
lifecycleversioneffective_fromeffective_toDunningPolicy
created_atidis_activenameorganization_idupdated_atdeleted_atplan_idDunningStepPayload
actionThe action the step performed (e.g. EMAIL, SUSPEND).
customer_idThe customer billed on the invoice.
days_after_dueHow many days after the due date this step fired.
email_eventThe email sub-event name, for email steps only.
invoice_idThe overdue invoice the dunning step acted on.
organization_idstep_indexThe 0-based index of this step in the dunning schedule.
timestampWhen the step fired (RFC3339).
workspace_idThe workspace that owns the invoice.
EInvoiceDocument
byte_sizeSize of the stored artifact in bytes.
content_hashHex-encoded content hash of the artifact bytes.
content_typeMIME type of the stored artifact (e.g. application/xml, application/pdf).
created_atidjurisdictionJurisdiction the artifact was rendered for (e.g. DE).
profileProfile the artifact was rendered as (e.g. XRECHNUNG_CII).
signedTrue when the artifact carries a cryptographic signature.
syntaxSerialization syntax of the artifact (e.g. UBL, CII).
credit_note_idThe credit note this document was generated for; zero/omitted when it is anchored to an invoice.
invoice_idThe invoice this document was generated for; zero/omitted when it is anchored to a credit note.
quarantine_reasonReason the artifact was quarantined; empty when it passed validation.
EInvoiceDocumentCounts
Map of invoice id to the number of e-invoice documents that exist for it.
EInvoiceFinding
found_atWhen the finding was first recorded.
idmessageHuman-readable description of the finding.
rule_idIdentifier of the validation rule that produced the finding (e.g. an EN 16931 business rule code).
rule_setThe rule set the rule belongs to (e.g. EN16931, XRECHNUNG, PEPPOL).
severityFinding severity, e.g. error, warning, or info.
resolution_notesOperator-supplied notes captured when the finding was resolved.
resolved_atWhen an operator marked the finding resolved; null while still open.
xpathXPath into the e-invoice XML where the finding applies; empty when not element-specific.
EInvoicingDocumentGeneratedPayload
byte_sizeThe document size in bytes.
content_hashHex-encoded sha256 over the document bytes.
credit_note_idThe source credit note, when the document is a credit note.
document_idThe e-invoicing document that was generated.
generated_atWhen the document was generated (RFC3339).
invoice_idThe source invoice, when the document is an invoice.
jurisdictionThe jurisdiction the document was generated for.
organization_idprofileThe e-invoicing profile the document conforms to (e.g. XRECHNUNG, PEPPOL_BIS).
storage_bucketThe object-storage bucket the document was written to.
storage_keyThe object-storage key of the document.
syntaxThe document syntax (e.g. UBL, CII).
workspace_idThe workspace that owns the document.
EInvoicingDocumentQuarantinedPayload
credit_note_idThe source credit note, when the document is a credit note.
document_idThe e-invoicing document that was quarantined.
error_rule_idsThe validation rule ids the document failed.
invoice_idThe source invoice, when the document is an invoice.
organization_idprofileThe e-invoicing profile the document was validated against.
quarantine_reasonWhy the document was quarantined.
quarantined_atWhen the document was quarantined (RFC3339).
workspace_idThe workspace that owns the document.
EUVATRate
country_codecountry_nameeffective_fromparking_ratereduced_ratereduced_rate_2standard_ratesuper_reducedeffective_toEdgeSpec
conditionEdge satisfaction condition; defaults to on_success.
from_keyKey of the upstream step this edge depends on.
to_keyKey of the downstream step that waits on from_key.
Effect
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · kind="percentage_discount" | |
| type = object · kind="fixed_discount" | |
| type = object · kind="price_override" | |
| type = object · kind="free_product" | |
| type = object · kind="free_periods" | |
| type = object · kind="wallet_credit" | |
| type = object · kind="usage_credits" |
kindUnion discriminator.
apply_per_linePer-line application flag; a percentage rate applies to each line's own subtotal regardless, so this has no effect at invoice time for percentage discounts.
cap_per_invoice^-?\d+(\.\d+)?$Whole-invoice cap on the total discount summed across all matched lines (MAJOR units, in currency).
cap_per_period^-?\d+(\.\d+)?$Not yet enforced; a positive value is rejected at validation — use cap_per_invoice instead.
currencyISO 4217 currency pinning the money caps (max_discount / cap_per_invoice); empty for an uncapped rate, required once any cap is set. A capped discount no-ops on an invoice of a different currency.
max_discount^-?\d+(\.\d+)?$Per-line cap on the discount amount (MAJOR units, in currency); the computed discount for each line is clamped to this.
rate^-?\d+(\.\d+)?$Percentage rate as a plain number (0-100); "10" means 10% off — the engine divides by 100 and applies it to each matching line's subtotal.
Which invoice lines the discount applies to; empty = every line.
EffectMeta
applies_atWhen the effect is applied: REDEEM_TIME or INVOICE_TIME.
summaryOne-line human-readable description of the effects.
typeThe effect kind (e.g. percentage_discount, free_product).
EffectScope
charge_kindsRestricts the effect to lines of these charge kinds (RECURRING, USAGE, SETUP); empty = all charge kinds.
excluded_product_idsDeny-list of product IDs the effect never applies to; a line for an excluded product is skipped even if it matches target_product_ids.
Narrows the scope to keyed variants: a line matches when its price_key is in keys, or carries one of tags in the product's key registry (authoring requires target_product_ids alongside a key filter).
target_product_idsAllow-list of product IDs the effect applies to; when non-empty, only lines for these products match (empty = all products).
EffectiveSetting
categorykeylabelsourcetypevalueEligiblePromotion
Per-condition evaluation detail behind the eligibility decision.
The promotion the customer is eligible for.
EnrichedPlanProduct
Head-state cost summaries for the attached product (reflects the product's current costs, not a publish snapshot).
created_atidHead-state meter-binding summaries for the attached product (reflects the product's current bindings, not a publish snapshot).
organization_idplan_idPlan this membership belongs to.
Head-state price summaries for the attached product.
pricing_modelPricing model of the attached product: VOLUME, STAIRCASE or PACKAGE.
product_idProduct attached to the plan by this membership.
product_nameName of the attached product.
product_track_modeWhether this membership auto-follows the product head (latest) or holds its snapshotted version (pinned).
quantity_adjustableWhen true the buyer picks the product's quantity (seats/licenses); false is a flat charge.
quantity_sourceWhere the product's billed quantity comes from: DECLARED (set on the subscription item) or METERED (from the meter evaluator).
unit_labelSingular noun one billed unit of the product is called (e.g. seat, GB).
credit_unit_value^-?\d+(\.\d+)?$Money value of one POOL unit, MAJOR units in currency; POOL only.
currencyISO 4217 currency for a POOL's money-denominated knobs (credit_unit_value, spend_limit).
included_quantity^-?\d+(\.\d+)?$Quantity bundled into the base price before per-unit billing applies (the included allowance/seat floor); null means none.
kindEntitlement kind: REFRESHING (per-period allowance, the empty-string default) or POOL (durable credit that never resets).
Free-form operator key/value metadata for this membership.
product_head_version_idProduct's current live head version; when it differs from product_version_id the plan's pin trails the product's live head.
product_version_idProduct version pinned for this product by the plan's current head version; null for an unpinned (legacy or in-progress-draft) row.
refresh_countPlan-level default allowance-refresh cadence count; null (with refresh_unit) means one whole-period pool.
refresh_unitUnit for the refresh cadence: day, week, month, year or billing_cycle.
rollover_enabledWhen true, unused included allowance carries forward into later periods.
rollover_expiry_periodsNumber of periods after which rolled-over allowance expires; null means it never expires.
rollover_max^-?\d+(\.\d+)?$Cap on accumulated rolled-over allowance; null means uncapped.
spend_limit^-?\d+(\.\d+)?$Ceiling on a POOL's money spend, MAJOR units in currency; POOL only.
unit_limit^-?\d+(\.\d+)?$Ceiling on a POOL's unit balance; POOL only.
EntryInput
display_nameCustomer-facing label for the key; defaults to the key itself when empty.
keyThe key identifier (matching ^[a-zA-Z0-9._-]{1,64}$); the conflict target for the upsert.
Free-form key/value metadata for the key.
statusEntry status: active or retired; defaults to active.
tagsFree-form tags for the key.
ExportAuditRecord
created_atidinvoice_countNumber of invoices included in the export.
kindArtifact kind produced: bookings, master_data, or invoices_pdf.
line_countNumber of booking lines produced.
organization_idproviderProvider id the export ran against.
summary_jsonPersisted structured export summary; hydrates the Recent Exports detail view.
user_idUser who ran the export.
file_sha256SHA-256 of the generated file, for tamper-evidence and dedup.
period_fromStart of the exported invoice-issue-date range; null when unbounded.
period_toEnd of the exported invoice-issue-date range; null when unbounded.
ExportDescriptor
extensionFile extension of the produced file (without the dot).
kindArtifact kind this descriptor produces: bookings, master_data, or invoices_pdf.
labelHuman-readable name of the export shown on its card.
mime_typeMIME type of the produced file.
User-tunable options for this export (e.g. grouping, posting_mode).
descriptionLonger explanation of what the export contains.
ExternalVerificationCondition
kindUnion discriminator.
verification_typeIdentifier of the external verification pool (e.g. a student/nonprofit check) the customer must have passed.
FXOverride
created_atidorganization_idsource_currencyISO 4217 currency being converted from.
target_currencyISO 4217 currency being converted to.
updated_atvalid_fromInstant the override begins taking precedence over the policy-selected ECB rate.
workspace_idWorkspace this override applies within.
deleted_atWhen the override was soft-deleted; null unless deleted.
rateManual conversion rate as a decimal string (1 source = rate target); set only in manual-rate mode.
reasonOptional free-text note explaining why the override exists.
snapshot_dateCalendar day whose ECB snapshot the pair resolves against; set only in snapshot-pin mode, zero in manual-rate mode.
valid_toInstant the override stops applying; null means open-ended.
FXSnapshot
created_atidratePublished conversion rate as a decimal string (1 source = rate target).
snapshot_dateCalendar day this rate snapshot represents (plain date, no clock or zone).
sourceRate provider that published this snapshot (e.g. ECB).
source_currencyISO 4217 currency being converted from.
target_currencyISO 4217 currency being converted to.
FeedAttention
manual_duestuck_releasingwith_warningsFeedEvent
bucketchange_typeeffective_atentity_identity_nameentity_typeevent_idrelease_strategysourcestatuswarningsbatch_idbatch_labelcreated_atcreated_bydepends_on_idversionFixedDiscountEffect
kindUnion discriminator.
amount^-?\d+(\.\d+)?$The fixed discount amount (MAJOR units, in currency).
apply_per_lineWhen true, the full amount is deducted from EACH matching line; when false, a single amount budget is spread across matching lines until exhausted.
cap_per_invoice^-?\d+(\.\d+)?$Whole-invoice cap on the total discount summed across all matched lines (MAJOR units, in currency).
cap_per_period^-?\d+(\.\d+)?$Not yet enforced; a positive value is rejected at validation — use cap_per_invoice instead.
currencyISO 4217 currency of the amount; required — a fixed discount no-ops on an invoice of a different currency.
Which invoice lines the discount applies to; empty = every line.
Flow
created_atfailure_policyidlock_versionnameorganization_idprioritystatustarget_bindingupdated_atworkspace_idactivated_atactivated_bycreated_bydescriptionfinished_attrigger_attrigger_localtrigger_tzFooter
show_page_numbersWhen true, renders page numbers in the footer.
textFooter text rendered at the bottom of the document.
FormulaVariable
defaultDefault value applied when the caller supplies no binding; a currency-neutral numeric factor, never a money amount.
nameThe variable name referenced in the formula expression.
typeThe variable's value type: number, string, or boolean.
FreePeriodsEffect
kindUnion discriminator.
periodsNumber of billing periods to make free; consumed against the redemption's free_periods_remaining and may be drawn down fractionally for pro-rated invoices.
Which invoice lines the free periods apply to; empty defaults to recurring charges.
FreeProductEffect
kindUnion discriminator.
product_idProduct whose matching invoice lines are made free (zeroed).
quantity^-?\d+(\.\d+)?$Optional number of units to grant free; unset means the entire matching line is made free.
Further narrows which of the product's lines qualify; empty = every line for the product.
GDPRErasureResult
audit_rows_redactedNumber of audit-log rows whose personal data was redacted.
customer_idUUID of the customer whose data was erased.
customers_rows_tombstonedNumber of customer rows tombstoned (personal fields replaced with a placeholder).
payment_customers_rows_redactedNumber of payment-provider customer rows whose sensitive fields were redacted.
payment_methods_rows_redactedNumber of payment-method rows whose sensitive fields were redacted.
GDPRExportDocument
credit_notesAll non-deleted credit-note rows held about the customer.
customerThe customer record(s); an empty array means the customer was not found.
customer_idUUID of the data subject the export was generated for.
formatExport format identifier, currently "kontorion.gdpr-export.v1".
generated_atWhen the export was generated (RFC3339 UTC).
invoicesAll non-deleted invoice rows held about the customer.
payment_methodsAll payment-method rows for the customer, with the provider_token field stripped.
paymentsAll payment rows held about the customer.
subscriptionsAll subscription rows held about the customer.
verificationsAll customer-verification rows held about the customer.
wallet_transactionsAll wallet-transaction rows across the customer's wallets.
walletsAll wallet rows held about the customer.
GenerateEInvoiceRequest
credit_note_idCredit note to generate the e-invoice for; set exactly one of invoice_id or credit_note_id.
invoice_idInvoice to generate the e-invoice for; set exactly one of invoice_id or credit_note_id.
jurisdictionOptional jurisdiction hint (e.g. DE) that selects jurisdiction-specific rules.
profileTarget e-invoice profile (e.g. EN16931_UBL, XRECHNUNG_CII, PEPPOL_BIS); required.
GenerateEInvoiceResponse
byte_sizeSize of the generated artifact in bytes.
content_hashHex-encoded content hash of the generated artifact bytes.
created_atWhen the artifact was generated.
document_idThe persisted e-invoice document row created by this generation.
profileProfile the artifact was rendered as.
quarantinedTrue when validation findings held the artifact back from being marked deliverable.
storage_bucketObject-storage bucket the artifact was written to.
storage_keyObject-storage key of the artifact within the bucket.
syntaxSerialization syntax of the artifact (e.g. UBL, CII).
Validation findings raised while rendering; present even on success as warnings.
GenerateInvoiceRequest
billing_period_endEnd of the period to bill; defaults to the subscription's current open period when omitted.
billing_period_startStart of the period to bill; defaults to the subscription's current open period when omitted.
localeRendering locale (en, de, fr, es, it, pt, nl, ja); null inherits the org default.
subscription_idSubscription to generate an invoice for (required).
GenerateTokensRequest
countNumber of coupon tokens to generate (1-10000); larger campaigns repeat the call.
emailsOptional customer emails to lock the tokens to, one per token; when provided its length must equal count.
Grant
consumed_quantity^-?\d+(\.\d+)?$ · requiredDecimal number encoded as a string to preserve precision.
created_atentitlement_ididorganization_idquantity^-?\d+(\.\d+)?$ · requiredDecimal number encoded as a string to preserve precision.
sourceworkspace_idcharge_iddedup_keyexpires_atHit
display_namePrimary label shown for the hit in the results list.
entity_typeKind of the matched entity (e.g. customer, invoice, subscription).
idIdentifier of the matched entity.
scoreRelevance score from the search engine; higher ranks first.
customer_idOwning customer's id; empty for catalog entities that have no owning customer.
customer_nameOwning customer's display name; empty for catalog entities.
dataEntity-type-specific payload with the fields needed to render the hit.
secondary_textSupporting line shown under the display name (e.g. an invoice number or email).
Tags attached to the matched entity.
HoldRequest
amount^-?\d+(\.\d+)?$MAJOR units, in the hold's currency (the currency field, else the wallet's).
currencyISO 4217 currency of the hold; when empty the addressed wallet's currency is used.
expires_atWhen the wallet auto-releases the hold if it has not been captured.
metric_keyMetric key of the usage stream this hold reserves capacity for; set by the reserve service, null via the public hold API.
Promotions that reduced this hold's amount up-front; set by the reserve service, never via the public hold API.
reasonFree-text explanation of what the hold reserves for.
reference_idIdentifier of the record this hold reserves against; paired with reference_type.
reference_typeType of the record this hold reserves against; paired with reference_id.
reverse_chargeTrue when the captured amount is subject to VAT reverse-charge.
subscription_idSubscription whose usage stream this hold reserves capacity for; set by the reserve service, null via the public hold API.
tax_rate^-?\d+(\.\d+)?$Tax rate to apply at capture, as a decimal fraction (0.19 = 19%).
tax_rule_idTax rule to apply when this hold is captured; null for an untaxed hold.
IDPSummary
aliasenabledprovider_iddisplay_namehide_on_loginIneligiblePromotion
Per-condition evaluation detail showing which conditions failed.
The promotion the customer is not eligible for.
IngestEventRequest
customer_idCustomer that consumed the metric.
Named dimension values used to select the price tier.
external_cost_amount^-?\d+(\.\d+)?$Caller-supplied wholesale cost (COGS) fed to cost-plus formulas, MAJOR units; requires external_cost_currency.
external_cost_currencyISO 4217 currency of external_cost_amount; one currency per (subscription, metric) group.
hold_idReserve hold this event captures against; null for direct (non-reserve) ingest.
idempotency_keyCaller key that dedupes replays of the same event; required.
Arbitrary caller-supplied key/value annotations carried on the event.
metric_keyMetric this event records usage for; must match the product's meter binding.
price_keyPrice key selecting a tier for keyed products; required when the product exposes keyed prices.
Named numeric variables bound into the price formula at finalize time.
product_idMetered product the event is billed under.
quantity^-?\d+(\.\d+)?$Number of metric units to record; must be non-negative.
subscription_idSubscription the usage is charged against.
timestampWhen the usage occurred; omitted or zero stamps the server's ingest time. Set explicitly for backfill/historical imports.
wallet_currencyISO 4217 currency pinning the event to a specific wallet; the wallet must exist for (customer_id, wallet_currency). Null uses the customer's preferred-currency cascade.
IntegrationCatalogEntry
display_nameproviderIntegrationConfig
configProvider-specific configuration; the provider package decodes it into its own typed struct.
created_atdisplay_nameHuman-readable name for this integration.
idis_enabledWhether exports may run against this integration; false blocks them with a hint to enable in Settings.
organization_idproviderRegistered accounting provider id (e.g. datev, lexware, sage).
updated_atInvitation
created_atemailidinvited_byorganization_idrole_namesInvoice
Outstanding balance: total minus amount paid minus any credit applied.
Cumulative amount recorded as paid against this invoice.
created_atcurrencyISO 4217 currency; every money field on this invoice and its lines is denominated in it.
customer_idThe customer this invoice bills.
idinvoice_typeDocument classification: INVOICE, CREDIT_NOTE, or CORRECTIVE.
organization_idstatusLifecycle status: draft, finalized, paid, void, overdue, pending_approval, or error.
Net total of all lines before tax, as a currency-tagged amount.
Total tax across all lines, as a currency-tagged amount.
Gross amount owed (subtotal plus tax), as a currency-tagged amount.
updated_atbilling_period_endEnd of the service period this invoice covers.
billing_period_startStart of the service period this invoice covers.
buyer_referenceBuyer's routing reference (Leitweg-ID / PO number) for B2G and e-invoicing.
deleted_atSoft-delete timestamp; null for live invoices.
delivery_dateDate of supply (Leistungsdatum, §14 UStG): when the goods/services were delivered.
due_dateDate payment is due.
invoice_numberSequential legal invoice number, allocated at finalize; null while the invoice is a draft.
issued_atTimestamp the invoice was finalized/issued; null while it is a draft.
last_dunning_step_atTimestamp the last dunning step ran; null if never dunned.
last_dunning_step_indexZero-based index of the most recent dunning step executed; null if never dunned.
Line items; populated on single-invoice reads, omitted from list responses.
localeLocale used to render this invoice's document (e.g. en, de); null inherits the org default.
Arbitrary caller-supplied key/value pairs.
paid_atTimestamp the invoice was fully paid; null until then.
subscription_idThe subscription this invoice was generated from; null for standalone (manual) invoices.
supplier_tax_numberSupplier domestic tax number, denormalized onto the invoice for rendering.
supplier_vat_idSupplier VAT identification number, denormalized onto the invoice for rendering.
supply_typeTax supply classification: DOMESTIC, INTRA_EU_B2B, etc.
Tags attached to this invoice.
tax_category_codeEN 16931 tax category code (BT-151): S, Z, E, AE, K, G, or O.
tax_exemption_reasonFree-text reason when tax is exempted or reverse-charged (e.g. "Reverse Charge §13b UStG").
tax_point_dateTax point date (Steuerentstehung): when the tax liability arises.
InvoiceCreatedPayload
created_atcurrencyThe invoice currency, ISO-4217.
customer_idThe customer billed on the invoice.
invoice_idThe standalone (manual) invoice that was created.
organization_idsourceHow the invoice originated (e.g. "manual").
The invoice grand total, as a money object.
workspace_idThe workspace that owns the invoice.
InvoiceCreditSummary
The invoice's gross total, as a currency-tagged amount.
Invoice total minus total credited, floored at zero, as a currency-tagged amount.
Sum of all issued credit notes against this invoice, as a currency-tagged amount.
InvoiceFinalizedPayload
The amount still owed after finalization, as a money object.
customer_idThe customer billed on the invoice.
due_dateThe payment due date (RFC3339), when set.
finalized_atWhen the invoice was finalized (RFC3339).
invoice_idThe invoice that was finalized.
invoice_numberThe human-readable invoice number assigned at finalization.
organization_idThe invoice grand total, as a money object.
workspace_idThe workspace that owns the invoice.
InvoiceGeneratedPayload
customer_idThe customer billed on the invoice.
generated_atWhen the invoice was generated (RFC3339).
invoice_idThe invoice that was generated.
organization_idsubscription_idThe subscription that drove generation, when subscription-billed.
The pre-tax subtotal, as a money object.
The total tax, as a money object.
The invoice grand total, as a money object.
workspace_idThe workspace that owns the invoice.
InvoiceLine
created_atcurrencyISO 4217 currency the line's money fields are denominated in.
descriptionHuman-readable line description shown on the document.
idinvoice_idThe invoice this line belongs to.
line_typeLine classification: RECURRING, USAGE, PRORATION_CREDIT, PRORATION_CHARGE, ADD_ON, EXPENSE_PASSTHROUGH, MILESTONE, ADJUSTMENT, or CREDIT.
organization_idquantity^-?\d+(\.\d+)?$ · requiredBilled quantity.
Line net (quantity times unit price) before tax, as a currency-tagged amount.
Tax charged on this line, as a currency-tagged amount.
tax_rate^-?\d+(\.\d+)?$ · requiredTax rate applied to this line, as a fraction (0.19 = 19%).
Price per unit, as a currency-tagged amount.
Per-segment atoms that compose this line's price; the replay-authoritative records.
Structured pricing breakdown (tiers, formulas) when the resolver produced one.
Arbitrary caller-supplied key/value pairs.
period_endEnd of the service period this line covers.
period_startStart of the service period this line covers.
price_keyStable key of the price component that produced this line; null for manual lines.
price_key_display_nameHuman-readable label for the price key.
product_idThe catalog product that priced this line; null for manual/ad-hoc lines.
tax_category_codeEN 16931 tax category code (BT-151): S, Z, E, AE, K, G, or O.
tax_exemption_reasonPer-line exemption reason text (BT-120) when the line is tax-exempt.
tax_typeTax type label (e.g. VAT, GST); null when the line is untaxed.
InvoiceLineAddedPayload
customer_idThe customer billed on the invoice.
descriptionThe line description.
invoice_idThe invoice the line was added to.
line_idThe invoice line that was added.
line_typeThe kind of line added (e.g. SUBSCRIPTION, USAGE, ADJUSTMENT).
The invoice total after the line was added, as a money object.
occurred_atWhen the line was added (RFC3339).
organization_idquantityThe line quantity, as a decimal string.
The line subtotal, as a money object.
The per-unit price, as a money object.
workspace_idThe workspace that owns the invoice.
InvoiceLineAtom
atom_indexZero-based position of this atom within its parent line's ordered segments.
idquantity^-?\d+(\.\d+)?$ · requiredBilled quantity for this atom's segment.
subtotal^-?\d+(\.\d+)?$ · requiredMAJOR units, in the parent invoice line's currency.
tax_amount^-?\d+(\.\d+)?$ · requiredMAJOR units, in the parent invoice line's currency.
tax_rate^-?\d+(\.\d+)?$ · requiredTax rate applied to this atom, as a fraction (0.19 = 19%).
unit_price^-?\d+(\.\d+)?$ · requiredMAJOR units, in the parent invoice line's currency.
exchange_rate_idFX snapshot used to value this atom; null for same-currency lines.
fx_policy_appliedFX conversion policy applied when the atom crossed currencies; null when none.
period_endEnd of the service sub-period this atom covers (whole calendar day, UTC).
period_startStart of the service sub-period this atom covers (whole calendar day, UTC).
price_keyStable key of the price component that produced this atom; null for manual segments.
price_key_display_nameHuman-readable label for the atom's price key.
Per-component tax breakdown (e.g. compound taxes) that composes this atom's tax.
tax_rule_idTax rule resolved for this atom; null when the segment is untaxed.
Per-tier pricing breakdown when the atom was priced by a tiered/volume model.
InvoiceLineAtomTaxComponent
amount^-?\d+(\.\d+)?$ · requiredTax charged by this component, in MAJOR units of the parent invoice line's currency.
atom_idThe atom this tax component contributes to.
base^-?\d+(\.\d+)?$ · requiredTaxable base this component was applied to, in MAJOR units of the parent invoice line's currency.
component_indexZero-based order in which components are applied; compound components see the running total of lower indices.
idis_compoundTrue when this component taxes the base plus preceding components (compound tax) rather than the bare base.
organization_idrate^-?\d+(\.\d+)?$ · requiredThis component's tax rate, as a fraction (0.19 = 19%).
tax_rule_idThe tax rule that produced this component.
tax_typeTax type label for this component (e.g. VAT, GST).
InvoiceLineAtomTier
amount^-?\d+(\.\d+)?$ · requiredCharge for this tier (quantity times unit price), in MAJOR units of the parent invoice line's currency.
atom_idThe atom this tier row breaks down.
idorganization_idquantity^-?\d+(\.\d+)?$ · requiredQuantity that fell into this tier.
tier_indexZero-based position of this tier within the tiered/volume price.
unit_price^-?\d+(\.\d+)?$ · requiredPrice per unit within this tier, in MAJOR units of the parent invoice line's currency.
lower_bound^-?\d+(\.\d+)?$Inclusive lower quantity bound of the tier; null for the first (open-below) tier.
tier_labelOptional human-readable label for this tier (e.g. "First 1000").
upper_bound^-?\d+(\.\d+)?$Exclusive upper quantity bound of the tier; null for the last (open-above) tier.
InvoiceLineDeletedPayload
customer_idThe customer billed on the invoice.
descriptionThe description of the deleted line.
invoice_idThe invoice the line was removed from.
line_idThe invoice line that was deleted.
line_typeThe kind of line (e.g. SUBSCRIPTION, USAGE, ADJUSTMENT).
The invoice total after deletion, as a money object.
occurred_atWhen the line was deleted (RFC3339).
organization_idThe subtotal of the deleted line, as a money object.
workspace_idThe workspace that owns the invoice.
InvoiceLineFieldChange
fieldThe name of the changed line field.
newThe new value, as a string.
oldThe previous value, as a string.
InvoiceLineType
InvoiceLineUpdatedPayload
The per-field before/after changes made to the line.
customer_idThe customer billed on the invoice.
invoice_idThe invoice whose line was updated.
line_idThe invoice line that was updated.
line_typeThe kind of line (e.g. SUBSCRIPTION, USAGE, ADJUSTMENT).
The invoice total after the update, as a money object.
occurred_atWhen the line was updated (RFC3339).
organization_idworkspace_idThe workspace that owns the invoice.
InvoicePayment
created_atidkindoccurred_atstatefailure_messageinitiatornoteproviderrecorded_by_user_idreferencesourceInvoicePaymentAttemptFailedPayload
attempt_numberThe 1-based index of this payment attempt.
customer_idThe customer billed on the invoice.
error_codeThe provider-specific error code, when available.
error_messageThe provider-specific error message, when available.
error_typeThe classified failure category.
invoice_idThe invoice whose payment attempt failed.
next_retry_atWhen the next retry is scheduled (RFC3339); empty when terminal.
occurred_atWhen the attempt failed (RFC3339).
organization_idproviderThe payment gateway that processed the attempt.
workspace_idThe workspace that owns the invoice.
InvoicePaymentFailedTerminalPayload
customer_idThe customer billed on the invoice.
invoice_idThe invoice whose payment failed terminally.
last_attempt_idThe id of the final failed payment attempt.
last_error_messageThe error message of the final attempt, when available.
last_error_typeThe classified failure category of the final attempt.
occurred_atWhen the terminal failure was recorded (RFC3339).
organization_idtotal_attemptsThe total number of payment attempts made.
workspace_idThe workspace that owns the invoice.
InvoicePaymentRecordedPayload
The remaining amount due after this payment, as a money object.
The amount recorded as paid, as a money object.
customer_idThe customer billed on the invoice.
invoice_idThe invoice a payment was recorded against.
organization_idrecorded_atWhen the payment was recorded (RFC3339).
statusThe invoice status after the payment.
workspace_idThe workspace that owns the invoice.
InvoicePendingApprovalPayload
invoice_idThe invoice awaiting approval.
organization_idtransitioned_atWhen the invoice entered the pending-approval state (RFC3339).
workspace_idThe workspace that owns the invoice.
InvoiceTemplate
created_atdefault_forDocument types this template is the org's favorite for: a subset of document_types, empty for most templates.
descriptionFree-text description of the template.
document_typesDocument types this template can render: a non-empty subset of {invoice, credit_note}.
idis_systemTrue for built-in system templates, which cannot be edited or deleted.
nameHuman-readable template name.
organization_idstatusTemplate status, e.g. active or archived.
The template document: ordered blocks plus theme, branding, and footer.
updated_atversionOptimistic-concurrency version, bumped on every update.
deleted_atSoft-delete timestamp; null for live templates.
InvoiceUpdatedPayload
customer_idThe customer billed on the invoice.
fields_changedNames of the invoice fields modified in this update.
invoice_idThe invoice that was updated.
organization_idupdated_atworkspace_idThe workspace that owns the invoice.
InvoiceVoidedPayload
credit_note_idThe credit note issued to reverse the voided invoice.
customer_idThe customer billed on the invoice.
invoice_idThe invoice that was voided.
organization_idvoided_atWhen the invoice was voided (RFC3339).
workspace_idThe workspace that owns the invoice.
IssueLinkResponse
expires_atWhen the link token expires (RFC3339); the token is stateless and rejected after this time.
tokenRaw signed portal-access JWT, also embedded in the URL.
urlPortal URL the org admin forwards to the customer; embeds the signed access token.
IssuePortalLinkRequest
scopeOptional scope string embedded in the link token to narrow what the customer may access; omit for an unscoped link.
ItemResolutions
item_idproduct_idquantityprice_keypricing_modelproduct_namequantity_sourceItemTax
determinedrate^-?\d+(\.\d+)?$ · requiredDecimal number encoded as a string to preserve precision.
taxablebuyer_countryexemption_codeexemption_reasonproduct_tax_categoryreasonreverse_chargeseller_countrysupply_typetax_category_codetax_typeKeyCoverage
effective_keyspriced_keysmissing_keysKeyFilter
keysExplicit price_key values to match; OR-ed with tags (empty keys and tags = matches everything).
tagsRegistry tags to match; expanded into concrete keys against the product's key registry before line matching, then OR-ed with keys.
KeySet
created_atentry_countNumber of keys defined in this set.
idlifecycle_statusSet lifecycle: active or archived.
nameDisplay name of the key set.
organization_idproduct_countNumber of products that reference this key set.
slugURL-safe unique identifier for the key set, matching ^[a-z0-9][a-z0-9_-]{0,63}$.
updated_atdeleted_atSoft-delete timestamp; null for live sets.
descriptionOptional description of what this set of keys represents.
The keys this set defines; eager-loaded on single-set reads, null on list reads.
KeySetEntry
created_atdisplay_nameCustomer-facing label for the key.
idkeyThe key identifier (matching ^[a-zA-Z0-9._-]{1,64}$); the validated domain of prices.price_key once a product references the set.
key_set_idThe key set this entry belongs to.
statusEntry lifecycle: active or retired.
tagsFree-form tags for grouping and filtering keys.
updated_atFree-form key/value metadata attached to the entry.
KeySetReference
product_idA product that references the key set.
product_nameDisplay name of the referencing product.
MRRByTypeResponse
MRR totals across all customer types.
currencyISO 4217 currency every amount is denominated in.
MRR broken down per customer type.
MRRByTypeSegment
change_ratePercentage change from previous to current for this segment.
Latest-month MRR for this segment, {value, currency}.
customer_typeCustomer type this segment's MRR is for.
Prior-month MRR for this segment, {value, currency}.
Per-month MRR points for this segment, oldest first.
MRRDataPoint
monthCalendar month of this point, formatted YYYY-MM.
value^-?\d+(\.\d+)?$ · requiredMRR for the month, MAJOR units in the parent response's currency.
MRRResponse
change_ratePercentage change from previous to current (e.g. 12.5 for +12.5%).
currencyISO 4217 currency every amount and time-series point is denominated in.
MRR for the latest month in the series, {value, currency}.
MRR for the prior month, {value, currency}.
Per-month MRR points, oldest first.
ManualInvoiceHostedLinkRequestedPayload
The amount due on the hosted link, as a money object.
currencyThe invoice currency, ISO-4217.
customer_idThe customer billed on the invoice.
invoice_idThe manual invoice a hosted payment link was requested for.
invoice_numberThe human-readable invoice number, when assigned.
organization_idreasonWhich branch caused the request: no_collector, collect_failed, or post_collect.
requested_atWhen the hosted link was requested (RFC3339).
workspace_idThe workspace that owns the invoice.
MeOrgMembership
aliasidnamerolesMeResponse
active_orgactive_workspacerealm_rolesMeUser
emailidlocalenamepicturetimezoneMember
emailrolesstatususer_idnameMergeConflict
plan_idPlan both subscriptions are on, which is what makes them conflict.
source_subscription_idSubscription on the source customer that blocks the merge because it shares a plan with a target subscription.
target_subscription_idSubscription on the target customer that shares the plan with the source subscription.
MergeCustomerRequest
source_customer_idCustomer whose records are moved and which is then retired; must differ from target_customer_id.
strategyPREVIEW to compute the merge result without applying it, or MOVE_ALL to perform the merge.
target_customer_idSurviving customer that absorbs the source's records.
MergeResult
customer_scoped_prices_countNumber of customer-scoped prices reassigned from source to target.
invoices_countNumber of invoices moved from source to target.
payment_methods_countNumber of payment methods reassigned from source to target.
promotion_redemptions_countNumber of promotion redemptions reassigned from source to target.
source_customer_idCustomer whose records were (or would be) moved and then retired.
subscriptions_countNumber of subscriptions moved from source to target.
target_customer_idSurviving customer that absorbs the source's records.
usage_events_countNumber of usage events reassigned from source to target.
wallets_merged_countNumber of source wallets that had a same-currency counterpart on the target and were combined into it.
wallets_moved_countNumber of source wallets with no target counterpart that were moved to the target wholesale.
Subscription-plan conflicts that block a MOVE_ALL merge; populated on PREVIEW and on a rejected merge, empty when the merge can proceed.
The target customer after the merge; present only on a completed MOVE_ALL merge, null on PREVIEW.
Meter
created_atfunctionAggregation applied over the window: SUM, COUNT, MAX, MIN, AVG, UNIQUE_COUNT, LAST, or P95.
idkeyOrg-unique slug identifying the meter, e.g. "api_calls".
metric_keyEvent ingestion key this meter aggregates over.
nameHuman-readable label for the meter.
negative_allowedWhether the aggregated value may go negative (e.g. for credits/reversals).
organization_idupdated_atTime window over which the aggregation is computed.
workspace_idWorkspace the meter belongs to.
When set, this is a derived meter computed from other meters via a formula.
dedup_key_pathJSON-path to the event field used for deduplication; default uses the event's idempotency_key.
dimensionsEvent metadata fields exposed for group-by.
event_schemaJSON-Schema document validating ingested events; null disables validation.
Predicate tree restricting which events the meter includes.
late_event_policyHow events arriving after period close are handled: DROP, CLAMP_TO_PERIOD, or REBILL_PRIOR.
Alert conditions evaluated against the meter's output.
unique_by_fieldEvent field whose distinct values are counted; set for UNIQUE_COUNT.
unit_currency_fieldEvent field carrying the currency when the metric measures money.
unit_labelDisplay label for one metric unit (e.g. "calls").
value_fieldEvent field aggregated; set for SUM/MAX/MIN/AVG/P95/LAST.
MeterBindingMeterSummary
functionidkeynameunit_labelMeterBreach
comparatoridmeter_idmeter_keyobserved_valueoccurred_atorganization_idthreshold_namethreshold_valuedelivered_atproduct_idsubscription_idMeterFormula
expressionArithmetic expression over the variable names, e.g. "max(0, calls - free)".
Maps each short name used in expression to the source meter id it draws from.
MeterThresholdBreachedPayload
action_event_typeThe custom event type emitted by the action, when the action emits an event.
action_kindThe action the threshold triggers (e.g. WEBHOOK, SLACK, EVENT).
action_targetThe action's target (e.g. webhook URL, Slack channel), when set.
comparatorThe comparison operator that defines the breach (e.g. GTE, GT).
meter_idThe meter that breached its threshold.
meter_keyThe meter's stable key.
observed_valueThe observed meter value that crossed the threshold, as a decimal string.
organization_idproduct_idThe metered product the meter belongs to.
subscription_idThe subscription whose meter breached the threshold.
threshold_nameThe name of the configured threshold that was crossed.
threshold_valueThe configured threshold value, as a decimal string.
window_endThe end of the evaluation window (RFC3339).
window_startThe start of the evaluation window (RFC3339).
workspace_idThe workspace that owns the meter.
MigrateSubscribersRequest
modeMigration mode: PREVIEW (dry run, no changes), IMMEDIATE (migrate now) or SCHEDULED (migrate at scheduled_at).
proration_strategyOptional proration strategy applied to the version change.
scheduled_atWhen to run the migration; required for and only valid with SCHEDULED mode, and must be in the future.
target_versionPlan version to migrate subscribers onto; must be greater than 0.
MigratedSubscriberResult
customer_idCustomer owning the subscription.
has_price_overrideTrue when the subscription carries a price override that migration must preserve or flag.
new_versionPlan version the subscription moves (or would move) to.
previous_versionPlan version the subscription was on before migration.
subscription_idSubscription evaluated or migrated.
override_detailsIDs of the subscription's price overrides, when present.
MigrationPreviewResult
plan_idPlan whose subscribers were previewed.
Per-subscriber preview rows.
target_versionPlan version the preview targets.
total_affectedTotal subscribers currently on an older version of the plan.
total_flaggedSubscribers flagged for manual review (e.g. carrying price overrides).
total_migratableSubscribers that can migrate cleanly.
MinimumSpendCondition
kindUnion discriminator.
amount^-?\d+(\.\d+)?$Minimum spend the customer must reach for the condition to pass, MAJOR units in the currency field.
currencyISO 4217 currency the amount / max_amount thresholds are denominated in.
max_amount^-?\d+(\.\d+)?$Optional upper bound (MAJOR units); when set the spend must fall within [amount, max_amount] rather than merely meeting the minimum.
scopeWhich spend total the threshold measures: per_invoice (current invoice subtotal, default), period (spend in the current billing period), or lifetime (total spend ever).
Money
currencyvalue^-?\d+(\.\d+)?$Monetary amount in MAJOR units (e.g. euros, not cents), encoded as a decimal string.
MutationRecordedPayload
actionA short verb for the mutation: CREATED, UPDATED, ARCHIVED, DELETED, or COPIED.
customer_idThe parent customer, when the mutated entity belongs to one.
diffAn optional structured changeset; shape is caller-defined and not uniform.
entity_idThe id of the entity that was mutated.
entity_typeThe kind of entity that was mutated (e.g. PRICE, COST, BINDING).
organization_idplan_idThe parent plan, when the mutated entity belongs to one.
product_idThe parent product, when the mutated entity belongs to one.
recorded_atWhen the mutation was recorded (RFC3339).
subscription_idThe parent subscription, when the mutated entity belongs to one.
summaryA human-readable one-liner for the mutation; falls back to "
OSSThresholdState
crossed_atWhen the threshold was approached or crossed (RFC3339).
currencyThe seller's local currency, ISO-4217.
Cross-border EU revenue accumulated so far this year, as a money object.
organization_idseller_countryThe seller's country of establishment, ISO-3166 alpha-2.
The EU OSS revenue threshold (EUR 10,000), always denominated in EUR, as a money object.
workspace_idThe workspace this threshold state belongs to.
yearThe calendar year the threshold is tracked for.
OrgSecuritySettings
allowed_email_domainsallowed_idpscreated_atjit_default_rolejit_enabledorganization_idrequire_mfaupdated_atsession_timeout_secondsOrgTaxProfile
legal_nametax_numbertax_regimevat_iddefault_countryoss_countryOrganizationResponse
billing_emailbusiness_addresscreated_atdefault_currencydefault_date_formatdefault_first_day_of_weekdefault_languagedefault_localedefault_number_formatdefault_timezoneidlegal_namenamephonesales_audienceslugstatussupport_emailtax_registration_numberPaginationBlock
cursorOpaque continuation token for the next page; pass it back verbatim as ?cursor=. Null when there is no further page or the list paginates by offset. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
has_moreTrue when another page exists. This is the authoritative continuation signal; prefer it over total_count arithmetic.
Optional facet counts, keyed facet then value (e.g. counts.status.active). Present only on lists that declare facets.
total_countBest-effort total for the whole (filtered) list. Keyset lists compute it on the first page only and omit it afterwards; offset lists always set it; small bounded sub-lists set it to the returned length. Absent means unknown, not zero - use has_more to drive paging.
Payment
attempt_numbercreated_atcurrencycustomer_idididempotency_keyinitiatororganization_idproviderpurposestateupdated_atworkspace_idconfirmed_atdecline_codefailed_atfailure_codefailure_messagemetadatanext_actionparent_payment_idpayment_method_idprovider_payment_idpurpose_ref_idsucceeded_atPaymentChangedPayload
organization_idpayment_idThe payment that was created or changed and needs re-indexing.
PaymentGatewayConfig
Provider-specific credential document. Stripe: api_key (required), stripe_account_id, webhook_secret, api_base. GoCardless: access_token, webhook_secret. PATCH merges shallowly - send only the keys to change; omitted keys keep their stored value (so a masked read never needs to be resent). Reads project through an allowlist: non-secret keys pass through, known secrets keep a masked hint, undeclared keys are withheld.
created_atdisplay_nameidis_defaultis_enabledmodeorganization_idprovidersupported_currenciessupported_methodsupdated_atworkspace_idPaymentMethod
created_atcustomer_idCustomer this payment method belongs to.
idis_defaultWhether this is the customer's default payment method; only one method per customer is default at a time.
organization_idproviderPayment provider that holds this method, e.g. "stripe" or "gocardless".
statusLifecycle status: active, expired, or removed.
typeMethod type: CREDIT_CARD, BANK_ACCOUNT, SEPA_DIRECT_DEBIT, SEPA_DIRECT_DEBIT_B2B, ACH_BUSINESS, PAYPAL, or EXTERNAL; the B2B/ACH types require a BUSINESS customer.
updated_ataccount_last4Last four digits of the bank account / IBAN for direct-debit methods; null for card methods.
bank_nameBank name for direct-debit / bank-account methods; null for card methods.
display_brandCard brand for card methods (e.g. "visa"); null for non-card methods.
exp_monthCard expiry month (1-12) for card methods; null for non-card methods.
exp_yearCard expiry year for card methods; null for non-card methods.
last4Last four digits of the card number for card methods; null for non-card methods.
Free-form key/value metadata for caller use; not interpreted by billing.
provider_idProvider's own identifier for the stored method (e.g. a Stripe payment-method id); null when not tracked externally.
PercentageDiscountEffect
kindUnion discriminator.
apply_per_linePer-line application flag; a percentage rate applies to each line's own subtotal regardless, so this has no effect at invoice time for percentage discounts.
cap_per_invoice^-?\d+(\.\d+)?$Whole-invoice cap on the total discount summed across all matched lines (MAJOR units, in currency).
cap_per_period^-?\d+(\.\d+)?$Not yet enforced; a positive value is rejected at validation — use cap_per_invoice instead.
currencyISO 4217 currency pinning the money caps (max_discount / cap_per_invoice); empty for an uncapped rate, required once any cap is set. A capped discount no-ops on an invoice of a different currency.
max_discount^-?\d+(\.\d+)?$Per-line cap on the discount amount (MAJOR units, in currency); the computed discount for each line is clamped to this.
rate^-?\d+(\.\d+)?$Percentage rate as a plain number (0-100); "10" means 10% off — the engine divides by 100 and applies it to each matching line's subtotal.
Which invoice lines the discount applies to; empty = every line.
Permission
grouplabelpermissionsystemdescriptionPhase
allow_regressionWhether a redemption may regress out of this phase to the one below.
idPhase ID; client-supplied on create and canonical thereafter.
is_terminalWhether this is a terminal phase the redemption cannot advance beyond.
nameOperator-facing phase name.
orderPosition in the ladder; advance enters the next phase by order, regress falls to the previous.
Conditions required to enter this phase from the one below.
effectsEffects applied while a redemption is in this phase.
Conditions required to remain in this phase.
min_dwell_daysMinimum days a redemption must dwell in this phase before any exit (advance or regress) is allowed.
Max-bound triggers that drop a redemption out of this phase to the one below.
transition_timingWhen a phase transition takes effect relative to the billing cycle.
PinSubscriptionItemVersionRequest
product_version_idProduct version to pin the item to; null unpins it to follow the product head version.
Plan
created_atidnameInternal operator-facing plan name.
organization_idrequires_continuous_coverageWhen true a subscription must keep this plan continuously covered (no coverage gaps).
statusCatalog lifecycle status: draft, scheduled, active or archived.
updated_atversionCurrent published version number of the plan.
archived_atTimestamp the plan was archived, if it has been.
Org-defined custom field values for this plan.
deleted_atSoft-delete timestamp; null for a live plan.
deprecated_atTimestamp the plan was deprecated, if it has been.
descriptionInternal operator-facing description; not shown to buyers.
external_idCaller-supplied external identifier for reconciliation with an upstream system.
head_version_idThe plan's current live head version row; null until the plan has been published at least once.
Free-form operator key/value metadata.
public_descriptionBuyer-facing description shown in checkout and the customer portal.
published_atTimestamp the current version was published; null while only a draft exists.
published_byUser who published the current version.
Tags attached to this plan.
Locale-keyed overrides for name, description and public_description.
PlanPricePreviewLine
currencypricing_modelproduct_idproduct_namequantityquantity_sourcetax_rate^-?\d+(\.\d+)?$ · requiredDecimal number encoded as a string to preserve precision.
errorincluded_quantityPlanPricePreviewRequest
billing_interval_unitcurrencycustomer_idplan_idPlanPricePreviewResponse
currencyPlanProduct
created_atidorganization_idplan_idPlan this membership belongs to.
product_idProduct attached to the plan by this membership.
product_track_modeWhether this membership auto-follows the product head (latest) or holds its snapshotted version (pinned).
credit_unit_value^-?\d+(\.\d+)?$Money value of one POOL unit, MAJOR units in currency; POOL only.
currencyISO 4217 currency for a POOL's money-denominated knobs (credit_unit_value, spend_limit).
included_quantity^-?\d+(\.\d+)?$Quantity bundled into the base price before per-unit billing applies (the included allowance/seat floor); null means none.
kindEntitlement kind: REFRESHING (per-period allowance, the empty-string default) or POOL (durable credit that never resets).
Free-form operator key/value metadata for this membership.
refresh_countPlan-level default allowance-refresh cadence count; null (with refresh_unit) means one whole-period pool.
refresh_unitUnit for the refresh cadence: day, week, month, year or billing_cycle.
rollover_enabledWhen true, unused included allowance carries forward into later periods.
rollover_expiry_periodsNumber of periods after which rolled-over allowance expires; null means it never expires.
rollover_max^-?\d+(\.\d+)?$Cap on accumulated rolled-over allowance; null means uncapped.
spend_limit^-?\d+(\.\d+)?$Ceiling on a POOL's money spend, MAJOR units in currency; POOL only.
unit_limit^-?\d+(\.\d+)?$Ceiling on a POOL's unit balance; POOL only.
PlanProductCostSummary
cost_idID of the product cost summarized here.
keyFormula-reference key of the cost (referenced in formulas as cost.
requires_continuous_coverageWhen true a subscription referencing this cost must keep it continuously covered.
scopeCost scope: PRODUCT (per-product) or ORG (org-wide).
Static money value of the cost; null when the cost is a formula.
descriptionOperator-facing description of what this cost represents.
Formula that computes the cost; null when the cost is a static amount.
PlanProductMeterBindingSummary
binding_idID of the product-meter binding summarized here.
meter_idMeter the binding consumes.
meter_keyMeter's reference key (joined from the meters table for display).
pricing_var_nameFormula variable name the meter result is exposed as.
roleBinding role: BILLABLE_QUANTITY, PRICING_VAR or INFORMATIONAL.
meter_nameHuman-readable meter name (joined from the meters table for display).
PlanProductPriceSummary
currencyISO 4217 currency of the price.
list_price^-?\d+(\.\d+)?$ · requiredList price, MAJOR units, in the currency field.
price_idID of the price row captured in this plan-version snapshot.
country_codeISO 3166-1 alpha-2 country the price applies to, when country-scoped.
display_nameCustomer-facing label for the price key.
price_keyKey selecting this price within a keyed product; null for unkeyed products.
PlanPublishedPayload
organization_idplan_idThe plan that was published.
published_atWhen the plan version was published (RFC3339).
versionThe plan version that was published.
workspace_idThe workspace that owns the plan.
PlanSubscribersMigratedPayload
migrated_atWhen the migration completed (RFC3339).
organization_idplan_idThe plan whose subscribers were migrated.
target_versionThe plan version subscribers were migrated onto.
total_flaggedThe number of subscriptions flagged for manual review instead of migrated.
total_migratedThe number of subscriptions migrated.
workspace_idThe workspace that owns the plan.
PlanTransitionRequest
new_plan_idPlan to transition the subscription onto.
Per-product key-set selections keyed by product ID, for keyed products on the new plan.
proration_modeHow the transition is charged: pro_rata, pay_in_full or do_not_charge; defaults to pro_rata.
PlanVersion
idorganization_idplan_idPlan this published version belongs to.
published_atTimestamp this plan version was published.
Frozen plan state (products, pinned versions, prices) captured at publish time.
versionSequential version number of this published plan version.
PlanVersionProduct
Price summaries frozen into this plan version for the product.
pricing_modelProduct pricing model frozen at publish: VOLUME, STAIRCASE or PACKAGE.
product_idProduct captured in this plan-version snapshot.
product_nameProduct name frozen at publish time.
credit_unit_value^-?\d+(\.\d+)?$Money value of one POOL unit, MAJOR units in currency; POOL only.
currencyISO 4217 currency for a POOL's money-denominated knobs (credit_unit_value, spend_limit).
included_quantity^-?\d+(\.\d+)?$Quantity bundled into the base price before per-unit billing applies (the included allowance/seat floor); null means none.
kindEntitlement kind: REFRESHING (per-period allowance, the empty-string default) or POOL (durable credit that never resets).
Free-form operator key/value metadata for this membership.
product_version_idProduct version in force when the plan was published; null for legacy rows written before version pinning.
refresh_countPlan-level default allowance-refresh cadence count; null (with refresh_unit) means one whole-period pool.
refresh_unitUnit for the refresh cadence: day, week, month, year or billing_cycle.
rollover_enabledWhen true, unused included allowance carries forward into later periods.
rollover_expiry_periodsNumber of periods after which rolled-over allowance expires; null means it never expires.
rollover_max^-?\d+(\.\d+)?$Cap on accumulated rolled-over allowance; null means uncapped.
spend_limit^-?\d+(\.\d+)?$Ceiling on a POOL's money spend, MAJOR units in currency; POOL only.
Locale-keyed overrides frozen at publish time.
unit_limit^-?\d+(\.\d+)?$Ceiling on a POOL's unit balance; POOL only.
PlanVersionRebasedPayload
new_versionThe version number after the rebase.
old_versionThe version number before the rebase.
organization_idover_versionThe just-published version the rebase was renumbered above.
plan_idThe plan whose pending version was rebased.
rebased_atWhen the version was rebased (RFC3339).
version_idThe plan version row that was rematerialized.
workspace_idThe workspace that owns the plan.
PlanVersionSnapshot
plan_namePlan name frozen at publish time.
Products and their pinned versions/values frozen into this plan version.
descriptionPlan description frozen at publish time.
Plan metadata frozen at publish time.
PortalBranding
created_atorganization_idupdated_ataccent_colorcustom_cssdisplay_namefavicon_urllogo_urlprimary_colorprivacy_urlsupport_emailsupport_urlterms_urlPortalSettings
allow_add_payment_methodallow_cancel_subscriptionallow_invoice_payallow_wallet_topupcreated_atorganization_idshow_billing_settingsshow_invoicesshow_payment_methodsshow_subscriptionsshow_walletsupdated_atPreviewInvoiceTemplateRequest
document_typeSingle document type to render; defaults to INVOICE.
document_typesDocument types to render (e.g. INVOICE, CREDIT_NOTE); defaults to the template's.
Unsaved template draft to preview instead of the stored template.
PreviewTargetRequest
actionforcetarget_latesttarget_versionPreviewTargetResponse
countsampleestimated_overPrice
created_atcurrencyISO 4217 currency the list price and tier amounts are denominated in.
effective_fromTimestamp this price version became effective on the billing timeline.
idkindResolution scope of this price: BASE, PLAN_OVERRIDE, or CUSTOMER_OVERRIDE; more specific kinds win the resolve cascade.
List price as a currency-tagged money envelope; nominal (often 0) for tiered and formula pricing where the real amount comes from the tier walk.
organization_idproduct_idThe product this price belongs to.
product_nameDisplay name of the owning product.
quantity_sourceHow the product's billable quantity is sourced (e.g. LICENSED, METERED); drives whether the resolve quantity is caller- or usage-supplied.
statusLifecycle status: draft, scheduled, active, or archived.
updated_atcountry_codeCountry this price is scoped to; null matches any country and country-specific rows outrank generic ones.
customer_idCustomer this override is scoped to; set only when kind=CUSTOMER_OVERRIDE.
deleted_atSoft-delete timestamp; null for live prices.
display_nameCustomer-facing label for this price / price_key.
is_set_priceMarks the single row covering every effective key of the product's key set; the resolver falls back to it when no exact key price matches.
Free-form key/value metadata attached to the price.
plan_idPlan this override is scoped to; set only when kind=PLAN_OVERRIDE.
price_keyThe keyed variant this price covers on a keyed product; null on unkeyed prices and on the set price.
Costs referenced by this price's tier expressions, surfaced for the 'this price uses these costs' view.
The tier ladder ordered by ascending up_to; drives quantity-based pricing.
PriceBreakdown
Ordered adjustments applied to the list price to reach the effective price.
The final price after all adjustments.
The starting list price before any adjustments.
Underlying cost used to compute margin, when cost data is available.
Effective price minus cost basis, when cost data is available.
PriceDerivation
quantity^-?\d+(\.\d+)?$ · requiredThe quantity the tier walk was evaluated at.
The effective per-unit amount the resolver landed on.
The pre-conversion leg when the resolved currency differs from the price's own currency.
formula_appliedTrue when a tier rate came from a formula or rate expression rather than a static unit_amount.
pricing_modelThe pricing model that shaped the tier walk (VOLUME, STAIRCASE, or PACKAGE); empty for a flat single-rate price.
quantity_is_probeTrue when quantity was a probe value (1) for a metered item with no declared quantity, so the figure reads 'per unit' rather than a period total.
Per-tier steps showing how the total was actually built for the quantity.
The tier ladder as defined on the price (bounds, rate, flat, formula presence); present only for tiered pricing.
PriceFormula
created_atexpressionThe expression evaluated to produce a tier rate; may reference declared variables, cost.
idis_systemTrue for built-in system formulas that organizations cannot edit or delete.
nameDisplay name of the formula.
organization_idupdated_atvariablesDeclared variables (name, type, optional default) the expression may reference.
versionCurrent head version number of the formula.
head_version_idThe currently-active price_formula_versions row; null only briefly between insert and the v1 auto-publish.
PriceFormulaVersion
expressionFormula expression as of this version.
formula_idThe parent formula this immutable version snapshots.
idnameFormula name as of this version.
organization_idpublished_atWhen this version was published.
statusVersion lifecycle: draft, scheduled, published, or archived.
variablesDeclared variables as of this version.
versionThis snapshot's version number.
effective_fromWhen this version starts being effective on the billing timeline; null while draft.
effective_toWhen this version was superseded; null while it is the current version.
published_byThe user who published this version.
PriceOverrideEffect
kindUnion discriminator.
currencyISO 4217 currency of the override amount; required — the override no-ops on an invoice of a different currency.
override_amount^-?\d+(\.\d+)?$The price each matching line is overridden to (MAJOR units, in currency); applied only when it is below the line's current subtotal, so it never raises a charge.
Which invoice lines the override applies to; empty = every line.
PriceReferencedCost
cost_idThe cost row this price's tier expressions reference.
keyThe cost key, referenced in tier formulas as cost.
The cost's flat amount, when the cost is a fixed value.
The cost's own expression, when the cost is itself computed.
PriceResolution
cachedTrue when this resolution was served from the resolver cache.
conversion_appliedTrue when a currency conversion was applied to reach the resolution currency.
currencyISO 4217 currency all amounts in this resolution are denominated in.
override_appliedTrue when a customer override changed the resolved amount.
price_idThe price row the cascade selected as the winner.
pricing_modelThe pricing model that shaped the tier walk (e.g. VOLUME, STAIRCASE, PACKAGE).
quantity^-?\d+(\.\d+)?$ · requiredThe quantity the resolution was computed for.
tier_expr_appliedTrue when at least one tier rate came from a rate expression or formula rather than a static unit_amount.
total_amount^-?\d+(\.\d+)?$ · requiredTotal amount for the quantity, MAJOR units in Currency.
unit_amount^-?\d+(\.\d+)?$ · requiredEffective per-unit amount, MAJOR units in Currency, at the resolved quantity.
Optional list-price-to-effective-price adjustment breakdown for display.
exchange_rateThe exchange rate applied, as a decimal string, when a conversion occurred.
exchange_rate_idThe exchange-rate row used for the conversion.
Maps a tier's formula_id to the pinned formula version whose expression must be substituted; populated only for version-pinned subscriptions.
original_amount^-?\d+(\.\d+)?$Pre-conversion total in original_currency; present only when a conversion was applied.
original_currencyThe currency the price was denominated in before conversion.
original_unit_amount^-?\d+(\.\d+)?$Pre-conversion per-unit amount in original_currency; present only when a conversion was applied.
override_idThe CUSTOMER_OVERRIDE price row that supplied the applied override, when one applied.
override_sourceWhether the applied customer override came from a subscription phase (PHASE) or was customer-wide (CUSTOMER).
product_version_idThe product version whose revision rows this resolution was read from; nil on the replay path.
Maps a rate-table slug to the pinned rate_table_versions id captured at the resolved product version's anchor; populated only for version-pinned subscriptions.
Per-tier walk steps with currency-tagged amounts; the shared derivation shape for how the total was built.
The resolved tier ladder with currency-tagged amounts.
PriceTier
Flat amount as a currency-tagged money envelope; the currency comes from the parent price.
idprice_idThe parent price this tier belongs to.
tier_orderZero-based position of this tier in the ascending ladder; tiers are evaluated in this order.
Per-unit amount as a currency-tagged money envelope; the currency comes from the parent price.
up_to^-?\d+(\.\d+)?$ · requiredInclusive upper quantity bound; the tier covers (previous tier's up_to, up_to]. Null marks the open-ended final tier (infinity).
created_atPer-tier numeric overrides of the formula's declared variable defaults.
formula_idOptional reference to a price_formulas row whose expression computes the tier rate; takes precedence over rate_expression and unit_amount.
rate_expressionOptional arithmetic expression evaluated for the tier rate; overrides unit_amount when set.
updated_atProblem
codeStable machine-readable error code. Branch on this, not on detail text.
detailstatustitletypeField-level failures; present when code=VALIDATION. Field codes (REQUIRED, INVALID_FORMAT, UNKNOWN_FIELD, TOO_SHORT, ...) are a separate, smaller vocabulary from Problem.code.
instancerequest_idCorrelation id of the failed request - the same value as the X-Request-Id response header. Quote it in support tickets.
Product
active_price_countNumber of active prices currently attached to the product.
allowed_pricing_modelsPricing models the product's quantity source admits (PACKAGE requires METERED).
Per-currency rollup of the product's static costs; formula-form costs are excluded.
created_atidinvoiceable_standaloneWhen true the product is eligible to appear in the manual-invoice picker.
nameInternal operator-facing product name.
organization_idpricing_modelPricing model applied to this product: VOLUME, STAIRCASE or PACKAGE.
quantity_adjustableWhen true the buyer picks the quantity (seats/licenses); false is a flat charge.
quantity_sourceWhere the billed quantity comes from: DECLARED (set on the subscription item) or METERED (from the meter evaluator).
statusCatalog lifecycle status: draft, scheduled, active or archived.
tax_categoryProduct tax category: DEFAULT, REDUCED, ZERO or EXEMPT.
unit_labelSingular noun one billed unit is called (e.g. seat, GB).
updated_atversionCurrent published version number of the product.
Named, non-billable cost variants that price formulas can reference.
Org-defined custom field values for this product.
deleted_atSoft-delete timestamp; null for a live product.
descriptionInternal operator-facing description; not shown to buyers.
external_idCaller-supplied external identifier for reconciliation with an upstream system.
key_set_excluded_keysKeys subtracted from the linked key set's active entries (subtract-only).
key_set_idNon-null marks the product as keyed, linking it to an org-global key set whose entries define its price-key domain.
Free-form operator key/value metadata.
public_descriptionBuyer-facing description shown in checkout and the customer portal.
requires_product_idsProducts that must also be present for this product to be sold (dependency set).
Tags attached to this product.
Locale-keyed overrides for name, description and public_description.
ProductActivatedPayload
activated_atWhen the product was activated (RFC3339).
nameThe product name at activation.
organization_idproduct_idThe product that was activated.
workspace_idThe workspace that owns the product.
ProductAllowanceState
billable_usage^-?\d+(\.\d+)?$ · requiredUsage above all allowance that is billed as overage.
consumed_allowance^-?\d+(\.\d+)?$ · requiredTotal allowance consumed across all sources.
consumed_credits^-?\d+(\.\d+)?$ · requiredUsage-credit allowance consumed.
consumed_plan^-?\d+(\.\d+)?$ · requiredPlan allowance consumed.
consumed_rollover^-?\d+(\.\d+)?$ · requiredRolled-over allowance consumed.
credit_allowance^-?\d+(\.\d+)?$ · requiredTotal usage-credit (granted) allowance available.
plan_allowance^-?\d+(\.\d+)?$ · requiredIncluded allowance from the plan, in metered units.
product_idThe product this allowance state is for.
product_nameDisplay name of the product.
remaining_allowance^-?\d+(\.\d+)?$ · requiredUnused plan allowance remaining in the period.
rollover_allowance^-?\d+(\.\d+)?$ · requiredAllowance carried over from prior periods.
total_allowance^-?\d+(\.\d+)?$ · requiredSum of plan, rollover and credit allowance.
total_usage^-?\d+(\.\d+)?$ · requiredTotal metered usage in the current period.
Per-grant attribution behind credit_allowance (source, quantity, optional expiry); omitted when empty.
credit_unit_value^-?\d+(\.\d+)?$Money value of one pool unit (e.g. 0.002 per credit); null for a REFRESHING or unvalued pool.
currencyISO 4217 currency credit_unit_value is denominated in; null when the pool is unvalued.
kindAllowance kind: REFRESHING (per-period allowance) or POOL (a durable cross-period balance that drains as usage is metered).
refresh_countSub-period refresh cadence count (e.g. 1 with unit=day refreshes daily); null refreshes once per billing cycle.
refresh_unitUnit of the refresh cadence (day/week/month/year/billing_cycle); null refreshes once per billing cycle.
unit_labelBillable meter's unit label (e.g. AI credits, API calls); empty when the meter sets none.
ProductArchivedPayload
archived_atWhen the product was archived (RFC3339).
nameThe product name at archival.
organization_idproduct_idThe product that was archived.
workspace_idThe workspace that owns the product.
ProductCombinationCondition
kindUnion discriminator.
grace_anchorEvent the grace window is measured from: event (the triggering event time, default) or phase_boundary (the current subscription phase's start/end).
grace_directionWhich way the grace window extends from its anchor: lookback, lookahead, or bidirectional (default).
grace_period_daysLegacy grace window in days: nil/0 = strict (all products must be present now), N = allow a bidirectional +/-N-day window around the event; superseded by grace_window_count when that is set.
grace_window_countExplicit grace window magnitude in grace_window_unit units; when set (>0) it supersedes grace_period_days.
grace_window_unitUnit of grace_window_count (day, week, month, billing_cycle); defaults to day when a count is set.
The set of product requirements the basket must jointly satisfy (each an AND term of the bundle).
ProductConsumer
nameName of the consuming product.
product_idID of the ACTIVE product whose billed values depend on the shared entity being edited.
ProductCopiedPayload
copied_atWhen the product was copied (RFC3339).
nameThe name of the new copy.
organization_idproduct_idThe id of the newly created copy.
source_product_idThe product the copy was made from.
workspace_idThe workspace that owns the product.
ProductCreatedPayload
created_atnameThe product name at creation.
organization_idpricing_modelThe product's pricing model (e.g. VOLUME, STAIRCASE, PACKAGE).
product_idThe product that was created.
typeThe product type.
workspace_idThe workspace that owns the product.
ProductDeletedPayload
deleted_atWhen the product was deleted (RFC3339).
nameThe product name at deletion.
organization_idproduct_idThe product that was deleted.
workspace_idThe workspace that owns the product.
ProductMeterBinding
created_atidmeter_idorganization_idproduct_idroleupdated_atworkspace_idpricing_var_nameProductRequirement
Narrows the requirement to specific keyed variants of the product; only subscription items whose price_key matches count toward presence/quantity (conditions support explicit keys only, not tag selectors).
min_quantityMinimum quantity required; nil or <=1 means simple presence, N>1 means the subscription carries N+ of the item OR the window's usage totals reach N.
product_idProduct the basket must contain for this bundle line to be satisfied.
ProductSaving
Amount saved on this product.
product_idProduct the saving applies to.
product_nameDenormalized product name for display.
ProductUpdatedPayload
The field-level diff of auditable fields that changed.
organization_idproduct_idThe product that was updated.
updated_atworkspace_idThe workspace that owns the product.
ProductVersionRebasedPayload
new_versionThe version number after the rebase.
old_versionThe version number before the rebase.
organization_idover_versionThe just-published version the rebase was renumbered above.
product_idThe product whose pending version was rebased.
rebased_atWhen the version was rebased (RFC3339).
version_idThe product version row that was rematerialized.
workspace_idThe workspace that owns the product.
ProductVersionSnapshot
effective_fromeffective_toidnameproduct_idproduct_statuspublished_atrelease_strategystatusversiondescriptionexternal_idmetadatapublished_byProformaInvoice
currencyISO 4217 currency; every money field on this preview and its lines is denominated in it.
customer_idThe customer this preview would bill.
Projected line items that would appear on the invoice.
subscription_idThe subscription this preview was projected from.
Projected net total of all lines before tax, as a currency-tagged amount.
Projected total tax across all lines, as a currency-tagged amount.
Projected gross amount (subtotal plus tax), as a currency-tagged amount.
billing_period_endEnd of the service period this preview covers.
billing_period_startStart of the service period this preview covers.
ProformaInvoiceLine
descriptionHuman-readable line description shown on the document.
line_typeLine classification: RECURRING, USAGE, PRORATION_CREDIT, PRORATION_CHARGE, ADD_ON, EXPENSE_PASSTHROUGH, MILESTONE, ADJUSTMENT, or CREDIT.
quantity^-?\d+(\.\d+)?$ · requiredProjected billed quantity.
Line net (quantity times unit price) before tax, as a currency-tagged amount.
Tax charged on this line, as a currency-tagged amount.
tax_rate^-?\d+(\.\d+)?$ · requiredTax rate applied to this line, as a fraction (0.19 = 19%).
Price per unit, as a currency-tagged amount.
Structured pricing breakdown (tiers, formulas) when the resolver produced one.
Arbitrary caller-supplied key/value pairs.
period_endEnd of the service period this line covers.
period_startStart of the service period this line covers.
product_idThe catalog product that priced this line; null for manual/ad-hoc lines.
tax_typeTax type label (e.g. VAT, GST); null when the line is untaxed.
Promotion
application_timingWhen a redeemed promotion first takes effect: NEXT_CYCLE, RETROACTIVE, or IMMEDIATE.
archetypeFrontend-only preset hint the promotion was authored from; not persisted rule logic.
Live targeting set (Bucket-A): who sees — and under auto-enrollment, who receives — the promotion.
budget_behaviorWhat happens when a redemption would exceed max_budget: SKIP (do not apply) or PARTIAL (apply up to the remaining budget).
created_atcurrent_budget_used^-?\d+(\.\d+)?$ · requiredMAJOR units, denominated in budget_currency (this object's field).
current_redemptionsNumber of redemptions counted against max_redemptions so far.
derived_statusEffective status computed from status, validity window, and budget/redemption exhaustion (e.g. active, expired, budget_exhausted, redemptions_exhausted).
distributionHow a customer comes to hold the promotion: AUTO_APPLY, AUTO_ENROLL, COUPON, or DIRECT.
evaluation_scopeWhere the engine evaluates the promotion: invoice (default), subscription, usage_event, or reserve.
idnameOperator-facing promotion name.
organization_idpriorityOrdering priority on the invoice pass; higher priority applies first and wins within a stacking group.
requires_continuous_coverageWhether the benefit requires the qualifying subscription/product to remain held continuously.
stacking_modeHow the promotion combines with others on the invoice pass: stack (combines, subject to stacking_group) or exclusive (applies alone).
statusLifecycle status: draft, scheduled, active, or archived.
updated_atvalid_fromFirst calendar day (UTC) the promotion is valid; plain date, no clock or zone.
versionVersion number of this promotion snapshot.
archived_atWhen the promotion was archived; null unless archived.
budget_currencyISO 4217 currency max_budget / current_budget_used are denominated in; empty when no budget is set.
codeCoupon code; set only when distribution is COUPON, null otherwise.
Human-readable summaries of the entry phase's eligibility conditions.
deleted_atSoft-delete timestamp; non-null means the promotion is deleted and hidden from normal reads.
descriptionInternal description of the promotion (not shown to customers).
Human-readable summary of the entry phase's effects.
head_version_idID of the current head (latest published) promotion version.
max_budget^-?\d+(\.\d+)?$MAJOR units, denominated in budget_currency (this object's field).
max_redemptionsCap on total redemptions across all customers; null = unlimited.
max_redemptions_per_customerCap on redemptions by any single customer; null = unlimited.
Canonical rule model: an ordered list of phases (at least one), each carrying its eligibility/advance/regress condition sets and effects.
public_descriptionCustomer-facing description of the promotion.
published_atWhen this version was published; null while still a draft.
published_byID of the user who published this version.
remaining_budget^-?\d+(\.\d+)?$MAJOR units, denominated in budget_currency (the embedded promotion field). max_budget - current_budget_used.
remaining_redemptionsRedemptions left before max_redemptions is reached; null when unlimited.
stacking_groupNamed group for mutual exclusion under stacking_mode=stack; promotions sharing a group never combine with each other (highest priority wins).
Localized overrides for customer-facing text, keyed by locale.
valid_toLast calendar day (UTC) the promotion is valid, inclusive of all of that day; null = open-ended.
PromotionActivatedPayload
activated_atWhen the promotion became active (RFC3339).
organization_idpromotion_idThe promotion that became active.
workspace_idThe workspace that owns the promotion.
PromotionArchetype
PromotionArchivedPayload
archived_atWhen the promotion was archived (RFC3339).
organization_idpromotion_idThe promotion that was archived.
workspace_idThe workspace that owns the promotion.
PromotionAudience
countriesAny-of ISO 3166-1 alpha-2 country codes matched against the customer's billing address; empty = no country constraint.
customer_idsExplicitly picked customers; an explicit pick always counts (unioned with the tag/fact branch).
customer_typesAny-of customer types the customer must be one of (BUSINESS, CONSUMER, UNKNOWN); empty = no type constraint.
tag_idsCustomer-tag IDs the audience targets; a customer matches when they carry these tags per tag_match (empty = no tag constraint).
tag_matchHow tag_ids combine: any (default, one matching tag suffices) or all (the customer must carry every tag).
PromotionBudgetExhaustedPayload
exhausted_atWhen the budget was exhausted (RFC3339).
final_usedTotal budget consumed at exhaustion, MAJOR units in the promotion's currency as a decimal string.
max_budgetThe configured maximum budget, MAJOR units in the promotion's currency as a decimal string.
organization_idpromotion_idThe promotion whose budget was exhausted.
workspace_idThe workspace that owns the promotion.
PromotionCouponToken
created_atidorganization_idpromotion_idPromotion the token redeems.
statusToken status: available, redeemed, expired, or revoked.
tokenThe single-use coupon token string a customer redeems with.
customer_emailEmail the token is locked to, when minted for a specific customer.
customer_idCustomer the token is locked to, when known.
expires_atWhen the token expires; null = no expiry.
redeemed_atWhen the token was redeemed; null while still available.
redemption_idRedemption created when the token was redeemed; null while still available.
PromotionCreatedPayload
archetypeThe promotion's archetype classification.
created_atdistributionHow the promotion is distributed (e.g. automatic vs. code-based).
organization_idpromotion_idThe promotion this event concerns.
workspace_idThe workspace that owns the promotion.
PromotionEffectAppliedPayload
applied_atWhen the effect was applied (RFC3339).
customer_idThe customer billed on the invoice.
invoice_idThe invoice the promotion discount was applied to.
organization_idphase_idThe phase that produced the effect, when phased.
promotion_idThe promotion that produced the discount.
redemption_idThe redemption that produced the effect, when tracked.
The total discount applied, as a money object.
workspace_idThe workspace that owns the invoice.
PromotionExpiredPayload
expired_atWhen the promotion expired (RFC3339).
organization_idpromotion_idThe promotion that expired.
reasonWhy the promotion expired.
workspace_idThe workspace that owns the promotion.
PromotionPhaseChangedPayload
customer_idThe customer holding the redemption.
directionWhether the transition advanced or reverted (e.g. FORWARD/BACKWARD).
from_phase_idThe phase the redemption left; null on initial entry.
from_phase_orderThe ordinal of the phase left; null on initial entry.
organization_idpromotion_idThe promotion the redemption belongs to.
reasonOptional explanation of the phase change.
redemption_idThe redemption whose phase changed.
to_phase_idThe phase the redemption entered.
to_phase_orderThe ordinal of the phase entered.
transitioned_atWhen the phase transition occurred (RFC3339).
trigger_typeWhat triggered the phase change.
workspace_idThe workspace that owns the redemption.
PromotionPreviewRequest
customer_idCustomer to evaluate the promotion's conditions for; required.
subscription_idSubscription context to evaluate against, when applicable.
PromotionPreviewResponse
Per-condition pass/fail breakdown.
eligibleWhether the customer currently satisfies the promotion's conditions.
promotion_idThe previewed promotion.
promotion_nameThe promotion's name.
effectThe effects that would apply if the promotion were redeemed.
effect_summaryOne-line human-readable summary of the effects.
reasonExplanation when the customer is not eligible; null when eligible.
PromotionRedeemedPayload
customer_idThe customer who redeemed the promotion.
organization_idpromotion_idThe promotion that was redeemed.
redeemed_atWhen the promotion was redeemed (RFC3339).
redemption_idThe redemption created by this redeem.
subscription_idThe subscription the promotion was redeemed against, when subscription-scoped.
workspace_idThe workspace that owns the redemption.
PromotionRedemption
applied_atWhen the promotion was redeemed / applied for the customer.
created_atcustomer_idCustomer holding the redemption.
idorganization_idpromotion_idPromotion this redemption is for.
promotion_versionPromotion version this redemption is bound to.
statusRedemption status: active, dormant, expired, revoked, pending, or opted_out.
updated_atarchetypeDenormalized promotion archetype for display.
Eligibility conditions captured at redeem time; null means use the live promotion rule.
current_phase_idWhich phase of a phased promotion the redemption is currently in.
dormant_reasonBrief reason the redemption went dormant, e.g. "eligibility_lost".
dormant_sinceWhen the redemption became dormant; populated only when status=dormant.
effect_snapshotEffects captured at redeem time, immune to later promotion edits; empty means use the live promotion rule.
expires_atWhen the redemption's benefits expire; null = no expiry.
free_periods_remaining^-?\d+(\.\d+)?$Free billing periods left to consume; null = unused. Decimal so pro-rated invoices can draw fractional amounts (e.g. 0.5 for a half-period line).
grace_period_expires_atFor pending redemptions, when the grace window for completing the qualifying product combination expires.
phase_entered_atWhen the current phase was entered.
promotion_nameDenormalized promotion name for display.
subscription_idSubscription the redemption is scoped to, when applicable.
workspace_idThe redemption's owning workspace (ADR-008 RLS scope).
PromotionRedemptionCapReachedPayload
current_redemptionsThe redemption count at the moment the cap was reached.
max_redemptionsThe configured maximum number of redemptions.
organization_idpromotion_idThe promotion whose redemption cap was reached.
reached_atWhen the redemption cap was reached (RFC3339).
workspace_idThe workspace that owns the promotion.
PromotionRedemptionDormantPayload
customer_idThe customer holding the redemption.
dormant_atWhen the redemption became dormant (RFC3339).
failed_conditionsThe condition keys that failed, putting the redemption dormant.
organization_idpromotion_idThe promotion the redemption belongs to.
redemption_idThe redemption that became dormant.
workspace_idThe workspace that owns the redemption.
PromotionRedemptionFreePeriodsExhaustedPayload
customer_idThe customer holding the redemption.
exhausted_atWhen the free periods were exhausted (RFC3339).
organization_idpromotion_idThe promotion the redemption belongs to.
redemption_idThe redemption whose free periods were exhausted.
subscription_idThe subscription the redemption applies to, when subscription-scoped.
workspace_idThe workspace that owns the redemption.
PromotionRedemptionReactivatedPayload
customer_idThe customer holding the redemption.
organization_idpromotion_idThe promotion the redemption belongs to.
reactivated_atWhen the dormant redemption was reactivated (RFC3339).
redemption_idThe redemption that was reactivated.
workspace_idThe workspace that owns the redemption.
PromotionRedemptionRevokedPayload
customer_idThe customer whose redemption was revoked.
organization_idpromotion_idThe promotion the redemption belongs to.
reasonWhy the redemption was revoked.
redemption_idThe redemption that was revoked.
revoked_atWhen the redemption was revoked (RFC3339).
workspace_idThe workspace that owns the redemption.
PromotionUpdatedPayload
changed_fieldsNames of the fields modified in this update.
organization_idpromotion_idThe promotion that was updated.
updated_atversionThe promotion version after this update.
workspace_idThe workspace that owns the promotion.
PromotionVersionSnapshot
application_timingApplication timing at this version (NEXT_CYCLE, RETROACTIVE, IMMEDIATE).
budget_behaviorOver-budget behavior at this version (SKIP or PARTIAL).
distributionDistribution axis at this version (AUTO_APPLY, AUTO_ENROLL, COUPON, DIRECT).
idnamePromotion name at this version.
priorityInvoice-pass ordering priority at this version.
promotion_idThe promotion this version belongs to.
promotion_statusLifecycle status of the parent promotion (draft, scheduled, active, archived).
published_atWhen this version was published.
release_strategyHow this version is released: automatic (flips at effective_from) or manual.
stacking_modeStacking mode at this version (stack or exclusive).
statusVersion status in the scheduling timeline (draft, scheduled, published, archived).
valid_fromFirst moment the promotion is valid at this version.
versionVersion number within the promotion's timeline.
budget_currencyCurrency max_budget is denominated in; empty when no budget is set.
codeCoupon code at this version; set only for COUPON distribution.
descriptionInternal description at this version.
effective_fromWhen this version becomes effective on the timeline; null for unscheduled drafts.
effective_toWhen this version stops being effective (the next version's start); null for the head.
max_budget^-?\d+(\.\d+)?$MAJOR units, in budget_currency.
max_redemptionsTotal-redemptions cap at this version; null = unlimited.
published_byID of the user who published this version.
stacking_groupMutual-exclusion group at this version, if any.
valid_toLast moment the promotion is valid at this version; null = open-ended.
ProrationLedger
Booked subtotal, as a currency-tagged amount; the direction is carried by proration_type.
appliedTrue once the entry has been pulled onto an invoice line.
change_dateInstant the proration accrued into the ledger.
currencyISO 4217 currency the amount is denominated in.
descriptionHuman-readable description of what the proration covers.
idproration_typeDirection of the booked entry: CHARGE or CREDIT.
invoice_line_idInvoice line the entry was applied to; null until applied.
period_endEnd of the proration coverage window, as a UTC calendar day.
period_startStart of the proration coverage window, as a UTC calendar day.
ProrationRecord
Prorated amount, as a currency-tagged amount; the direction is carried by proration_type.
appliedTrue once the proration has been pulled onto an invoice line.
change_dateInstant the change occurred; orders multiple changes within the same day.
created_atcurrencyISO 4217 currency the amounts on this record are denominated in.
days_remainingUnused days of the period the proration was charged or credited across.
idnew_quantityItem quantity after the change that triggered this proration.
old_quantityItem quantity before the change that triggered this proration.
organization_idproration_typeDirection of the adjustment: CREDIT or CHARGE.
subscription_idThe subscription this proration belongs to.
subscription_item_idThe subscription item the proration was booked against.
Per-unit price in effect at the moment of the change, as a currency-tagged amount.
invoice_idInvoice the proration was applied to; null until applied.
period_endEnd of the coverage window the proration is computed over, as a UTC calendar day.
period_startStart of the coverage window the proration is computed over, as a UTC calendar day.
PublishImpact
plan_countplan_subscribersproduct_idproduct_subscriberssubscriptions_affectedPublishImpactPlan
plan_idplan_namecurrent_product_versionQuantityThresholdCondition
kindUnion discriminator.
max_quantityOptional inclusive upper bound; when set the summed quantity must fall within [min_quantity, max_quantity].
min_quantityInclusive lower bound the summed quantity must reach.
product_idsProducts whose subscription-item quantities are summed for the threshold check (any of these contributes).
RateTable
created_atcurrencyISO 4217 currency the entry values are denominated in when they represent money (CUR-S5).
idlifecycle_statusTable lifecycle: draft, active, or archived.
nameDisplay name of the rate table.
on_missing_keyBehaviour when no entry matches a lookup: 'error', 'zero', or 'default_value'.
organization_idrequires_continuous_coverageWhen true, published versions must leave no gap in the table's effective-date timeline.
slugURL-safe unique identifier that formula lookup()/bracket() calls reference this table by.
table_typeMatching mode: 'lookup' (exact key match) or 'bracket' (numeric range match).
updated_atdefault_valueDecimal value returned when on_missing_key=default_value and nothing matches.
deleted_atSoft-delete timestamp; null for live tables.
descriptionOptional human description of the table's purpose.
head_version_idThe currently-active rate_table_versions row that lookups resolve against by effective date.
RateTableEntry
idlookup_keyExact-match key for a lookup-table entry; null on bracket entries.
range_max^-?\d+(\.\d+)?$Exclusive upper bound of a bracket entry; the entry matches values where value < range_max. Null means unbounded above.
range_min^-?\d+(\.\d+)?$Inclusive lower bound of a bracket entry; the entry matches values where range_min <= value. Null means unbounded below.
value^-?\d+(\.\d+)?$The rate value returned on a match: a monetary amount (MAJOR units in the table's currency) or a unitless multiplier consumed by a formula reference.
RateTableVersion
created_atcurrencyISO 4217 currency inherited from the parent rate table when this version was minted (CUR-S5).
effective_fromWhen this version starts being effective on the billing timeline.
idrate_table_idThe parent rate table this version snapshots.
statusVersion lifecycle: draft, scheduled, published, or archived (the parent table's lifecycle_status is the one that uses 'active').
versionThis version's number, incrementing per publish.
archived_atWhen this version was archived; null while not archived.
effective_toWhen this version was superseded; null while it is the current version.
The rate rows in this version: exact-match lookup keys or numeric brackets.
noteOptional note describing this version's change.
published_atWhen this version was published; null while draft.
published_byThe user who published this version.
ReachablePrice
applicable_to_subscriptionTrue when the row currently matches the subscription's customer/plan scope.
currencyISO 4217 currency of the row.
interval_countNumber of interval units per billing period for the row.
interval_unitBilling interval unit (week, month, or year) of the row.
kindResolution scope of the row: BASE, PLAN_OVERRIDE, or CUSTOMER_OVERRIDE.
The row's list price.
price_idThe Price row that could apply to the subscription.
country_codeCountry the row is scoped to; null matches any country.
covered_key_countNumber of effective keys the set price covers; populated only when is_set_price.
is_set_priceMarks the row covering every effective key of the product's key set.
price_keyThe keyed variant the row covers, on a keyed product.
valid_fromCustomer-facing start of the row's applicability window.
valid_toCustomer-facing end of the row's applicability window.
why_notShort reason the row does not currently apply, when applicable_to_subscription is false.
RecordManualPaymentRequest
amount^-?\d+(\.\d+)?$MAJOR units, in the addressed invoice's currency.
currencyOptional echo-guard: must equal the invoice's currency when set.
notereceived_atreferencesourceRedeemPromotionRequest
coupon_codeCoupon code, required when the promotion's distribution is COUPON.
customer_idCustomer to redeem the promotion for; required.
subscription_idSubscription to scope the redemption to, when applicable.
RedeemWithTokenRequest
customer_idCustomer redeeming the token; must match the customer the token is locked to. Required.
subscription_idSubscription to scope the redemption to, when applicable.
tokenThe customer-locked coupon token to redeem; required.
ReferrerRow
idcreated_atcustomer_idcustomer_nameinvoice_idinvoice_numberlabelsincesub_labeltypeRefundInvoiceRequest
amount^-?\d+(\.\d+)?$Optional partial-refund amount in MAJOR units, in the addressed invoice's currency. Omit for a full refund of amount_paid.
currencyOptional echo-guard: must equal the invoice's currency when set.
reasonOptional refund classification: duplicate, fraudulent, requested_by_customer, service_issue, or other. Empty defaults to requested_by_customer.
RefundInvoiceResponse
The invoice after the refund was recorded against it.
statusOutcome of the refund request, e.g. refund_pending while the gateway settles it.
refund_idGateway-side refund identifier (e.g. re_...); empty when the refund was applied as an inline credit note rather than through the gateway.
RegenerateInvoiceResult
original_invoice_idThe existing invoice that was re-priced.
The freshly re-priced proforma preview; not persisted until the caller confirms.
subtotal_delta^-?\d+(\.\d+)?$ · requiredChange in subtotal versus the original invoice, in MAJOR units of the regenerated invoice's currency.
tax_delta^-?\d+(\.\d+)?$ · requiredChange in tax versus the original invoice, in MAJOR units of the regenerated invoice's currency.
total_delta^-?\d+(\.\d+)?$ · requiredChange in gross total versus the original invoice, in MAJOR units of the regenerated invoice's currency.
missing_product_idsProducts on the original invoice that no longer resolve to a line in the regenerated preview.
new_product_idsProducts present in the regenerated preview but not on the original invoice.
Product id to catalog version the regeneration pinned each product at.
RemoveItemRequest
effective_atWhen the item stops being billed: null closes it now, a future instant queues it at that boundary; past is rejected.
proration_modeHow the removal is credited: pro_rata or do_not_charge; defaults to pro_rata.
subscription_item_idThe subscription item to stop billing.
RepublishPlanResult
plan_idPlan this result refers to.
statusPer-plan outcome: republished or failed.
errorFailure reason when status is failed; null on success.
versionNew plan version number after a successful republish; null on failure.
RepublishPlansRequest
plan_idsPlans to republish so their latest-mode products re-snapshot at the product head; at least one, at most 100 per request.
RepublishPlansResponse
failedCount of plans that failed to republish.
republishedCount of plans that republished successfully.
Per-plan republish outcomes, one entry per requested plan.
ReserveOutcomeEventPayload
customer_idThe customer the reservation belongs to.
errorThe failure detail, when the outcome failed.
hold_idThe wallet hold the reservation is associated with.
metric_keyThe metric being metered.
occurred_atWhen the outcome was recorded (RFC3339).
organization_idoutcome_idThe reservation outcome this event records.
price_keyThe price key resolved for the reservation, when known.
product_idThe metered product being reserved against.
quantityThe reserved quantity, as a decimal string.
statusThe reservation outcome status (e.g. PENDING, CAPTURED, FAILED).
subscription_idThe subscription the reservation applies to.
usage_event_idThe usage event that captured the reservation, when captured.
workspace_idThe workspace that owns the reservation.
ReserveRequest
customer_idCustomer whose wallet the hold reserves against.
Named dimension values used to select a dimensional price tier.
external_cost_amount^-?\d+(\.\d+)?$Caller-supplied wholesale cost fed to the price formula's cost.* variables, MAJOR units; requires external_cost_currency.
external_cost_currencyISO 4217 currency of external_cost_amount; must match the price's native currency.
hold_expires_atTTL of the created hold; the wallet auto-releases it if not captured by this instant. Null uses the server default window.
idempotency_keyCaller key that collapses retries of the same reserve to one hold.
Arbitrary caller-supplied key/value annotations carried on the reserve outcome.
metric_keyMetric being consumed; must match the product's meter binding.
price_keySelects a specific price when the product exposes keyed prices; null uses the default.
Named numeric variables bound into the price formula at resolve time.
product_idMetered product being consumed; drives price resolution.
quantity^-?\d+(\.\d+)?$Number of metric units to reserve; must be greater than zero.
subscription_idSubscription the usage is charged under.
wallet_currencyPins the hold to the customer's wallet in this ISO 4217 currency; null uses their primary wallet.
ReserveResponse
can_proceedTrue when the hold was created and the caller may serve the request; false means it was blocked and no hold exists (see blocked_reasons).
expires_atWhen the created hold auto-releases if not captured; zero when blocked.
hold_idIdentifier of the hold created when can_proceed is true; zero value when the reserve was blocked.
blocked_reasonsWhen can_proceed is false, the machine-readable reasons the reserve was blocked, e.g. insufficient wallet balance, no_wallet_for_currency, wallet_currency_mismatch, unit_limit_exceeded, spend_limit_exceeded, customer is not active.
fx_rate_idFX snapshot used to convert the price; null when no conversion occurred.
Pre-tax amount of the hold after promotion discounts, {value, currency}.
Gross amount held (net plus tax), {value, currency}; null when blocked.
resolved_currencyISO 4217 currency the price resolved to and the hold is denominated in.
Tax portion of the hold, {value, currency}; null when no tax rule applied.
tax_rate^-?\d+(\.\d+)?$Tax rate applied, as a decimal fraction (0.19 = 19%).
tax_rule_idTax rule applied to the hold; lets preview/reserve/invoice reconcile to the same rule.
wallet_idWallet the hold was placed against; ties the reserve back to a specific wallet.
ResolutionPeriod
endkindstartResolveFindingRequest
notesOptional operator notes explaining why the finding was overridden/resolved.
ResolvePriceRequest
at_timePoint in time to resolve at; the cascade honours each price's valid_from/valid_to against this instant. Defaults to now.
country_codeCountry context; country-specific prices outrank generic ones.
currencyCurrency to pin the resolution to; filters the cascade to prices in this currency rather than converting.
customer_idCustomer scope; when set, CUSTOMER_OVERRIDE rows for that customer become eligible and outrank plan/base rows.
Dimension values used to match a price's custom_dimensions scope.
plan_idPlan scope; when set, plan_version is required and PLAN_OVERRIDE rows for that plan become eligible.
plan_versionThe exact plan version PLAN_OVERRIDE rows must match; required when plan_id is set.
price_keyKeyed variant to resolve on a keyed product; falls back to the set price when no exact key price exists.
Named numeric/string variables supplied to tier formulas and rate expressions during resolution.
product_idProduct whose price to resolve.
quantity^-?\d+(\.\d+)?$Quantity to price; must be positive. Drives the tier walk and formula tier_quantity binding.
subscription_idSubscription context for the resolution, when resolving for an existing sub.
ResolvedPrice
currencyISO 4217 currency of this resolved tuple.
total_amount plus tax_amount — what the customer actually pays for this line in this currency.
interval_countNumber of interval units per billing period for this tuple.
interval_unitBilling interval unit (week, month, or year) of this resolved tuple.
is_primaryTrue for the tuple matching the subscription's bound interval and currency — the row that fires when nothing else is specified.
price_idThe price row that would fire for this tuple.
Tax on total_amount for the customer's jurisdiction; zero when tax could not be determined.
Total amount for the item's quantity in this tuple's currency.
Effective per-unit amount for this tuple.
won_byWhich cascade level produced the resolution: BASE, PLAN_OVERRIDE, or CUSTOMER_OVERRIDE.
How unit_amount and total_amount were computed (tier walk, formula, FX leg); null for a flat list price.
price_keyThe keyed variant this entry resolves, on a keyed product.
RevenueBreakdownItem
countNumber of subscriptions contributing to this plan's revenue.
plan_idIdentifier of the plan this revenue is attributed to.
plan_nameDisplay name of the plan.
Revenue attributed to the plan, {value, currency}.
RevenueByCustomerTypeItem
customer_typeCustomer type this revenue is attributed to.
invoice_countNumber of invoices contributing to this segment.
Revenue from this customer type, {value, currency}.
RevenueByCustomerTypeResponse
currencyISO 4217 currency every amount is denominated in.
Per-customer-type revenue breakdown.
Total revenue across all customer types, {value, currency}.
RevenueResponse
Per-plan revenue breakdown.
currencyISO 4217 currency every amount is denominated in.
Total revenue across all plans, {value, currency}.
RevokeRedemptionRequest
revert_benefitsWhen true, additionally claws back everything the redemption delivered (invoice-ledger benefits and wallet credit grants) via a signed wallet adjustment. Destructive and not restored by a later re-join.
RevokeRedemptionResponse
The redemption after revocation.
The clawback result; present only when revert_benefits was set.
Role
assigned_countidis_default_for_new_joinersis_systemnamepermissionsdescriptionRotateAPIKeyResponse
messagenew_keyold_key_expiryScheduleFlowEdge
conditionfrom_step_idto_step_idScheduleFlowStep
attemptsconfigcreated_atflow_ididlabelmax_attemptsstatusstep_keystep_typeupdated_atactual_effective_atdeadline_atfinished_atlast_errornext_attempt_atproduced_version_idsresultscheduled_effective_atstarted_atScheduleFlowStepItem
created_atidstatusstep_idtarget_idtarget_typeupdated_atdetailfinished_atScheduleFlowStepTransition
atflow_ididstep_idto_statusactor_typeactor_user_idfrom_statusreasonScheduledChange
change_payloadchange_typecreated_atentity_identity_typeidorganization_idrelease_strategyscheduled_atstatusupdated_atcreated_bydepends_on_change_identity_version_at_schedulenotification_configprevious_statereleased_atrollback_windowrolled_back_atScheduledChangeCancelledPayload
change_idThe scheduled change that was cancelled.
entity_idThe id of the entity the change targets.
entity_typeThe kind of entity the change targets (e.g. SUBSCRIPTION, PLAN, PRODUCT).
organization_idworkspace_idThe workspace that owns the scheduled change.
ScheduledChangeCreatedPayload
change_idThe scheduled change that was created.
entity_idThe id of the entity the change targets.
entity_typeThe kind of entity the change targets (e.g. SUBSCRIPTION, PLAN, PRODUCT).
organization_idscheduled_atWhen the change is scheduled to fire (RFC3339).
workspace_idThe workspace that owns the scheduled change.
ScheduledChangeDiff
afterbeforechanged_fieldsentity_identity_typeScheduledChangeReconfirmedPayload
change_idThe scheduled change that was reconfirmed.
entity_idThe id of the entity the change targets.
entity_typeThe kind of entity the change targets (e.g. SUBSCRIPTION, PLAN, PRODUCT).
organization_idworkspace_idThe workspace that owns the scheduled change.
ScheduledChangeReleasedPayload
change_idThe scheduled change that was released.
entity_idThe id of the entity the change targets.
entity_typeThe kind of entity the change targets (e.g. SUBSCRIPTION, PLAN, PRODUCT).
immediateTrue when the change was released immediately rather than at its scheduled time.
organization_idreleased_atWhen the change was released (RFC3339).
workspace_idThe workspace that owns the scheduled change.
ScheduledChangeRolledBackPayload
change_idThe scheduled change that was rolled back.
entity_idThe id of the entity the change targets.
entity_typeThe kind of entity the change targets (e.g. SUBSCRIPTION, PLAN, PRODUCT).
organization_idrolled_back_atWhen the change was rolled back (RFC3339).
workspace_idThe workspace that owns the scheduled change.
ScheduledChangeStatus
ScheduledChangeSupersededPayload
change_idThe scheduled change that was superseded.
entity_idThe id of the entity the change targets.
entity_typeThe kind of entity the change targets (e.g. SUBSCRIPTION, PLAN, PRODUCT).
organization_idreasonWhy the change was superseded.
superseded_by_change_idThe replacing change's id when a re-schedule retargeted the entity; empty otherwise.
workspace_idThe workspace that owns the scheduled change.
ScheduledChangeUpcomingPayload
change_idThe scheduled change that is coming due.
entity_idThe id of the entity the change targets.
entity_typeThe kind of entity the change targets (e.g. SUBSCRIPTION, PLAN, PRODUCT).
organization_idscheduled_atWhen the change is scheduled to fire (RFC3339).
workspace_idThe workspace that owns the scheduled change.
ScheduledChangeView
change_payloadchange_typecreated_atentity_identity_typeidorganization_idrelease_strategyscheduled_atstatusupdated_atcreated_bydepends_on_change_idnotification_configprevious_statereleased_atrollback_windowrolled_back_atSeatPolicy
adjustablecreated_atidlink_idproduct_idupdated_atdefault_qtymax_qtymin_qtySeatPolicyInput
adjustabledefault_qtymax_qtymin_qtyproduct_idSetAllowanceRefreshRequest
refresh_countHow often the included pool refreshes, as a count of refresh_unit; both fields null clears the override.
refresh_unitUnit of the refresh cadence: day, week, month, year or billing_cycle; both fields null clears the override.
SetProductPoolRequest
credit_unit_valueMoney value of one pool unit, as a decimal string in MAJOR units; requires currency.
currencyISO 4217 currency for the money-denominated fields; required when credit_unit_value or spend_limit is set.
spend_limitMaximum pool value in money, as a decimal string in MAJOR units; requires currency, null for no spend ceiling.
unit_limitMaximum pool balance in units, as a decimal string; null for no unit ceiling.
SetVATManualOverrideRequest
expires_atOptional expiry for the override; must be in the future when set.
reasonExplanation recorded for the manual override. Required.
statusManual override outcome: "valid" or "invalid"; defaults to "valid" when omitted.
SettingsCatalogItem
categorydefaultdescriptionkeylabeltypeSettingsEnum
labelHuman-readable label shown for the option.
valueValue stored in the config when this option is chosen.
SettingsField
keyStable identifier of the config field, used as the JSON key in the stored config.
labelHuman-readable label rendered next to the input.
requiredWhether the field must be supplied for a valid config.
typeInput type: string, number, bool, select, account, or custom_field_ref.
defaultDefault value applied when the field is left unset.
groupVisual grouping the field belongs to (e.g. "Mandantendaten").
helpLonger help text explaining the field.
Selectable options; present only when type is select.
placeholderPlaceholder text shown in an empty input.
SettingsSchema
Ordered config fields the provider exposes; the settings UI renders them in order.
SettingsUpsertRequest
allow_add_payment_methodallow_cancel_subscriptionallow_invoice_payallow_wallet_topupshow_billing_settingsshow_invoicesshow_payment_methodsshow_subscriptionsshow_walletsSimulateChangesRequest
Items to add in this dry run.
Quantity restatements to price; each entry prices as one cross-quantity diff.
A version repin to price onto another plan/product version.
new_plan_idPlan to retarget the subscription onto in this dry run; null leaves the plan unchanged.
Items to remove in this dry run.
SimulateInvoice
The individual invoice lines in the simulation.
Sum of line amounts before tax.
Total tax across all lines.
Invoice total (subtotal plus tax).
SimulateInvoiceLine
Line amount before tax.
descriptionHuman-readable line description.
Tax charged on the line.
product_idProduct the line charges for, when tied to one.
SimulateRequest
billing_period_endLast day (UTC) of the billing period to simulate; must be after billing_period_start.
billing_period_startFirst day (UTC) of the billing period to simulate; required.
customer_idCustomer to simulate the invoice for; required.
promotion_idsPromotions to apply in the simulation; at least one is required.
subscription_idSubscription whose charges are simulated; required.
SimulateResponse
The difference between the two invoices — what the promotions saved.
The simulated invoice with the requested promotions applied.
The simulated invoice with no promotions applied (the baseline).
SimulateSavings
Per-product breakdown of the savings.
Reduction in subtotal from the promotions.
Reduction in tax from the promotions.
Reduction in the invoice total from the promotions.
SimulateVersionChange
strategyMoney policy to simulate; empty defaults to immediate_prorate, the only strategy that books proration in the current period.
target_latestWhen true, price a repin to the head version. Mutually exclusive with target_version.
target_versionConcrete version to price a repin to; null uses target_latest. Mutually exclusive with target_latest.
SimulationLineItem
Priced impact of the change, as a currency-tagged amount.
descriptionHuman-readable description of the change this line prices.
Tax charged on this line, as a currency-tagged amount.
tax_rate^-?\d+(\.\d+)?$ · requiredTax rate applied to this line, as a decimal fraction (e.g. 0.19 = 19%).
typeDirection of the line: CHARGE or CREDIT.
days_remainingUnused days of the period the proration was computed across.
new_quantityItem quantity after this change (0 for a remove).
old_quantityItem quantity before this change (0 for an add).
subscription_item_idItem this line targets; null for an add, whose row does not exist yet.
SimulationResult
Total charges produced by the change set, as a currency-tagged amount.
Total credits produced by the change set, as a currency-tagged amount.
currencyISO 4217 currency every amount in this result is denominated in.
Per-change priced breakdown.
Net of charges minus credits before tax, as a currency-tagged amount.
Total tax across all lines, as a currency-tagged amount.
Gross total (net impact plus tax), as a currency-tagged amount.
period_endEnd of the proration window every line was priced across (RFC-3339): the subscription's current period.
period_startStart of the proration window every line was priced across (RFC-3339): the subscription's current period.
StateTransitionedPayload
entity_idThe id of the entity that changed state.
entity_typeThe kind of entity that changed state (e.g. SUBSCRIPTION, INVOICE).
from_statusThe status before the transition; empty on initial state.
metadataFree-form transition metadata; shape varies by entity type.
organization_idreasonWhy the transition occurred, when recorded.
to_statusThe status after the transition.
transitioned_atWhen the transition occurred (RFC3339).
version_idThe entity version the transition applies to, when versioned.
workspace_idThe workspace that owns the entity.
StepSpec
configStep-type-specific configuration; decoded and validated by the step's executor at author-time, activation, and fire time.
deadline_atOptional hard deadline after which the step is failed if still unfinished.
keyAuthor-assigned unique key for the step, referenced by edges.
labelHuman-readable label shown in the editor and monitor.
max_attemptsMax execution attempts before the step fails permanently; 0 uses the step type's default.
scheduled_effective_atOptional effective instant applied to the changes the step produces.
typeStep type selecting the executor that runs it.
Subscription
allowed_transitionsStatus values the subscription may legally transition to from its current status.
auto_renewWhether the subscription renews automatically at period end; false lets it expire when the current period closes.
billing_anchor_dayDay of the month (1-28) each billing period starts on.
billing_interval_countNumber of interval units per billing cycle (e.g. 3 with unit=month bills quarterly).
billing_interval_unitUnit of the billing cycle length: week, month or year.
created_atcurrencyISO 4217 currency every money field on this subscription is denominated in.
customer_idThe customer this subscription bills.
idorganization_idstarted_atInstant the subscription first transitioned to ACTIVE; zero while still DRAFT.
statusLifecycle status: DRAFT, ACTIVE, CANCELLED or EXPIRED.
updated_atPromotions currently applied to this subscription.
Annual recurring revenue for this subscription, as a currency-tagged amount; null when not computed.
billing_timingWhen invoices fire relative to the period: in_advance (at period start) or in_arrears (at period end).
cancellation_reasonWhy the subscription reached CANCELLED: USER_REQUEST, AUTO_NON_RENEWAL or DUNNING_TERMINAL.
cancelled_atInstant the subscription was cancelled; null unless cancelled.
current_period_endEnd of the current billing period, as a UTC calendar day.
current_period_startStart of the current billing period, as a UTC calendar day.
current_phase_idID of the currently ACTIVE phase; null when the subscription has no active phase.
Values for the org's configured custom fields on this subscription.
deleted_atSoft-delete timestamp; null for live subscriptions.
descriptionInternal operator-facing description; not shown to buyers.
Version-drift summary; populated only when the List endpoint is called with ?include=drift.
The billable product lines on this subscription.
Arbitrary caller-supplied key/value pairs.
Monthly recurring revenue for this subscription, as a currency-tagged amount; null when not computed.
nameInternal operator-facing subscription name.
next_billing_dateInstant the next invoice is expected; null once the subscription is cancelled.
payment_terms_daysNet payment window in days for this subscription's invoices; null inherits the org default.
pending_checkout_session_idProvider checkout session that will activate an on_checkout_complete DRAFT; null otherwise.
Ordered chain of billing-mode phases (setup/trial/standard/paused/dunning); exactly one is ACTIVE at a time.
plan_idPlan this subscription is based on; null for a product-direct subscription (plan-or-product XOR).
plan_versionPinned plan version the subscription currently bills under; null for product-direct subscriptions.
product_idProduct this subscription bills directly; null for a plan-based subscription (plan-or-product XOR).
product_versionPinned product version the subscription currently bills under; null for plan-based subscriptions.
public_descriptionBuyer-facing description shown in checkout and the customer portal.
Per-subscription billing setting overrides; unset keys inherit from customer, then org, then default.
start_atScheduled activation instant; set only when start_trigger is start_date.
start_triggerWhat activates a DRAFT subscription: immediate, on_checkout_complete, manual or start_date.
Operator-assigned tags on the subscription.
Locale-keyed overrides for name, description and public_description.
version_change_strategyMoney policy applied when an auto-upgrade fires: immediate_prorate, next_period or at_phase_change.
version_track_modeHow the subscription follows plan/product versions: pinned (stay put) or latest (auto-upgrade to head).
SubscriptionActivatedPayload
activated_atWhen the subscription became active (RFC3339).
customer_idThe customer the subscription belongs to.
organization_idsubscription_idThe subscription that was activated.
workspace_idThe workspace that owns the subscription.
SubscriptionAddOn
added_atcreated_atidorganization_idproduct_idquantitysubscription_idupdated_atremoved_atSubscriptionCancelledPayload
cancelled_atWhen the subscription was cancelled (RFC3339).
customer_idThe customer the subscription belongs to.
organization_idreasonWhy the subscription was cancelled (e.g. USER_REQUEST, AUTO_NON_RENEWAL, DUNNING_TERMINAL).
subscription_idThe subscription that was cancelled.
workspace_idThe workspace that owns the subscription.
SubscriptionCreatedPayload
billing_interval_countThe number of interval units per billing cycle.
billing_interval_unitThe unit of the billing interval (e.g. MONTH, DAY).
billing_periodThe billing period label (e.g. MONTHLY, ANNUAL).
created_atcustomer_idThe customer the subscription belongs to.
organization_idplan_idThe plan the subscription is on.
plan_versionThe plan version the subscription was created against.
statusThe subscription status at creation.
subscription_idThe subscription that was created.
workspace_idThe workspace that owns the subscription.
SubscriptionDrift
current_versionlatest_versionsub_idtrack_modeversions_behindlatest_published_atlatest_scheduled_atplan_idproduct_idSubscriptionDriftSummary
latest_versionLatest published version number of the subscription's plan or product.
versions_behindHow many versions behind the latest the subscription's pinned version is.
SubscriptionDunningEnteredPayload
customer_idThe customer the subscription belongs to.
invoice_idThe unpaid invoice that triggered dunning, when known.
organization_idstageThe dunning stage on entry (always WARNED).
subscription_idThe subscription that entered dunning.
timestampWhen dunning was entered (RFC3339).
workspace_idThe workspace that owns the subscription.
SubscriptionDunningStageChangedPayload
customer_idThe customer the subscription belongs to.
new_stageThe dunning stage after the change (e.g. GRACED, SUSPENDED).
organization_idprevious_stageThe dunning stage before the change.
subscription_idThe subscription whose dunning stage changed.
timestampWhen the stage changed (RFC3339).
workspace_idThe workspace that owns the subscription.
SubscriptionItem
created_ateffective_fromStart of the temporal window this row is billable for.
idorganization_idoverride_appliedTrue when a customer-specific price override is in effect for this item.
pricing_modelPricing model applied to this item: VOLUME, STAIRCASE or PACKAGE.
product_idThe product this item bills.
product_nameDisplay name of the product, denormalized for the items table.
quantityNumber of units billed for this item (e.g. seat count).
subscription_idThe subscription this item belongs to.
Resolved price for the full quantity, as a currency-tagged amount.
Resolved price for one unit, as a currency-tagged amount.
updated_atcurrent_term_endEnd of the item's current commitment term; null when the item has no explicit term.
current_term_startStart of the item's current commitment term; null when the item has no explicit term.
effective_toEnd of the billable window; null means open-ended / currently billable.
override_idID of the applied price override; null when no override applies.
override_sourceScope of the applied override: PHASE (phase-scoped), CUSTOMER (customer-scoped), or empty when none.
price_keyKey-set entry this item bills under; set only for keyed products.
product_version_idProduct version this item is pinned to; null follows the product head version.
quantity_adjustableTrue when the buyer picks the quantity (per-seat); false is a flat fee.
quantity_sourceWhere the billed quantity comes from: DECLARED (set on the item) or METERED (from the meter evaluator).
renewal_anchor_atAnchor instant the renewal scheduler advances the item's term from; null when the item has no explicit term.
term_auto_renewWhether the item's committed term auto-renews at term end; null follows the subscription cadence.
term_countNumber of term units the item is committed for; null follows the subscription cadence.
term_unitCommitment term unit (week/month/year); null means the item follows the subscription cadence.
unit_labelSingular noun one billed unit is called (e.g. seat, GB).
SubscriptionItemAddedPayload
added_atWhen the item was added (RFC3339).
customer_idThe customer the subscription belongs to.
organization_idproduct_idThe product added to the subscription.
quantityThe quantity of the added item.
subscription_idThe subscription the item was added to.
workspace_idThe workspace that owns the subscription.
SubscriptionItemInput
auto_renewWhether the committed term auto-renews at term end; null inherits the interval default, false is a one-shot purchase. Only meaningful with a term.
price_keyKey-set entry to bill under; set only for keyed products.
product_idProduct this item bills.
product_version_idProduct version to pin the item to; null follows the product head version.
quantityNumber of units to bill (e.g. seat count).
term_countNumber of term units the item is committed for; set together with term_unit.
term_unitCommitment term unit (week/month/year); set together with term_count, or leave both nil to follow the subscription cadence.
SubscriptionItemRemovedPayload
customer_idThe customer the subscription belongs to.
organization_idproduct_idThe product removed from the subscription.
removed_atWhen the item was removed (RFC3339).
subscription_idThe subscription the item was removed from.
workspace_idThe workspace that owns the subscription.
SubscriptionPausedPayload
customer_idThe customer the subscription belongs to.
organization_idpaused_atWhen the subscription was paused (RFC3339).
subscription_idThe subscription that was paused.
workspace_idThe workspace that owns the subscription.
SubscriptionPaymentFailedPayload
customer_idThe customer the subscription belongs to.
invoice_idThe invoice whose payment failed.
organization_idsubscription_idThe subscription whose payment failed.
timestampWhen the payment failed (RFC3339).
workspace_idThe workspace that owns the subscription.
SubscriptionPhase
auto_transitionWhether reaching this phase's end automatically starts the next pending phase.
created_atidorganization_idphase_kindBilling mode the subscription operates under during this phase: setup, trial, standard, paused or dunning.
phase_orderPosition of this phase in the subscription's phase chain; phases run in ascending order.
started_atInstant this phase became ACTIVE.
statusPhase lifecycle status: PENDING, ACTIVE, COMPLETED or SKIPPED.
subscription_idThe subscription this phase belongs to.
completed_atInstant the phase completed; null while pending or active.
dunning_stageDunning progression stage (WARNED, GRACED, SUSPENDED); populated only for a dunning phase.
dunning_stage_atInstant the current dunning stage was entered; populated only for a dunning phase.
duration_unitUnit of duration_value: day, week, month or billing_cycle; set only for a duration end policy.
duration_valueLength of the phase in duration_unit units; set only for a duration end policy.
end_atAbsolute instant the phase ends; set only for a date end policy.
end_kindEnd policy: manual (operator ends it), duration (ends after a span) or date (ends at end_at).
ends_atDerived instant the phase ends; mirrors end_at for a date policy or is computed from the duration.
SubscriptionPlanChangedPayload
changed_atWhen the plan change took effect (RFC3339).
new_plan_idThe plan the subscription moved to.
organization_idproration_modeHow the plan change was prorated.
subscription_idThe subscription whose plan changed.
workspace_idThe workspace that owns the subscription.
SubscriptionPlanCondition
kindUnion discriminator.
plan_idsPlan IDs the customer must be subscribed to; matching any one plan passes the condition.
SubscriptionPlanVersionHistoryRow
change_reasonWhy the version pin changed at effective_from.
created_ateffective_fromStart of the window this version pin was in effect.
idsubscription_idThe subscription this history row belongs to.
effective_toEnd of the window this version pin was in effect; null for the currently open window.
plan_idPlan pinned during this window; null for a product-based subscription.
plan_versionPlan version pinned during this window; null for a product-based subscription.
product_idProduct pinned during this window; null for a plan-based subscription.
product_versionProduct version pinned during this window; null for a plan-based subscription.
SubscriptionQuantityChangedPayload
changed_atWhen the quantity change took effect (RFC3339).
customer_idThe customer the subscription belongs to.
organization_idsubscription_idThe subscription whose quantity changed.
workspace_idThe workspace that owns the subscription.
SubscriptionRecoveredPayload
customer_idThe customer the subscription belongs to.
invoice_idThe invoice whose payment cleared the recovery.
organization_idrecovered_fromThe dunning stage the subscription recovered from.
subscription_idThe subscription that recovered from dunning.
timestampWhen the subscription recovered (RFC3339).
workspace_idThe workspace that owns the subscription.
SubscriptionRefundRequiredPayload
The refund amount, as a money object, when computed.
currencyThe refund currency, ISO-4217, when set.
customer_idThe customer the subscription belongs to.
days_remainingDays remaining in the period used to prorate the refund.
idempotency_keyThe key that de-duplicates the downstream refund action.
new_quantityThe quantity after the change that prompted the refund.
old_quantityThe quantity before the change that prompted the refund.
organization_idperiod_endThe end of the billing period the refund covers (RFC3339).
period_startThe start of the billing period the refund covers (RFC3339).
product_idThe product the refund relates to, when item-scoped.
proration_record_idThe proration record backing the refund amount, when applicable.
reasonWhy a refund is required.
requested_atWhen the refund was requested (RFC3339).
subscription_idThe subscription a refund is required for.
subscription_item_idThe subscription item the refund relates to, when item-scoped.
workspace_idThe workspace that owns the subscription.
SubscriptionResumedPayload
customer_idThe customer the subscription belongs to.
organization_idresumed_atWhen the subscription was resumed (RFC3339).
subscription_idThe subscription that was resumed.
workspace_idThe workspace that owns the subscription.
SubscriptionSettings
auto_finalize_invoicesdefault_proration_modeline_groupingprice_resolution_policysend_payment_reminderstax_inclusiveSubscriptionTargetSelector
countriesISO-2 country codes matched against the customer billing-address country (case-insensitive).
customer_tags_anyThe owning customer must carry AT LEAST ONE of these tag ids.
customer_typesFilter by customer type (BUSINESS/CONSUMER/UNKNOWN).
explicit_idsSubscription ids that always match, unioned with the filter dimensions.
statusesFilter by subscription status (DRAFT/ACTIVE/CANCELLED/EXPIRED).
sub_tags_allThe subscription must carry ALL of these tag ids.
version_track_modesFilter by version-track mode (pinned/latest); AND-ed with the other dimensions.
Summary
allowed_ipscreated_atidkey_prefixkey_typescopesstatusworkspace_idexpires_atlast_used_atlast_used_ipnameTag
created_atentity_typeEntity kind this tag applies to: CUSTOMER, SUBSCRIPTION, PRODUCT, PLAN, INVOICE, or CREDIT_NOTE.
idnameDisplay name of the tag, unique per (organization, entity_type).
organization_idupdated_atarchived_atWhen the tag was archived and hidden from pickers; null while active.
colorOptional display color as a #RRGGBB hex string.
deleted_atWhen the tag was soft-deleted; null unless deleted.
descriptionOptional free-text description of the tag's purpose.
usage_countNumber of entities currently carrying this tag; populated only on list endpoints that request counts.
TagRef
idIdentifier of the referenced tag.
nameDisplay name of the referenced tag.
TaxRule
apply_ordercreated_atidinclusiveis_compoundis_expiredjurisdiction_countryorganization_idrate^-?\d+(\.\d+)?$ · requiredDecimal number encoded as a string to preserve precision.
requires_continuous_coveragestatustax_typeupdated_atvalid_fromversionapplies_to_customer_typesapplies_to_product_categoriesapplies_to_supply_typesarchived_atjurisdiction_regionpublished_atpublished_byvalid_toTemplateDocument
Ordered content blocks rendered top to bottom on the document body.
Logo and company-name branding for the document.
Document footer text and page-number toggle.
Blocks repeated at the bottom of every page.
Blocks repeated at the top of every page.
schema_versionTemplate document schema version; the current version is 2.
Colors, fonts, margins, page size, and locale for rendering.
Theme
accent_colorAccent color as a hex string.
background_colorPage background color as a hex string.
currency_codeSample ISO 4217 currency used when rendering a preview; live documents use the invoice's own currency.
font_familyFont family name used for the document text.
font_sizeBase font size in points (pt).
line_heightLine height as a multiple of the font size.
localeLocale used to format numbers and dates on the document (e.g. en, de).
margin_bottomBottom page margin in millimeters (mm).
margin_leftLeft page margin in millimeters (mm).
margin_rightRight page margin in millimeters (mm).
margin_topTop page margin in millimeters (mm).
monochrome_on_printWhen true, the document renders in grayscale for printing.
page_orientationPage orientation: portrait or landscape (defaults to portrait).
page_sizePage size: A4, A5, LETTER, or LEGAL (defaults to A4).
primary_colorPrimary brand color as a hex string (e.g. #1A2B3C).
secondary_colorSecondary color as a hex string.
text_colorBody text color as a hex string.
Threshold
What to do when the threshold is breached.
comparatorHow the meter's evaluated value is compared against value: gt, gte, lt, lte, or eq.
nameHuman label for this alert condition.
value^-?\d+(\.\d+)?$Target the meter's evaluation result is compared against to detect a breach.
ThresholdAction
event_typeDomain event type to emit; required when kind is emit_event.
kindWhat the monitor does on a breach: webhook, slack, or emit_event.
targetDestination for the action: the webhook URL or Slack channel.
TopupRequest
descriptionOptional note recorded on the top-up grant.
product_idProduct whose allowance pool to top up.
quantity^-?\d+(\.\d+)?$Allowance quantity to top up (metered units, NOT money).
TopupResponse
PURCHASED grant created for a durable-POOL top-up; null on the REFRESHING path.
Promotion behind a REFRESHING-product top-up; null on the durable-POOL path.
Redemption of the promotion behind a REFRESHING-product top-up; null on the durable-POOL path.
Transaction
directionidkindoccurred_atraw_idsourcestatuscustomer_idinvoice_idreferencesubscription_idsummarywallet_idTransferRequest
Transfer amount as {value, currency}. currency must equal the SOURCE (path) wallet's currency; the target leg converts via the org's FX rate when currencies differ.
reasonOptional free-text explanation stored on both ledger legs of the transfer.
target_wallet_idWallet that receives the transfer; must belong to the same organization as the source wallet.
TransferResult
Ledger entry crediting the target wallet.
Ledger entry debiting the source wallet.
transfer_idShared identifier linking the debit and credit legs of this transfer.
Amount credited to the target after FX conversion, {value, currency}; null when both wallets share a currency.
FX snapshot that produced the conversion rate; null for a same-currency transfer.
TransitionPhaseRequest
forceWhen true, transition to the next phase even if the current phase's end conditions are not yet met.
UpcomingPrice
currencyISO 4217 currency of the scheduled row.
interval_countNumber of interval units per billing period for the scheduled row.
interval_unitBilling interval unit (week, month, or year) of the scheduled row.
The per-unit amount that takes effect at valid_from.
price_idThe scheduled price row.
scopeWhen the change lands: this_period (inside the resolution window) or next_period (start of the next window).
valid_fromWhen the scheduled change takes effect.
price_keyThe keyed variant the scheduled row covers, on a keyed product.
UpdateCostRequest
Replacement static money value; set at most one of amount or expression.
descriptionNew operator-facing description; null leaves it unchanged.
effective_atSchedule the change to take effect at this instant instead of applying immediately; mutually exclusive with save_as_draft.
Replacement formula referencing other costs by key; set at most one of amount or expression.
Free-form operator key/value metadata.
requires_continuous_coverageFlips the continuous-coverage requirement live without touching the billing value; null leaves it unchanged.
save_as_draftPersist the change as a working draft instead of applying it; mutually exclusive with effective_at.
Locale-keyed overrides for the cost's description.
UpdateCustomFieldDefinitionRequest
auditabledefault_valuedescriptiondisplay_nameexpected_versionfield_groupshow_in_tablesort_orderstatusvisibilitywrite_accessUpdateCustomerRequest
auto_validate_vatPer-request hint: null = auto-validate VAT after update when eligible, false = skip the auto-trigger. Still gated by the workspace and per-customer VAT disable flags.
Replacement billing address; omit to leave unchanged.
Replacement custom-field values; omit to leave unchanged.
customer_typeNew buyer classification: BUSINESS, CONSUMER, or UNKNOWN; omit to leave unchanged.
Default auto-topup amount as {value, currency}, MAJOR units. Currency should match preferred_currency.
default_auto_topup_enabledNew auto-top-up default for wallets seeded from this customer; omit to leave unchanged.
Default wallet credit limit as {value, currency}, MAJOR units. Currency should match preferred_currency.
Default low-balance threshold as {value, currency}, MAJOR units. Currency should match preferred_currency.
Default wallet max balance as {value, currency}, MAJOR units. Currency should match preferred_currency.
Default wallet max single-credit as {value, currency}, MAJOR units. Currency should match preferred_currency.
disabled_providersReplacement list of disabled payment provider ids; omit to leave unchanged, empty array to clear.
einvoice_emailNew e-invoice delivery email; empty string clears it and falls back to email.
emailNew primary contact email; omit to leave unchanged, cannot be set empty.
external_idNew caller-assigned external identifier; omit to leave unchanged.
localeNew locale (one of en, de, fr, es, it, pt, nl, ja); omit to leave unchanged.
Replacement free-form key/value metadata; omit to leave unchanged.
nameNew display / legal name; omit to leave unchanged, cannot be set empty.
payment_terms_daysNew net payment terms in days (0-365); omit to leave unchanged.
peppol_idNew Peppol participant identifier (scheme:value); empty string clears it.
prefer_einvoiceNew per-customer e-invoicing switch; omit to leave unchanged.
preferred_currencyNew ISO 4217 billing currency; must be allowed by the workspace billing-currency policy.
preferred_providerNew preferred payment provider id; empty string clears it. Must be a known provider and must not appear in disabled_providers.
statusNew lifecycle status: active, suspended, or churned; omit to leave unchanged.
Replacement tax identifiers keyed by scheme; omit to leave unchanged.
vat_validation_disabledWhen true, disables automatic VAT-ID validation; requires vat_validation_disabled_reason.
vat_validation_disabled_reasonReason recorded when vat_validation_disabled is true; required in that case.
UpdateFXOverrideRequest
clear_reasonSet true to remove the stored reason.
clear_valid_toSet true to make the override open-ended (clears valid_to).
rateSwitch to manual-rate mode with this rate (clears snapshot_date).
reasonNew free-text note; omitted leaves it unchanged. Use clear_reason to remove it.
snapshot_dateSwitch to snapshot-pin mode with this date (clears rate).
valid_fromNew activation start; omitted leaves it unchanged.
valid_toNew activation end; omitted leaves it unchanged. Use clear_valid_to to make it open-ended.
UpdateFlowRequest
descriptionOptional longer description of what the flow does.
Dependency edges between steps (the DAG arcs).
expected_versionOptimistic-lock token: the lock_version the client last read; a stale value or a non-draft flow 409s.
failure_policyHow the flow reacts to a step failure; defaults to continue_independent.
nameOperator-facing name of the flow.
priorityScheduling priority; higher-priority flows are advanced first when several are due.
The flow's step nodes (the DAG vertices).
target_bindingWhen bulk-step targets are resolved — snapshot at activation or live at fire time; defaults to snapshot_at_activate.
trigger_localWall-clock local time the flow should fire, paired with trigger_tz; both nil means run immediately on activation.
trigger_tzIANA timezone for trigger_local (e.g. Europe/Berlin); must be set together with it.
UpdateInvoiceLineRequest
currencyOptional echo-guard: must equal the invoice's currency when set.
descriptionNew line description; omit to leave unchanged, must be non-empty when provided.
Arbitrary caller-supplied key/value pairs; replaces the existing metadata when provided.
period_endNew end of the service period this line covers; omit to leave unchanged. Must be on or after period_start.
period_startNew start of the service period this line covers; omit to leave unchanged.
quantity^-?\d+(\.\d+)?$New billed quantity; omit to leave unchanged. Must be positive.
tax_rate^-?\d+(\.\d+)?$New tax rate as a fraction between 0 and 1 (0.19 = 19%); omit to leave unchanged.
unit_price^-?\d+(\.\d+)?$MAJOR units, in the addressed invoice's currency.
UpdateInvoiceRequest
billing_period_endNew end of the service period; omit to leave unchanged, or send null to clear it. Must be on or after billing_period_start.
billing_period_startNew start of the service period; omit to leave unchanged, or send null to clear it.
due_dateNew payment due date; omit to leave unchanged, or send null to clear it.
localeNew rendering locale (en, de, fr, es, it, pt, nl, ja); omit to leave unchanged.
Arbitrary caller-supplied key/value pairs; replaces the existing metadata when provided.
UpdateInvoiceTemplateRequest
expected_versionOptimistic-concurrency token: the version you last read. REQUIRED on this resource; a stale value answers 409 CONFLICT.
descriptionNew description; omit to leave unchanged.
document_typesNew set of renderable document types; omit to leave unchanged.
nameNew template name; omit to leave unchanged.
statusNew status (e.g. active, archived); omit to leave unchanged.
Replacement template document; omit to leave unchanged.
UpdateKeySetRequest
descriptionNew description; omit to leave unchanged.
nameNew display name; omit to leave unchanged.
UpdateMeterRequest
New derived-meter formula; omitted leaves it unchanged.
dedup_key_pathNew dedup JSON-path; omitted leaves it unchanged.
dimensionsNew group-by dimension fields; omitted leaves them unchanged.
event_schemaNew event JSON-Schema; omitted leaves it unchanged.
New event predicate tree; omitted leaves it unchanged.
functionNew aggregation function; omitted leaves it unchanged.
late_event_policyNew late-event policy; omitted leaves it unchanged.
nameNew human-readable label; omitted leaves it unchanged.
negative_allowedNew negative-value setting; omitted leaves it unchanged.
New alert thresholds; omitted leaves them unchanged.
unique_by_fieldNew distinct-count event field; omitted leaves it unchanged.
unit_currency_fieldNew unit-currency event field; omitted leaves it unchanged.
unit_labelNew unit display label; omitted leaves it unchanged.
value_fieldNew aggregated event field; omitted leaves it unchanged.
New aggregation window; omitted leaves it unchanged.
UpdateOrgSecuritySettingsRequest
allowed_email_domainsallowed_idpsjit_default_rolejit_enabledrequire_mfasession_timeout_secondsUpdateOrgTaxProfileRequest
legal_nameoss_countrytax_numbertax_regimevat_idUpdateOrganizationRequest
billing_emailbusiness_addressdefault_countrydefault_currencydefault_date_formatdefault_first_day_of_weekdefault_languagedefault_localedefault_number_formatdefault_timezonelegal_namenamephonesales_audiencesupport_emailtax_inclusivetax_registration_numbervat_id_collectionUpdatePaymentGatewayConfigRequest
Provider-specific credential document. Stripe: api_key (required), stripe_account_id, webhook_secret, api_base. GoCardless: access_token, webhook_secret. PATCH merges shallowly - send only the keys to change; omitted keys keep their stored value (so a masked read never needs to be resent).
display_nameis_defaultis_enabledmodesupported_currenciessupported_methodsUpdatePaymentMethodRequest
is_defaultWhen true, promote this method to the customer's default; omit to leave unchanged.
Replacement free-form key/value metadata; omit to leave unchanged.
providerNew payment provider; omit to leave unchanged.
provider_idNew provider-side identifier; omit to leave unchanged.
statusNew lifecycle status: active, expired, or removed; omit to leave unchanged.
UpdatePhaseRequest
auto_transitionNew auto-transition flag; null leaves it unchanged.
duration_unitNew unit of duration_value (day/week/month/billing_cycle); used with a duration end policy.
duration_valueNew phase length in duration_unit units; used with a duration end policy.
end_atNew absolute end instant; used with a date end policy.
end_kindNew end policy (manual/duration/date); empty leaves it unchanged.
UpdatePlanProductRequest
product_track_modeNew version-tracking mode for the membership: latest (auto-follow the product head) or pinned; required (the only mutable field on this path).
UpdatePlanRequest
Org-defined custom field values for this plan.
descriptionNew internal description; null leaves it unchanged.
effective_atSchedule the versioned change to take effect at this instant instead of publishing immediately; mutually exclusive with save_as_draft.
expected_versionOptimistic-concurrency token: send the version you last read and a stale value answers 409 CONFLICT. Omitted: the update applies unconditionally (last write wins).
external_idNew external identifier; null leaves it unchanged.
Free-form operator key/value metadata.
nameNew internal plan name; null leaves it unchanged.
Per-product overrides of which product version each attached product is pinned to on this publish (product_id to product_version_id); products omitted from the map snap at the product's current head.
public_descriptionNew buyer-facing description; null leaves it unchanged.
save_as_draftPersist the change as a working draft instead of publishing it; mutually exclusive with effective_at.
statusNew catalog lifecycle status (draft, scheduled, active, archived); null leaves it unchanged.
Locale-keyed overrides for name, description and public_description.
UpdatePriceFormulaRequest
expressionNew expression; omit to leave unchanged.
nameNew display name; omit to leave unchanged.
save_as_draftWhen true, parks the new expression/variables in a draft version without advancing the live head; billing is unaffected until it is published.
Replacement variable declarations; omit to leave unchanged.
UpdatePriceRequest
country_codeCountry scope to set on the price; omit to leave unchanged.
currencyISO 4217 currency to change the price to; omit to keep the existing currency.
Arbitrary dimension key/values that further scope the price.
display_nameCustomer-facing label for this price / price_key.
list_price^-?\d+(\.\d+)?$List price, MAJOR units, in the price's currency (the currency field when set, else the price's existing currency).
Free-form key/value metadata to attach to the price.
Replacement tier ladder; null carries the previous version's tiers forward, an empty array clears them.
UpdateProductMeterBindingRequest
Replacement overlay filter tree; null leaves it unchanged.
pricing_var_nameNew formula variable name; null leaves it unchanged.
roleNew binding role (BILLABLE_QUANTITY, PRICING_VAR or INFORMATIONAL); null leaves it unchanged.
UpdateProductRequest
Org-defined custom field values for this product.
descriptionNew internal description; null leaves it unchanged.
effective_atSchedule the versioned change to take effect at this instant instead of publishing immediately; mutually exclusive with save_as_draft.
expected_versionOptimistic-concurrency token: send the version you last read and a stale value answers 409 CONFLICT. Omitted: the update applies unconditionally (last write wins).
external_idNew external identifier; null leaves it unchanged.
invoiceable_standaloneFlips the manual-invoice picker eligibility; null leaves it unchanged.
key_set_excluded_keysReplacement excluded-keys list; null leaves it unchanged, non-null replaces the list.
key_set_idLinks or clears the product's key set; changing it once the product has keyed prices or items is rejected.
Free-form operator key/value metadata.
nameNew internal product name; null leaves it unchanged.
pricing_modelNew pricing model (VOLUME, STAIRCASE, PACKAGE); null leaves it unchanged.
public_descriptionNew buyer-facing description; null leaves it unchanged.
quantity_adjustableFlips whether the buyer picks the quantity; null leaves it unchanged, and setting true on a METERED product is rejected.
requires_product_idsReplacement product-dependency set for this product.
save_as_draftPersist the change as a working draft instead of publishing it; mutually exclusive with effective_at.
statusNew catalog lifecycle status (draft, scheduled, active, archived); null leaves it unchanged.
tax_categoryNew tax category (DEFAULT, REDUCED, ZERO, EXEMPT); null leaves it unchanged.
Locale-keyed overrides for name, description and public_description.
unit_labelNew singular unit label; null leaves it unchanged. quantity_source itself is immutable post-create.
UpdatePromotionRequest
application_timingNew application timing (NEXT_CYCLE, RETROACTIVE, IMMEDIATE); omit to leave unchanged.
archetypeFrontend-only preset hint; not persisted as rule logic.
New targeting set; a full replacement of the live audience when set (no version bump).
budget_behaviorNew over-budget behavior (SKIP or PARTIAL); omit to leave unchanged.
budget_currencyISO 4217 currency the budget is denominated in; required (on the merged state) when max_budget is set.
codeNew coupon code; only valid when distribution is COUPON (biconditional enforced on the merged state).
descriptionNew internal description; omit to leave unchanged.
distributionNew distribution axis (AUTO_APPLY, AUTO_ENROLL, COUPON, DIRECT); omit to leave unchanged.
effective_atADR-0006 control: schedule this edit to publish as a new version at the given time. Mutually exclusive with save_as_draft.
effectsSingle-phase shorthand effects; full replacement of the rule when set. Mutually exclusive with phases.
Single-phase shorthand eligibility set; full replacement of the rule when set. Mutually exclusive with phases.
evaluation_scopeNew evaluation scope (invoice, subscription, usage_event, reserve); omit to leave unchanged.
expected_versionOptimistic-concurrency token: send the version you last read and a stale value answers 409 CONFLICT. Omitted: the update applies unconditionally (last write wins).
max_budget^-?\d+(\.\d+)?$MAJOR units, denominated in budget_currency.
max_redemptionsNew total-redemptions cap; omit to leave unchanged.
max_redemptions_per_customerNew per-customer redemptions cap; omit to leave unchanged.
nameNew operator-facing name; omit to leave unchanged.
Phased-ladder rule; full replacement when set. Mutually exclusive with eligibility/effects.
priorityNew invoice-pass ordering priority; omit to leave unchanged.
public_descriptionNew customer-facing description; omit to leave unchanged.
save_as_draftADR-0006 control: save the edit as a draft version instead of publishing. Mutually exclusive with effective_at.
stacking_groupNew mutual-exclusion group; an empty string clears the group, omission leaves it unchanged.
stacking_modeNew stacking mode (stack or exclusive); omit to leave unchanged.
Localized overrides for customer-facing text, keyed by locale.
valid_fromNew first valid calendar day (UTC); omit to leave unchanged.
valid_toNew last valid calendar day (UTC), inclusive; omit to leave unchanged.
UpdateProviderSettingsRequest
disabled_providersReplacement list of payment provider ids that must not be used to charge this customer; omit to leave unchanged, empty array to clear.
preferred_providerNew preferred payment provider id tried first when charging; empty string clears it, omit to leave unchanged. Must be a known provider and must not appear in disabled_providers.
UpdateRateTableRequest
default_valueNew default value; omit to leave unchanged.
descriptionNew description; omit to leave unchanged.
effective_atPublish timestamp for this edit; mutually exclusive with save_as_draft.
nameNew display name; omit to leave unchanged.
on_missing_keyNew missing-key behaviour ('error', 'zero', or 'default_value'); omit to leave unchanged.
requires_continuous_coverageNew continuous-coverage requirement; omit to leave unchanged.
save_as_draftWhen true, parks the edit in a draft version instead of publishing it; mutually exclusive with effective_at.
UpdateScheduledChangeRequest
change_payloadReplacement change body applied by the release hook at fire time; validated only for non-emptiness at authoring.
Replacement free-form metadata map.
notification_configReplacement notification configuration.
release_strategyNew release strategy: AUTOMATIC or MANUAL.
rollback_windowReplacement Postgres interval string bounding the post-release rollback window.
scheduled_atNew release time; must be in the future.
UpdateSubscriptionItemRequest
effective_atWhen the quantity change takes effect: null applies now, a future instant schedules it; ignored when new_quantity is absent.
new_quantityRestated quantity, prorated over the rest of the period; omit to leave the quantity unchanged.
Version pin to apply (a null product_version_id unpins to head); omit to leave the pin untouched.
UpdateSubscriptionItemResponse
Proration records the change produced; empty for a version-pin-only update.
The updated subscription.
UpdateSubscriptionRequest
billing_timingNew invoice timing (in_advance/in_arrears); editable only while DRAFT, null leaves it unchanged.
clear_settingsSetting keys to reset back to inherit (NULL the column); use to clear an override that Settings alone cannot.
Values for the org's configured custom fields.
descriptionNew internal operator-facing description; null leaves it unchanged.
Arbitrary caller-supplied key/value pairs; replaces the stored map.
nameNew internal operator-facing name; null leaves it unchanged.
public_descriptionNew buyer-facing description; null leaves it unchanged.
Per-subscription billing setting overrides to set or change; null leaves them unchanged.
Locale-keyed overrides for name, description and public_description.
version_change_strategyNew default money policy for auto-upgrades; null leaves it unchanged.
version_track_modeNew version-track mode (pinned/latest); null leaves it unchanged.
UpdateTagRequest
archivedSet true to archive the tag or false to restore it; omitted leaves it unchanged.
colorNew display color as #RRGGBB; omitted leaves it unchanged.
descriptionNew description; omitted leaves it unchanged.
nameNew display name; omitted leaves it unchanged.
UpdateTaxRuleRequest
applies_to_customer_typesapplies_to_product_categoriesapplies_to_supply_typesapply_ordereffective_atinclusiveis_compoundjurisdiction_countryjurisdiction_regionrate^-?\d+(\.\d+)?$Decimal number encoded as a string to preserve precision.
requires_continuous_coveragesave_as_draftstatustax_typevalid_fromvalid_toUpdateUserPreferencesRequest
currencydate_formatfirst_day_of_weeklanguagelocalenumber_formatthemetimezoneUpdateVerificationStatusRequest
statusNew verification status: one of pending, verified, expired, failed, manual, or maintenance. Required, and must be a permitted transition from the current status.
UpdateWalletSettingsRequest
auto_topup_amount^-?\d+(\.\d+)?$MAJOR units, in the wallet's currency.
auto_topup_enabledWhether the wallet auto-tops-up when it drops below low_balance_threshold.
auto_topup_payment_method_idPayment method charged for auto-topups.
credit_limit^-?\d+(\.\d+)?$MAJOR units, in the wallet's currency.
currencyOptional echo-guard: must equal the wallet's currency when set.
low_balance_threshold^-?\d+(\.\d+)?$MAJOR units, in the wallet's currency.
max_balance^-?\d+(\.\d+)?$MAJOR units, in the wallet's currency.
max_single_credit^-?\d+(\.\d+)?$MAJOR units, in the wallet's currency.
UpdateWebhookEndpointRequest
clear_secretdescriptionevent_typessecret_idstatusurlUpdateWorkspaceCurrencyRequest
billing_enabledNew billing-enabled setting; omitted leaves it unchanged. At least one of the two fields must be supplied.
catalog_enabledNew catalog-enabled setting; omitted leaves it unchanged. At least one of the two fields must be supplied.
UpsertEntriesRequest
The keys to upsert; each existing key is overwritten and new keys are added.
UpsertIntegrationRequest
configProvider-specific configuration, validated against the provider's settings schema before it is stored.
display_nameHuman-readable name; omitted defaults to the provider's own display name.
is_enabledWhether the integration is active and exports may run against it.
UsageAggregateResponse
bucketgroup_bymetricseriessinceuntilUsageCreditsEffect
kindUnion discriminator.
product_idMetered product the usage credits apply to.
quantity^-?\d+(\.\d+)?$Number of usage units granted as credit.
UsageEvent
customer_idCustomer that consumed the metric.
ididempotency_keyKey that dedupes replays of the same event.
ingested_atServer-side instant the event was accepted; distinct from timestamp.
metric_keyMetric this event records usage for.
organization_idproduct_idMetered product the event is billed under.
quantity^-?\d+(\.\d+)?$ · requiredNumber of metric units this event records.
subscription_idSubscription the usage is charged against.
timestampWhen the usage occurred (when the unit was consumed).
Named dimension values used to select the price tier.
external_cost_amount^-?\d+(\.\d+)?$Caller-supplied wholesale cost (COGS) fed to cost-plus price formulas, MAJOR units.
external_cost_currencyISO 4217 currency of external_cost_amount.
Arbitrary caller-supplied key/value annotations on the event.
price_keyPrice key selected for keyed products; null uses the default price.
Named numeric variables bound into the price formula at finalize time.
wallet_currencyISO 4217 currency pinning the event to a specific wallet at finalize; null uses the customer's preferred-currency cascade.
UsageSummary
entity_identity_typetotal_referrersversionlatest_invoice_reflifecycleUsageThresholdCondition
kindUnion discriminator.
max_usage^-?\d+(\.\d+)?$Optional inclusive upper bound; when set the summed usage must fall within [min_usage, max_usage].
min_usage^-?\d+(\.\d+)?$Inclusive lower bound the summed usage quantity must reach.
product_idsProducts whose usage in the evaluation window is summed for the threshold check (any of these contributes).
UserPreferences
created_atupdated_atuser_idcurrencydate_formatfirst_day_of_weeklanguagelocalenumber_formatthemetimezoneUserProfileResponse
emailidnamepicturerolestatusValidatePromotionRequest
coupon_codeCoupon code to include coupon-gated promotions in the eligibility check.
customer_idCustomer to check promotion eligibility for; required.
invoice_subtotalDecimal string, MAJOR units. Currency is the evaluated customer/subscription context's currency.
subscription_idSubscription context to evaluate against, when applicable.
ValidateResult
Promotions the customer currently qualifies for.
Promotions the customer does not currently qualify for, with reasons.
ValidationRules
max_lengthmax_valuemin_lengthmin_valueregex_messageregex_patternrequiredunique_per_orgVersionHeader
created_atentity_ididorganization_idrelease_strategystatusversionarchived_reasonbatch_idbatch_labelcancelled_atdepends_on_version_ideffective_fromeffective_topublished_atpublished_byVersionRow
created_ateffective_fromeffective_toidpublished_atstatusversionarchived_reasoncreated_byusage_countVersionWarning
fieldraised_attypecurrent_valueraised_byscheduled_valueVoidInvoiceResponse
Credit note issued to reverse a finalized invoice; null when the invoice was voided before finalization and no reversal was needed.
The invoice after being voided (status void).
Wallet
auto_topup_enabledWhether the wallet automatically tops up when its balance drops below low_balance_threshold.
Real money the customer paid in (top-ups, payments, refunds), {value, currency}; spent only after promotional_balance is exhausted.
created_atcurrencyISO 4217 currency this wallet is denominated in; a wallet holds exactly one currency.
customer_idCustomer this wallet belongs to; there is one wallet per (customer, currency).
Funds reserved by pending holds, {value, currency}; not spendable. Available = cash_balance + promotional_balance − held_balance.
idis_primaryTrue for the customer's default wallet, used by flows that do not pin a specific currency.
modePREPAID wallets only spend available funds; POSTPAID wallets may run negative up to credit_limit.
organization_idGranted credit (promotions, goodwill), {value, currency}; spent before cash_balance and may expire.
updated_atAmount charged on each auto-topup.
How far a POSTPAID wallet may go negative. Null = no credit extended.
Balance at which a low-balance event (and auto-topup, if enabled) fires.
Cap on total balance (cash + promotional); credits that would exceed it are rejected. Null = no cap.
Largest amount a single credit may add. Null = no per-credit cap.
Arbitrary caller-supplied key/value annotations on the wallet.
promotional_balance_expires_atWhen the promotional balance expires and is forfeited; null means it never expires.
WalletApplyToInvoicePayload
The amount due to be settled from the wallet, as a money object.
currencyThe invoice currency, ISO-4217.
customer_idThe customer billed on the invoice.
finalized_atWhen the invoice was finalized and wallet application requested (RFC3339).
invoice_idThe invoice wallet funds were applied to.
organization_idsubscription_idThe subscription that drove the invoice, when subscription-billed.
workspace_idThe workspace that owns the invoice.
WalletAutoTopupTriggeredPayload
balanceThe wallet balance that tripped the threshold, MAJOR units in the wallet's currency, as a decimal string.
customer_idThe customer who owns the wallet.
thresholdThe configured low-balance threshold, MAJOR units in the wallet's currency, as a decimal string.
topup_amountThe configured top-up amount, MAJOR units in the wallet's currency, as a decimal string, when set.
wallet_idThe wallet whose auto top-up triggered.
WalletCreditEffect
kindUnion discriminator.
amount^-?\d+(\.\d+)?$Wallet credit granted at redeem time (MAJOR units, in currency).
currencyISO 4217 currency of the granted wallet credit.
WalletHold
Amount reserved by this hold, {value, currency}; excluded from the wallet's available balance while PENDING.
created_atcurrencyISO 4217 currency of the held amount; matches the wallet's currency.
expires_atWhen the wallet auto-releases the hold if it has not been captured.
idorganization_idreasonFree-text explanation of what the hold reserves for.
statusLifecycle state: PENDING, CAPTURED, VOIDED, or EXPIRED.
wallet_idWallet whose available balance this hold reserves against.
Amount actually captured when the hold settled, {value, currency}; null until capture and may be less than amount on a partial capture.
captured_atWhen the hold was captured; null while PENDING or if voided/expired.
metric_keyMetric key of the usage stream this hold reserves capacity for; null for non-subscription holds.
Promotions that reduced this hold's amount up-front; consumed once at capture for budget accounting.
reference_idIdentifier of the record this hold reserves against; paired with reference_type.
reference_typeType of the record this hold reserves against; paired with reference_id.
resolved_atWhen the hold reached a terminal state (captured, voided, or expired); null while PENDING.
reverse_chargeTrue when the captured amount is subject to VAT reverse-charge.
subscription_idSubscription whose usage stream this hold reserves capacity for; null for non-subscription holds like deposits.
tax_rate^-?\d+(\.\d+)?$Tax rate applied at capture, as a decimal fraction (0.19 = 19%).
tax_rule_idTax rule applied when this hold is captured; null for untaxed holds.
voided_atWhen the hold was voided; null unless status is VOIDED.
WalletHoldExpiredPayload
amountThe held amount released on expiry, MAJOR units in the wallet's currency, as a decimal string.
hold_idThe wallet hold that expired.
organization_idreasonWhy the hold was originally placed.
wallet_idThe wallet the hold was placed on.
workspace_idThe workspace that owns the wallet.
WalletModeSnapshot
cash_balanceThe cash balance, MAJOR units in the wallet's currency, as a decimal string.
credit_limitThe credit limit, MAJOR units in the wallet's currency, as a decimal string, when set.
currencyThe wallet currency, ISO-4217.
held_balanceThe held (reserved) balance, MAJOR units in the wallet's currency, as a decimal string.
promotional_balanceThe promotional-credit balance, MAJOR units in the wallet's currency, as a decimal string.
wallet_idThe wallet this snapshot describes.
WalletPaymentSkippedPayload
The amount that could not be settled from the wallet, as a money object.
currencyThe invoice currency, ISO-4217.
customer_idThe customer billed on the invoice.
invoice_idThe invoice whose wallet payment was skipped.
organization_idreasonWhy wallet payment was skipped (e.g. no_wallet, insufficient_funds, currency_mismatch).
skipped_atWhen wallet payment was skipped (RFC3339).
subscription_idThe subscription that drove the invoice, when subscription-billed.
workspace_idThe workspace that owns the invoice.
WalletTopupRequest
modehosted_checkout (default) or off_session
payment_method_idRequired for mode=off_session
WalletTopupResponse
modeclient_secretdecline_codefailure_codefailure_messagenext_actionpayment_intent_idsession_idstateurlWalletTransaction
Amount moved by this entry, {value, currency}; positive for CREDIT/DEBIT, signed for ADJUSTMENT.
Wallet total balance (cash + promotional) immediately after this entry, {value, currency}.
created_atidorganization_idsourceWhat originated the entry: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER.
typeCREDIT adds funds, DEBIT removes them, ADJUSTMENT applies a signed correction.
wallet_idWallet this ledger entry belongs to.
created_byUser who initiated the entry; null for system-generated entries.
reasonFree-text explanation shown in the ledger.
referenceCaller-supplied external reference tying the entry to its originating record.
reverse_chargeTrue when the entry is subject to VAT reverse-charge.
Tax portion of the entry, {value, currency}.
tax_rate^-?\d+(\.\d+)?$Tax rate applied, as a decimal fraction (0.19 = 19%).
tax_rule_idTax rule applied to this entry; null for untaxed movements.
WalletTransactionSource
WalletTransferredPayload
amountThe debited amount, MAJOR units in source_currency, as a decimal string.
converted_amountThe credited amount, MAJOR units in target_currency, as a decimal string.
exchange_rateThe FX rate applied, as a decimal string, when cross-currency.
exchange_rate_idThe exchange-rate record used for cross-currency conversion, when applicable.
source_currencyThe source wallet's currency, ISO-4217.
source_wallet_idThe wallet funds were debited from.
target_currencyThe target wallet's currency, ISO-4217.
target_wallet_idThe wallet funds were credited to.
transfer_idThe transfer this event records.
WebhookDelivery
attemptscreated_atendpoint_idevent_typeididempotency_keymax_attemptsorganization_idpayloadstatusupdated_atlast_errornext_retry_atWebhookEndpoint
created_atevent_typesidorganization_idstatusupdated_aturldescriptionsecret_idWebhookSecret
created_atentity_identity_typeidkey_prefixorganization_idsigning_methodupdated_atdescriptionWorkingDraft
created_atdraft_version_idversionWorkspace
created_atidmodenameorganization_idslugstatusupdated_atactive_test_clock_idWorkspaceCurrency
billing_enabledWhether customers can be billed and invoiced in this currency.
catalog_enabledWhether prices and costs can be authored in this currency.
created_atcurrency_codeISO 4217 currency code (uppercase) enabled in the workspace.
updated_atworkspace_idWorkspace this currency is enabled for.
Counts of records already using this currency; populated when checking whether it can be disabled.