query revenue records

GET https://api.suger.cloud/org/{orgId}/revenueRecord/query

Query revenue records with filtering, sorting, and pagination using the CRUD query language. Returns a paginated envelope with total_count so callers can page one screen at a time.

Parameters

Name	In	Type	Required	Description
`orgId`	path	string	yes	Organization ID
`page_size`	query	integer	no	Number of items per page (default 20, max 1000)
`page_number`	query	integer	no	Page number (default 1)
`q`	query	string	no	LISP-style filter expression (e.g., '(and (= partner \
`s`	query	string	no	Sort fields: 'field:asc,field2:desc' or '-field,field2' (e.g., 'invoice_date:desc')

Responses

200 — Paginated list of revenue records

Content-Type: application/json · Schema: crud.ListBaseResponse-orm_BillingRevenueRecord

crud.ListBaseResponse-orm_BillingRevenueRecord fields:

Field	Type	Required
`data`	array<orm.BillingRevenueRecord>	no
`page_number`	integer	no
`page_size`	integer	no
`total_count`	integer	no

orm.BillingRevenueRecord fields:

Field	Type	Required	Description
`accountsReceivableCounterpartyType`	string	no	AccountsReceivableCounterpartyType holds the value of the "accounts_receivable_counterparty_type" field.
`awsTaxAmount`	number	no	AWSTaxAmount holds the value of the "aws_tax_amount" field.
`bankMatchStatus`	string	no	BankMatchStatus holds the value of the "bank_match_status" field.
`baseAmount`	number	no	BaseAmount holds the value of the "base_amount" field.
`baseCurrency`	string	no	BaseCurrency holds the value of the "base_currency" field.
`billingPeriodEnd`	string	no	BillingPeriodEnd holds the value of the "billing_period_end" field.
`billingPeriodStart`	string	no	BillingPeriodStart holds the value of the "billing_period_start" field.
`buyerID`	string	no	BuyerID holds the value of the "buyer_id" field.
`channelFeeAmount`	number	no	ChannelFeeAmount holds the value of the "channel_fee_amount" field.
`channelRecordID`	string	no	ChannelRecordID holds the value of the "channel_record_id" field.
`collectableAmount`	number	no	CollectableAmount holds the value of the "collectable_amount" field.
`collectedAmount`	number	no	CollectedAmount holds the value of the "collected_amount" field.
`collectedDate`	string	no	CollectedDate holds the value of the "collected_date" field.
`currency`	string	no	Currency holds the value of the "currency" field.
`deferredAmount`	number	no	DeferredAmount holds the value of the "deferred_amount" field.
`disburseAmount`	number	no	DisburseAmount holds the value of the "disburse_amount" field.
`disburseDate`	string	no	DisburseDate holds the value of the "disburse_date" field.
`entitlementID`	string	no	EntitlementID holds the value of the "entitlement_id" field.
`foreignExchangeRate`	number	no	ForeignExchangeRate holds the value of the "foreign_exchange_rate" field.
`id`	string	no	ID of the ent.
`info`	RevenueRecordInfo	no
`invoiceAmount`	number	no	InvoiceAmount holds the value of the "invoice_amount" field.
`invoiceDate`	string	no	InvoiceDate holds the value of the "invoice_date" field.
`lastUpdateTime`	string	no	LastUpdateTime holds the value of the "last_update_time" field.
`lifecycleStage`	string	no	LifecycleStage holds the value of the "lifecycle_stage" field.
`organizationID`	string	no	OrganizationID holds the value of the "organization_id" field.
`partner`	string	no	Partner holds the value of the "partner" field.
`paymentDueDate`	string	no	PaymentDueDate holds the value of the "payment_due_date" field.
`paymentStatus`	string	no	PaymentStatus holds the value of the "payment_status" field.
`productID`	string	no	ProductID holds the value of the "product_id" field.
`providerUpdatedAt`	string	no	ProviderUpdatedAt holds the value of the "provider_updated_at" field.
`recognitionConfig`	RevenueRecognitionConfig	no
`recognitionMethod`	string	no	RecognitionMethod holds the value of the "recognition_method" field.
`recognitionPolicyID`	string	no	RecognitionPolicyID holds the value of the "recognition_policy_id" field.
`recognitionStatus`	string	no	RecognitionStatus holds the value of the "recognition_status" field.
`recognitionTriggerDate`	string	no	RecognitionTriggerDate holds the value of the "recognition_trigger_date" field.
`recognizedAmount`	number	no	RecognizedAmount holds the value of the "recognized_amount" field.
`refundDisburseAmount`	number	no	RefundDisburseAmount holds the value of the "refund_disburse_amount" field.
`refundDisburseDate`	string	no	RefundDisburseDate holds the value of the "refund_disburse_date" field.
`refundInvoiceAmount`	number	no	RefundInvoiceAmount holds the value of the "refund_invoice_amount" field.
`refundInvoiceDate`	string	no	RefundInvoiceDate holds the value of the "refund_invoice_date" field.
`refundStatus`	string	no	RefundStatus holds the value of the "refund_status" field.
`reportingBasis`	string	no	ReportingBasis holds the value of the "reporting_basis" field.
`sellerTaxAmount`	number	no	SellerTaxAmount holds the value of the "seller_tax_amount" field.
`sequenceNumber`	integer	no	SequenceNumber holds the value of the "sequence_number" field.
`serviceEndDate`	string	no	ServiceEndDate holds the value of the "service_end_date" field.
`serviceStartDate`	string	no	ServiceStartDate holds the value of the "service_start_date" field.
`taxAmount`	number	no	TaxAmount holds the value of the "tax_amount" field.

RevenueRecordInfo fields:

Field	Type	Required	Description
`awsRevenueRecords`	array<AwsBillingEvent>	no	For raw revenue records in AWS Marketplace
`azureRevenueRecords`	array<AzureCmaRevenue>	no	For raw revenue records in Azure Marketplace
`bankTraceId`	string	no	The bank trace ID of the revenue record if applicable
`billingModel`	RevenueBillingModel	no
`cancellationEffectiveDate`	string	no	CancellationEffectiveDate is the date a subscription was actually terminated (ISO 8601 date or date-time string). Used by the analytics waterfall churn rule (F30) to distinguish records that were active at a measurement date but later canceled — those still count toward starting ARR and contribute to churn. Empty string means no explicit cancellation date; downstream code falls back to recognition_trigger_date when payment_status=CANCELED.
`channel`	RevenueChannel	no
`chargebeeInvoiceId`	string	no	The Chargebee invoice ID for this revenue record if synced to Chargebee
`chargebeePaymentTransactionId`	string	no	The Chargebee payment transaction ID for this revenue record if a payment was recorded in Chargebee
`chargebeeRefundTransactionId`	string	no	The Chargebee refund transaction ID for this revenue record if a refund was recorded in Chargebee
`createNotificationDigestId`	string	no	Stable audited identity for the CREATE digest batch. It survives activity retries so a successful enqueue followed by an acknowledgement failure is deduplicated on replay.
`createNotificationDigestPending`	boolean	no	Whether this record still needs to be included in the human-channel CREATE digest after its invoice projection has completed successfully.
`createNotificationPending`	boolean	no	Whether the per-record CREATE notification still needs to be delivered. Persisting this with the revenue row makes notification delivery retryable after a partially-completed sync.
`creditAmount`	number	no	The credit amount used in the revenue record.
`crmDealName`	string	no	Human-readable CRM deal/opportunity name for unbilled queue display.
`crmOpportunityId`	string	no	Native CRM opportunity/deal identifier used for idempotent booking upsert and later cancellation/invoice matching.
`crmPartner`	string	no	CRM source that produced a booking-stage revenue record. V1 CRM inbound stores booking facts here because billing.revenue_record remains the canonical lifecycle record and no separate CRM booking table exists.
`crmStage`	string	no	Native CRM stage at the time Suger last polled the deal.
`dealNotInvoicedAlertedAt`	string	no	DealNotInvoicedAlertedAt is the RFC3339 timestamp of the last fired DEAL_NOT_INVOICED alert for this record (D07 durable dedup). Prevents the alert from re-firing daily for the same long-unbilled deal — the alert fires once, then suppressed until manually cleared.
`disbursementBillingEventId`	string	no	The disbursement ID of the revenue record if applicable
`disbursementNotificationSent`	boolean	no	Whether the disbursement notification has been sent to the seller/ISV.
`disbursementReferenceNumber`	string	no	The disbursement reference number generated by AWS upon creating each disbursement request. It can be used to correlate seller bank-provided deposit notifications and reports to invoices in AWS Marketplace reports.
`dismissReason`	string	no	DismissReason is the free-text reason recorded on manual dismiss (D03).
`dismissedBy`	string	no	DismissedBy is the user ID that performed the manual dismiss (D03 audit).
`dismissedFromQueueAt`	string	no	DismissedFromQueueAt is the RFC3339 timestamp at which a CRM booking record was manually removed from the unbilled queue (D03). Only valid for direct/Stripe deals with no linked marketplace offer in ACCEPTED state; the dismiss handler rejects marketplace-accepted deals because those can only exit via auto-removal on entitlement provisioning (F27).
`earningId`	string	no	The earning ID of the revenue record if applicable
`gcpRevenueRecords`	array<GcpChargeUsage>	no	For raw revenue records in GCP Marketplace
`idSource`	string	no	Source of the revenue record ID.
`invoiceId`	string	no	The invoice ID of the revenue record if applicable
`paymentId`	string	no	The payment ID of the revenue record if applicable
`prepayCreditAmount`	number	no	The prepay credit amount drawn down on this revenue record. Applicable only to GCP Marketplace. Sourced from the "Prepay Credits" column of the GCP Charges and Usage V2 report.
`queueAutoRemovedAt`	string	no	QueueAutoRemovedAt is the RFC3339 timestamp at which the unbilled queue reconciliation removed a marketplace CRM booking because its linked offer was provisioned into an active entitlement (F27 auto-removal). Distinct from DismissedFromQueueAt so the audit trail differentiates manual finance action from automatic system reconciliation.
`relatedEntitlementIDs`	array<string>	no	RelatedEntitlementIDs is populated on aggregated invoice projections when one provider invoice contains revenue relationships for multiple contracts.
`resellerId`	string	no	The reseller ID of the revenue record if applicable
`resellerName`	string	no	The reseller name of the revenue record if application
`resource`	string	no	Resource name for the revenue record. Applicable only to GCP Marketplace.
`usagePeriodEndDate`	string	no	The end of the usage period covered by this revenue record, if applicable.
`usagePeriodStartDate`	string	no	The start of the usage period covered by this revenue record, if applicable.

RevenueRecognitionConfig fields:

Field	Type	Required	Description
`externalTriggerRef`	string	no	ExternalTriggerRef links to an external delivery event or milestone completion.
`milestoneAmounts`	object	no	MilestoneAmounts maps milestone identifiers to their recognition amounts.
`usageMeasurementMeta`	object	no	UsageMeasurementMeta holds metadata about usage measurement windows.

AwsBillingEvent fields:

Field	Type	Required
`action`	string	no
`actionDate`	NullableTime	no
`agreementID`	string	no
`amount`	number	no
`balanceImpacting`	integer	no
`bankTraceID`	string	no
`billingAddressID`	string	no
`brokerID`	string	no
`buyerID`	string	no
`buyerTransactionReferenceID`	string	no
`currency`	string	no
`dataFeedProductID`	string	no
`disbursementBillingEventID`	string	no
`disbursementReferenceNumber`	string	no
`endUserAccountID`	string	no
`entitlementID`	string	no
`fromAccountID`	string	no
`id`	string	no
`insertDate`	NullableTime	no
`invoiceDate`	NullableTime	no
`invoiceID`	string	no
`offerID`	string	no
`organizationID`	string	no
`parentBillingEventID`	string	no
`paymentDueDate`	NullableTime	no
`productID`	string	no
`refundedBuyerTransactionReferenceID`	string	no
`toAccountID`	string	no
`transactionReferenceID`	string	no
`transactionType`	string	no
`usagePeriodEndDate`	NullableTime	no
`usagePeriodStartDate`	NullableTime	no

AzureCmaRevenue fields:

Field	Type	Required
`azureAssetID`	string	no
`azureBillingAccountID`	string	no
`azureCustomerID`	string	no
`azureOfferID`	string	no
`azurePlanID`	string	no
`billingModel`	string	no
`buyerID`	string	no
`earningID`	string	no
`earningUsd`	number	no
`entitlementID`	string	no
`estimatedPayoutMonth`	NullableTime	no
`invoiceDate`	NullableTime	no
`invoiceDueDate`	NullableTime	no
`invoiceID`	string	no
`offerID`	string	no
`organizationID`	string	no
`paymentID`	string	no
`paymentSentDate`	NullableTime	no
`paymentStatus`	string	no
`payoutStatus`	string	no
`productID`	string	no
`programName`	string	no
`purchaseRecordID`	string	no
`resellerCity`	string	no
`resellerCompany`	string	no
`resellerCountry`	string	no
`resellerEmail`	string	no
`resellerID`	string	no
`resellerState`	string	no
`revenueUsd`	number	no
`termEndDate`	string	no
`termStartDate`	string	no
`transactionDate`	NullableTime	no

GcpChargeUsage fields:

Field	Type	Required
`abandoned`	number	no
`accountID`	string	no
`buyerID`	string	no
`charges`	number	no
`currency`	string	no
`dueVendor`	number	no
`entitlementID`	string	no
`googleEntity`	string	no
`insightAccountID`	string	no
`offerID`	string	no
`ordinal`	integer	no
`organizationID`	string	no
`paymentSchedule`	string	no
`paymentType`	string	no
`prepayCredits`	number	no
`productID`	string	no
`refundBalanceDeductedThisMonth`	number	no
`refundBalanceOutstanding`	number	no
`refundReason`	string	no
`released`	number	no
`reportDate`	string	no
`resource`	string	no
`sku`	string	no
`trialUse`	number	no
`unit`	string	no
`usage`	number	no
`usedBy`	string	no
`withheld`	number	no

NullableTime fields:

Field	Type	Required	Description
`Time`	string	no
`Valid`	boolean	no	Valid is true if Time is not NULL.

400 — Bad request error

Content-Type: application/json

500 — Internal server error

Content-Type: application/json

View as Markdown · Interactive API reference

Spotted something wrong or out of date on this page? Tell us and we'll correct it.