# list revenue records

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

list the revenue records for the given organization, product, entitlement, or buyer.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | path | string | yes | Organization ID |
| `partner` | path | string | yes | Cloud Partner |
| `productId` | query | string | no | Filter revenue records by the given product ID |
| `entitlementId` | query | string | no | Filter revenue records by the given entitlement ID |
| `buyerId` | query | string | no | Filter revenue records by the given buyer ID |
| `startDate` | query | string | no | start date (UTC) in YYYY-MM-DD format, default is 30 days before the endDate |
| `endDate` | query | string | no | end date (UTC) in YYYY-MM-DD format, default is today |
| `limit` | query | integer | no | List pagination size, default 1000, max value is 1000 |
| `offset` | query | integer | no | List pagination offset, default 0 |

## Responses

### 200 — OK

Content-Type: `application/json` · Schema: `ListRevenueRecordsResponse`

**`ListRevenueRecordsResponse`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `nextOffset` | integer | no |  |
| `revenueRecords` | array<RevenueRecord> | no | list of revenue records. |

**`RevenueRecord`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | number | no | The revenue amount for the revenue report |
| `awsTaxAmount` | number | no | AwsTaxAmount is buyer tax collected and remitted by AWS. AWS classifies an AWS_TAX_SHARE row as buyer tax when buyer_transaction_reference_id equals transaction_reference_id. It is informational to the seller and does not affect the seller balance; tax on AWS's listing-fee seller invoice is stored separately in Info.AwsListingFeeTaxAmount. |
| `buyerID` | string | no |  |
| `channelFeeAmount` | number | no | ChannelFeeAmount is the marketplace commission/fee for this record per F16 / data-model.md. Nullable pointer so partner handlers can leave it unset (post-sync normalization respects nil and skips the URR write, preserving any previous value). Azure derives = RevenueUsd − EarningUsd; AWS derives = -SUM(AWS_REV_SHARE rows) per invoice relationship; listing-fee tax is stored separately in Info.AwsListingFeeTaxAmount and buyer tax in TaxAmount. GCP derives = charges − prepay credits − due vendor. |
| `collectableAmount` | number | no | The revenue amount that the seller/ISV can collect. |
| `collectedAmount` | number | no |  |
| `collectedDate` | string | no |  |
| `currency` | string | no | The currency of the revenue in ISO 4217 format, such as "USD". |
| `date` | string | no | The date for the revenue report |
| `disburseAmount` | number | no |  |
| `disburseDate` | string | no |  |
| `entitlementID` | string | no |  |
| `id` | string | no |  |
| `info` | RevenueRecordInfo | no |  |
| `invoiceAmount` | number | no |  |
| `invoiceDate` | string | no |  |
| `organizationID` | string | no |  |
| `partner` | string | no | The value is from type Partner string |
| `paymentDueDate` | string | no |  |
| `paymentStatus` | string | no |  |
| `productID` | string | no |  |
| `refundDisburseAmount` | number | no |  |
| `refundDisburseDate` | string | no |  |
| `refundInvoiceAmount` | number | no |  |
| `refundInvoiceDate` | string | no |  |
| `refundStatus` | string | no |  |
| `sellerTaxAmount` | number | no | SellerTaxAmount is tax collected by the marketplace and disbursed to the seller, who is responsible for remitting it. |
| `taxAmount` | number | no |  |

**`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<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. |

**`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/