# 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 | Description | | --- | --- | --- | --- | | `data` | array | 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 | | --- | --- | --- | --- | | `awsListingFeeTaxAmount` | number | no | AwsListingFeeTaxAmount is the net VAT AWS charges the seller on its listing fee. It is stored separately from ChannelFeeAmount and added only when a tax-inclusive marketplace charge is needed. | | `awsRevenueRecords` | array | no | For raw revenue records in AWS Marketplace | | `azureRevenueRecords` | array | 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 | 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 | 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 | Description | | --- | --- | --- | --- | | `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 | Description | | --- | --- | --- | --- | | `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 | Description | | --- | --- | --- | --- | | `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` --- Interactive API reference: https://doc.suger.io/api/