AcknowledgeCreditNoteInputBody
acknowledged_atWhen the proof came into your possession (not when it was recorded here).
kindWhat the proof is. The closed set the Autoridade Tributária admits (Ofício-Circulado 33129/1993, confirmed in AT ruling 23501/2023): a written communication from the customer referring to the IVA correction, a signed or stamped copy of the note, an EDI acknowledgement, or proof the buyer was refunded the tax. A bare read receipt is NOT among them.
evidenceA reference to the proof itself: a message id, a document reference, a note of where the signed copy is filed. The artefact lives outside this system; this is the pointer an inspection follows.
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's benefit stops applying to the subscription. Null means no per-redemption expiry is set — NOT that the promotion is open-ended: one carrying valid_to still ends when that date passes.
AddInvoiceLineRequest
descriptionLine description; required unless product_id is set, in which case the product name is used.
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.
legal_basis_codeLegal-basis code for the overridden tax category (e.g. EU_AE_ART196, EXEMPT_ART132, SMALL_BUSINESS_DOMESTIC). Optional; derived from tax_category_code when omitted.
line_typeManual line type: EXPENSE_PASSTHROUGH, MILESTONE, ADJUSTMENT, or CREDIT; defaults to ADD_ON when omitted. CREDIT reduces the invoice total: supply a positive amount, it is stored negative.
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
product_idProduct to add as a billable item.
quantityNumber of units to bill for the new item; must be at least 1.
charge_span_countHow many charge_span_unit the single up-front charge covers. Set together with charge_span_unit.
charge_span_unitUnit of the span one up-front charge for this line covers (week/month/year). Set with charge_span_count to bill the whole span once at the start; leave both null to bill the line every billing period.
price_keyKey-set entry to bill under; set only for keyed products.
proration_modeHow the mid-period addition is charged: pro_rata, pay_in_full or do_not_charge. Omit to inherit the subscription's settings.default_proration_mode, which itself falls back to pro_rata.
AddProductRequest
product_idProduct to attach to the plan.
default_quantityQuantity a new subscription seeds for this product when the caller passes no explicit item; omit to seed 1.
included_quantity^-?\d+(\.\d+)?$Quantity bundled into the base price before per-unit billing applies (the included allowance/seat floor); null means none.
max_quantityHighest quantity a buyer may pick for this product; omit for no plan-level ceiling.
min_quantityLowest quantity a buyer may pick for this product; omit for 1.
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.
unit_limit^-?\d+(\.\d+)?$Ceiling on a POOL's unit balance; POOL only.
AdjustRequest
amount^-?\d+(\.\d+)?$ · requiredSigned adjustment, MAJOR units, in the addressed wallet's currency.
sourceWhat originates the adjustment: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER.
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.
AgingBand
amountOpen amount in this band, in the response currency.
bandAging band: current, 1-30, 31-60, 61-90, 90+ (days past due).
invoice_countHow many invoices are in this band.
shareThis band's fraction of the total, 0-1. Absent bands are zero.
AgingResponse
as_ofThe instant the report describes. Bands are aged against THIS date, not against today.
Always all five bands, in aging order, zero-filled. A missing band is indistinguishable from an empty one, so they are all present.
currencytotalTotal open receivable across all bands.
AgreementTermEndedPayload
action_at_term_endThe end-of-term action that was applied: RENEW, RENEW_ONCE, CONTINUE_WITHOUT_TERM, SWITCH_PLAN, CANCEL or RENEGOTIATE.
action_summaryOne operator-facing sentence describing what the action did.
agreement_idThe agreement whose term ended.
ends_atWhen the agreed term ran out (RFC3339).
occurred_atWhen the term end was processed (RFC3339).
organization_idstarts_atWhen the agreed term began (RFC3339).
subscription_changedWhether the action changed the subscription. False for the actions that deliberately touch nothing, so 'nothing happened' is distinguishable from 'nothing was recorded'.
subscription_idThe subscription the agreement governed.
source_quote_idThe offer that promised the agreement; set when it came from a quote.
workspace_idThe workspace that owns the subscription.
AgreementTermEndingSoonPayload
action_at_term_endWhat will happen when the term runs out: RENEW, RENEW_ONCE, CONTINUE_WITHOUT_TERM, SWITCH_PLAN, CANCEL or RENEGOTIATE.
agreement_idcustomer_iddays_remainingWhole days between the announcement and ends_at.
ends_atWhen the agreed term runs out (RFC3339).
occurred_atorganization_idsubscription_idterm_countHow many term_units the agreement ran for.
term_end_reminder_daysThe notice period the agreement asked for.
term_unitUnit of the agreed term: week, month or year.
source_quote_idsuccessor_plan_idThe plan the subscription will move to; set when the action is SWITCH_PLAN.
workspace_idAgreementTermStartedPayload
action_at_term_endWhat will happen when the term runs out: RENEW, RENEW_ONCE, CONTINUE_WITHOUT_TERM, SWITCH_PLAN, CANCEL or RENEGOTIATE.
agreement_idThe agreement whose term came into force.
ends_atWhen the agreed term runs out (RFC3339).
occurred_atWhen the term was put into force (RFC3339). The instant the Change resolved to, not the moment the tick reached it.
organization_idstarts_atWhen the agreed term begins (RFC3339).
subscription_idThe subscription the agreement governs.
source_quote_idThe offer that promised the agreement; set when it came from a quote.
workspace_idThe workspace that owns the subscription.
AllowanceIncludedQuantityChangedPayload
changed_atWhen the change was applied (RFC3339).
organization_idproduct_idThe product whose included quantity changed.
sourceProvenance after the change: OPERATOR for a deliberate override, PLAN after a reset.
subscription_idThe subscription whose allowance changed.
included_quantityThe included quantity now in effect, as a decimal string; omitted when the reset left no plan pin to copy.
previous_quantityThe included quantity before this change, as a decimal string; omitted when there was none.
workspace_idThe workspace that owns the subscription.
AllowanceRefreshChangedPayload
changed_atWhen the change was applied (RFC3339).
organization_idproduct_idThe product whose refresh cadence changed.
subscription_idThe subscription whose refresh cadence changed.
refresh_countHow often the included pool refreshes, as a count of refresh_unit; null means the override was cleared.
refresh_unitUnit of the refresh cadence (day, week, month, year, billing_cycle); empty means the override was cleared.
workspace_idThe workspace that owns the subscription.
AllowanceRolledOverPayload
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.
expires_atWhen the rolled-over allowance expires (RFC3339), when capped.
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+)?$ · requiredAmount of the up-front reduction, MAJOR units in the hold's currency.
promotion_idPromotion that reduced this hold up-front.
ApplyCreditNoteRequest
amount^-?\d+(\.\d+)?$ · requiredMAJOR units, in the addressed credit note's currency.
invoice_idInvoice to apply the credit against, or refund from (required).
currencyOptional echo-guard: must equal the credit note's currency when set.
ApprovalPending
already_pendingTrue when a request for this subject was already waiting: the call raised nothing new and the id is the existing request's. A double-clicked button lands here, which is a no-op rather than a conflict — the partial unique index on (organization, checkpoint, subject) settles it in the database.
approval_request_idThe parked approval request. Poll GET /v1/approvals/{id} for its outcome, or watch the approvals queue.
checkpoint_idThe checkpoint that parked the operation (for example invoice.refund, wallet.adjust, quote.send).
stateAlways approval_pending. The operation has NOT been carried out: no money moved, no ledger row was written, no document was sent, and none of it will happen unless a person approves the request.
subject_idThe record the request is about — the invoice, wallet or quote named in the path. Unchanged by this call.
ApprovalRequestApprovedPayload
checkpoint_idThe checkpoint that parked the operation.
decided_byThe person who approved. Never a machine: an API key cannot decide.
entity_idThe id of the subject that was approved.
entity_typeThe kind of subject that was approved.
organization_idThe organization the request belongs to.
request_idThe approval request that was approved.
self_approval_overrideTrue when the approver was the requester, permitted only by the break-glass permission approval.self_decide. Such a decision always carries a comment — the API refuses one without.
commentThe approver's own words. Optional on approve — REQUIRED when self_approval_override is true.
initiated_byThe person who raised the request. Present so a subscriber can check self_approval_override against the two ids rather than trusting the flag alone.
workspace_idThe workspace that owns the approval request.
ApprovalRequestCancelledPayload
cancelled_byThe person who withdrew the request.
checkpoint_idThe checkpoint that parked the operation.
entity_idThe id of the subject whose request was cancelled.
entity_typeThe kind of subject whose request was cancelled.
organization_idThe organization the request belongs to.
request_idThe approval request that was cancelled.
commentTheir own words, if they gave any.
workspace_idThe workspace that owns the approval request.
ApprovalRequestCreatedPayload
checkpoint_idThe checkpoint that parked the operation (quote.send, invoice.refund, wallet.adjust, schedule_flow.gate).
entity_idThe id of the subject awaiting approval.
entity_typeThe kind of subject awaiting approval (QUOTE, REFUND, WALLET_ADJUSTMENT, SCHEDULE_FLOW_STEP).
organization_idThe organization the request belongs to.
request_idThe approval request that was created.
expires_atRFC 3339 deadline. Absent when the checkpoint holds without a deadline of its own.
The data the headline is rendered with — customer names, amounts, dates, ids. Never translated: a name is a name in every language.
headline_keyMessage key for the one line describing what needs deciding, as the approver sees it. A dotted path into the dashboard's message catalogue; render it in your own copy or ignore it and use headline_args.
initiated_byThe operator whose action was parked. Empty only for a flow gate the reconciler healed back into existence.
workspace_idThe workspace that owns the approval request.
ApprovalRequestExpiredPayload
checkpoint_idThe checkpoint that parked the operation.
entity_idThe id of the subject whose request expired.
entity_typeThe kind of subject whose request expired.
expired_atRFC 3339 instant the request was resolved EXPIRED.
organization_idThe organization the request belongs to.
request_idThe approval request that expired undecided.
workspace_idThe workspace that owns the approval request.
ApprovalRequestRejectedPayload
checkpoint_idThe checkpoint that parked the operation.
commentWhy it was rejected. Always present: a rejection with no reason is refused at the API.
decided_byThe person who rejected.
entity_idThe id of the subject that was rejected.
entity_typeThe kind of subject that was rejected.
organization_idThe organization the request belongs to.
request_idThe approval request that was rejected.
self_approval_overrideTrue when the decider was the requester, permitted only by the break-glass permission approval.self_decide.
initiated_byThe person who raised the request. Present so a subscriber can check self_approval_override against the two ids rather than trusting the flag alone.
workspace_idThe workspace that owns the approval request.
AttachIDPRequest
aliasprovider_iddisplay_nameenabledhide_on_loginAudience
content_hashHash of the canonical rule document. Two definitions that select the same population share it, so re-typing "de" as "DE" or reordering the values inside a rule is correctly recognised as no change.
created_atWhen the audience was created.
The saved rule set: either match_all, or a root rule group. Never both, and never neither.
idAudience UUID.
nameOperator-facing name. Unique within the workspace.
organization_idOwning organization.
owned_by_promotionTrue when any promotion points at this audience, including a deleted one. Distinguishes an operator's saved preset from the row migration 309 created for a promotion's own targeting.
purposesWhich surfaces may point at this audience. Never empty. "email" is both mail tiers, "schedule" is a scheduled change's scope, "rollout" is the e-invoice rollout target, "documents" is a document-template block gated on the recipient (visible_when.audience_id) — those four are ENFORCED on the write. "promotion" is a PICKER FILTER AND NOT A GUARD: a promotion copies an audience's rules client-side and never sends an audience id, so no server-side write knows which library audience was copied.
revisionBumped on every rule write whose canonical content hash actually moved. A rename never bumps it, and neither does a rules write that changes nothing — the broadcast re-fire confirm compares (revision, count), so a spurious bump would refuse a send for a population that never moved.
updated_atWhen the audience was last written, by either a rename or a rules write.
used_by_countHow many live promotions point at this audience. Populated on the list; always 0 on a single read, where /usage is the answer.
workspace_idOwning workspace. An audience is workspace-scoped, so a sandbox audience and a live one never see each other.
descriptionWhat this population is for. Optional.
AudienceCountsResponse
mailableMatched, narrowed to customers who could receive email at all (active status, non-empty address). This is the population the fan-out pages, and the number to confirm against.
matchedCustomers the audience rules select. This is the number promotion enrolment is governed by: a suspended customer with no mailbox is still a member.
sendableMailable, narrowed by the per-recipient send gates: the address is not suppressed and marketing consent allows it. It deliberately ignores the org-wide switches above, so a paused organization still sees the size of what unpausing would reach.
AudienceMatch
customer_idcustomer_typeemailnamecountryredemption_statusAudienceMember
customer_idCustomer UUID.
customer_typeBUSINESS / CONSUMER / ...
emailCustomer email address.
nameCustomer display name.
countryBilling-address country, upper-cased. Absent when the customer has no billing country on file.
AudienceMembershipResponse
audience_idThe audience that answered.
audience_revisionWHICH revision of the rules answered. The server reads the definition itself, so this is the audience as it is NOW — not as the client last saw it. Log it beside the answer: "audience 3f2a… revision 7 said no" survives the next edit of that audience and "the audience said no" does not.
customer_foundWhether the customer id names a live customer this organization can see. False ⇒ member is null.
memberTRUE inside the audience, FALSE outside it, NULL when the customer id names no live customer of this organization. Null is NOT false: render it as unknown. A soft-deleted customer is null, never false, because the audience predicate excludes deleted rows and would otherwise report a deletion as an exclusion.
AudiencePreviewCounts
mailableMatched, narrowed to customers who could receive email at all (active status, non-empty address). Null when this deployment has no mail layer wired to contribute the condition — null means NOT MEASURED HERE, never zero and never "same as matched".
matchedCustomers the audience rules select. This is the number promotion enrolment is governed by: a suspended customer with no mailbox is still a member of the audience.
sendableMailable, narrowed by the per-recipient send gates (not suppressed, marketing consent allows it). Always null on this endpoint: those joins belong to the mail layer and the consent arm needs a bound template's own-similar-products attestation, which a library preview has none of.
AudiencePreviewResponse
all_customerstotalAudienceRefResponse
idAudience UUID. Empty when the promotion points at no saved audience.
nameThe audience's operator-facing name.
revisionThe revision the counts were taken at. Echo it back as expected_audience_revision; any edit to the rules bumps it and refuses the confirmation.
AudienceReference
kindWhat kind of thing holds the reference. "promotion" is promotions.audience_id; "mail" is an email narrowed to this audience, either one kind of email or the workspace-wide default; "change" is a scheduled change whose scope is this audience and which has not run yet; "setting" is a setting whose value is this audience id, today only the e-invoice rollout target.
nameThe referencing row's operator-facing name. Empty for kind=mail, whose wording the client owns, and empty when this deployment cannot resolve promotion names.
idThe referencing row's UUID. Present for kind=promotion and kind=change.
keyFor kind=mail: the anchor key of the email narrowed to this audience, e.g. "invoice.finalized"; ABSENT means the workspace-wide email audience on /mail/defaults, which narrows every kind at once. For kind=setting: the setting key, e.g. "einvoice_rollout_audience_id".
AudienceRevision
audience_idThe audience this revision belongs to.
content_hashCanonical content hash at this revision.
created_atWhen this revision was written.
What the rules said at this revision, as stored — unmarshalled from the revision document and never re-derived from the live rule rows.
revisionRevision number. Revision 1 is the definition the audience was created with.
created_byWho wrote it. Absent for a migration or a background job, which have no signed-in principal to record.
AudienceRulesPreviewRequest
The rule set to count and sample. Taken by VALUE and not by id, so the builder can preview unsaved editor state.
limitHow many matching customers to sample. Default 25. The counts are exact regardless of this bound — it caps the sample, never the arithmetic.
AudienceRulesPreviewResponse
The matched/mailable/sendable ladder, taken in one statement so the rungs cannot disagree with each other.
A bounded sample of matching customers, ordered by customer id. It samples the MATCHED population — the top rung — so the sample and the headline number describe the same set.
AudienceUsageResponse
Everything currently pointing at this audience. Empty means the audience can be deleted.
BatchIngestRequest
Usage events to ingest in one call; 1-1000 per batch, one external_cost_currency per (subscription, metric) group.
BillingAddress
citycountryline1postal_codeline2stateBillingMilestone
created_atidis_overduenameOperator-facing milestone name.
organization_idpercentage^-?\d+(\.\d+)?$ · requiredFraction of the resolved price this milestone bills, as a decimal in (0,1] (e.g. 0.25 = 25%). NOT money.
positionThe row's place in its plan, from 0. Meaningless for a milestone with no plan.
product_idThe product whose resolved price the milestone bills a fraction of.
statusMilestone status: PENDING, INVOICED or CANCELLED.
subscription_idThe subscription this milestone bills against.
trigger_typeWhat fires the milestone: MANUAL (operator triggers) or DATE (fires on trigger_date).
updated_atcancel_reasonWhy the milestone was cancelled, as the operator wrote it.
cancelled_atInstant the milestone was cancelled; null unless status is CANCELLED.
descriptionOptional operator-facing description of the milestone.
invoice_idInvoice generated when the milestone fired; null while pending.
Arbitrary caller-supplied key/value pairs.
plan_idThe milestone plan this row belongs to; absent for a standalone milestone.
titleThe milestone's title as shown in the plan editor. Written together with name.
trigger_dateDate a DATE-trigger milestone fires; null for a MANUAL milestone.
triggered_atInstant the milestone was triggered and invoiced; null while pending.
workspace_idOwning workspace (RLS scope); read from the milestone row for scheduler-driven triggers.
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).
Breakdown
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.
BreakdownResponse
dimensionlabelmetricreductionHow each slice's window became one number. A FLOW is summed; a STOCK is the level at the end and is never summed across buckets.
series_kindDescending by value, with the folded 'Other' tail last regardless of size — a residual sitting mid-list reads as a real category.
totalunitBreakdownSlice
is_otherTrue for the folded tail of a top_n request, so it can be rendered differently rather than string-matched.
seriesshareFraction of total, 0..1. Computed at read time, never stored — a share cannot be re-aggregated, and both value and total are on the wire so any subset can be recomputed.
valueDecimal string.
BroadcastRefirePreviewResponse
already_sent_are_excludedAlways true. A re-fire cannot deliver a second copy to a customer who was already sent this broadcast; only recipients who were blocked or never sent can receive one.
The saved audience the counts were taken against, at the revision they were taken at. Empty unless targeting is "audience" — a promotion open to everyone has no audience row and therefore no id and no revision.
binding_enabledFalse when no enabled promotion.activated template is bound to this promotion, in which case the fan-out would reach nobody.
Matched, mailable and sendable, counted in one statement so the three cannot disagree with each other.
mail_service_enabledFalse when email is switched off for the organization.
promotional_pausedTrue when promotional email is paused. A re-fire queued now would wait for the unpause, so it is refused instead.
recipientsHow many mailable customers the promotion's audience currently matches — the same number as counts.mailable, kept as its own field because it is the one that must be sent back as expected_recipients to confirm.
targetingWho the broadcast is addressed to. "everyone": the promotion carries no targeting, so it reaches every mailable customer. "audience": a saved audience, reported under audience. "unresolvable": the promotion is narrowed to an audience that has been deleted — the broadcast stops rather than widening to everyone. "entity_gone": the promotion itself no longer exists.
would_sendTrue only when every gate passes and the audience is not empty. This is the field a confirm button should key off.
BroadcastRefireRequest
expected_audience_revisionThe audience.revision returned by the dry run. Echo it back exactly: any edit to the audience rules bumps it, so a re-fire confirmed against the old revision is refused even when the count is unchanged. Send 0 when targeting is "everyone" — a match-all promotion has no audience row and the dry run reports no revision.
expected_recipientsThe recipients count returned by the dry run. Required. Re-counted server-side; any difference refuses the request rather than sending to a population nobody reviewed.
reasonWhy the broadcast is being re-fired. Required, and recorded on the durable event.
expected_audience_idThe audience.id returned by the dry run. Echo it back when targeting is "audience": a re-fire is refused if the promotion has been re-pointed at a different audience since, which the revision alone cannot detect. Omit when targeting is "everyone" — a match-all promotion has no audience row.
BroadcastRefireResponse
enqueuedTrue when the fan-out was enqueued. The send itself is asynchronous.
The freshly counted preview the confirmation was checked against.
BulkEnrollResponse
cap_reachedenrolledfailedrequestedskippedBulkUpgradeRequest
strategyMoney policy for each upgrade: immediate_prorate, next_period or at_phase_change.
subscription_idsSubscriptions to upgrade; at least one, at most 500.
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).
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.
CapabilitiesWire
charging_delay_secondsWorst-case seconds between first charge attempt and money movement. 0 for card-only.
refund_window_secondsSeconds after a charge during which a refund can still be initiated. 0 means unbounded by the provider.
requires_mandate_for_ddWhether direct debit needs a signed mandate first.
supported_method_typesMethod types an instrument can be created as here: card, plus one entry per direct-debit scheme. This is the axis routing decides on.
supports_cardsWhether card brands can be charged.
supports_countriesISO 3166-1 alpha-2 billing-address countries, upper-case.
supports_currenciesISO 4217 codes, lower-case.
supports_debitsDirect-debit schemes this provider can debit under, e.g. sepa_core, bacs.
supports_hosted_checkoutWhether the public checkout-link flow can use this provider.
supports_off_sessionWhether a saved method can be charged without the customer present.
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
new_quantityNew quantity to bill for the item; must be at least 1.
subscription_item_idThe subscription item to restate the quantity on.
ChannelRequest
channelPEPPOL, PDP, SDI, KSEF, AEAT or AT.
countryThe SELLER's country, ISO 3166-1 alpha-2. A channel is bought, paid for and credentialled by the seller, so it is keyed on the seller's country and not the buyer's.
credentials_refNAMES a secret in the secret store, for example vault://peppol/be. It is logged by the adapter and returned unmasked by this API, so it must never be the credential itself.
endpoint_urlis_enabledmodetest or live. Absent means test: the other default would have a first save send real invoices to a real authority under credentials nobody has confirmed.
participant_idparticipant_schemeThe seller's own issuing-agency code on the network (a Peppol EAS code). A pair with participant_id: state both or neither.
regionNarrows the row below the country (the Basque and Navarrese territories run TicketBAI rather than Verifactu). Empty means the whole country.
ChannelView
channelcountrycreated_atidis_enabledupdated_atcredentials_refendpoint_urllast_self_test_atlast_self_test_statusmodetest or live. Absent means test: the other default would have a first save send real invoices to a real authority under credentials nobody has confirmed.
participant_idparticipant_schemeregionChargeInvoiceResponse
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_atdeemed_supplieridmetadataorganization_idplan_idslugstatusupdated_atcurrencydefault_billing_timingdefault_payment_terms_daysdefault_preferred_providerdefault_wallet_modenamesuccess_urltax_inclusivetrial_daysvat_id_collectionCheckoutLinkCreateRequest
plan_idslugcollect_addresscollect_phonecollect_vat_idcurrencydeemed_supplierdefault_billing_timingdefault_payment_terms_daysdefault_preferred_providerdefault_wallet_modemetadatanamesuccess_urltax_inclusivetrial_daysvat_id_collectionCheckoutLinkUpdateRequest
collect_addresscollect_phonecollect_vat_idcurrencydeemed_supplierdefault_billing_timingdefault_payment_terms_daysdefault_preferred_providerdefault_wallet_modemetadatanamestatussuccess_urltax_inclusivetrial_daysvat_id_collectionChildSetDiff
addedchangedremovedClause
attachment_countTotal catalog entities that pull this clause in automatically.
Clause text keyed by locale ("en", "de", …). This is the authoritative content.
bodyREAD-ONLY projection: bodies resolved for the org's default locale, with fallback. Authoritative content is bodies.
created_atidlocalesSorted locales this clause is authored in.
nameplan_idsPlans this clause is attached to.
product_idsProducts this clause is attached to.
quote_preset_idsQuote presets this clause is attached to.
updated_atarchived_atWhen the clause was retired; null means active.
countryISO 3166-1 alpha-2 country the clause is scoped to; null means global.
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" · requires: amount, currency | |
| type = object · kind="subscription_plan" · requires: plan_ids | |
| type = object · kind="external_verification" · requires: verification_type | |
| type = object · kind="product_combination" · requires: products | |
| type = object · kind="key_combination" · requires: product_id, keys | |
| type = object · kind="quantity_threshold" · requires: product_ids, min_quantity | |
| type = object · kind="first_purchase" | |
| type = object · kind="usage_threshold" · requires: product_ids, min_usage |
amount^-?\d+(\.\d+)?$ · requiredMinimum 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.
kindUnion discriminator.
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).
multipleHow many times over this condition was satisfied; absent when the condition does not multiply.
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).
Named plans/products this condition gates on; empty when the condition names none.
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
keytypeaudiencekindrequiredversionCopyAsDraftRequest
effective_fromEffective-from timestamp for the new draft version.
effective_toOptional effective-to timestamp for the new draft version.
release_nameOptional name for the new draft version.
release_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
valid_fromFirst calendar day (UTC) the new draft is valid; required.
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_toLast calendar day (UTC) the new draft is valid, inclusive; null = open-ended.
CopyTaxRuleAsDraftRequest
valid_fromvalid_toCorrectiveInvoiceReviewRequiredPayload
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: active, or retired once a release lands whose head no longer carries the key.
updated_atStatic money value of the cost; set for amount-form costs, null when the cost is a formula.
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.
retired_atWhen the cost fell out of the catalogue at a release; null while it is still carried.
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.
CountersignRequest
consentAcceptance of the signing wording shown before the action. Must be true.
localeBCP-47 locale of the wording that was displayed. Defaults to the organisation's.
nameThe name signed under. Defaults to the name on the request.
CreateAPIKeyRequest
nameHuman-readable label for the key, shown in the dashboard list. Leading and trailing whitespace is trimmed.
scopesPermissions the key carries, e.g. "customer.read". Must name at least one scope: an empty list is NOT shorthand for all-access, and a key with no scopes can reach no endpoint. To grant broad access, pass the explicit list. GET /v1/permissions returns the catalog; every scope must also be held by the caller minting the key.
allowed_ipsIP addresses or CIDR blocks permitted to present this key. Omit or pass an empty list to leave the key unrestricted.
expires_atMoment the key stops authenticating. Omit for a non-expiring key.
key_typeKey environment: "sk_live" or "sk_test". Omit to inherit the workspace mode (sandbox workspaces mint sk_test, live workspaces mint sk_live).
CreateAPIKeyResponse
allowed_ipscreated_atidkeykey_prefixkey_typenamescopesexpires_atCreateAudienceRequest
The rule set. An empty tree is REFUSED rather than interpreted: the two targeting systems that predate this domain read an empty selector as "everyone" and as "nobody" respectively, and the difference between those readings is the entire customer base — so targeting everyone is something the operator states, with match_all.
nameOperator-facing name. Must be unique within the workspace; a taken name is refused as a field error on name, not as a bare conflict.
descriptionWhat this population is for. Optional.
purposesWhich surfaces may point at this audience. OMIT to allow all five, which is what every audience created before this field existed allows. An empty array is refused: an audience marked for nothing could not be used anywhere.
CreateBillingMilestoneRequest
nameOperator-facing milestone name; required.
percentage^-?\d+(\.\d+)?$ · requiredFraction of the resolved price to bill, as a decimal in (0,1] (e.g. 0.25 = 25%). NOT money.
product_idThe product whose resolved price a fraction is billed; required.
trigger_typeWhat fires the milestone: MANUAL (operator triggers) or DATE (fires on trigger_date).
descriptionOptional operator-facing description of the milestone.
Arbitrary caller-supplied key/value pairs.
trigger_dateDate the milestone fires; required when trigger_type is DATE.
CreateBracketEntry
range_min^-?\d+(\.\d+)?$ · requiredInclusive lower bound of the bracket; it matches values where range_min <= value.
value^-?\d+(\.\d+)?$ · requiredThe value returned when a value falls in this bracket.
range_max^-?\d+(\.\d+)?$Exclusive upper bound of the bracket; it matches values where value < range_max. Null means unbounded above.
CreateClauseRequest
Clause text keyed by locale ("en", "de", "fr", "es", "it", "pt", "nl", "ja"). At least one required.
nameClause name.
countryISO 3166-1 alpha-2 country scope; null means global.
CreateContactRequest
categoryWhat this contact receives. Required.
emailThe mailbox to add. Required.
is_primaryWhether mail for this category is addressed here. Omit to let the first contact in a category become its primary and later ones not. true takes the category over from whichever contact currently holds it.
nameOptional display name.
CreateCostRequest
keyFormula-reference key for the new cost; 1-64 chars matching [a-zA-Z0-9._-].
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.
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).
line_typeFree-form line classification, typically carried over from the credited source line.
quantity^-?\d+(\.\d+)?$ · requiredCredited quantity; must be positive.
tax_rate^-?\d+(\.\d+)?$ · requiredTax rate applied to this line, as a fraction (0.19 = 19%).
unit_price^-?\d+(\.\d+)?$ · requiredMAJOR units, in the credit note's currency (the request's currency field).
invoice_line_idSource invoice line this credits; omit for an ad-hoc credit 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.
tax_typeTax type label (e.g. VAT, GST); null when the line is untaxed.
CreateCreditNoteRequest
currencyISO 4217 currency for the note and all its lines (required).
customer_idCustomer to issue the credit note to (required).
Credit-note line items; at least one is required.
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.
fx_snapshot_base_leg_idFor a triangulated cross-pair invoice rate, the EUR→source FX snapshot it was divided by; populated by refund builders.
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.
Arbitrary caller-supplied key/value pairs.
template_idTemplate to render the note's document with; omit to inherit the org default.
CreateCustomFieldDefinitionRequest
display_nameentity_typesfield_typekeyauditabledefault_valuedescriptionfield_groupshow_in_tablesort_ordervisibilitywrite_accessCreateCustomerRequest
customer_typeBuyer classification driving tax treatment and invoicing: BUSINESS, CONSUMER, or UNKNOWN. Required.
emailPrimary contact email; the default recipient for invoices and portal links. Required.
nameCustomer's display / legal name as it appears on invoices. Required.
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.
contact_nameDisplay name for the primary billing contact - the natural person behind a company account. Defaults to the customer's own name when omitted.
Values for the organization's configured custom-field definitions.
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.
EN 16931 BG-15 DELIVER TO ADDRESS, when supplies are delivered somewhere other than the billing address; when provided, line1, city, postal_code and country are required.
delivery_location_idEN 16931 BT-71, the deliver-to location identifier (GLN or agreed site code).
delivery_party_nameEN 16931 BT-70, the deliver-to party name.
disabled_providersPayment provider ids that must not be used to charge this customer; each must be a known provider and unique.
einvoice_profileStanding per-customer e-invoice format (e.g. XRECHNUNG_3_0_UBL); omit to inherit. Must name a profile this deployment still offers - see GET /v1/e-invoicing/profiles.
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.
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's rollout audience, true/false decide outright.
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.
CreateDocumentTemplateRequest
descriptionFree-text description of the template.
nameTemplate name (required).
The template document: ordered blocks plus theme, branding, and footer.
document_typesDocument types this template can render (subset of {invoice, credit_note, quote, email}); defaults to [invoice] when omitted.
CreateExportInputBody
currencyISO 4217 code.
fromInclusive start, YYYY-MM-DD.
grainmetricMetric key, as listed by GET /analytics/metrics.
toExclusive end, YYYY-MM-DD.
dimensionOptional dimension to slice by.
timezoneIANA zone for bucket boundaries. Defaults to the organization's.
CreateFXOverrideRequest
source_currencyISO 4217 currency being converted from (normalized to uppercase).
target_currencyISO 4217 currency being converted to; must differ from source_currency.
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.
valid_fromInstant the override begins applying; null means now.
valid_toInstant the override stops applying; null means open-ended.
CreateFileRequest
categoryWhat the document is. Decides the size cap and the accepted formats.
declared_content_typeThe format you believe the file is. The server checks the file's actual bytes when you confirm the upload, and rejects a file that disagrees.
declared_sizeThe file's size in bytes. Checked against the limit for this category before the upload starts, and again against the real size afterwards.
filenameThe file's name, shown in lists.
owner_idThe owning record's UUID.
owner_kindWhat this document hangs off.
visibilityDefaults to internal. Set shared to also show the document to the customer.
CreateKeySetRequest
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}$.
descriptionOptional description of the set.
Optional keys to seed the set with in the same call; validated like UpsertEntries.
CreateLookupEntry
keyExact-match key for this lookup entry.
value^-?\d+(\.\d+)?$ · requiredThe value returned for this key: money in the table's currency or a unitless multiplier.
CreateManualInvoiceRequest
customer_idCustomer to bill (required).
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.
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
functionAggregation applied over the window: SUM, COUNT, MAX, MIN, AVG, UNIQUE_COUNT, LAST, or P95. Matched case-insensitively: the server also accepts the all-uppercase and all-lowercase form of each value. The form published here is the canonical one and is what reads back.
keyOrg-unique slug identifying the meter; lowercase letter then [a-z0-9_-], 1-64 chars.
metric_keyEvent ingestion key this meter aggregates over.
nameHuman-readable label for the meter.
When set, defines this as a derived meter computed from other meters via a formula. An empty object is the same as omitting it.
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 or omitted disables validation. Must compile as a JSON Schema — a document that does not is rejected here rather than failing every later ingest.
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. Matched case-insensitively: the server also accepts the all-uppercase and all-lowercase form of each value. The form published here is the canonical one and is what reads back.
negative_allowedWhether the aggregated value may go negative (e.g. for credits/reversals).
How the billable quantity is snapped before pricing (increment + mode). Omitted, or an empty object, means exact: priced at the metered precision, up to 8 decimal places.
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.
Reset cadence for the aggregation; null aggregates over the whole billing period.
CreateOrganizationContactRequest
categoryWhat this contact receives. Required.
kindWhich arm this row carries. Required.
emailRequired when kind is email; must be absent otherwise.
is_primaryWhether mail for this category is addressed here. Omit to let the first row in a category become its primary.
nameOptional label.
roleRequired when kind is role; must be absent otherwise.
user_idRequired when kind is user; must be absent otherwise.
CreateOrganizationRequest
namedefault_currencydefault_localesignup_emailslugCreatePaymentGatewayConfigRequest
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).
providerdisplay_namesupported_currenciesCreatePaymentMethodRequest
customer_idCustomer to attach the payment method to. Required.
providerPayment provider holding this method, e.g. "stripe" or "gocardless". Required.
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.
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.
provider_idProvider's own identifier for the stored method; omit when not tracked externally.
CreatePhaseInput
nameOperator-facing phase name.
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.
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.
CreatePlanRequest
nameInternal operator-facing plan name.
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.
price_cadence_unitThe billing period this plan's prices are authored for (week, month or year); defaults to month. Subscriptions, quotes and checkouts against this plan must bill on exactly this cadence.
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
currencyISO 4217 currency for the list price and tier amounts.
list_price^-?\d+(\.\d+)?$ · requiredList price, MAJOR units, in the currency field.
product_idThe product to attach this price to.
country_codeCountry to scope this price to; omit to match any country.
Arbitrary dimension key/values that further scope the price.
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 or PLAN_OVERRIDE. Defaults to the most specific scope implied by the ids present. A price is a CATALOG row; a rate agreed with one customer is a subscription negotiated price, not a price.
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._-].
The tier ladder in ascending up_to order; omit it for a flat price, which then needs a non-zero list_price.
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+)?$ · requiredFlat amount, MAJOR units, in the price's currency.
unit_amount^-?\d+(\.\d+)?$ · requiredPer-unit 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; overrides unit_amount when present. Its RESULT is the per-unit rate under STAIRCASE but the WHOLE line amount under VOLUME and PACKAGE; a VOLUME/PACKAGE expression must reference tier_quantity.
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.
pricing_var_nameFormula variable name to expose the meter result as: a slug, lowercase letter then [a-z0-9_-], 1-64 chars. Required for BILLABLE_QUANTITY and PRICING_VAR, and unused by INFORMATIONAL — but unique per product in EVERY role, so an INFORMATIONAL binding that carries one still reserves it. The slug grammar is enforced by the API, not by this schema, because "" is a legal value for INFORMATIONAL.
roleHow the pipeline consumes the result: BILLABLE_QUANTITY, PRICING_VAR or INFORMATIONAL. Matched case-insensitively: the server also accepts the all-uppercase and all-lowercase form of each value. The form published here is the canonical one and is what reads back.
Additional filter tree AND-ed onto the meter's own filters for this product only.
CreateProductRequest
nameInternal operator-facing product name.
pricing_modelPricing model applied to this product: VOLUME, STAIRCASE or PACKAGE. Required.
quantity_sourceWhere the billed quantity comes from: DECLARED (set on the subscription item) or METERED (from the meter evaluator). Required.
unit_labelSingular noun one billed unit is called (e.g. seat, GB). Required.
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.
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.
requires_product_idsProducts that must also be present for this product to be sold (dependency set).
supply_natureWhat this product is for place-of-supply purposes. Omit to leave it undeclared, which is treated as SERVICES.
tax_categoryProduct tax category: which statutory tier the product is billed at. DEFAULT is the country's standard rate; ZERO and EXEMPT are decided by what the supply is and are not tiers. Defaults to DEFAULT.
Locale-keyed overrides for name, description and public_description.
CreateProfileRuleRequest
countryISO 3166-1 alpha-2 country code of the buyer, upper-case. Matched against the customer's billing address country.
profile_idE-invoice profile buyers matching this rule get. Must be one this deployment offers - see GET /v1/e-invoicing/profiles.
regionSub-national region as an ISO 3166-2 code without the country prefix (BY for Bavaria); a name from GET /v1/e-invoicing/regions is accepted and stored as its code. Only countries listed there have a region axis. Omit for a rule covering the whole country; a region rule outranks its own country-wide rule.
CreatePromotionRequest
distributionHow a customer comes to hold the promotion: AUTO_APPLY, AUTO_ENROLL, COUPON, or DIRECT. Required.
nameOperator-facing promotion name.
valid_fromFirst calendar day (UTC) the promotion is valid; required.
announcement_audienceWho this promotion's activation announcement is emailed to: promotion_audience (the promotion's own audience decides, and the per-email audience set for this kind is waived) or email_audience (that per-email audience applies too, so the announcement reaches the intersection of the two). The WORKSPACE-wide email audience on mail_defaults narrows both — it is a standing statement about who receives customer email at all and a promotion cannot reach past it. Omit to take the workspace creation preset. Decides who is emailed only — it never changes who may enrol in or redeem the promotion.
application_timingWhen a redeemed promotion first takes effect: NEXT_CYCLE, RETROACTIVE, or IMMEDIATE.
archetypeFrontend-only preset hint; not persisted as rule logic.
Live ENROLMENT audience: who may hold this promotion. Send audience.definition to set the rule tree (applying a saved audience copies its rules in); the four flat fields are the legacy shape and are ignored when a definition is present. Omit for all customers.
benefit_on_window_closeWhat valid_to means for customers who already redeemed: end (default) expires their benefit with the promotion; keep leaves each redemption running to its own benefit duration. Either way, past valid_to nobody new can redeem.
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).
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.
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_toLast calendar day (UTC) the promotion is valid, inclusive; null = open-ended.
CreateQuotePresetRequest
namePreset name.
activeDefaults to true when omitted.
auto_renewWhether those subscriptions renew at period end. Omit to inherit the organization default.
billing_anchor_dayDay of month (1-28) those subscriptions anchor their billing period to. 0 or omitted inherits the organization default.
contract_termsdefault_expiry_daysPublic-link lifetime in days for quotes created from this preset.
descriptiondocument_template_idDocument template to render quotes from this preset with. Omit to use the organization's quote default.
note_for_customerplan_idplan_versionWhat quotes from this preset demand of the buyer before signing, destinations included.
require_payment_methodrequire_shippingrequire_vat_idversion_change_strategyMoney policy when a latest-tracking subscription moves version. Required when version_track_mode is latest; omit to inherit the organization default.
version_track_modeHow subscriptions provisioned from this preset's quotes follow plan/product versions. Omit to inherit the organization default.
CreateQuoteRequest
customer_idkindaction_at_term_endWhat happens when the agreed term runs out. Omit for CONTINUE_WITHOUT_TERM: the negotiated rates lapse on their own windows and the subscription carries on at catalogue prices. Requires negotiated_term_unit/count.
auto_renewWhether the provisioned subscription renews at period end. Omit to inherit the preset, then the organization default.
billing_anchor_dayDay of month (1-28) the provisioned subscription anchors its billing period to. 0 or omitted inherits the preset, then the organization default, then derivation from the start date.
billing_intervalInterval unit (week|month|year) used to price plan-backed items; defaults to month.
Library clauses to snapshot onto the quote; body is an optional override of the library text.
co_terminate_with_subscription_idEnd this deal on the same date as that subscription's deal. Requires negotiated_term_unit/count, and the term must match the group's. The new agreement takes the group's end date, which can make its first window shorter than the agreed term.
contract_termscoupon_codecreated_bycurrencycustom_fieldsWhat the offer says happens later, in order. Each entry gives an offset from the deal's start and the plan, quantities and agreed prices in force from then.
document_template_idDocument template this quote renders through. Omit to inherit the preset's pinned layout, then the organization's quote default.
What the customer owes for ending the subscription before the agreed term is up. A policy, not an amount: kind picks the formula (NONE, FLAT, PERCENT_OF_REMAINING, REMAINING_VALUE, REMAINING_PERIODS, DISCOUNT_RECAPTURE) and carries the one input that formula needs, plus an optional cap. Omit for an offer that says nothing, which charges nothing; send {"kind":"NONE"} to record that leaving was agreed to be free. Requires negotiated_term_unit/count.
early_termination_gateWhat happens when a governed operation is attempted inside the term: NONE allows it silently, WARN records it, BLOCK refuses it with a 409 naming the date the term ends. Omit for WARN.
excluded_clause_idsAuto-attached clause ids to leave off this quote. Each id must be one the catalog attaches to this offer, and must not also appear in clauses.
expires_atfree_trial_daysDays of free trial this offer sells before billing starts; 0 or omitted means billing starts on activation.
governed_operationsWhich operations the early-termination gate applies to. Omit to govern cancel, which is what every agreement does today. Send an explicit empty array for a term that governs nothing.
localeLanguage the offer is for (en, de, fr, es, it, pt, nl, ja). Drives the PDF, the buyer mail and the language a clause body is snapshotted in. Omit to inherit the customer's locale, then the organization default.
negotiated_term_countNumber of negotiated_term_unit periods the agreed rates hold for, measured from the subscription start. Send with negotiated_term_unit; omit both for open-ended.
negotiated_term_unitUnit of the term the negotiated rates hold for. Send with negotiated_term_count; omit both for open-ended.
note_for_customernotice_countHow many notice_units a cancellation asked for inside the term waits before it takes effect. Omit both fields for a cancellation that takes effect at once.
notice_unitUnit of the notice a cancellation requires: week or month. NOT the same mechanism as term_end_reminder_days, which announces that the term is ENDING — this one defers a cancellation the customer ASKS FOR, to notice_count units later or the end of the term, whichever is sooner. Send with notice_count or not at all.
orchestration_modeowner_user_idplan_idplan_versionpreset_idproration_snapshotrenegotiates_agreement_idThe agreement this offer renegotiates. Only meaningful on a SUBSCRIPTION_UPDATE quote for the subscription that agreement governs; the agreement page lists the offer as its pending renewal.
What the buyer must answer before signing, each entry naming a custom-field key, WHERE the answer goes after signature (target) and what happens when the destination already holds a value (on_conflict). Omit to inherit the preset's list.
require_payment_methodrequire_shippingrequire_vat_idInvoicing overrides for the provisioned subscription: line grouping, price resolution, default proration mode and payment terms. Omit any field to inherit the customer's, then the organization's, setting.
signature_modesourcesource_subscription_idstarts_atWhen the offer begins. Prices resolve as of this date and the provisioned subscription starts on it. Omit to price at now and start on signature.
successor_plan_idPlan the subscription moves onto when the term ends. Required when action_at_term_end is SWITCH_PLAN, refused otherwise, and the plan must already have a published version.
term_end_reminder_daysHow many days before the term ends the customer is given notice. Required (and at least 1) for RENEGOTIATE, which drafts the renewal quote on that day. Omit for no notice.
titleChange set for SUBSCRIPTION_UPDATE quotes (add/remove/quantity/plan/version), priced into proration_snapshot at create.
update_effectiveupdate_effective_dateversion_change_strategyMoney policy when a latest-tracking subscription moves version. Required whenever version_track_mode resolves to latest on this quote. Omit to inherit the preset, then the organization default.
version_track_modeHow the PROVISIONED SUBSCRIPTION follows plan/product versions: pinned or latest. Omit to inherit the preset, then the organization default. Unrelated to plan_version, which pins what this offer was priced against.
CreateRateTableRequest
nameDisplay name for the table.
on_missing_keyBehaviour when no entry matches: 'error', 'zero', or 'default_value'.
slugURL-safe unique identifier formulas reference this table by.
table_typeMatching mode: 'lookup' (exact key match) or 'bracket' (numeric range match).
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.
requires_continuous_coverageWhen true, published versions may not leave a gap in the effective-date timeline.
CreateSegmentRuleRequest
applied_tag_idThe tag this rule applies to (and removes from) customers. Must not already be claimed by another active rule.
metricWhich computed fact the rule tests.
operatorHow the metric is compared to value.
value^-?\d+(\.\d+)?$ · requiredThe threshold the metric is compared against.
CreateSubscriptionRequest
customer_idCustomer the subscription bills; required.
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. Matched case-insensitively: the server also accepts the all-uppercase and all-lowercase form of each value. The form published here is the canonical one and is what reads back.
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 this subscription bills in, for its whole life - it is the contract and cannot be changed afterwards. Defaults to the customer's preferred_currency, else the currency of the plan version's first price, else EUR. The organization default is NOT consulted here.
Values for the org's configured custom fields.
descriptionInternal operator-facing description; not shown to buyers.
free_trial_daysLength of the free trial in days before billing starts; 0 or omitted means billing starts immediately.
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.
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 LATEST paired with immediate_prorate, so publishing a new plan version DOES migrate this subscription and can charge proration for it. Send pinned explicitly to opt out.
CreateTagRequest
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).
colorOptional display color as a #RRGGBB hex string.
descriptionOptional free-text description of the tag's purpose.
CreateTaxRuleRequest
jurisdiction_countryrate^-?\d+(\.\d+)?$ · requiredDecimal number encoded as a string to preserve precision.
tax_typeMatched case-insensitively: the server also accepts the all-uppercase and all-lowercase form of each value. The form published here is the canonical one and is what reads back.
valid_fromapplies_to_customer_typesapplies_to_product_categoriesapplies_to_supply_typesapply_orderinclusiveis_compoundjurisdiction_regionrequires_continuous_coveragevalid_toCreateVersionRequest
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. Optional: the publish that takes the draft sets it; omitted, the draft is stamped with the request instant.
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.
release_nameOptional name for the version, shown beside its number.
release_noteOptional note describing the version.
CreateWalletRequest
currencyISO 4217 currency the wallet is denominated in.
customer_idCustomer the new wallet belongs to.
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.
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
event_typesurldescriptionsecret_idsigning_methodCreateWebhookEndpointResponse
created_atevent_typesidorganization_idsigning_methodstatusupdated_aturldescriptionsecret_idsigning_keyunknown_event_typesSubscribed event types that no longer exist in the catalog. These deliver nothing and never will: registration-time validation only gates writes, so an endpoint registered before an event was renamed or retired keeps the dead subscription until someone edits it. Absent when every subscription is live.
CreateWebhookSecretRequest
entity_identity_typedescriptionsigning_methodCreateWorkspaceCurrencyRequest
currency_codeISO 4217 currency code to enable (normalized to uppercase).
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.
CreateWorkspaceRequest
modenameslugCredentialField
keyConfig key this value is stored under, e.g. api_key.
requiredWhether a provider can be connected without it.
secretTrue when reads return a masked hint rather than the value.
CredentialView
refThe locator a channel's credentials_ref points at.
labelOperator-facing name — which contract this is. Never the secret.
CredentialsResponse
The credentials on file. The secrets themselves are never returned by any endpoint.
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_atGoverning invoicing law, inherited from the credited invoice at issue. Read-only. Absent on drafts, standalone notes and notes whose invoice has none.
invoice_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_idThe customer the credit note is issued to.
invoice_idThe invoice the credit note references.
organization_idstatusThe credit note status at creation.
The credit note total, as a money object.
customer_emailThe customer's email at creation time, when known.
numberThe human-readable credit note number, when already assigned.
reasonThe reason the credit note was created.
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_idThe customer the credit note is issued to.
invoice_idThe invoice the credit note references.
issued_atWhen the credit note was issued (RFC3339).
organization_idThe credit note total, as a money object.
customer_emailThe customer's email at issue time, when known.
reason_codeThe coded reason the credit note was issued.
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_idvoided_atWhen the credit note was voided (RFC3339).
reasonThe reason the credit note was voided.
workspace_idThe workspace that owns the credit note.
CreditRequest
amount^-?\d+(\.\d+)?$ · requiredMAJOR units, in the addressed wallet's currency.
sourceWhat originates the credit: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER.
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.
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.
CustodySummary
Promotional credit forfeited on expiry in the window, {value, currency}.
Customer money currently held and not yet spent — a liability, not revenue, {value, currency}.
currencyISO 4217 currency this summary is denominated in; wallets hold exactly one currency each.
Promotional portion of spending in the window — a discount, not revenue, {value, currency}.
period_fromStart of the reporting window (inclusive).
period_toEnd of the reporting window (exclusive).
Granted credit not yet spent or expired; carries no liability, {value, currency}.
Customer money returned in the window; decreases what we owe, {value, currency}.
Cash portion of spending in the window — revenue earned, {value, currency}.
Customer money received in the window; increases what we owe, {value, currency}.
unclassified_rowsLedger rows still unclassified (pre-split history); when non-zero the period figures exclude them.
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.
EN 16931 BG-15 DELIVER TO ADDRESS: where supplies to this customer are actually delivered, when that is not the billing address; null means delivered to the billing address.
delivery_location_idEN 16931 BT-71, the deliver-to location identifier (a GLN or a site code agreed with the buyer); null emits nothing.
delivery_party_nameEN 16931 BT-70, the deliver-to party name (e.g. "Acme GmbH - Warehouse North"); null emits no name rather than restating the buyer name.
disabled_providersPayment provider ids that must not be used to charge this customer.
einvoice_profileStanding per-customer e-invoice format (e.g. XRECHNUNG_3_0_UBL); null = inherit, resolving through the country rules to the workspace default profile. Not the same as prefer_einvoice (whether to produce one) or peppol_id (where to send it).
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's rollout audience; false = never auto-generate; true = always auto-generate, whether or not the customer is in the audience.
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.
CustomerContact
categoryWhat this contact receives: billing, quotes_contracts, dunning, legal_notices or technical.
created_atcustomer_idemailThe mailbox. Stored as entered; uniqueness within a category is case-insensitive.
idis_primaryWhether mail for this category is addressed here. At most one contact per (customer, category) can be primary; a category with no primary falls back to the billing contact.
organization_idpositionThe slot within the category, 1 to 3. The primary normally holds 1; the others are copied on the mail in position order.
updated_atupdated_by_kindWhich side last changed this contact: operator (a tenant user), portal (the customer, self-service) or system (the automatic mirror of the account's main address).
workspace_idThe workspace the contact belongs to; always the owning customer's workspace, so a sandbox customer's contact stays in sandbox.
nameOptional display name for the person or team behind the address.
CustomerCreatedPayload
created_atcustomer_idThe customer that was created.
emailThe customer's email address.
organization_idpreferred_currencyThe customer's preferred billing currency, ISO-4217.
wallet_idThe default wallet provisioned for the customer.
external_idThe caller-supplied external id, when provided.
workspace_idThe workspace that owns the customer.
CustomerCurrencyChangedPayload
changed_atWhen the billing currency changed (RFC3339).
customer_idThe customer whose billing currency changed.
fromThe ISO 4217 billing currency before the change - the only record of it that survives the write.
organization_idtoThe ISO 4217 billing currency after the change.
actor_idThe actor who performed the currency change, when known.
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
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_idtoThe wallet mode after the change (e.g. PREPAID, POSTPAID).
actor_idThe actor who performed the mode change, when known.
reasonWhy the wallet mode was changed.
Per-wallet balance snapshots captured at the moment of the change.
workspace_idThe workspace that owns the customer.
CustomerNegotiatedPrice
created_atidproduct_idproduct_nameName of the product the rate applies to, so a rate for a product not on the new offer is still readable.
sourceWho agreed the rate: QUOTE (a signed offer) or OPERATOR.
subscription_idThe deal this rate belongs to; a rate is scoped to one subscription item and never leaks onto another engagement.
subscription_item_idsubscription_statusStatus of the subscription carrying the rate; only live deals are listed.
The agreed per-unit rate, major units, currency-tagged. It is FLAT: it replaces the tier ladder rather than scaling it.
valid_fromStart of the rate's window.
price_keyThe key of the product's key set this rate covers — the consultant, seat class or variant; null on unkeyed lines.
source_quote_idThe offer that promised this rate; set whenever source is QUOTE.
valid_toExclusive end of the window; null means open-ended — for the duration of the subscription, until a later offer supersedes it.
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
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).
actor_idThe actor who performed the type change, when known.
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.
DataEnvelopeAdjustWalletData
Outcome-dependent: on 200 the posted WalletTransactionDTO; on 202 an ApprovalPendingDTO because this workspace requires human approval for wallet adjustments — nothing has been applied yet (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).
DataEnvelopeRefundInvoiceData
Outcome-dependent: on 200 the VoidInvoiceResponseDTO (voided invoice + credit note); on 202 either the RefundInvoiceResponse with status=refund_pending while the gateway refund settles (observe completion via GET /invoices/{id}/payments), or the ApprovalPendingDTO with state=approval_pending when an approval checkpoint parked the refund and NOTHING has been refunded yet (observe via GET /approvals/{id}).
DataEnvelopeSendQuoteData
Outcome-dependent: the QuoteDTO (status SENT) on 200, when the quote.send checkpoint did not gate; the ApprovalPendingDTO on 202, when it did and the quote is parked in PENDING_APPROVAL awaiting a decision.
DataEnvelopeSubmitQuoteData
Outcome-dependent: the QuoteDTO (status APPROVED) on 200, when the quote.send checkpoint did not gate; the ApprovalPendingDTO on 202, when it did and the quote is parked in PENDING_APPROVAL awaiting a decision.
DealStep
positionstarts_after_countstarts_after_unitidplan_idplan_versionDealStepInput
starts_after_countHow many starts_after_unit after the deal begins this step takes effect.
starts_after_unitUnit of the offset from the deal's start. billing_cycle always lands on a billing-period boundary whatever the subscription bills on.
What this step says about each product: a quantity, an agreed price, or both.
plan_idThe plan this step moves the subscription onto. Omit to stay on the plan the step before was on.
plan_versionWhich version of that plan. Required when plan_id is given: the offer promises the configuration the customer read, not whatever the catalogue's head happens to be a year later.
positionRead-only. The array's order is what decides; a value here is checked against it and never overrides it.
DealStepLine
product_ididprice_keyquantityDealStepLineInput
product_idThe product this line is about.
negotiated_amountPer-unit rate agreed from this step on, as a decimal string in the quote's currency. Omit to leave the line's rate alone.
price_keyWhich of the product's named prices this step bills at. Omit for the product's default.
quantityThe units the line carries from this step on — the new total, not a delta. Omit to leave the quantity alone.
DebitRequest
amount^-?\d+(\.\d+)?$ · requiredMAJOR units, in the addressed wallet's currency.
sourceWhat originates the debit: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER.
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.
DeclaredAllowanceState
billable_quantityUnits billed: held minus included, never below zero.
included_quantityUnits included free, after any operator override.
quantity_heldUnits this subscription carries, as stated by the operator.
unrealized_quantityIncluded units the customer is not using; zero once they hold at least the included amount.
Definition
match_allTarget every customer. Mutually exclusive with root.
Root rule group. Required unless match_all is set.
DependentPlan
plan_idplan_nameplan_statusstaletrack_modecurrent_versionpinned_versionDependsOn
conditioneffectfield_keyvalueDerivationFX
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).
DeviationEntry
kindHow this product departs from the plan: INCLUDED_QUANTITY, QUANTITY, PRODUCT_NOT_IN_PLAN or NEGOTIATED_PRICE.
product_idproduct_nameProduct name, from the plan-version snapshot where the plan still carries the product and the live catalog row otherwise.
actual_quantity^-?\d+(\.\d+)?$The subscription's number: the overridden included quantity, or the purchased quantity.
What the catalog would have charged for the same line at the window's start; absent when it could not be resolved — never rendered as zero.
negotiated_sourceWho agreed the rate: QUOTE (a signed offer) or OPERATOR.
The agreed per-unit rate; NEGOTIATED_PRICE deviations only.
plan_max_quantityUpper bound of the plan's authored quantity band, when it set one.
plan_min_quantityLower bound of the plan's authored quantity band, when it set one.
plan_quantity^-?\d+(\.\d+)?$What the plan version authored: the included-quantity pin, or the default purchased quantity. Absent when the plan authored none.
price_keyKey of the product's key set this row is about; null for unkeyed lines and product-grained shapes.
source_quote_idThe quote that promised this rate; set when negotiated_source is QUOTE.
subscription_item_idProvenance: the subscription item row that was open when this negotiated rate landed. The rate is bound to the line (subscription, product, price key), not to this row, which a later quantity change supersedes. NEGOTIATED_PRICE only.
valid_fromStart of the negotiated rate's window; NEGOTIATED_PRICE only.
valid_toExclusive end of the negotiated rate's window; null means open-ended.
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.
quarantine_idThe document-quarantine record id for operator inspection.
quarantined_atWhen the request was quarantined (RFC3339).
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.
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_idsource_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.
profileThe rendering profile used, when profile-specific.
workspace_idThe workspace that owns the source record.
DocumentRequestedPayload
idempotency_keyThe consumer-side de-duplication key for this render request.
kindThe document kind to render.
organization_idrequested_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).
jurisdictionThe jurisdiction the document is rendered for, when applicable.
profileThe rendering profile, when profile-specific.
workspace_idThe workspace that owns the source record.
DocumentTemplate
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, quote, email}.
idis_systemTrue for built-in system templates, which cannot be edited or deleted.
nameHuman-readable template name.
organization_idQuote inputs this layout prints, derived from its blocks. Empty unless the template renders quotes.
statusTemplate status, e.g. active or archived.
The template document: ordered blocks plus theme, branding, and footer.
updated_atversionOptimistic-concurrency version, bumped on every update.
anchor_keyThe mail kind this email template renders for, e.g. "invoice.finalized". Empty on printed templates. Stable technical identifier, not a label — show anchor_name.
anchor_nameThe mail kind's human name in the request locale, e.g. "Invoice finalized". Resolved server-side from the code-owned registry; empty on printed templates.
deleted_atSoft-delete timestamp; null for live templates.
Draft
created_atdraft_version_idupdated_atversionbase_version_idrelease_namerelease_noteupdated_byDriftCandidateVersion
lifecycleversioneffective_fromeffective_toDunningStepPayload
actionThe action the step performed (e.g. EMAIL, SUSPEND).
customer_idThe customer billed on the invoice.
days_after_dueThe step's SCHEDULE threshold: how many days after the due date this step was configured to fire.
days_overdueHow many whole days past its due date the invoice ACTUALLY was when the step fired; >= days_after_due when the sweep ran late.
invoice_idThe overdue invoice the dunning step acted on.
organization_idstep_countHow many steps the dunning policy in force has in total.
step_indexThe 0-based index of this step in the dunning schedule.
timestampWhen the step fired (RFC3339).
email_eventThe email sub-event name, for email steps only.
next_actionThe action of the next step in the ladder; empty when this was the last step.
next_days_after_dueHow many days after the due date the next step is scheduled for; zero when this was the last step.
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).
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.
credit_note_numberHuman credit-note number of the anchoring credit note. Empty when the credit note is still a draft, was deleted, or is outside the caller's scope - fall back to credit_note_id.
invoice_idThe invoice this document was generated for; zero/omitted when it is anchored to a credit note.
invoice_numberHuman invoice number of the anchoring invoice (e.g. RE-2025-0413). Empty when the invoice is still a draft, was deleted, or is outside the caller's scope - fall back to invoice_id.
profile_sourceWhich level of the resolution chain chose the profile: invoice_override (a human chose it for this document), customer (the buyer's standing preference), jurisdiction_rule (a country/region rule matched) or org_default. Absent on documents issued before this was recorded - absent means unknown, not org_default.
profile_source_detailWhich ROW chose the profile, in the operator's words: "customer
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.
EInvoiceProfile
containerXML for a bare XML document, PDF_A3 for a hybrid PDF with the XML embedded.
hybridTrue when producing this profile additionally requires a configured mustangserver.
idStable identifier, e.g. XRECHNUNG_3_0_UBL. Use this value wherever a profile is required.
nameHuman-readable label.
syntaxUBL, CII or PDF_A3_CII.
EInvoiceProfileRule
countryISO 3166-1 alpha-2 country code of the buyer.
created_atidprofile_idE-invoice profile buyers matching this rule get.
updated_atregionSub-national region; empty means the rule covers the whole country. A region rule outranks its own country-wide rule.
EInvoiceRegion
codeISO 3166-2 code without the country prefix, e.g. BY. This is what a rule stores.
nameEnglish name.
local_nameOfficial local spelling where it differs from the English name.
EInvoiceRolloutDecision
decided_atWhen the gate decided. Moves if the source event is redelivered, because the row then describes the decision that governed the latest attempt.
generateWhat the gate decided, BEFORE rendering. true with no document in GET /e-invoicing/documents?invoice_id= beside it means rendering never completed — the rollout said yes and the pipeline did not finish, which is a diagnosis and not a contradiction.
reasonWHICH mechanism answered, from a closed vocabulary: customer.prefer_einvoice, rollout_audience.not_a_member, rollout_audience.unresolved, rollout_audience.unset, rollout_audience.no_customer, workspace.auto_generate_einvoice, workspace.auto_generate_einvoice_unset. It is the same string the worker logs as rollout_reason. Note that workspace.auto_generate_einvoice_unset (never configured) is deliberately distinct from workspace.auto_generate_einvoice written false.
reason_detailWHICH ROW decided, in the words an operator can act on: "audience
credit_note_idThe credit note this decision was made about.
customer_idThe buyer the decision was made about. Absent when the source event named no customer, which is itself one of the reasons.
invoice_idThe invoice this decision was made about. Exactly one of invoice_id / credit_note_id is present.
EInvoicingDocumentGeneratedPayload
byte_sizeThe document size in bytes.
content_hashHex-encoded sha256 over the document bytes.
document_idThe e-invoicing document that was generated.
generated_atWhen the document was generated (RFC3339).
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).
credit_note_idThe source credit note, when the document is a credit note.
invoice_idThe source invoice, when the document is an invoice.
reissue_reasonWhy the document was re-issued.
supersedes_submission_idThe refused submission this document replaces, when the generate answered a buyer refusal.
workspace_idThe workspace that owns the document.
EInvoicingDocumentQuarantinedPayload
document_idThe e-invoicing document that was quarantined.
error_rule_idsThe validation rule ids the document failed.
organization_idprofileThe e-invoicing profile the document was validated against.
quarantine_reasonWhy the document was quarantined.
quarantined_atWhen the document was quarantined (RFC3339).
credit_note_idThe source credit note, when the document is a credit note.
invoice_idThe source invoice, when the document is an invoice.
workspace_idThe workspace that owns the document.
EUVATRate
country_codecountry_nameeffective_fromparking_ratereduced_ratereduced_rate_2standard_ratesuper_reducedeffective_toEffect
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · kind="percentage_discount" · requires: rate | |
| type = object · kind="fixed_discount" · requires: amount | |
| type = object · kind="price_override" · requires: override_amount | |
| type = object · kind="free_product" · requires: product_id | |
| type = object · kind="free_periods" · requires: periods | |
| type = object · kind="wallet_credit" · requires: amount | |
| type = object · kind="usage_credits" · requires: product_id, quantity |
kindUnion discriminator.
rate^-?\d+(\.\d+)?$ · requiredPercentage 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.
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).
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.
Which invoice lines the discount applies to; empty = every line.
EffectMeta
applies_atWhen the effect is applied: REDEEM_TIME or INVOICE_TIME.
applies_to_allTrue when at least one discount effect has an empty scope and therefore applies to EVERY line on the invoice.
summaryHuman-readable description of the effects across every phase, joined with a middot.
typeThe effect kind (e.g. percentage_discount, free_product).
key_restrictedTrue when an effect scope is narrowed to specific keyed variants; the concrete keys are not resolved here.
Named products the effects apply to (or exclude, see excluded); empty together with applies_to_all=false means the effects touch no invoice line at all (e.g. a wallet credit).
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).
EligiblePromotion
Per-condition evaluation detail behind the eligibility decision.
The promotion the customer is eligible for.
EndRegistrationRequest
countryschemevalid_toYYYY-MM-DD, the last day the registration was in force. Defaults to today.
EnrichedPlanProduct
Head-state cost summaries for the attached product (reflects the product's current costs, not a publish snapshot).
created_atidin_head_versionTrue when the plan's current head version contains this product. False means the membership is not part of what the plan currently offers — it was added after the head version was published (or the plan has no published version yet) — so quotes, checkout and subscriptions built from the pinned version exclude it until the plan is published again.
Head-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).
default_quantityQuantity a new subscription seeds for this product when the caller passes no explicit item; null seeds 1.
included_quantity^-?\d+(\.\d+)?$Quantity bundled into the base price before per-unit billing applies (the included allowance/seat floor); null means none.
max_quantityHighest quantity a buyer may pick for this product; null means no plan-level ceiling.
min_quantityLowest quantity a buyer may pick for this product; null means 1.
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.
unit_limit^-?\d+(\.\d+)?$Ceiling on a POOL's unit balance; POOL only.
EntityNameRow
idThe entity's uuid
kindThe entity kind
refThe reference as supplied, 'kind:uuid'
display_nameThe row's human name
referenceThe short per-org human id, e.g. SUB-000123
EntryInput
keyThe key identifier (matching ^[a-zA-Z0-9._-]{1,64}$); the conflict target for the upsert.
display_nameCustomer-facing label for the key; defaults to the key itself when empty.
Free-form key/value metadata for the key.
statusEntry status: active or retired; defaults to active.
tagsFree-form tags for the key.
EvaluateMeterRequest
subscription_idSubscription to evaluate against. Required: usage_events are keyed by (product, subscription), so "what does this meter compute" is not a well-formed question without one.
fromInclusive start. Defaults to the subscription's current period start.
include_headAlso evaluate the LIVE meter row alongside the billed snapshot, so an unpublished edit is visible as a difference. Defaults to true; set false to skip the second aggregation.
product_idWhich of the subscription's metered products to scope to. Optional when exactly one of them bills through this meter; required when more than one does.
toExclusive end. Defaults to the subscription's current period end.
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.
ExportResponse
currencyexpires_atfromgrainidmetricstatuspending, running, ready, failed or expired.
tobyte_sizedownload_urlerrorWhy the export failed, when status is failed.
row_countsha256ExternalVerificationCondition
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. API_ECB).
source_currencyISO 4217 currency being converted from.
target_currencyISO 4217 currency being converted to.
File
categoryWhat the document is. Decides the size cap and the accepted formats.
created_atWhen the file was added.
declared_content_typeThe format the uploader said this was, before any byte was checked. Never render this as the file's type — use content_type.
filenameThe name the uploader gave the file. Display only.
idFile UUID.
owner_idThe owning record's UUID.
owner_kindWhat this document hangs off.
sourceWho put the document here.
statuspending_upload while the bytes are still expected, ready once the server has checked them, quarantined when they did not match, deleted after removal.
visibilityinternal = operator surfaces only. shared = also visible to the customer on the portal and, for a quote, on the offer page.
byte_sizeThe size the server measured. Absent until the upload has been confirmed.
content_sha256SHA-256 of the stored file, computed by the server. Absent until the upload has been confirmed.
content_typeThe format the server determined from the file's own bytes. Absent until the upload has been confirmed.
retention_untilWhen set, the file is removed automatically after this date.
uploaded_byThe user who uploaded it, when a user did.
FileURL
expires_atAfter this moment the link stops working.
urlA temporary link to the file's bytes.
FileUpload
expires_atAfter this moment the upload URL stops working and the upload must be started again.
upload_urlPUT the file's bytes here, then call the confirm endpoint. Use it once: after the file is confirmed, uploading through this link again does not replace the document — it makes the file unreadable and it must be uploaded again.
FixedDiscountEffect
The fixed discount amount with its currency; the discount no-ops on an invoice of a different currency.
kindUnion discriminator.
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.
Whole-invoice cap on the total discount summed across all matched lines; must be in the amount's currency.
Which invoice lines the discount applies to; empty = every line.
Footer
show_page_numbersWhen true, renders page numbers in the footer.
textFooter text rendered at the bottom of the document.
FormulaVariable
nameThe variable name referenced in the formula expression.
typeThe variable's value type: number, string, or boolean.
defaultDefault value applied when the caller supplies no binding; a currency-neutral numeric factor, never a money amount.
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.
GatewayVerifyResult
checked_atdetailWhat was checked and, when ok=false, what the vendor said. Never contains the credential.
okGenerateEInvoiceRequest
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) recorded on the document and used to pick the archival retention policy. It does NOT select the format - that is what the profile rules do.
profileTarget e-invoice profile (e.g. XRECHNUNG_3_0_UBL). OMIT IT to resolve the format from the customer's preference, then the country rules, then the organization default; supply it only to override that decision for this one document. See GET /v1/e-invoicing/profiles for the accepted values.
reissue_reasonShort operator-facing note recorded on the superseded submission.
supersedes_submission_idThe refused submission this document replaces. Set it when re-issuing after a buyer refusal; the link is refused unless that submission is REFUSED_BY_BUYER and not already superseded.
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
subscription_idSubscription to generate an invoice for (required).
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.
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.
expires_atOptional expiry stamped on every token generated by this call; after it a token can no longer be redeemed. Does NOT affect anyone who already redeemed — for that, see the promotion's own valid_to.
Governing
jurisdictionISO 3166-1 alpha-2 country whose invoicing law governs this document (VAT Directive art. 219a, or its non-EU analogue).
legal_basis_keyStable key of the provision the exemption or reverse charge rests on (e.g. VATD_ART_196). Absent for a plain domestic taxable supply.
provenanceOrdered identifiers of the resolver branches that fired, for audit.
resolved_atWhen the resolution ran. Absent on a document whose values were backfilled from its stored tax facts rather than resolved.
seller_establishment_countryISO 3166-1 alpha-2 country of the seller's business seat. Document retention follows this, not the governing jurisdiction.
tax_systemTax system the governing country runs: EU_VAT, CH_MWST, UK_VAT, NO_MVA, JP_CT, or UNKNOWN.
tax_treatmentWhat the supply is: DOMESTIC, REVERSE_CHARGE_AT_RECIPIENT, INTRA_EU_SUPPLY_EXEMPT, EXPORT_EXEMPT, OUTSIDE_SCOPE, OSS_DESTINATION, or NOT_TAXABLE_SMALL_BUSINESS.
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_keyeffective_fromexpires_atgranted_bynatureoriginorigin_ref_idprice_keyreasonrevoked_atrevoked_reasonGrantUsageRequest
product_idProduct to grant usage against.
quantity^-?\d+(\.\d+)?$ · requiredUsage quantity to grant (metered units, NOT money).
descriptionOptional note recorded on the grant.
GrantUsageResponse
The entitlement grant created. PURCHASED for a durable credit pool, GRANTED for a per-period allowance.
Group
Child groups and leaves. Must not be empty.
opHow the children combine: and | or.
negateInvert the whole group.
HealthChangedPayload
connection_idThe connection whose health changed.
kindWhat kind of connection this is (payment_gateway, mail_provider).
new_stateThe health after the check (ok, failed).
occurred_atWhen the check ran (RFC3339).
organization_idprevious_stateThe health before the check (ok, failed, unknown).
providerThe vendor behind the connection.
detailWhat the check reported.
display_nameThe operator's own name for this connection.
workspace_idThe workspace that owns the connection.
Hit
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+)?$ · requiredMAJOR units, in the hold's currency (the currency field, else the wallet's).
expires_atWhen the wallet auto-releases the hold if it has not been captured.
reasonFree-text explanation of what the hold reserves for.
currencyISO 4217 currency of the hold; when empty the addressed wallet's currency is used.
exchange_rate_base_leg_idFor a triangulated cross-pair rate, the EUR→source FX snapshot the rate was divided by; set by the reserve service, null via the public hold API.
exchange_rate_idFX snapshot that supplied the rate this hold was valued at; set by the reserve service, null via the public hold API.
fx_policy_appliedFX timing policy that selected the rate; set by the reserve service, null via the public hold API.
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.
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_loginIdentifierCheckView
checksum_okchecksum_rankindlabelnormalized_valueokpattern_okcountrynotereasonIdentifierView
checksum_availablecountryidkindlabelnormalized_valuevalid_fromvalueverified_statusvalid_toverification_refverified_atverified_by_sourceverifierIneligiblePromotion
Per-condition evaluation detail showing which conditions failed.
The promotion the customer is not eligible for.
IngestEventRequest
customer_idCustomer that consumed the metric.
idempotency_keyCaller key that dedupes replays of the same event; required.
metric_keyMetric this event records usage for; must match the product's meter binding.
product_idMetered product the event is billed under.
quantity^-?\d+(\.\d+)?$ · requiredNumber of metric units to record; must be non-negative.
subscription_idSubscription the usage is charged against.
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.
Arbitrary caller-supplied key/value annotations carried on the event.
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.
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.
IntegrationConfig
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, 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.
Governing invoicing law, resolved once at finalize and frozen. Read-only. Absent on drafts and on documents whose resolution was refused.
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.
originHow this invoice came to exist: subscription, manual, quote, milestone, or prepaid_capture. Absent on rows written before the origin column existed whose writer did not declare one.
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.
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.
due_dateThe payment due date (RFC3339), when set.
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_idThe pre-tax subtotal, as a money object.
The total tax, as a money object.
The invoice grand total, as a money object.
subscription_idThe subscription that drove generation, when subscription-billed.
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.
idincluded_quantity^-?\d+(\.\d+)?$ · requiredUnits covered by an allowance and therefore not billed. Quantity is what was charged; this is what was free, so quantity + included_quantity is what the customer actually consumed.
invoice_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_base_leg_idFor a triangulated cross-pair rate, the EUR→source FX snapshot the atom's rate was divided by; null otherwise.
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_typeThe classified failure category.
invoice_idThe invoice whose payment attempt failed.
occurred_atWhen the attempt failed (RFC3339).
organization_idproviderThe payment gateway that processed the attempt.
error_codeThe provider-specific error code, when available.
error_messageThe provider-specific error message, when available.
next_retry_atWhen the next retry is scheduled (RFC3339); empty when terminal.
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_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.
last_error_messageThe error message of the final attempt, when available.
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.
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_typeJobDeadLetteredPayload
attemptsHow many times the job ran before it stopped.
job_idThe job that stopped retrying.
max_attemptsThe attempt ceiling configured for this job.
occurred_atWhen the job stopped retrying (RFC3339).
organization_idpermanentTrue when the handler declared the failure unrecoverable rather than running out of attempts.
topicThe kind of work the job was doing.
error_classThe handler's classification of the failure.
error_codeThe handler's error code, when it set one.
error_messageWhat the job said when it stopped.
workspace_idThe workspace that owns the job.
KeyCombinationCondition
The keys the customer must jointly hold (each an AND term of the bundle), with a minimum quantity per key.
kindUnion discriminator.
product_idThe keyed product whose key set this bundle is expressed over. One product; the bundle's members are its keys.
max_multipleCeiling on the per_set multiple; nil is unbounded. The budget cap cannot do this job — it is per-promotion and bounds the period, not the single basket that runs away inside it.
repeat_modeHow often a satisfied bundle pays: once (a threshold, the default) or per_set (the reward scales by the number of complete sets held).
KeyCoverage
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.
KeyRequirement
keyThe key-set entry this line requires (a TLD, a region, a plan code…). Must be an entry of the product's key set.
min_quantityHow many of this key the customer must hold; nil or <1 means one (plain presence).
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.
KindView
idlabelrequired_oncountryhintpattern_noteverifierLeaf
dimensionWhich fact this rule tests, from the closed dimension vocabulary.
operatorComparator; must be one the dimension declares.
valuesValues for the comparator. Always strings; UUIDs and timestamps are marshalled as text and parsed by the dimension's declared kind.
MailConsentEventResponse
actor_kindWho moved it: operator | system | recipient | checkout | backfill.
basisexpress_consent | soft_opt_in | withdrawn | none.
consent_idcreated_atemailfrom_stateThe state before this transition. Empty means there was no prior record.
idoccurred_atpurposesyntheticTrue for the single row seeded per recipient when the history was introduced: it re-states the state as it stood then and is NOT evidence of a transition we observed. Surfaces must say so.
to_stateopted_in | soft_opt_in | opted_out | unknown.
actor_idThe user behind the change, when there was one.
captured_ipcaptured_user_agentcustomer_idevidence_refThe checkout acceptance snapshot backing an express opt-in.
origin_sale_refThe sale that founded a soft opt-in.
proof_textThe exact statement the recipient agreed to.
sourceWhere the change came from: checkout | sale | objection | api | esp_unsubscribe.
MailConsentResponse
basisexpress_consent | soft_opt_in | withdrawn | none.
emailidpurposestateopted_in | soft_opt_in | opted_out | unknown.
updated_atcustomer_ideffective_atsourcewithdrawn_atManualInvoiceHostedLinkRequestedPayload
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.
organization_idreasonWhich branch caused the request: no_collector, collect_failed, or post_collect.
requested_atWhen the hosted link was requested (RFC3339).
invoice_numberThe human-readable invoice number, when assigned.
workspace_idThe workspace that owns the invoice.
MarkSignedRequest
executed_file_idThe uploaded signed copy, from POST /v1/files with owner_kind=quote and category=uploaded_signed_copy.
signer_nameWho signed the paper copy.
signer_emailTheir email, if known. Defaults to the customer's.
MergeConflict
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
charge_ledger_countNumber of charge-ledger rows 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.
payments_countNumber of payments 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.
How the billable quantity is snapped before pricing (increment + mode). Absent means exact: priced at the metered precision, up to 8 decimal places. Never applied to usage views, analytics, thresholds or pricing variables.
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.
MeterAggregationDefinition
functionAggregation applied: SUM, COUNT, MAX, MIN, AVG, UNIQUE_COUNT, LAST or P95.
metric_keyEvent ingestion key selected. Never snapshotted — identity, not aggregation config.
Reset cadence; an absent duration aggregates over the whole period.
Set when this is a derived meter computed from other meters.
The meter's own predicate.
late_event_policyDROP, CLAMP_TO_PERIOD or REBILL_PRIOR.
The binding's predicate, AND-ed onto the meter's for this product only.
unique_by_fieldEvent field whose distinct values are counted.
value_fieldEvent field aggregated.
MeterBindingMeterSummary
functionidkeynameunit_labelMeterBreach
comparatoridmeter_idmeter_keyobserved_valueoccurred_atorganization_idthreshold_namethreshold_valuedelivered_atproduct_idsubscription_idMeterEvaluation
frommeter_idmeter_keysubscription_idtoWhere the invoice would NOT simply carry the totals above, for this subscription and period. Each entry is a step the pipeline runs AFTER the resolver returned these numbers. Empty means none of the steps this endpoint can evaluate applies - it is not a guarantee that the invoice's lines match these buckets one for one, because one step is not readable from here: whether the billing period SEGMENTS. Segmentation depends on the org's price/tax/FX resolution policy and on boundaries (a tax-rule change, a daily FX split) the preview does not load, and a segmented period bills one line per segment for every aggregation function. The two segmentation causes that ARE readable - a non-additive function, and a product on the latest track whose version can flip mid-period - are reported.
What the invoice pipeline computes for this subscription and period: the product-version snapshot. Absent when the published version does not bill this meter — see billed_absent_reason.
billed_absent_reasonWhy billed is absent.
What the LIVE meter row computes. Not billing truth. Absent when the request did not ask for it.
head_differs_from_billedTrue when head and billed produced different BUCKET SETS - i.e. a meter edit has not reached this subscription's product version yet. Compared per (reset window, price_key, wallet_currency) rather than on one flat total, because each of those three axes fans out into its own invoice line: a reset cadence changed from 24h to 12h keeps the total and changes the bill. Absent when only one side ran.
product_idThe metered product the evaluation was scoped to. usage_events carry product_id, so the same meter under two products measures two different numbers. Absent when the subscription has several candidate products and none of their published versions bills this meter.
MeterEvaluationBucket
event_countHow many usage events fell into this bucket.
fromInclusive start of the reset window this bucket aggregates.
price_keyKeyed-billing axis the events carried; null when the events were not keyed.
toExclusive end of the reset window this bucket aggregates.
valueThe aggregated quantity, as an exact decimal string. Not money — a count of units.
wallet_currencyPer-event wallet pin; null means the customer's preferred-currency cascade applies.
MeterEvaluationRun
One row per (reset window, price_key, wallet_currency) group.
is_billing_truthTrue when an invoice actually consumes this number: a product-version snapshot AND a role of BILLABLE_QUANTITY (the line's quantity) or PRICING_VAR (bound into the price formula). False for the live meter row - which is what you are editing, and which no invoice reads until the consuming products are republished - and false for an INFORMATIONAL binding, which the pipeline evaluates and then consumes nowhere.
sourceWhich definition produced these numbers.
totalSum of every bucket's value, as an exact decimal string. What it means for the invoice: for a BILLABLE_QUANTITY binding the pipeline fans these buckets out into one line per (reset window, price_key, wallet_currency), so this is the sum of those lines' quantities rather than any single line's. Two pipeline steps re-partition AFTER the resolver returns and can break even that identity - a sub-period allowance-refresh cadence and a segmented billing period; whenever either applies to this request it is named in total_caveats.
The reset windows the period tiled into, in order. They tile [from, to) exactly.
binding_idThe product-meter binding whose overlay was applied.
product_version_idThe product version whose snapshot was evaluated. Absent on the live run.
roleHow the pipeline consumes this binding: BILLABLE_QUANTITY, PRICING_VAR or INFORMATIONAL.
MeterEventTest
event_interpreted_asWhich of the two readings the endpoint took of the event object: METADATA means the object itself was treated as the event's properties; INGEST_ENVELOPE means it was treated as an ingest body, whose properties are its metadata member (none when it has no metadata) and whose other fields are usage_events columns no filter path resolves against.
filter_checkedTrue when a non-empty filter_tree was supplied. An empty tree matches every event by definition and is not probed.
indeterminateTrue when the whole-tree predicate evaluated to SQL NULL. The event is still not counted.
Per-leaf verdicts in tree order.
matchedWhether the compiled predicate — the same SQL the invoice's WHERE clause carries — counts this event. True when no filter was supplied. Meaningless when filter_error is set.
schema_checkedTrue when an event_schema was supplied and compiled. False means no schema was tested, not that the event passed one.
Why the schema rejected the event. Empty when it did not.
schema_validWhether the event satisfies the supplied JSON Schema. Meaningless when schema_checked is false.
filter_errorSet when the tree as a whole could not be evaluated because at least one leaf could not be — see that leaf's error. The per-leaf verdicts of the leaves that DID evaluate are still reported; the whole-tree verdict is not, because it is the combined predicate that failed.
MeterFilterLeafResult
fieldThe leaf's dotted path into the event's metadata.
indeterminateTrue when the comparison evaluated to SQL NULL rather than false — almost always because the field is absent from the event. The leaf still does not match; this says why. Meaningless when error is set.
matchedWhat a WHERE clause would do with this leaf. A SQL NULL counts as not matched. Meaningless when error is set.
opThe leaf's comparison operator.
pathChild-index route from the tree root to this leaf, so an editor can line the verdict up with the node being edited. Empty for a single-leaf tree.
errorSet when Postgres refused to EVALUATE this leaf rather than returning true, false or NULL: gt/gte/lt/lte cast the value to numeric, so a present-but-non-numeric value ({"duration":"10s"}) is a cast failure; a malformed jsonpath and an invalid regex fail the same way. The leaf has no verdict - the filter itself needs fixing.
MeterFormula
expressionArithmetic expression over the variable names, e.g. "max(0, calls - free)". Omit with variables omitted to send the empty formula {}, which CLEARS composed_of.
Maps each short name used in expression to the source meter id it draws from.
MeterSchemaIssue
messagepathJSON pointer into the event, empty for the document root.
MeterThresholdBreachedPayload
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.
MeterTotalCaveat
codeWhich re-partitioning step may apply.
messageWhat it does to the number, in one sentence.
MeterWindow
fromInclusive start of the reset window.
toExclusive end of the reset window.
MetricDescriptor
additivityWhether a coarser figure may be derived by summing finer buckets. A semi-additive metric (any stock) may not.
availableFalse for a metric that is declared but not yet served. Present rather than absent so the catalogue does not appear to shrink and grow between releases.
descriptiondimensionsThe closed set this metric may be sliced by. Anything else is refused.
grainskeylabelseries_kindunitderived_fromWhen set, this metric is computed from another at read time rather than stored.
MetricMeta
as_ofThe instant this answer is true as of. For a live query, when it ran. Once rollups exist it is the MINIMUM watermark across every source read — never the freshest — because freshness cascades downward and reporting the level you happened to hit is how a stale month passes for current.
basisWhere the number came from. Rollups land metric by metric, so a mixed response is normal rather than exceptional.
partialTrue when a source was knowingly incomplete. See notes.
timezoneThe IANA zone that actually produced the buckets — which may differ from the one configured, if that could not be resolved.
timezone_fallbackTrue when the configured timezone was unusable and UTC was substituted. Reported rather than hidden.
complete_fromEarliest instant the series is known to be complete from. Absent means unbounded.
currencyISO 4217 code every value is denominated in. Absent for count metrics.
notesPlain-language qualifications on this answer. A number bounded by an accrual horizon or served in a substituted timezone says so here.
MetricPoint
bucketStart of the bucket, in the timezone reported in meta.
imputedTrue when this point was CARRIED FORWARD rather than observed. Only ever true for a stock: a level persists through a bucket in which nothing happened, and that is not the same claim as a measurement.
seriesSeries name. 'total' when unsliced; 'Other' is the folded tail of a top-N breakdown.
valueDecimal STRING, never a JSON number: money is decimal and a float round-trip loses cents.
MetricSeriesResponse
grainlabelmetricseries_kindA STOCK is a level at an instant and must never be summed across buckets; a FLOW is additive over time. This is the difference between a correct chart and one that adds up balances.
series_namesEvery series present, sorted, with 'Other' last. Lets a client build a stable legend without scanning the points.
unitMigrateSubscribersRequest
modeMigration mode: PREVIEW (dry run, no changes), IMMEDIATE (migrate now) or SCHEDULED (migrate at scheduled_at). Matched case-insensitively: the server also accepts the all-uppercase and all-lowercase form of each value. The form published here is the canonical one and is what reads back.
target_versionPlan version to migrate subscribers onto; must be greater than 0.
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.
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.
MilestonePlan
created_atidThe plan's instalments in order, cancelled ones included: a cancelled row is the record that an instalment was dropped rather than forgotten.
organization_idproduct_idThe product whose resolved price the plan's milestones bill a fraction of.
remaining_percentage1 minus the sum of the non-cancelled percentages, as a decimal string. 0.3 means thirty percent of the price is still unallocated.
source_kindWho authored the plan: operator or quote.
statusDRAFT, ACTIVE, COMPLETED or CANCELLED.
subscription_idThe subscription the plan bills against.
titleOperator-facing plan name, e.g. “Implementation 2026”.
updated_atcurrencyOptional ISO 4217 pin. Empty means the plan bills in whatever currency the product's price resolves to.
source_idThe quote line the plan was copied from, when source_kind is quote.
workspace_idOwning workspace (RLS scope).
MinimumSpendCondition
amount^-?\d+(\.\d+)?$ · requiredMinimum 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.
kindUnion discriminator.
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+)?$ · requiredMonetary amount in MAJOR units (e.g. euros, not cents), encoded as a canonical decimal string with trailing zeros trimmed. "10", "10.0" and "10.00" are all valid encodings of the same amount, and the digit count does NOT indicate the currency's minor-unit scale (EUR 49.50 is emitted as "49.5"; KWD 3.100 as "3.1"). Parse into a decimal type and compare numerically — never as strings. Use the sibling "currency" (ISO 4217) to decide display precision.
MutationRecordedPayload
actionA short verb for the mutation: CREATED, UPDATED, REMOVED, ARCHIVED, DELETED, or COPIED.
entity_idThe id of the entity that was mutated.
entity_typeThe kind of entity that was mutated (e.g. PRICE, COST, BINDING).
organization_idrecorded_atWhen the mutation was recorded (RFC3339).
customer_idThe parent customer, when the mutated entity belongs to one.
diffAn optional structured changeset; shape is caller-defined and not uniform.
plan_idThe parent plan, when the mutated entity belongs to one.
product_idThe parent product, when the mutated entity belongs to one.
subscription_idThe parent subscription, when the mutated entity belongs to one.
summaryA human-readable one-liner for the mutation; falls back to "
NegotiatedRung
flat_amount^-?\d+(\.\d+)?$ · requiredFlat component for this rung; its meaning is the pricing model's, exactly as on a catalog tier.
unit_amount^-?\d+(\.\d+)?$ · requiredPer-unit amount for this rung, MAJOR units, in the negotiated rate's currency.
formula_drivenRead-only, and only ever set on a catalog ladder: this tier's catalog rate is computed at billing time (formula or rate expression), so unit_amount is its static fallback rather than the rate that would be charged. Ignored on an agreed ladder.
up_to^-?\d+(\.\d+)?$Inclusive upper quantity bound; the rung covers (previous rung's up_to, up_to]. Null marks the open-ended final rung.
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.
yearThe calendar year the threshold is tracked for.
workspace_idThe workspace this threshold state belongs to.
OrgSecuritySettings
allowed_email_domainsallowed_idpscreated_atjit_default_rolejit_enabledorganization_idrequire_mfaupdated_atsession_timeout_secondsOrganizationContact
categoryWhat this contact receives: quotes_contracts, approvals, finance, operations or reports.
created_atidis_primaryWhether mail for this category is addressed here. At most one row per (workspace, category) can be primary.
kindWhether this row names a shared mailbox, a person, or a role expanded at send time.
organization_idpositionThe slot within the category, 1 to 3. The primary normally holds 1; the others are copied on the mail in position order.
updated_atworkspace_idThe workspace these recipients apply to, so a sandbox alert does not reach the live finance desk.
emailThe mailbox, when kind is email.
nameOptional label for the row, e.g. "Finance desk".
roleThe organisation role, when kind is role. Every active member holding it receives the mail.
user_idThe member, when kind is user.
OrganizationContactCategory
OrganizationResponse
business_addresscreated_atdefault_currencydefault_date_formatdefault_first_day_of_weekdefault_languagedefault_localedefault_number_formatdefault_timezoneidlegal_namemain_emailWhere mail for this organisation lands when no recipient list in its category answers.
namephonesales_audiencesignup_emailThe address the tenant signed up with. An account fact, not a mailbox we send to.
slugstatussupport_emailtax_registration_numberOverviewResponse
currencyfromprevious_fromEchoed so a reader can see exactly what the deltas compare against rather than inferring it.
previous_totoEXCLUSIVE — the window is half-open [from, to).
OverviewTile
availableFalse when this metric is declared but not yet servable. The tile is still returned, with a reason — a missing number that says why is more useful than a plausible wrong one.
delta_abskeylabelpartialpreviousThe same reduction over the immediately preceding window of equal length.
reductionHow the window was collapsed to this number. A FLOW is summed; a STOCK is the level at the end of the window and is never summed across buckets.
series_kindunitvalueDecimal string.
delta_pctPercent change. ABSENT when the previous value was zero: a change from nothing is undefined, not infinite and not +100%.
notesreasonWhy the tile is unavailable.
PaginationBlock
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_currenciesupdated_atworkspace_idlast_verified_atlast_verify_detailWhat the last check found, in the operator's terms. Never contains the credential.
last_verify_okPaymentMethod
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.
provider_method_idProvider-side identifier used to charge this method. Resolved from provider_method_id, falling back to provider_id for methods recorded through the admin API.
PercentageDiscountEffect
kindUnion discriminator.
rate^-?\d+(\.\d+)?$ · requiredPercentage 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.
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).
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.
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.
PinRepointedPayload
organization_idpin_kindWhich id-pin moved: rate_table or formula.
product_idThe product whose version now carries the new pin.
product_version_idThe product version this publish produced.
referenceThe pin's stable name within the version: a rate-table slug, or a price formula's id.
repointed_atWhen the pin moved (RFC3339).
to_version_idThe version this publish captured.
triggerWhy the publish ran: scheduled_publish, publish, or consumer_republish.
change_idThe catalog.publish_version Change that fired, when one did.
from_versionThat version's number; 0 when it could not be read.
from_version_idThe version the row being published was pinned to.
pinned_entity_idThe rate table or price formula itself.
scheduled_forThat Change's instant (RFC3339) — the 'when scheduled' half of the sentence.
to_versionThat version's number; 0 when it could not be read.
workspace_idThe workspace that owns the product.
Plan
created_atidnameInternal operator-facing plan name.
organization_idprice_cadence_unitThe billing period this plan's prices were authored for (week, month or year). A subscription, quote or checkout that bills on a different cadence is refused — nothing scales a resolved amount by period length.
requires_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.
lifecycleDerived entity state: draft, published or archived. It is NEVER 'scheduled' — pending releases live on scheduled_versions, and an entity with one is still whatever it already was and still editable.
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.
Every version scheduled to publish, in the order they will publish. Their rows are FROZEN — they no longer answer GET /{kind}/{id}/draft — so the entity's working draft is free for immediate changes while they stand. The version numbers are PROVISIONAL: head + rank, recomputed whenever the timeline moves.
Tags attached to this plan.
Locale-keyed overrides for name, description and public_description.
PlanDetailResponse
Products the plan's current head version still offers but which are no longer attached to the plan. They keep being sold through quotes, checkout and subscriptions until the plan is published again.
PlanDraftBaseInputBody
base_version_idThe release the working draft is authored on top of — the live head, or one of the plan's scheduled releases (its scheduled_versions[].version_id). Omit for the head. Re-basing an open draft keeps its staged rail edits.
PlanOverridePendingPublish
plan_idThe plan the override is scoped to.
plan_versionThe plan version the override row pins to.
price_idThe PLAN_OVERRIDE price row that exists but did not price this line.
reasonWhy it did not apply, in one line the operator can act on.
PlanPricePreviewItem
product_idProduct this line prices.
quantityNumber of units to price (e.g. seat count).
The agreed tier ladder for this line; omit for a flat rate or for the catalog price.
negotiated_unit_amount^-?\d+(\.\d+)?$The agreed per-unit rate for this line, as a decimal string in major units; omit for the catalog price or when negotiated_tiers carries the ladder.
price_keyKey-set entry to price under; set only for keyed products. Two lines of one keyed product resolve two different prices.
PlanPricePreviewLine
currencypricing_modelproduct_idproduct_namequantityquantity_sourcetax_rate^-?\d+(\.\d+)?$ · requiredDecimal number encoded as a string to preserve precision.
The catalog's authored tier ladder for this line, including rungs this quantity does not reach; empty for a flat price.
errorincluded_quantityPer-rung walk steps showing how this line's amount was built for the quoted quantity.
PlanPricePreviewRequest
plan_idas_ofDate to price for; omit to price for now. Folded to day granularity.
currencycustomer_idplan_versionPublished plan version to price against; omit to price the plan's current head.
PlanPricePreviewResponse
currencyprice_cadence_unitPlanProduct
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).
default_quantityQuantity a new subscription seeds for this product when the caller passes no explicit item; null seeds 1.
included_quantity^-?\d+(\.\d+)?$Quantity bundled into the base price before per-unit billing applies (the included allowance/seat floor); null means none.
max_quantityHighest quantity a buyer may pick for this product; null means no plan-level ceiling.
min_quantityLowest quantity a buyer may pick for this product; null means 1.
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.
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.
is_overrideTrue when this row is the plan's own override — the value of record for billing; false rows are copies of the catalog 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.
PlanPublishImpact
pinned_subscribersplan_idstaged_price_changesPlan overrides with a staged edit this publish would ship; they take effect at publish and not before.
subscriptions_affectedPlanPublishImpactStrategies
at_phase_changeat_phase_change_heldimmediate_proratenext_periodPlanPublishPreflightResult
okTrue when a publish right now would succeed.
codemessagePlanPublishedPayload
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.
PlanVersion
idorganization_idplan_idPlan this published version belongs to.
price_cadence_unitThe billing period this version's prices were authored for (week, month or year).
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.
default_quantityQuantity a new subscription seeds for this product when the caller passes no explicit item; null seeds 1.
included_quantity^-?\d+(\.\d+)?$Quantity bundled into the base price before per-unit billing applies (the included allowance/seat floor); null means none.
max_quantityHighest quantity a buyer may pick for this product; null means no plan-level ceiling.
min_quantityLowest quantity a buyer may pick for this product; null means 1.
plan_product_terms_idMembership terms revision this snapshot row was built from; null for rows predating membership revisions.
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.
Locale-keyed overrides frozen at publish time.
unit_limit^-?\d+(\.\d+)?$Ceiling on a POOL's unit balance; POOL only.
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.
Policy
kindHow the charge is worked out. NONE is a deal that decided leaving is free, which is not the same as saying nothing. FLAT needs amount; PERCENT_OF_REMAINING needs percent; REMAINING_PERIODS needs periods; REMAINING_VALUE bills the whole remainder and DISCOUNT_RECAPTURE bills back the discount already given, and neither takes an input.
The fee a FLAT charge bills, in the deal's own currency. Required by FLAT and ignored by every other kind.
A ceiling on whatever the formula works out at, in the deal's own currency. Orthogonal to kind: "50% of the remainder, up to 10,000" is one clause, not two.
percent^-?\d+(\.\d+)?$PERCENT_OF_REMAINING's share, as a percentage: 50 means 50%. Above 100 is allowed - a punitive clause is a real negotiated term - and cap is how a deal limits it.
periodsHow many billing periods REMAINING_PERIODS bills, each at the rate scheduled for it. Capped by what is actually left, because charging four periods on a term with two to run charges for time that does not exist.
PortalSettings
allow_add_payment_methodallow_cancel_subscriptionallow_invoice_payallow_wallet_topupcreated_atorganization_idshow_billing_settingsshow_invoicesshow_payment_methodsshow_subscriptionsshow_walletsupdated_atPreviewDocumentTemplateRequest
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.
PreviewQuotePriceRequest
Requested quantities per quote line, keyed by quote item id.
starts_atPrice the quote as if it started on this date, without saving it. Omit to use the quote's own start date.
Price
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 or PLAN_OVERRIDE; the more specific kind wins 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 retired (the price fell out of the catalogue at a release that no longer carried it).
updated_atcountry_codeCountry this price is scoped to; null matches any country and country-specific rows outrank generic ones.
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 while the formula has never been published (a newly created formula is a draft).
lifecycleDerived entity state: draft, published or archived. It is NEVER 'scheduled' — pending releases live on scheduled_versions, and an entity with one is still whatever it already was and still editable.
Every version scheduled to publish, in the order they will publish. Their rows are FROZEN — they no longer answer GET /{kind}/{id}/draft — so the entity's working draft is free for immediate changes while they stand. The version numbers are PROVISIONAL: head + rank, recomputed whenever the timeline moves.
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.
The price each matching line is overridden to, with its currency; applied only when it is below the line's current subtotal, so it never raises a charge. The override no-ops on an invoice of a different currency.
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-specific rate 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, rounded at the currency's minor-unit scale. Authoritative for what is charged; see unit_amount for why the two need not multiply out on a converted line.
unit_amount^-?\d+(\.\d+)?$ · requiredEffective per-unit amount, MAJOR units in Currency, at the resolved quantity. This is a RATE and may carry more fractional digits than the currency's minor-unit scale (up to 8). When conversion_applied is true it is rounded independently of total_amount, so unit_amount * quantity is NOT guaranteed to equal total_amount - do not re-derive one from the other.
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_base_leg_idFor a triangulated cross-pair rate, the EUR→original exchange-rate row the applied rate was divided by.
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.
fx_policy_appliedFX timing policy that selected the exchange rate.
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 subscription negotiated price that supplied the applied rate.
override_sourceWhere the applied rate came from: NEGOTIATED, a subscription-scoped negotiated price.
Set when an active PLAN_OVERRIDE price for this plan version exists but was not applied because the plan version has not published it yet; republish the plan to make it effective.
plan_price_idPlan-version price row the value was read from; null when the catalog supplied it.
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.
formula_version_idThe price_formula_versions row this tier is pinned to — captured at product publish from the version active at the version's anchor. A pinned subscription bills this exact formula version; a latest-track one dereferences formula_id to the formula's live head instead, so the two can differ.
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.
lifecycleDerived entity state: draft, published or archived. It is NEVER 'scheduled' — pending releases live on scheduled_versions, and an entity with one is still whatever it already was and still editable.
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).
Every version scheduled to publish, in the order they will publish. Their rows are FROZEN — they no longer answer GET /{kind}/{id}/draft — so the entity's working draft is free for immediate changes while they stand. The version numbers are PROVISIONAL: head + rank, recomputed whenever the timeline moves.
supply_natureWhat the product is for place-of-supply purposes: GOODS, SERVICES or DIGITAL_SERVICES. Empty means undeclared, treated as SERVICES.
Tags attached to this product.
Locale-keyed overrides for name, description and public_description.
ProductActivatedPayload
activated_atWhen the product was activated (RFC3339).
organization_idproduct_idThe product that was activated.
nameThe product name at activation.
workspace_idThe workspace that owns the product.
ProductAllowanceState
billable_usage^-?\d+(\.\d+)?$ · requiredUsage above all allowance that is billed as overage, snapped by the meter's quantity rounding — the quantity the invoice line will carry.
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_purchased^-?\d+(\.\d+)?$ · requiredPurchased balance 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.
purchased_allowance^-?\d+(\.\d+)?$ · requiredDurable balance the customer purchased; consumed after every free rung.
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.
Seat/declared-quantity projection; null for metered products.
included_quantity_sourceProvenance of plan_allowance: PLAN (the plan version's pin) or OPERATOR (a deliberate per-subscription override). Omitted for POOL products, whose allowance is their balance.
plan_pin_quantity^-?\d+(\.\d+)?$The plan version's own included quantity for this product, for comparison against an OPERATOR override; null when the plan pins none.
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).
organization_idproduct_idThe product that was archived.
nameThe product name at archival.
workspace_idThe workspace that owns the product.
ProductCombinationCondition
kindUnion discriminator.
The set of product requirements the basket must jointly satisfy (each an AND term of the bundle).
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.
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).
organization_idproduct_idThe id of the newly created copy.
source_product_idThe product the copy was made from.
nameThe name of the new copy.
workspace_idThe workspace that owns the product.
ProductCreatedPayload
created_atorganization_idproduct_idThe product that was created.
nameThe product name at creation.
pricing_modelThe product's pricing model (e.g. VOLUME, STAIRCASE, PACKAGE).
typeThe product type.
workspace_idThe workspace that owns the product.
ProductDeletedPayload
deleted_atWhen the product was deleted (RFC3339).
organization_idproduct_idThe product that was deleted.
nameThe product name at deletion.
workspace_idThe workspace that owns the product.
ProductDraftBaseInputBody
base_version_idThe version the working draft is authored on top of — the live head, or one of the entity's scheduled versions. Omit for the head. Rebasing an existing draft keeps its edits and re-materialises them over the new base.
ProductMeterBinding
created_atidmeter_idorganization_idproduct_idrolestatusWhether the version being read carries this binding: active, or retired once it has been removed.
updated_atworkspace_idpricing_var_nameProductPoolConfiguredPayload
changed_atWhen the change was applied (RFC3339).
organization_idproduct_idThe product configured as a durable credit pool.
subscription_idThe subscription whose product became a credit pool.
unit_limitMaximum pool balance in units, as a decimal string; empty for no unit ceiling.
workspace_idThe workspace that owns the subscription.
ProductRequirement
product_idProduct the basket must contain for this bundle line to be satisfied.
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.
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: draft, scheduled (published, but valid_from is still in the future), active, expired, budget_exhausted, redemptions_exhausted, archived.
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.
head_versionCatalog number of the head (latest published) version — what the version switcher and version titles count from. Distinct from version, the optimistic-concurrency counter.
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.
announcement_audienceWho this promotion's activation announcement is emailed to: promotion_audience (the promotion's own audience; the per-email audience for this kind is waived; the workspace-wide one still narrows it) or email_audience (that per-email audience applies too, so the announcement reaches the intersection). Empty on promotions authored before this field existed, which behave as email_audience. Decides who is emailed only — enrolment eligibility is the audience field and is untouched by this.
archived_atWhen the promotion was archived; null unless archived.
benefit_on_window_closeWhat the promotion's valid_to means for customers who already redeemed: end (default) expires their benefit along with the promotion; keep lets each redemption run to its own benefit duration. Independent of whether new customers can still redeem — past valid_to nobody can, either way.
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 promotion's effects, and what they apply to.
head_version_idID of the current head (latest published) promotion version.
lifecycleDerived entity state: draft, published or archived. It is NEVER 'scheduled' — pending releases live on scheduled_versions, and an entity with one is still whatever it already was and still editable.
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.
Every version scheduled to publish, in the order they will publish. Their rows are FROZEN — they no longer answer GET /{kind}/{id}/draft — so the entity's working draft is free for immediate changes while they stand. The version numbers are PROVISIONAL: head + rank, recomputed whenever the timeline moves.
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_idsLegacy flat shadow of the rule tree, ignored when definition is set: explicitly picked customers, unioned with the tag/fact branch.
customer_typesAny-of customer types the customer must be one of (BUSINESS, CONSUMER, UNKNOWN); empty = no type constraint.
The full rule tree this promotion's audience matches by. When set it is the whole audience and the flat fields above are ignored. Applying a saved audience copies its rules here; there is no link back to the library entry.
tag_idsLegacy flat shadow of the rule tree, ignored when definition is set: customer-tag IDs the audience targets per tag_match.
tag_matchLegacy flat shadow of the rule tree, ignored when definition is set: how tag_ids combine, any (default) or all.
PromotionBudgetExhaustedPayload
exhausted_atWhen the budget was exhausted (RFC3339).
organization_idpromotion_idThe promotion whose budget was exhausted.
Total budget consumed at exhaustion, as a money object; absent when the promotion's budget predates migration 083 and names no currency, since a currency-less amount cannot form a valid money object.
The configured maximum budget in the promotion's budget currency, as a money object; absent when the promotion carried no budget cap, or when its budget predates migration 083 and names no currency.
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.
PromotionDefaultsBody
announcement_audienceWho a NEW promotion's activation announcement is emailed to: promotion_audience (the promotion's own audience decides, and the audience set for that one email is waived) or email_audience (that per-email audience applies too, so the announcement reaches the intersection of the two). The WORKSPACE-wide email audience on mail_defaults narrows both — it is a standing statement about who receives customer email at all and a promotion cannot reach past it. Omit for no preset. Decides who is EMAILED only; it never changes who may enrol in or redeem a promotion.
application_timingWhen a NEW promotion first takes effect once redeemed. Omit for no preset, which means the next billing cycle.
archetypeThe authoring preset a NEW promotion is filed under. A display and filter hint, not rule logic. Omit for no preset, which means generic.
budget_behaviorWhat a NEW promotion does when a redemption would exceed its budget cap: SKIP it entirely, or apply PARTIAL up to what is left. Omit for no preset, which means SKIP.
condition_modeWhether a NEW promotion requires ALL of its eligibility conditions to pass or ANY one of them. Omit for no preset, which means ALL.
priorityOrdering priority a NEW promotion starts with; higher applies first and wins inside a stacking group. Omit for no preset, which means 0 — and note that presetting 0 deliberately is a real choice this field can express, distinct from omitting it.
stacking_modeHow a NEW promotion combines with others on the invoice pass. Omit for no preset, which means it stacks. Only promotions created after this is set are affected — existing promotions keep whatever they were created with.
PromotionDefaultsEffective
announcement_audienceWhat a new promotion gets for this field if the author leaves it blank.
application_timingWhat a new promotion gets for this field if the author leaves it blank.
archetypeWhat a new promotion gets for this field if the author leaves it blank.
budget_behaviorWhat a new promotion gets for this field if the author leaves it blank.
condition_modeWhat a new promotion gets for this field if the author leaves it blank.
Per field, where the effective value came from: "preset" if this workspace set it, "built_in" if nothing did.
priorityWhat a new promotion gets for this field if the author leaves it blank.
stacking_modeWhat a new promotion gets for this field if the author leaves it blank.
PromotionDefaultsResponse
The built-in values the system applies when this workspace has no preset for a field. Fixed in code; shown so a create form can say what a blank field will inherit.
What a new promotion starts with when its author leaves every one of these fields blank — the preset folded over the built-in values.
source"stored" when a preset has been saved, "default" when nothing has ever been set for this workspace.
workspace_idThe workspace this preset applies to. It is stored per workspace: setting it here leaves your other workspaces untouched.
announcement_audienceWho a NEW promotion's activation announcement is emailed to: promotion_audience (the promotion's own audience decides, and the audience set for that one email is waived) or email_audience (that per-email audience applies too, so the announcement reaches the intersection of the two). The WORKSPACE-wide email audience on mail_defaults narrows both — it is a standing statement about who receives customer email at all and a promotion cannot reach past it. Omit for no preset. Decides who is EMAILED only; it never changes who may enrol in or redeem a promotion.
application_timingWhen a NEW promotion first takes effect once redeemed. Omit for no preset, which means the next billing cycle.
archetypeThe authoring preset a NEW promotion is filed under. A display and filter hint, not rule logic. Omit for no preset, which means generic.
budget_behaviorWhat a NEW promotion does when a redemption would exceed its budget cap: SKIP it entirely, or apply PARTIAL up to what is left. Omit for no preset, which means SKIP.
condition_modeWhether a NEW promotion requires ALL of its eligibility conditions to pass or ANY one of them. Omit for no preset, which means ALL.
priorityOrdering priority a NEW promotion starts with; higher applies first and wins inside a stacking group. Omit for no preset, which means 0 — and note that presetting 0 deliberately is a real choice this field can express, distinct from omitting it.
stacking_modeHow a NEW promotion combines with others on the invoice pass. Omit for no preset, which means it stacks. Only promotions created after this is set are affected — existing promotions keep whatever they were created with.
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_idpromotion_idThe promotion that produced the discount.
The total discount applied, as a money object.
phase_idThe phase that produced the effect, when phased.
redemption_idThe redemption that produced the effect, when tracked.
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).
organization_idpromotion_idThe promotion the redemption belongs to.
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.
from_phase_idThe phase the redemption left; null on initial entry.
from_phase_orderThe ordinal of the phase left; null on initial entry.
reasonOptional explanation of 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.
Human-readable summaries of this version's entry-phase eligibility conditions.
descriptionInternal description at this version.
Human-readable summary of this version's effects, and what they apply to.
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.
The rule at this version, in the canonical phase shape the live promotion uses.
published_byID of the user who published this version.
rule_preview_unavailableTrue when the timeline could not preview this version's rule; the rule shown is the predecessor's.
rule_sourceWhere the rule was read from: live (the head version reads the live tables), mirror (a published or queued version reads its own per-version mirrors), draft_overlay (the working draft's staged delta over the live rule).
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.
ProviderDescriptor
availableFalse when no gateway factory exists yet: shown as coming soon, not connectable.
Config keys this provider's credential document accepts.
display_nameVendor's own name, unlocalised.
idProvider slug, e.g. stripe.
What the provider can do. Absent while a provider is coming soon.
PublishImpact
pinned_subscribersplan_countplan_subscribersproduct_idproduct_subscriberssubscriptions_affectedPublishImpactPlan
plan_idplan_namecurrent_product_versionPublishImpactStrategies
at_phase_changeat_phase_change_heldimmediate_proratenext_periodPutCredentialRequest
refThe locator to store it under — the same string a channel's credentials_ref names.
secretThe credential itself. Sealed at rest under the organization's own key and never returned by any endpoint; writing again replaces it, which is how rotation works.
labelOperator-facing name for this credential.
QuantityChange
new_quantityNew quantity to bill for the item; must be at least 1.
subscription_item_idThe subscription item to restate the quantity on.
QuantityRounding
increment^-?\d+(\.\d+)?$ · requiredStep the billable quantity is snapped to, e.g. "1" (whole units), "0.01", "1000". Positive, at most 8 decimal places.
modeWhich multiple of the increment a value between two of them lands on: DOWN, UP or NEAREST (halfway rounds up). Matched case-insensitively: the server also accepts the all-uppercase and all-lowercase form of each value. The form published here is the canonical one and is what reads back.
QuantityThresholdCondition
kindUnion discriminator.
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).
max_quantityOptional inclusive upper bound; when set the summed quantity must fall within [min_quantity, max_quantity].
Quote
contract_termsContract terms rendered to the buyer.
created_atcurrencyISO 4217 currency of value_amount and all line amounts.
customer_idCustomer the quote addresses.
document_template_frozenTrue once the quote was sent and its layout was frozen. From then on the document renders from the frozen copy and template edits cannot reach it; returning the quote to DRAFT clears it.
free_trial_daysDays of free trial this offer sells before billing starts; 0 means billing starts on activation.
governed_operationsWhich operations the early-termination gate applies to. Null means the offer did not say and the agreement it mints governs cancel. An EMPTY ARRAY is the offer saying the term governs nothing at all; the two are different and must not be collapsed.
idkindWhat a signature orchestrates: NEW_SUBSCRIPTION, SUBSCRIPTION_UPDATE, or ONE_OFF.
note_for_customerNote rendered to the buyer on the public page.
orchestration_attemptsHow many times provisioning has been attempted. Survives a later success.
orchestration_modeAUTO orchestrates on signature; MANUAL waits for an operator.
orchestration_statusWhere provisioning stands: NOT_APPLICABLE (not signed), PENDING (armed), MANUAL (an operator provisions this by hand), RETRYING (transient failure, the rail will try again), FAILED (terminal failure, needs an operator), SUCCEEDED.
organization_idquote_numberPer-org sequential number (QUO-
require_payment_methodBuyer must register a payment method before signing.
require_shippingBuyer must supply a shipping address before signing.
require_vat_idBuyer must supply a VAT id before signing.
signature_modeHow the buyer signs: BASIC (typed name), OTP (email code), or EXTERNAL (wet-ink, operator-recorded).
sourceCreation channel (e.g. DASHBOARD).
statusLifecycle status: DRAFT, PENDING_APPROVAL, APPROVED, CHANGE_REQUESTED, SENT, VIEWED, SIGNED, DECLINED, EXPIRED, or VOIDED.
titleOperator-facing title.
updated_atQuote value in major units, as a currency-tagged amount.
value_autoTrue while value_amount tracks the line sum; an operator value override flips it off.
versionRevision counter; Revise bumps it.
view_countTotal public-page views.
workspace_idaction_at_term_endWhat this offer says happens when the agreed term runs out. Absent means the offer did not say and the agreement it mints continues without a term: the negotiated rates lapse and the subscription carries on at catalogue prices.
auto_renewWhether the subscription this quote provisions renews at period end. Null inherits the organization default.
billing_anchor_dayDay of month (1-28) the provisioned subscription anchors its billing period to. Null inherits the organization default, then derivation from the start date.
Clause snapshots picked from the library; populated on single-quote reads.
co_terminate_with_subscription_idThe subscription whose live agreement this offer's deal ends together with, joining its co-termination group at signature. Absent when the deal ends on its own agreed term.
What coupon_code does, in words; populated on single-quote reads when a code is set. Carries no amount by design.
coupon_codePromotion coupon the buyer redeems at orchestration.
created_byOperator user who created the quote.
custom_fieldsOrg-scoped custom field values.
What the offer says happens later, in order: an offset from the deal's start, and the plan, quantities and agreed prices in force from then.
decline_reasonBuyer's decline reason.
declined_atDecline instant.
display_nameHuman name for this quote: "". Derived at read time from the customer it addresses; never stored.
document_template_idDocument template this quote renders through. Null means the organization's quote default; a value that no longer resolves falls back to it too.
What this offer says the customer owes for ending the subscription before the agreed term is up. Absent means the offer did not say and nothing is charged; an explicit kind of NONE is the offer deciding that leaving is free.
early_termination_gateWhat happens when a governed operation is attempted inside the term. Absent means the offer did not say and the agreement gets WARN.
expires_atPublic-link expiry; the sweep flips live quotes past it to EXPIRED.
first_viewed_atFirst public-page view.
Governing invoicing law, resolved once at send and frozen with the tax determination. Read-only. Absent on drafts and where the resolution was refused.
Priced lines; populated on single-quote reads.
last_viewed_atMost recent public-page view.
localeLanguage the offer is for (en, de, fr, es, it, pt, nl, ja): the PDF's render language, the buyer mail's copy language, and the language a clause body is snapshotted in. Null inherits the customer's locale, then the organization default.
Arbitrary caller-supplied key/value pairs.
negotiated_term_countHow many negotiated_term_unit periods the agreed rates hold for, measured from the subscription start. Always paired with negotiated_term_unit.
negotiated_term_unitUnit of the term the agreed rates on this offer hold for. Absent means the rates are open-ended. Always paired with negotiated_term_count.
notice_countHow many notice_units a cancellation asked for inside the term waits before it takes effect, clamped to the end of the term.
notice_unitUnit of the notice a cancellation requires. Absent means a cancellation takes effect at once. Not term_end_reminder_days, which announces that the term is ending.
orchestrated_atWhen provisioning landed. Null on quotes orchestrated before this column existed.
orchestrated_invoice_idOne-off invoice issued by orchestration; set once.
orchestrated_subscription_idSubscription created/applied by orchestration; set once.
orchestration_errorLast attempt's failure message, verbatim. Operator-facing; cleared when provisioning succeeds.
orchestration_error_codeDomain code of the last failure (DUPLICATE, CONFLICT, VALIDATION, ...) for a typed operator hint.
orchestration_last_attempt_atWhen provisioning was last attempted.
owner_user_idOperator user owning the quote.
plan_idPlan backing the quoted lines (plan-backed quotes).
plan_versionPinned plan version the line snapshots were built from.
preset_idQuote preset the quote was prefilled from.
referenceShort human id, unique within the organization and stable for the quote's life. For a quote this IS quote_number, repeated under the name every referenced object uses.
What the buyer must answer before signing. Each entry names a custom-field key, WHERE the answer goes after signature (target: DOCUMENT_ONLY keeps it on the offer, CUSTOMER and SUBSCRIPTION write it through) and what happens when the destination already holds a value (on_conflict).
sent_atWhen the quote was released to the buyer.
Invoicing overrides the provisioned subscription is created with: line grouping, price resolution, default proration mode and payment terms. Absent when the offer inherits all four.
Signature summary; populated on single-quote reads when a signature exists.
signed_atSignature instant.
The buyer's signing link, returned ONCE. Present only on the response to a send/reissue made while no email rail is bound for this organization, so nothing else can deliver it. Never returned by a read: copy it now or reissue it.
source_subscription_idSubscription being updated; SUBSCRIPTION_UPDATE only.
starts_atWhen the offer begins. The lines were priced against the catalog as of this date, and the provisioned subscription starts on it. Null means on signature: priced at the moment of authoring, provisioned immediately.
successor_plan_idPlan the subscription moves onto when the term ends. Present only with action_at_term_end SWITCH_PLAN.
term_end_reminder_daysHow many days before the term ends the customer is given notice. Absent means no notice is promised. Always present with RENEGOTIATE, which drafts the renewal quote on that day.
update_effectiveWhen a SUBSCRIPTION_UPDATE applies: ON_SIGNATURE or SCHEDULED.
update_effective_dateScheduled apply date; required when update_effective is SCHEDULED.
version_change_strategyMoney policy when a latest-tracking subscription moves version. Null inherits the organization default. Always present when version_track_mode is latest.
version_track_modeHow the subscription this quote provisions follows plan/product versions (pinned|latest). Null means the offer inherits the organization default. Distinct from plan_version, which is the version the offer was priced against.
voided_atVoid instant.
QuoteApprovedPayload
customer_idorganization_idquote_idThe quote whose pending approval was granted.
approved_byOperator user who approved.
QuoteClause
auto_attachedTrue when the clause came from a product, plan or preset attachment rather than an operator pick.
bodySnapshot text as sent; a later library edit never mutates it.
clause_idmodifiedTrue when the snapshot body was edited after insertion.
nameLibrary clause name at read time; empty when the library clause was deleted.
sortQuoteClauseInput
clause_idLibrary clause to snapshot onto the quote.
bodyOptional override of the library text; empty snapshots the library body.
sortDisplay order among the quote's clause snapshots.
QuoteCoupon
codeThe coupon code stored on the quote.
honored_by_kindFalse when this quote's kind never redeems a coupon (only NEW_SUBSCRIPTION does), which makes the stored code inert.
lookupWhy effects is or is not populated: RESOLVED (the code names an active coupon), NOT_FOUND (it no longer does), UNAVAILABLE (the lookup failed - nothing is known), SKIPPED (the quote's kind ignores coupons, so no lookup was made).
descriptionPromotion's customer-facing description; present only when the code resolved and one is authored.
effectsHuman-readable descriptions of what the coupon does, one per effect, in phase order. Descriptions only - no amount is computed.
inapplicable_effectsEffects pinned to a currency other than the quote's; the engine skips these at invoicing, so they are reported apart from effects rather than promised.
nameOperator-facing promotion name; present only when the code resolved.
QuoteCreatedPayload
customer_idCustomer the quote addresses.
kindNEW_SUBSCRIPTION | SUBSCRIPTION_UPDATE | ONE_OFF.
organization_idquote_idThe quote that was created.
quote_numberPer-org sequential number (QUO-
created_byOperator user who created the quote.
workspace_idThe workspace that owns the quote.
QuoteDeclinedPayload
customer_iddeclined_atRFC 3339 decline instant.
organization_idquote_idThe declined quote.
reasonBuyer's decline reason.
QuoteEvent
actor_typeWho caused the event: OPERATOR, CUSTOMER, or SYSTEM.
created_atidquote_idtypeTracking event type (CREATED, SUBMITTED, APPROVED, SENT, VIEWED, SIGNED, ...).
actor_idippayloadEvent-type-specific extra data.
user_agentQuoteExpiredPayload
customer_idexpired_atRFC 3339 instant the expiry was applied (sweep or opportunistic flip).
organization_idquote_idThe quote that expired.
QuoteInput
blockingTrue when a quote cannot be sent until this input is satisfied.
keyWhich quote input the layout prints.
Every block that carries this input, in document order. Counts PLACES IN THE LAYOUT, not printings: a repeat-zone block prints once per page, and a block nested in a column renders a placeholder instead of the value.
custom_fieldCustom-field key the layout prints; set only when key is custom_field.
QuoteInputSource
block_typeBlock type that carries this input, e.g. quote_validity, key_value or acceptance_terms.
block_idID of the block within the template. Distinguishes two blocks of the same type.
QuoteInvoicingSettings
default_proration_modeProration mode applied when a change on the provisioned subscription names none. Omit to inherit.
line_groupingHow the provisioned subscription's invoice lines are grouped. Omit to inherit.
payment_terms_daysNet payment window in days for the provisioned subscription's invoices. Omit to inherit.
price_resolution_policyWhen the provisioned subscription resolves prices. Omit to inherit.
QuoteItem
adjustableBuyer may adjust the quantity within [min_quantity, max_quantity].
Line total in major units, as a currency-tagged amount.
idincluded_quantityFree floor; only quantity above it bills.
min_quantityproduct_idproduct_namequantityquantity_sourceDECLARED lines bill the quoted quantity; METERED lines bill from real usage.
sortPer-unit price in major units, as a currency-tagged amount.
billing_intervalInterval unit (week|month|year) for recurring lines.
max_quantityThe agreed rate steps during the term, ascending by offset; empty when the line's agreed rate holds flat. The opening rate is negotiated_unit_amount, never a step.
The agreed tier ladder for this line; empty when the line was agreed at a single flat rate.
The agreed per-unit rate for this line; null when the line is at the catalog price. With negotiated_tiers it is the ladder's first rung.
price_keyKey of the product's key set this line offers; null for unkeyed lines.
price_version_idPinned price row the line resolved to.
pricing_modelPricing model the line's rungs are walked at: VOLUME, STAIRCASE or PACKAGE. Absent on a hand-authored line. Read it before rendering negotiated_tiers[].flat_amount, whose meaning it decides.
pricing_snapshotFrozen resolved price config; a later catalog change never mutates a sent quote.
QuoteItemInput
product_idproduct_namequantityunit_amountadjustablebilling_intervalincluded_quantitymax_quantitymin_quantityScheduled changes to this line's agreed rate during the term, ascending; omit for a rate that holds flat.
The agreed tier ladder for this line, ascending, at most one open final rung; omit for a flat rate or the catalog price.
negotiated_unit_amountThe agreed per-unit rate for this line, as a decimal string in major units; omit for the catalog price or when negotiated_tiers carries the ladder.
price_keyKey of the product's key set this line offers. Required for keyed products, omitted for unkeyed ones.
QuoteLineQuantity
item_idQuote item to restate the quantity on.
quantityRequested quantity for that line.
QuoteOrchestratedPayload
customer_idorganization_idquote_idThe quote that was orchestrated.
charge_errorNon-fatal reason the ONE_OFF auto-charge of the buyer-collected payment method did not complete; the invoice stays open for dunning.
coupon_errorNon-fatal reason the quote's coupon code was not enrolled; the orchestrated outcome stands.
invoice_idOne-off invoice created by orchestration.
promotion_idPromotion the quote's coupon code enrolled the customer into.
redemption_idRedemption created by the coupon enrollment.
subscription_idSubscription created/updated by orchestration.
QuoteOrchestrationRequestedPayload
customer_idorganization_idprevious_statusOrchestration status the retry replaced (FAILED, RETRYING or PENDING).
quote_idThe signed quote whose provisioning should run again.
quote_numberrequested_atRFC 3339 instant the re-run was requested.
requested_byOperator user who asked for the re-run.
workspace_idQuotePreset
activeInactive presets stay selectable on existing quotes but hidden from pickers.
contract_termscreated_atdescriptionidnamenote_for_customerWhat quotes from this preset demand of the buyer before signing, destinations included. This is what lets two presets ask for two different things.
require_payment_methodrequire_shippingrequire_vat_idupdated_atauto_renewWhether subscriptions provisioned from this preset's quotes renew at period end. Absent inherits the organization default.
billing_anchor_dayDay of month (1-28) those subscriptions anchor their billing period to. Absent inherits the organization default.
default_expiry_daysPublic-link lifetime in days for quotes created from this preset.
document_template_idDocument template quotes from this preset render through. Absent means the organization's quote default; a value that no longer resolves falls back to it too.
plan_idplan_versionversion_change_strategyMoney policy when a latest-tracking subscription moves version. Absent inherits the organization default. Always present when version_track_mode is latest.
version_track_modeHow subscriptions provisioned from this preset's quotes follow plan/product versions (pinned|latest). Absent inherits the organization default.
QuoteProvisioningFailedPayload
occurred_atWhen the run stopped for good (RFC3339).
organization_idquote_idThe signed quote whose provisioning stopped.
codeThe typed error code, when the failure had one.
messageWhat the provisioning run said when it stopped.
workspace_idThe workspace that owns the quote.
QuoteRejectedPayload
customer_idorganization_idquote_idThe quote whose pending approval was rejected (status CHANGE_REQUESTED).
reasonRejection reason shown to the quote owner.
rejected_byOperator user who rejected.
QuoteRemindedPayload
customer_idorganization_idquote_idThe quote the buyer was reminded about.
quote_numberreminded_atRFC 3339 reminder instant (billing clock).
workspace_idQuoteReprice
Lines after clamping/applying the requested quantities.
Quote total in major units, as a currency-tagged amount.
QuoteSentPayload
customer_idorganization_idquote_idThe quote that was sent.
quote_numbersent_atRFC 3339 send instant (billing clock).
workspace_idQuoteSignature
countersign_pendingTrue while the counterparty has signed and the organisation has not.
envelope_idevidence_availableTrue once the evidence record — who signed, when, from where, having accepted what wording — has been produced.
executed_document_availableTrue once the signed document can be downloaded from /quotes/{id}/signature/document.
providerWhich signing strategy is driving it; "builtin" is this product's own portal flow.
recorded_by_operatorTrue when an operator recorded a signature made outside the portal, from an uploaded copy.
Every party, in position order, including copies.
statusWhere the signature request stands.
cancel_reasonWhy the request was withdrawn. SUPERSEDED means a newer one replaced it.
cancelled_atcompleted_atcountersignWhat the organisation does once the counterparty has signed, as this request was released: NONE, SEAL or PERSON.
countersigned_atcountersigner_emailcountersigner_nameThe person who signs for the organisation, under a PERSON countersignature.
declined_atdocument_sha256SHA-256 of the document presented for signature.
expires_atrecorded_byThe user who recorded it.
seal_methodledger_anchor — tamper-evident over the archival hash chain, and NOT a qualified electronic seal — or provider.
seal_nameThe legal person the seal speaks for, as named at the moment it was applied.
sealed_atWhen the organisation's seal was applied.
sent_atQuoteSignedPayload
currencyISO 4217 currency of value_amount and all line amounts.
customer_idkindNEW_SUBSCRIPTION | SUBSCRIPTION_UPDATE | ONE_OFF.
methodSignature method: BASIC | OTP | EXTERNAL.
orchestration_modeAUTO orchestrates on signature; MANUAL waits for an operator.
organization_idquote_idThe signed quote (re-read key for the orchestrator).
signed_atRFC 3339 signature instant.
value_amountQuote value in MAJOR units, denominated in currency.
signer_emailsource_subscription_idSubscription being updated; SUBSCRIPTION_UPDATE only.
workspace_idQuoteSigner
auth_levelHow this party's identity was established.
emailroleSIGNER binds; CC is kept informed and has no link.
statusaddress_provenanceconsent_textThe exact wording this party accepted.
decline_reasonThe signer's own words.
declined_atnamenotified_atsigned_atviewed_atWhen they FIRST opened it. Repeat opens are in the chronology, not here.
QuoteSigning
What this caller may do to the request right now, computed from the same rules the write paths enforce.
The request's most recent chronology rows, oldest first. Empty when there is no request. Bounded: a buyer who opens their signing link two hundred times writes two hundred rows, and this read is a screen rather than the evidence record.
events_truncatedOlder rows were cut. There is no cursor: the complete account of what happened is the evidence record, which this is not.
The signature request. Absent until the offer has been sent for signature at least once.
QuoteSigningCapabilities
can_countersignTrue when THIS user may sign for the organisation on this request now.
can_download_signed_copyGET /quotes/{id}/signature/document will serve bytes.
can_record_paper_signatureA signature made outside the portal can still be recorded.
can_reissueThe signing link can be replaced; the old one dies at once.
can_remindSomebody is still to act AND the request's own reminder cadence allows another nudge now.
can_sendSending for signature would release the offer.
can_withdrawThe request can be withdrawn. FALSE once anybody has signed.
has_portal_signatureSomebody has already signed in the portal. It is the reason can_withdraw is false, published so the refusal can be explained rather than left as a greyed control.
countersign_waiting_onremind_available_atWhen the next reminder becomes allowed. Present only while can_remind is false because the request was reminded too recently; absent when the reminder budget is spent or nobody is left to nudge.
QuoteSigningEvent
actor_kindWho caused it.
created_atseqMonotonic per request. Two rows written in one transaction share a timestamp; this is what orders them.
typeWhat happened.
actor_refHow the domain recorded them — a user id, an address, or a vendor's name.
ipip_kindWhere the address came from. One that arrived on a forwarded header is weaker evidence than one the socket reported, and the difference is stated rather than hidden.
notesigner_emailThe party this row belongs to. Absent on rows about the request as a whole.
user_agentQuoteSigningLink
expires_atWhen the link is advertised as expiring. A later reissue invalidates it sooner.
urlThe buyer's signing URL, carrying their bearer token. Shown once; it cannot be read back.
QuoteUpdateDiff
Products to add to the subscription; only product_id and quantity are priced.
Quantity restatements on existing subscription items.
change_versionPlan version to repin onto; null leaves the version unchanged.
new_plan_idPlan to retarget the subscription onto; null leaves the plan unchanged.
remove_item_idsSubscription item ids to stop billing.
QuoteViewedPayload
customer_idorganization_idquote_idThe quote that was viewed for the first time.
viewed_atRFC 3339 first-view instant.
RampStep
starts_after_countHow many starts_after_unit periods after the deal begins this step takes effect.
starts_after_unitUnit of the offset from the deal's start.
unit_amount^-?\d+(\.\d+)?$ · requiredPer-unit amount from this step onward, MAJOR units, in the deal's currency.
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.
lifecycleDerived entity state: draft, published or archived. It is NEVER 'scheduled' — pending releases live on scheduled_versions, and an entity with one is still whatever it already was and still editable.
Every version scheduled to publish, in the order they will publish. Their rows are FROZEN — they no longer answer GET /{kind}/{id}/draft — so the entity's working draft is free for immediate changes while they stand. The version numbers are PROVISIONAL: head + rank, recomputed whenever the timeline moves.
RateTableEntry
value^-?\d+(\.\d+)?$ · requiredThe 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.
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.
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.
idoriginWho made this version: manual, scheduled_release, or cascade.
rate_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.
published_atWhen this version was published; null while draft.
published_byThe user who published this version.
release_nameOperator-given name of this version, shown beside its number.
release_noteFree-text note describing this version's change.
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 or PLAN_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.
ReadinessFindingView
codelabelmessagepartyrule_idseveritysurfacefacthintkindReadinessItemView
labelstatefacthintkindvalueReadinessSurfaceView
completemissing_countsurfaceReadinessView
advisory_countatblocker_countgoverning_jurisdictionlocaleprofiledRecipientPreview
categoryThe recipient list this row is about.
ccThe category's other addresses, copied on the mail, in slot order.
toThe address mail for this category is sent to. Empty when there is nobody: the send would record a blocked message.
viaWhere this answer came from: the category's own list, the fallback list, the main address, the next address because the chosen one is suppressed, or nobody.
RecordManualPaymentRequest
amount^-?\d+(\.\d+)?$ · requiredMAJOR units, in the addressed invoice's currency.
sourcecurrencyOptional echo-guard: must equal the invoice's currency when set.
notereceived_atreferenceRedeemPromotionRequest
customer_idCustomer to redeem the promotion for; required.
coupon_codeCoupon code, required when the promotion's distribution is COUPON.
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.
tokenThe customer-locked coupon token to redeem; required.
subscription_idSubscription to scope the redemption to, when applicable.
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.
reason_noteOptional free-text justification in the operator's own words. INTERNAL: shown to the approver when the invoice.refund checkpoint is on and stamped into payment-provider metadata; never shown to the 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.
RegisterFactsView
in_liquidationlegal_formseat_regionshare_capital_currencyshare_capital_minorRegistration
CountryIDSchemeRegistrationSchemeOption
countryISO 3166-1 alpha-2 of the state the register belongs to.
descriptionWhat the registration covers, and what it does not.
labelShort name of the register, in English.
schemeScheme identifier, e.g. GB_VAT, VOEC, OSS.
RegistryCurrency
chargeable_via_providerAdvisory: whether any integrated payment provider can charge this currency. false = invoicing/bank-transfer only.
codeISO 4217 code, uppercase.
scaleMinor-unit decimal places (0 for JPY, 2 for EUR, 3 for KWD, 4 for CLF).
minor_unit_nameHuman name of the minor unit (cent, fils, ...), when one exists.
RemoveItemRequest
subscription_item_idThe subscription item to stop billing.
proration_modeHow the removal is credited: pro_rata or do_not_charge. Omit to inherit the subscription's settings.default_proration_mode; an inherited pay_in_full credits pro_rata here, since a removal cannot credit an unearned full period.
RenameAudienceRequest
nameNew operator-facing name.
descriptionNew description. ABSENT MEANS EMPTY: this endpoint replaces both naming fields, it does not merge them.
RepairRedemptionPhaseRequest
reasonWhy the phase is being moved by hand. Required, and recorded on the transition.
to_phase_idThe phase of THIS promotion to point the redemption at. Omit for the promotion's entry phase.
RepairRedemptionPhaseResponse
recordedFalse when a concurrent automatic transition won: nothing was written, and the redemption returned is the value that beat this request.
The redemption after the move.
to_phase_idThe phase the redemption now points at.
to_phase_orderThe ordinal of that phase.
from_phase_idThe phase the redemption was pointing at; null when the pointer was unset, which is the fault this repairs.
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.
RequiredCustomField
keyCustom-field key from the organization's catalog.
targetWhere the answer goes after signature. DOCUMENT_ONLY keeps it on the offer.
on_conflictWhat happens when the destination already holds a value. Required for CUSTOMER and SUBSCRIPTION; must be absent for DOCUMENT_ONLY, which never writes.
ReserveOutcomeEventPayload
customer_idThe customer the reservation belongs to.
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.
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.
errorThe failure detail, when the outcome failed.
price_keyThe price key resolved for the reservation, when known.
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.
metric_keyMetric being consumed; must match the product's meter binding.
product_idMetered product being consumed; drives price resolution.
quantity^-?\d+(\.\d+)?$ · requiredNumber of metric units to reserve; must be greater than zero.
subscription_idSubscription the usage is charged under.
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.
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.
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, 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
product_idProduct whose price to resolve.
quantity^-?\d+(\.\d+)?$ · requiredQuantity to price; must be positive. Drives the tier walk and formula tier_quantity binding.
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. SEND THIS whenever the product is priced in more than one currency: currency is not a ranking term in the cascade, so an unpinned resolve over a multi-currency slot picks a stable but arbitrary row (and that row becomes the FX source). A pin the catalog cannot satisfy is not an error - it degrades to the catalog currency and converts into the pinned one, reporting conversion_applied plus original_currency and exchange_rate.
customer_idThe customer this resolution is for. It scopes currency preference and the audit record; it does not select a price — the catalog has no customer-scoped prices.
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.
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 or PLAN_OVERRIDE. A negotiated rate is not a cascade level — it is applied above the cascade and reported through override_applied / override_source.
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.
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_expiryScheduledVersion
change_idThe pending catalog.publish_version Change — reschedule or cancel it here.
versionThe version number it will publish as; 0 when the kind cannot say until it publishes.
version_idThe frozen version row that is scheduled to publish.
base_version_idThe version this one publishes on top of — the head for the first pending release, the preceding pending release for the rest. Absent when nothing is live yet.
scheduled_forWhen the publish is due. Absent for a symbolic 'when' that has not resolved to an instant.
ScopeTarget
idThe product or plan id.
kindWhat the target is: product or plan.
nameDisplay name; falls back to a shortened id when the entity could not be resolved (deleted, or out of scope).
excludedTrue when the effect scope EXCLUDES this product rather than targeting it.
SeatPolicy
adjustablecreated_atidlink_idproduct_idupdated_atdefault_qtymax_qtymin_qtySeatPolicyInput
product_idadjustabledefault_qtymax_qtymin_qtySegmentRule
applied_tag_idcreated_atidis_activemetricoperatororganization_idupdated_atvalue^-?\d+(\.\d+)?$ · requiredDecimal number encoded as a string to preserve precision.
deleted_atSendQuoteCountersigner
emailTheir address, recorded on the request.
nameThe name as it should appear on the signed copy.
user_idThe team member who will sign. Omit to let any authorised colleague countersign.
SendQuoteRecipient
emailWhere the offer goes.
nameWho this is, as it should appear on the request.
SendQuoteRequest
countersignWhat your organisation does once the counterparty has signed. SEAL marks the signed copy in the organisation's name automatically. PERSON waits for the person named in countersigner. NONE finishes on the counterparty's signature. Omit to use the organisation's setting.
The person who signs for your organisation. Required when countersign is PERSON; ignored otherwise.
expires_atWhen the signing link should stop working. Clamped to the offer's own validity — it cannot outlive the offer it presents. Omit to use the offer's expiry.
Who to send to. The first entry signs; the others are copied. Omit to use the customer's Quotes & contracts contacts. At most three, matching the contact lists themselves.
reminder_every_daysNudge an unsigned request every N days. Omit for no automatic nudges.
reminder_maxHow many nudges at most. Omit for the provider's own cap.
SetAllowanceRefreshRequest
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.
SetAudiencePurposesRequest
purposesThe replacement set. At least one. Case-insensitive, de-duplicated and stored in a fixed order, so the response is the canonical form rather than what was sent. ADDING a purpose always succeeds; REMOVING one that a live reference still needs is refused with 409 naming the rows, exactly as a delete is.
SetIdentifierRequest
kindvaluecountryvalid_fromvalid_toSetIncludedQuantityRequest
included_quantityUnits included for this subscription, as a non-negative decimal string. 0 is a valid override meaning nothing is included; to go back to the plan's number use DELETE instead.
SetMailConsentInputBody
emailThe recipient address (required).
stateThe state to record: opted_in | opted_out | unknown. soft_opt_in is not manually settable (it is seeded from sales).
customer_idThe customer this address belongs to, when known.
proof_textThe consent statement the recipient agreed to. Required to record opted_in; without proof an opt-in lands as unknown (§4.1).
purposeConsent purpose; defaults to marketing_email.
SetProductPoolRequest
unit_limitMaximum pool balance in units, as a decimal string; null for no unit ceiling.
SetRegistrationRequest
countryISO 3166-1 alpha-2 of the state the registration is HELD IN, which is not always the organization's own country.
identifierThe number as issued, e.g. GB999999973, CHE-123.456.789 MWST.
schemeScheme identifier out of the closed set the jurisdiction registry owns.
evidence_refWhat proves it: a VIES check id, an HMRC consultation number, an uploaded certificate's document id, or an operator's note.
valid_fromYYYY-MM-DD. Defaults to today. It is part of the row's identity: a number reissued after a deregistration is a NEW registration with a new start date, and the old row survives so an invoice issued under it can still say so.
valid_toYYYY-MM-DD, or null for an open-ended registration.
SetVATManualOverrideRequest
reasonExplanation recorded for the manual override. Required.
statusManual override outcome: "valid" or "invalid"; defaults to "valid" when omitted.
expires_atOptional expiry for the override; must be in the future when set.
SettingsEnum
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.
SettingsUpsertRequest
allow_add_payment_methodallow_cancel_subscriptionallow_invoice_payallow_wallet_topupshow_billing_settingsshow_invoicesshow_payment_methodsshow_subscriptionsshow_walletsSigningCountersignRequestedPayload
envelope_idorganization_idrequested_atRFC 3339 instant the countersignature became owed.
signer_emailsigner_idThe countersigner whose signature is owed.
signer_localeBCP-47 locale the notification is composed in.
subject_idsubject_kindquote | agreement | customer_document.
signer_nameworkspace_idSigningEnvelopeCancelledPayload
cancelled_atRFC 3339 cancellation instant.
envelope_idorganization_idreasonWhy the envelope was withdrawn. SUPERSEDED means a newer envelope replaced it.
subject_idsubject_kindworkspace_idSigningEnvelopeCompletedPayload
completed_atRFC 3339 completion instant.
envelope_idorganization_idprovidersigner_countsubject_idsubject_kinddocument_sha256Digest of the presented bytes. Absent on an envelope carried over from the pre-611 signatures table, which never froze a document.
workspace_idSigningEnvelopeExpiredPayload
envelope_idexpired_atRFC 3339 expiry instant.
organization_idsubject_idsubject_kindworkspace_idSigningEnvelopeSentPayload
document_sha256SHA-256 of the bytes presented to the signers. Immutable from this moment.
envelope_idThe envelope that was sent.
organization_idproviderRegistry name of the driving strategy (builtin | yousign | docusign).
sent_atRFC 3339 send instant (billing clock).
signer_countSigners whose signature the envelope waits for.
subject_idThe thing being signed.
subject_kindquote | agreement | customer_document.
expires_atRFC 3339 expiry, when one was set.
workspace_idSigningReminderSentPayload
envelope_idorganization_idreminded_atRFC 3339 reminder instant.
reminder_number1-based count of reminders sent for this envelope.
signer_emailsigner_idsigner_localeBCP-47 locale the reminder is composed in.
subject_idsubject_kindexpires_atworkspace_idSigningSignerDeclinedPayload
declined_atRFC 3339 refusal instant.
envelope_idorganization_idreasonThe signer's own words. Mandatory.
signer_emailsigner_idsigner_rolesubject_idsubject_kindworkspace_idSigningSignerSignedPayload
auth_levelHow the signer's identity was established: CLICK | OTP_EMAIL | OTP_SMS | AES | QES.
envelope_idenvelope_statusThe envelope's status AFTER this signature: PARTIALLY_SIGNED or COMPLETED.
organization_idsigned_atRFC 3339 signature instant.
signer_emailsigner_idsigner_roleSIGNER | COUNTERSIGNER.
subject_idsubject_kindworkspace_idSigningSignerViewedPayload
envelope_idorganization_idsigner_emailsigner_idsubject_idsubject_kindviewed_atRFC 3339 first-open instant.
workspace_idSimulateChangesRequest
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).
organization_idto_statusThe status after the transition.
transitioned_atWhen the transition occurred (RFC3339).
from_statusThe status before the transition; empty on initial state.
metadataFree-form transition metadata; shape varies by entity type.
reasonWhy the transition occurred, when recorded.
version_idThe entity version the transition applies to, when versioned.
workspace_idThe workspace that owns the entity.
SubmissionView
attemptschannelcreated_atdocument_ididprofile_idreissuablestateterminalupdated_atauthority_document_idclearance_kindreasonreason_codevalidation_reportSubscription
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.
How the subscription differs from its plan version; populated only when the List endpoint is called with ?include=deviation.
display_nameHuman name for this subscription: "
Version-drift summary; populated only when the List endpoint is called with ?include=drift.
When this subscription stops, resolved on the server from every clock that can stop it (renewal, the agreed term, a booked cancellation, a cancellation that happened). The earliest armed clock is named.
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.
referenceShort human id, unique within the organization and stable for the subscription's life (e.g. SUB-000123). Minted at creation, never reissued, and matched by the list endpoint's ?search. Not a key: it is unique per organization, so it never appears in a URL.
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_idsubscription_idThe subscription that was cancelled.
reasonWhy the subscription was cancelled (e.g. USER_REQUEST, AUTO_NON_RENEWAL, DUNNING_TERMINAL).
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.
SubscriptionDeviation
deviatesTrue when the subscription differs from its plan version in at least one of the reported ways.
Every (product, kind) departure from the plan version, ordered by product then kind.
subscription_idSubscriptionDeviationSummary
countNumber of (product, kind) departures from the plan.
deviatesTrue when the subscription differs from its plan version in at least one reported way.
kindsDistinct deviation kinds present, sorted: INCLUDED_QUANTITY, QUANTITY, PRODUCT_NOT_IN_PLAN.
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.
organization_idstageThe dunning stage on entry (always WARNED).
subscription_idThe subscription that entered dunning.
timestampWhen dunning was entered (RFC3339).
invoice_idThe unpaid invoice that triggered dunning, when known.
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.
SubscriptionEnding
kindWhich clock stops this subscription: RUNS_UNTIL_CANCELLED (no clock is armed), ENDS_AT_PERIOD_END (auto_renew is off), ENDS_AT_AGREED_TERM_END (the live agreement cancels at its term end), SCHEDULED_CANCELLATION (a booked subscription.cancel change), or CANCELLED (it already stopped). When several clocks are armed the earliest one is named.
agreement_idThe agreement whose term end stops the subscription; set only for ENDS_AT_AGREED_TERM_END.
atThe instant the named clock fires; absent for RUNS_UNTIL_CANCELLED.
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_atcharge_span_countHow many charge_span_unit the single up-front charge covers, measured from the item's effective_from.
charge_span_unitUnit of the span one up-front charge for this line covers (week/month/year); null means the line bills every billing period. The line does not recur — the whole span is billed once, at the start.
display_nameHuman name for this line: "
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_sourceHow the override was agreed: NEGOTIATED (a subscription-scoped rate from a quote or an operator), or empty when none. PHASE and CUSTOMER were removed with the CUSTOMER_OVERRIDE price kind (migration 201) and never appear.
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).
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
product_idProduct this item bills.
quantityNumber of units to bill (e.g. seat count).
charge_span_countHow many charge_span_unit the single up-front charge covers. Set together with charge_span_unit.
charge_span_unitUnit of the span one up-front charge for this line covers (week/month/year). Set with charge_span_count to bill the whole span once at the start; leave both null to bill the line every billing period.
price_keyKey-set entry to bill under; set only for keyed products.
product_version_idProduct version to pin the item to; null follows the product head version.
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.
SubscriptionNegotiatedPriceExpiredPayload
currencyISO 4217 currency of unit_amount.
negotiated_price_idThe subscription_negotiated_prices row that lapsed.
negotiated_sourceWho agreed the rate: QUOTE (a signed offer) or OPERATOR.
occurred_atWhen the lapse was observed and announced (RFC3339).
organization_idproduct_idThe product the lapsed rate applied to.
subscription_idThe subscription whose negotiated rate lapsed.
unit_amountThe agreed per-unit rate that has stopped applying, as a decimal string in major units.
valid_fromWhen the agreed rate started applying (RFC3339).
valid_toWhen the agreed rate stopped applying (RFC3339); the line bills catalog from this instant.
price_keyKey of the product's key set the rate applied to; empty on an unkeyed line.
source_quote_idThe offer that promised the rate; set when negotiated_source is QUOTE.
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
customer_idThe customer the subscription belongs to.
idempotency_keyThe key that de-duplicates the downstream refund action.
organization_idreasonWhy a refund is required.
requested_atWhen the refund was requested (RFC3339).
subscription_idThe subscription a refund is required for.
The refund amount, as a money object, when computed.
currencyThe refund currency, ISO-4217, when set.
days_remainingDays remaining in the period used to prorate the refund.
new_quantityThe quantity after the change that prompted the refund.
old_quantityThe quantity before the change that prompted the refund.
period_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.
subscription_item_idThe subscription item the refund relates to, when item-scoped.
workspace_idThe workspace that owns the subscription.
SubscriptionRenewalUpcomingPayload
customer_idThe customer the subscription belongs to.
item_idThe subscription item whose term is renewing.
occurred_atWhen the notice fired (RFC3339).
organization_idrenews_atWhen the committed term renews (RFC3339); the term-end the notice was scheduled for.
subscription_idThe subscription whose committed term is approaching renewal.
plan_nameThe subscription's plan name at notice time, when it has a plan.
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
default_proration_modeline_groupingprice_resolution_policySubscriptionTimeline
When and why the subscription stops, resolved by the same function GET /v1/subscriptions/{id} uses so the two cannot disagree.
Ascending by at, with the ending last. Never null; an empty list means nothing is planned inside the window.
generated_atThe operative instant this projection was taken at. A derived event is only true as of an instant, so the instant travels with it.
truncatedTrue when limit dropped events the window contained. A client that hides this teaches an operator that the timeline simply ends.
The horizon actually projected.
SubscriptionTimelineAction
idThe action's stable identifier: reschedule, cancel or trigger.
The row the action acts on — not always the event's subject: cancelling a pin acts on the Change, not on the line it holds.
SubscriptionTimelineEvent
atWhen it happens.
certaintyHow firm the instant is: fixed (a wall-clock instant somebody wrote down), anchored (follows a moving anchor such as period_end or phase_change), derived (computed from today's state and shown as expected). Certainty is TEXT, not colour — everything in the future renders the same colour.
kindWhat happens.
refThe row id in the source rail. (source, ref, at) is the event's identity.
reversibleWhether the underlying fact can still be undone or changed.
sourceWhich time rail this came off. 'ending' is the resolved ending itself and is always the last event.
What the event is about.
title_keyi18n message key. Never prose: the reader's locale decides how it reads.
Doors a client may offer on this row. Derived events carry none: there is no booked row to act on.
The money this moves, when it is known cheaply. Absent is normal and does NOT mean zero — pricing a change is POST /v1/changes/preview's job.
Arguments for the message key. Rendered verbatim in every locale, so they are data (names, numbers, references) and never English phrases.
SubscriptionTimelineRef
idThe row's id.
kindWhat sort of thing this points at: subscription, subscription_item, agreement, plan, product, promotion, change or billing_milestone.
display_nameOperator-facing name, e.g. "Acme GmbH · Standard". Absent when the row could not be named (deleted, or invisible under row security).
referenceShort per-org reference an operator says out loud, e.g. SUB-000123. Only subscriptions, agreements and quotes have one; a line deliberately does not.
SubscriptionTimelineWindow
fromStart of the projected window, inclusive.
toEnd of the projected window, exclusive.
Summary
allowed_ipscreated_atidkey_prefixkey_typescopesstatusworkspace_idexpires_atlast_used_atlast_used_ipnameSweepAlertPayload
dayThe UTC day this alert is collapsed on (YYYY-MM-DD).
entity_idThe record the sweep could not process.
entity_kindWhat kind of record the sweep could not process.
errorWhat went wrong on that record.
occurred_atWhen the row failed (RFC3339).
organization_idsweepWhich background sweep could not finish a row.
workspace_idThe workspace that owns the row that failed.
Tag
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.
TagAppliedPayload
entity_identity_typeoccurred_atorganization_idtag_idtag_nameTagDeletedPayload
occurred_atorganization_idtag_idTagRef
idIdentifier of the referenced tag.
nameDisplay name of the referenced tag.
TagRemovedPayload
entity_identity_typeoccurred_atorganization_idtag_idTagRenamedPayload
new_nameoccurred_atold_nameorganization_idtag_idTaxProfileView
available_small_business_schemeslegal_nametax_numbertax_regimevat_idbank_account_namebank_bicbank_ibandefault_countryinvoice_contact_emailinvoice_contact_nameinvoice_contact_phoneoss_countrypeppol_idregister_courtregister_numbersmall_business_crossed_onsmall_business_schemesmall_business_statussmall_business_warningTaxRule
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_regionlifecycleDerived entity state: draft, published or archived. It is NEVER 'scheduled' — pending releases live on scheduled_versions, and an entity with one is still whatever it already was and still editable.
published_atpublished_byEvery version scheduled to publish, in the order they will publish. Their rows are FROZEN — they no longer answer GET /{kind}/{id}/draft — so the entity's working draft is free for immediate changes while they stand. The version numbers are PROVISIONAL: head + rank, recomputed whenever the timeline moves.
valid_toTemplateBlock
idtypevisiblepropertiesshow_onTemplateDocument
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.
Colors, fonts, margins, page size, and locale for rendering.
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.
Email subject line (email templates only): a plain string, or authored runs plus locale-keyed translations of them.
TestMeterEventRequest
A usage-event-shaped object, read one of two ways. Send a metadata object (optionally with dimension_vars) and it is treated as an ingest BODY: metadata is bound to the usage_events metadata column the filter compiler reads, dimension_vars to its own column, and every other top-level field is envelope no filter can reach. Send a flat object and it IS the metadata — the properties, without the envelope around them. Two or more envelope-only field names (customer_id, product_id, subscription_id, metric_key, price_key, idempotency_key, hold_id, wallet_currency, price/cost fields) also mark it a body; a single one does not, so a bag holding quantity or timestamp stays properties. The response reports which reading was taken in event_interpreted_as.
event_schemaJSON Schema to validate the event against, as a document rather than a meter reference, for the same reason. Omit to skip schema checking.
The predicate to test. Sent in the body rather than referenced by meter id because the question is asked while AUTHORING — in the create sheet where no meter exists yet, and on unsaved draft trees in the filter workbench. An empty tree matches everything.
Theme
accent_colorAccent color as a hex string.
background_colorSurface/card fill as a hex string; empty inherits the resolved brand.
border_colorHairline/divider color as a hex string; empty inherits the resolved brand.
brand_sourceWhere this template's colors/logo come from: 'brand' inherits the org's resolved brand, 'template' freezes the embedded theme. Empty defaults by provenance (system => brand, clone => template).
currency_codeSample ISO 4217 currency used when rendering a preview. Preview-only: a live document is always formatted in its own currency, never this one.
densityVertical spacing scale: compact, cozy or roomy. Empty means cozy.
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.
localeSample locale used to format labels, numbers and dates when rendering a preview. Preview-only: a live document is always rendered in the reader's language (invoice, then customer, then the organization default), never this one.
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.
muted_colorSecondary/label text color as a hex string; empty inherits the resolved brand.
page_orientationPage orientation: portrait or landscape (defaults to portrait).
page_sizePage size: A4, A5, LETTER, or LEGAL (defaults to A4).
text_colorBody text color as a hex string.
Threshold
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+)?$ · requiredTarget the meter's evaluation result is compared against to detect a breach.
TierBreakdownEntry
amount^-?\d+(\.\d+)?$ · requiredAmount contributed by this segment (quantity times unit_price), MAJOR units in the resolution currency.
quantity^-?\d+(\.\d+)?$ · requiredQuantity billed within this segment.
tier_indexIndex of the contributing tier in the price's tier ladder.
unit_price^-?\d+(\.\d+)?$ · requiredPer-unit rate applied within this segment, MAJOR units in the resolution currency.
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).
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.
target_wallet_idWallet that receives the transfer; must belong to the same organization as the source wallet.
reasonOptional free-text explanation stored on both ledger legs of the transfer.
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.
TriggerMilestoneInputBody
invoice_nowFinalise the invoice this trigger mints instead of leaving it as a draft. The response says whether it actually was finalised.
TriggerMilestoneResponse
invoice_finalizedTrue when invoice_now was asked for AND the invoice was finalised. False means the invoice is still a draft.
invoice_idwarningWhy the invoice was not finalised, when invoice_now was asked for and invoice_finalized came back false. The trigger itself succeeded and the invoice exists as a draft.
UnmeteredMetricKey
event_countEvents observed for this key while it matched no meter. Cumulative and exact — the scan windows never overlap.
first_seen_atTimestamp of the earliest unmetered event counted here.
idlast_seen_atTimestamp of the most recent unmetered event counted here.
metric_keyThe metric_key the events carried. No meter in this workspace has it, so nothing aggregates them.
resolvedConvenience flag: true when resolved_at is set.
resolved_atWhen a meter with this metric_key was first seen to exist. Absent means usage is still arriving for no meter. Present means the leak is closed going forward — event_count is then the size of the history that arrived before it was, which may warrant a correction.
UnpublishedPlanProductRemoval
product_idProduct still offered by the plan's head version but no longer attached to the plan.
product_nameProduct name as frozen into the plan version snapshot at publish time.
product_version_idProduct version the head plan version pins for this product; null for pre-Step-8 legacy snapshot rows.
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.
UpdateAudienceRulesRequest
The replacement rule set. A write whose canonical content hash equals the stored one is a NO-OP: no new revision row, no bump, the audience returned unchanged — so the editor may save freely without costing the operator a spurious refused re-fire.
UpdateClauseRequest
Replaces the whole per-locale body set. Omit to leave it untouched.
countrynameUpdateContactRequest
categoryMove this contact to a different category. It keeps is_primary, so moving a primary into an occupied category takes that category over.
emailMove this contact to a different mailbox.
is_primarytrue addresses this category here, demoting whichever contact held it. false leaves the category with no primary at all, so it falls back to the billing contact.
nameSet the display name; an empty string clears it.
UpdateCostRequest
Replacement static money value; set at most one of amount or expression.
descriptionNew operator-facing description; null leaves it unchanged.
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_draftRefused. A cost has no draft of its own: it is a child of its product and goes live with that product's next publish (POST /v1/changes, catalog.publish_version).
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.
Replacement EN 16931 BG-15 deliver-to address; when provided, line1, city, postal_code and country are required. Omit to leave unchanged.
delivery_location_idNew EN 16931 BT-71 deliver-to location identifier; empty string clears it.
delivery_party_nameNew EN 16931 BT-70 deliver-to party name; empty string clears it.
disabled_providersReplacement list of disabled payment provider ids; omit to leave unchanged, empty array to clear.
einvoice_profileNew standing per-customer e-invoice format (e.g. XRECHNUNG_3_0_UBL); empty string clears it back to inherit. Must name a profile this deployment still offers - see GET /v1/e-invoicing/profiles.
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.
UpdateDocumentTemplateRequest
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 (active or archived); omit to leave unchanged.
Replacement template document; omit to leave unchanged.
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.
UpdateFileVisibilityInputBody
visibilityinternal keeps the document on the operator surfaces; shared also shows it to the customer.
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.
UpdateKeySetRequest
descriptionNew description; omit to leave unchanged.
nameNew display name; omit to leave unchanged.
UpdateMeterRequest
New derived-meter formula; {} clears it (the meter becomes a plain one); omitted leaves it unchanged. null is indistinguishable from omission on the wire and also 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; null clears it (ingest validation off); omitted leaves it unchanged. Must compile as a JSON Schema.
New event predicate tree; omitted leaves it unchanged.
functionNew aggregation function; omitted leaves it unchanged. Matched case-insensitively: the server also accepts the all-uppercase and all-lowercase form of each value. The form published here is the canonical one and is what reads back.
late_event_policyNew late-event policy; "" clears it back to unset; omitted leaves it unchanged. Matched case-insensitively: the server also accepts the all-uppercase and all-lowercase form of each value. The form published here is the canonical one and is what reads back.
nameNew human-readable label; omitted leaves it unchanged.
negative_allowedNew negative-value setting; omitted leaves it unchanged.
New billable-quantity rounding (increment + mode); {} clears it back to exact; omitted leaves it unchanged. A snapshot field: saving it republishes every consuming product, like a function or filter edit.
New alert thresholds; [] clears them; 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
bank_account_namebank_bicbank_ibaninvoice_contact_emailinvoice_contact_nameinvoice_contact_phonelegal_nameoss_countrypeppol_idregister_courtregister_numbersmall_business_schemetax_numbertax_regimevat_idUpdateOrganizationContactRequest
categoryMove this row to a different category. It keeps is_primary, so moving a primary into an occupied category takes that category over.
emailThe mailbox, when the resulting kind is email.
is_primarytrue addresses this category here, demoting whichever row held it. false leaves the category with no primary at all, so it falls back to the operations list and then to the organisation's main address.
kindChange which arm this row carries. Supply the matching arm field with it.
nameSet the label; an empty string clears it.
roleThe organisation role, when the resulting kind is role.
user_idThe member, when the resulting kind is user.
UpdateOrganizationRequest
business_addresscompany_size_tierdefault_countrydefault_currencydefault_date_formatdefault_first_day_of_weekdefault_languagedefault_localedefault_number_formatdefault_timezonelegal_namemain_emailnamephonesales_audiencesignup_emailsupport_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_enabledsupported_currenciesUpdatePaymentMethodRequest
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.
UpdatePlanProductRequest
allowance_setSet true to rewrite the included allowance from the seven fields below; false leaves the stored allowance untouched.
default_quantityQuantity a new subscription seeds for this product; null clears it (seeds 1). Only applied when quantity_band_set is true.
included_quantity^-?\d+(\.\d+)?$Quantity bundled into the base price before per-unit billing applies; null clears it. Only applied when allowance_set is true.
max_quantityHighest quantity a buyer may pick; null clears it (no plan-level ceiling). Only applied when quantity_band_set is true.
min_quantityLowest quantity a buyer may pick; null clears it (1). Only applied when quantity_band_set is true.
product_track_modeNew version-tracking mode for the membership: latest (auto-follow the product head) or pinned.
quantity_band_setSet true to rewrite the quantity band from the three fields below; false leaves the stored band untouched.
refresh_countHow often the included quantity comes back, paired with refresh_unit; null (with refresh_unit) means one whole-period pool. Only applied when allowance_set is true.
refresh_unitUnit for the refresh cadence: day, week, month, year, billing_cycle, or never (granted once). Only applied when allowance_set is true.
rollover_enabledWhen true, unused included allowance carries forward. Only applied when allowance_set is true.
rollover_expiry_periodsPeriods after which carried-forward allowance expires; null means it never expires. Only applied when allowance_set is true.
rollover_max^-?\d+(\.\d+)?$Cap on the accumulated carried-forward bank; null means uncapped, 0 means nothing carries. Only applied when allowance_set is true.
unit_limit^-?\d+(\.\d+)?$Lifetime ceiling on units drawn; only valid beside a never-refreshing included quantity. Only applied when allowance_set is true.
UpdatePlanRequest
Org-defined custom field values for this plan.
descriptionNew internal description; null leaves it 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).
external_idNew external identifier; null leaves it unchanged.
Free-form operator key/value metadata.
nameNew internal plan name; null leaves it unchanged.
price_cadence_unitNew price cadence (week, month or year); null leaves it unchanged. Changing it re-scopes which billing intervals existing and future subscriptions may use — it does NOT restate any price amount.
public_descriptionNew buyer-facing description; null leaves it unchanged.
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.
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; {} clears it; omitted leaves it unchanged.
pricing_var_nameNew formula variable name: a slug, lowercase letter then [a-z0-9_-], 1-64 chars. "" RELEASES the name — required when moving to INFORMATIONAL from a role that consumed it, because (product_id, pricing_var_name) is unique regardless of role. Omitted leaves it unchanged. The slug grammar is enforced by the API, not by this schema: "" is a legal value here, so a JSON-Schema pattern would forbid the release.
roleNew binding role (BILLABLE_QUANTITY, PRICING_VAR or INFORMATIONAL); omitted leaves it unchanged. At most one BILLABLE_QUANTITY binding per product. Moving away from a role that consumes pricing_var_name requires saying what happens to the name in the same request. Matched case-insensitively: the server also accepts the all-uppercase and all-lowercase form of each value. The form published here is the canonical one and is what reads back.
UpdateProductRequest
Org-defined custom field values for this product.
descriptionNew internal description; null leaves it 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).
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.
statusNew catalog lifecycle status (draft, scheduled, active, archived); null leaves it unchanged.
supply_natureNew supply nature (GOODS, SERVICES, DIGITAL_SERVICES); null leaves it unchanged, empty string clears the declaration.
tax_categoryNew tax category (DEFAULT, REDUCED, REDUCED_2, SUPER_REDUCED, PARKING, 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.
UpdateProfileRuleRequest
profile_idReplacement e-invoice profile for this rule. Must be one this deployment offers.
UpdatePromotionRequest
announcement_audienceWho this promotion's activation announcement is emailed to: promotion_audience (the promotion's own audience decides, and the per-email audience set for this kind is waived) or email_audience (that per-email audience applies too). The WORKSPACE-wide email audience narrows both. Omit to leave unchanged. Decides who is emailed only — it never changes who may enrol in or redeem the promotion.
application_timingNew application timing (NEXT_CYCLE, RETROACTIVE, IMMEDIATE); omit to leave unchanged.
archetypeFrontend-only preset hint; not persisted as rule logic.
New ENROLMENT audience; a full replacement of the live audience when set (no version bump). Send audience.definition to replace the rule tree; a request carrying only the legacy flat fields is refused when the stored audience says more than those fields can hold.
benefit_on_window_closeWhat valid_to means for customers who already redeemed: end expires their benefit with the promotion; keep leaves each redemption running to its own benefit duration. Omit to leave unchanged. Either way, past valid_to nobody new can redeem.
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.
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.
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.
UpdateQuotePresetRequest
activeauto_renewWhether those subscriptions renew at period end. Send clear_auto_renew to go back to inheriting.
billing_anchor_dayDay of month (1-28) those subscriptions anchor their billing period to. Send 0 to go back to inheriting.
clear_auto_renewDrop the preset's auto-renew default so its quotes inherit the organization default.
clear_document_templateUnpin the document template so quotes fall back to the organization's quote default.
contract_termsdefault_expiry_daysdescriptiondocument_template_idPin a document template. Omitted leaves the current pin; send clear_document_template to remove it.
namenote_for_customerplan_idplan_versionReplace what quotes from this preset demand of the buyer, destinations included. Send [] to require none.
require_payment_methodrequire_shippingrequire_vat_idversion_change_strategyMoney policy when a latest-tracking subscription moves version. Send "" to go back to inheriting. Required whenever version_track_mode is latest.
version_track_modeHow subscriptions provisioned from this preset's quotes follow plan/product versions (pinned|latest). Send "" to go back to inheriting the organization default.
UpdateQuoteRequest
action_at_term_endWhat happens when the agreed term runs out. Naming any end-of-term field replaces the whole block, so send the ones you want kept.
auto_renewWhether the provisioned subscription renews at period end. Send clear_auto_renew to go back to inheriting.
billing_anchor_dayDay of month (1-28) the provisioned subscription anchors its billing period to. Send 0 to go back to inheriting.
Replace the quote's clause snapshots. Send [] to carry none. Omit to leave them untouched.
clear_auto_renewDrop the per-quote auto-renew override so the subscription inherits the organization default.
clear_coterminationStop co-terminating: this deal goes back to ending on its own term.
clear_coupon_codeclear_deal_stepsDrop every later step so the offer does one thing for its whole term.
clear_document_templateUnpin the document template so the quote falls back to the organization's quote default.
clear_end_of_termDrop everything the offer said about the end of the term, so the agreement it mints goes back to CONTINUE_WITHOUT_TERM with the default gate.
clear_expires_atclear_negotiated_termDrop the agreed term so the negotiated rates go back to open-ended.
clear_starts_atDrop the start date so the offer starts on signature and prices at now.
clear_value_overrideUnpin the quote's value so it tracks the sum of its lines again.
co_terminate_with_subscription_idEnd this deal on the same date as that subscription's deal. The term must match the group's.
contract_termscoupon_codecustom_fieldsReplace the offer's later configurations, in order. Omit to leave them alone; send clear_deal_steps to drop them.
document_template_idPin the document template this quote renders through. Omitted leaves the current pin; send clear_document_template to fall back to the organization's quote default.
What ending the subscription early costs. Naming any end-of-term field replaces the whole block, so send this again if it should be kept.
early_termination_gateWhat happens when a governed operation is attempted inside the term.
excluded_clause_idsAuto-attached clause ids to leave off this quote. Each id must be one the catalog attaches to this offer, and must not also appear in clauses.
expires_atfree_trial_daysDays of free trial this offer sells before billing starts; 0 means billing starts on activation.
governed_operationsWhich operations the gate applies to. An explicit empty array is a term that governs nothing; omitting it while naming another end-of-term field clears it back to the default.
localeLanguage the offer is for (en, de, fr, es, it, pt, nl, ja). Send "" to inherit the customer's locale, then the organization default.
negotiated_term_countNumber of negotiated_term_unit periods the agreed rates hold for; send with negotiated_term_unit.
negotiated_term_unitUnit of the term the negotiated rates hold for; send with negotiated_term_count.
note_for_customernotice_countHow many notice_units a cancellation waits before it takes effect.
notice_unitUnit of the notice a cancellation requires. Not term_end_reminder_days, which announces the end of the term; this defers a cancellation the customer asks for.
orchestration_modeowner_user_idQuantity restatements on the quote's existing lines, keyed by quote item id.
Replace what the buyer must answer before signing, destinations included. Send [] to require none.
require_payment_methodrequire_shippingrequire_vat_idInvoicing overrides for the provisioned subscription. Replaces the whole block: a field left out goes back to inheriting. Omit to leave the stored block alone.
signature_modestarts_atMove the offer's start date; the quote is re-priced as of the new date.
successor_plan_idPlan the subscription moves onto when the term ends. Required by SWITCH_PLAN and refused by every other action.
term_end_reminder_daysDays of notice before the term ends. Required (at least 1) for RENEGOTIATE.
titleupdate_effectiveupdate_effective_datevalue_overridePin the quote's headline value to this major-unit decimal. The lines are what get provisioned; a pin only changes what the document states. Send clear_value_override to go back to tracking the line sum.
version_change_strategyMoney policy when a latest-tracking subscription moves version (immediate_prorate|next_period|at_phase_change). Send "" to go back to inheriting. Required whenever version_track_mode is latest.
version_track_modeHow the provisioned subscription follows plan/product versions (pinned|latest). Send "" to go back to inheriting the organization default. Unrelated to the offer's pinned plan_version.
UpdateRateTableRequest
default_valueNew default value; omit to leave unchanged.
descriptionNew description; omit to leave unchanged.
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.
UpdateRegisterFactsRequest
clear_registered_office_addressclear_share_capitalin_liquidationlegal_formseat_regionshare_capital_currencyshare_capital_minorUpdateSubscriptionRequest
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
acknowledge_retroactiveRequired to set valid_from in the past. A backdated valid_from rewrites the tax timeline for periods already invoiced — regenerating those invoices will reproduce them at the new rate. Correcting a rate that was always wrong is a legitimate reason to do this; a mistyped date is not, and without this flag the two are indistinguishable.
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_typeMatched case-insensitively: the server also accepts the all-uppercase and all-lowercase form of each value. The form published here is the canonical one and is what reads back.
valid_fromvalid_toUpdateVerificationStatusRequest
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
descriptionevent_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+)?$ · requiredNumber 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.
min_usage^-?\d+(\.\d+)?$ · requiredInclusive 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).
max_usage^-?\d+(\.\d+)?$Optional inclusive upper bound; when set the summed usage must fall within [min_usage, max_usage].
ValidatePromotionRequest
customer_idCustomer to check promotion eligibility for; required.
coupon_codeCoupon code to include coupon-gated promotions in the eligibility check.
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_orgVerifactuDeclarationView
capabilitiesArt. 13's «tipología, composición y funcionalidades» of the system. Spanish.
generated_atlimitationsWhat this system does NOT do, stated in the declaration itself. Omitting them would make the declaration a false one, which LGT art. 201 bis fines at EUR 150,000 per system per financial year.
producer_nameproducer_tax_idprovisionsThe provisions the declaration asserts compliance with (LGT art. 29.2.j, RD 1007/2023, Orden HAC/1177/2024). Spanish.
system_versionThe SIF version this declaration is about. Art. 13 makes the declaration per-version, so this is read from the running binary's build info and is never a stored constant.
textThe declaración responsable itself, in Spanish. It is a statement to a Spanish authority under a Spanish regulation; a translated one is a different document, so this string is rendered verbatim whatever the reader's locale.
producer_addresssystem_built_atsystem_namesystem_revisionThe exact build (VCS revision), so that «which version produced this record» has an answer no release process can blur.
VersionCascaseSrc
entity_idThe source entity's id.
entity_nameThe source entity's display name.
entity_typeThe source's kind, e.g. product.
versionThe source version's number.
version_idThe source version row's id.
VersionHeader
created_atentity_ididorganization_idoriginrelease_strategystatusversionarchived_reasoncancelled_atcascade_source_version_iddepends_on_version_ideffective_fromeffective_topublished_atpublished_byrelease_namerelease_noteVersionPublishImpact
entity_identity_typelive_readersConsumers reading this entity's live head, which therefore move as soon as the publish lands.
pinnableWhether any consumer can hold this entity's version. False for tax rules, which are dated rather than pinned.
republishes_consumersEntities that will be republished as a direct, synchronous consequence of this publish. Non-zero only where publishing fans out across the catalog.
total_referrersversionlifecycleVersionReleaseInputBody
release_nameNew name; empty string clears it. Absent leaves it unchanged.
release_noteNew note; empty string clears it. Absent leaves it unchanged.
VersionRow
created_ateffective_fromeffective_toidoriginWho made this version: manual (an operator published it), scheduled_release (a scheduled publish fired), cascade (republished automatically because something it depends on published).
published_atstatusversionarchived_reasonFor origin=cascade: the version whose publish caused this one, resolved to its entity and number.
created_byrank1-based position in the entity's queue of scheduled versions — the order they will fire. Present only on scheduled rows.
release_nameOperator-given name of this version, shown beside its number.
release_noteFree-text note about this version.
scheduled_change_idThe pending catalog.publish_version Change that will publish this version — reschedule or cancel it there.
scheduled_forWhen this scheduled version is due to publish. Present only on the row a pending catalog.publish_version Change is bound to.
usage_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 on spend. Null means UNLIMITED credit (no floor); set 0 to extend no credit at all.
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.
workspace_idWorkspace that owns this wallet.
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
The wallet balance that tripped the threshold, as a money object.
customer_idThe customer who owns the wallet.
The configured low-balance threshold, as a money object.
wallet_idThe wallet whose auto top-up triggered.
The configured top-up amount, as a money object, when set.
WalletCreditEffect
Wallet credit granted at redeem time, with its currency.
kindUnion discriminator.
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.
exchange_rate_base_leg_idFor a triangulated cross-pair rate, the EUR→source FX snapshot the hold's rate was divided by; null otherwise.
exchange_rate_idFX snapshot that supplied the rate this hold was valued at; null when no conversion was applied.
fx_policy_appliedFX timing policy that selected the rate; null when no conversion was applied.
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
The held amount released on expiry, as a money object.
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.
WalletLowBalancePayload
The wallet total balance after the crossing debit, as a money object.
currencyThe wallet currency, ISO-4217.
customer_idThe customer who owns the wallet.
occurred_atWhen the crossing debit was recorded (RFC3339).
organization_idThe configured low-balance threshold, as a money object.
wallet_idThe wallet whose balance crossed below the threshold.
workspace_idThe workspace that owns the wallet.
WalletModeSnapshot
cash_balanceThe cash balance, MAJOR units in the wallet's currency, as a decimal string.
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.
credit_limitThe credit limit, MAJOR units in the wallet's currency, as a decimal string, when set.
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.
WalletPromotionalBalanceExpiredPayload
The promotional balance forfeited, as a money object.
currencyThe wallet currency, ISO-4217.
customer_idThe customer who owns the wallet.
expired_atWhen the balance was DUE to expire (RFC3339) — not when the sweep observed it, which may be later if the sweep was down.
organization_idtransaction_idThe DEBIT/EXPIRY wallet transaction recording the forfeiture.
wallet_idThe wallet whose promotional balance expired.
workspace_idThe workspace that owns the wallet.
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}.
Portion of amount that moved real customer money (cash balance), {value, currency}.
created_ateffectWhat the movement was economically: SPEND, TOPUP, GRANT, REFUND, BREAKAGE, TRANSFER, ADJUSTMENT, or UNCLASSIFIED for rows predating the split.
idorganization_idPortion of amount that moved granted credit (promotional balance), {value, currency}.
sourceWhat originated the entry: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER, EXPIRY. EXPIRY is written by the promotional-expiry sweep, never by a request.
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
The debited amount in source_currency, as a money object.
The credited amount in target_currency, as a money object: the EXACT value the target wallet's ledger was credited with, so it may carry sub-scale FX precision (amount * rate is not rounded to the currency's minor unit before it is booked).
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.
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.
WalletWritableTransactionSource
WebhookDelivery
attemptscreated_atendpoint_idevent_typeididempotency_keymax_attemptsorganization_idpayloadstatusupdated_atlast_errornext_retry_atWebhookEndpoint
created_atevent_typesidorganization_idstatusupdated_aturldescriptionsecret_idunknown_event_typesSubscribed event types that no longer exist in the catalog. These deliver nothing and never will: registration-time validation only gates writes, so an endpoint registered before an event was renamed or retired keeps the dead subscription until someone edits it. Absent when every subscription is live.
WebhookEventCatalogEntry
anchor_backedTrue when this event also backs a code-owned mail anchor; such events carry an anchor_class.
descriptionWhat the event fires on.
event_typeThe wire literal a tenant subscribes to, matched exactly against a registered endpoint's event_types at fan-out time.
groupPresentational family the event belongs to, e.g. "Invoices".
payload_versionShape revision of this event's payload, stamped on every delivery as the envelope's payload_version. Advances per event type and only for breaking payload changes; additive fields do not move it.
anchor_classLawful-basis class of the backing mail anchor: transactional|service_lifecycle|promotional. Empty when no anchor backs the event.
WebhookSecret
created_atentity_identity_typeidkey_prefixorganization_idsigning_methodupdated_atdescriptionWindow
durationReset cadence in nanoseconds; omitted aggregates over the whole billing period.
WithdrawSignatureRequest
reasonWhy the request is being withdrawn. Recorded on the request's chronology; not sent to the buyer.
WorkingDraft
created_atdraft_version_idupdated_atversionbase_version_idrelease_namerelease_noteupdated_byWorkspace
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.
chargeable_via_providerAdvisory: whether any integrated payment provider can charge this currency. false = invoicing/bank-transfer only; payments through a gateway are unavailable.
Counts of records already using this currency; populated when checking whether it can be disabled.