--- title: "List notification events" method: GET path: "/api/v1/notification/events" tags: ["Notifications"] --- # List notification events `GET /api/v1/notification/events` List all notification events. ## Query parameters - `from` string, date-time - `to` string, date-time - `feature` string[] - `subject` string[] - `rule` string[] - `channel` string[] - `page` integer - `pageSize` integer - `order` 'ASC' | 'DESC' — The order direction. - `orderBy` 'id' | 'createdAt' — Order by options for notification channels. ## Response `200` The request has succeeded. - NotificationEventPaginatedResponse — Paginated response - `totalCount` integer, required — The total number of items. - `page` integer, required — The page index. - `pageSize` integer, required — The maximum number of items per page. - `items` NotificationEvent[], required — The items in the current page. - `id` string, required — A unique identifier of the notification event. - `type` 'entitlements.balance.threshold' | 'entitlements.reset' | 'invoice.created' | 'invoice.updated', required — Type of the notification event. - `createdAt` string, date-time, required — Timestamp when the notification event was created in RFC 3339 format. - `rule` union, required — Notification Rule. - object — Notification rule with entitlements.balance.threshold type. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `id` string, required — Identifies the notification rule. - `type` 'entitlements.balance.threshold', required — Notification rule type. - `name` string, required — The user friendly name of the notification rule. - `disabled` boolean — Whether the rule is disabled or not. - `channels` NotificationChannelMeta[], required — List of notification channels the rule applies to. - `id` string, required — Identifies the notification channel. - `type` 'WEBHOOK', required — Type of the notification channel. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `thresholds` NotificationRuleBalanceThresholdValue[], required — List of thresholds the rule suppose to be triggered. - `value` number, double, required — Value of the threshold. - `type` 'PERCENT' | 'NUMBER' | 'balance_value' | 'usage_percentage' | 'usage_value', required — Type of the rule in the balance threshold specification: * `balance_value`: threshold defined by the remaining balance value based on usage and the total of grants in the current usage period * `usage_percentage`: threshold defined by the usage percentage compared to the total of grants in the current usage period * `usage_value`: threshold defined by the usage value in the current usage period * `NUMBER` (**deprecated**): see `usage_value` * `PERCENT` (**deprecated**): see `usage_percentage` - `features` FeatureMeta[] — Optional field containing list of features the rule applies to. - `id` string, required — Unique identifier of a feature. - `key` string, required — The key is an immutable unique identifier of the feature used throughout the API, for example when interacting with a subject's entitlements. - object — Notification rule with entitlements.reset type. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `id` string, required — Identifies the notification rule. - `type` 'entitlements.reset', required — Notification rule type. - `name` string, required — The user friendly name of the notification rule. - `disabled` boolean — Whether the rule is disabled or not. - `channels` NotificationChannelMeta[], required — List of notification channels the rule applies to. - `id` string, required — Identifies the notification channel. - `type` 'WEBHOOK', required — Type of the notification channel. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `features` FeatureMeta[] — Optional field containing list of features the rule applies to. - `id` string, required — Unique identifier of a feature. - `key` string, required — The key is an immutable unique identifier of the feature used throughout the API, for example when interacting with a subject's entitlements. - object — Notification rule with invoice.created type. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `id` string, required — Identifies the notification rule. - `type` 'invoice.created', required — Notification rule type. - `name` string, required — The user friendly name of the notification rule. - `disabled` boolean — Whether the rule is disabled or not. - `channels` NotificationChannelMeta[], required — List of notification channels the rule applies to. - `id` string, required — Identifies the notification channel. - `type` 'WEBHOOK', required — Type of the notification channel. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - object — Notification rule with invoice.updated type. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `id` string, required — Identifies the notification rule. - `type` 'invoice.updated', required — Notification rule type. - `name` string, required — The user friendly name of the notification rule. - `disabled` boolean — Whether the rule is disabled or not. - `channels` NotificationChannelMeta[], required — List of notification channels the rule applies to. - `id` string, required — Identifies the notification channel. - `type` 'WEBHOOK', required — Type of the notification channel. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `deliveryStatus` NotificationEventDeliveryStatus[], required — The delivery status of the notification event. - `state` 'SUCCESS' | 'FAILED' | 'SENDING' | 'PENDING' | 'RESENDING', required — The delivery state of the notification event to the channel. - `reason` string, required — The reason of the last deliverry state update. - `updatedAt` string, date-time, required — Timestamp of when the status was last updated in RFC 3339 format. - `channel` NotificationChannelMeta, required — Metadata only fields of a notification channel. - `id` string, required — Identifies the notification channel. - `type` 'WEBHOOK', required — Type of the notification channel. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `nextAttempt` string, date-time — Timestamp of the next delivery attempt. If null it means there will be no more delivery attempts. - `attempts` NotificationEventDeliveryAttempt[], required — List of delivery attempts. - `state` 'SUCCESS' | 'FAILED' | 'SENDING' | 'PENDING' | 'RESENDING', required — The delivery state of the notification event to the channel. - `response` EventDeliveryAttemptResponse, required — The response of the event delivery attempt. - `statusCode` integer — Status code of the response if available. - `body` string, required — The body of the response. - `durationMs` integer, required — The duration of the response in milliseconds. - `url` string — URL where the event was sent in case of notification channel with webhook type. - `timestamp` string, date-time, required — Timestamp of the delivery attempt. - `payload` union, required — The delivery status of the notification event. - object — Payload for notification event with `entitlements.reset` type. - `id` string, required — A unique identifier for the notification event the payload belongs to. - `type` 'entitlements.reset', required — Type of the notification event. - `timestamp` string, date-time, required — Timestamp when the notification event was created in RFC 3339 format. - `data` NotificationEventEntitlementValuePayloadBase, required — Base data for any payload with entitlement entitlement value. - `entitlement` EntitlementMetered, required — Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems. Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage). - `type` 'metered', required - `isSoftLimit` boolean — If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true. - `isUnlimited` boolean — Deprecated, ignored by the backend. Please use isSoftLimit instead; this field will be removed in the future. - `issueAfterReset` number, double — You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same. - `issueAfterResetPriority` integer — Defines the grant priority for the default grant. - `preserveOverageAtReset` boolean — If true, the overage is preserved at reset. If false, the usage is reset to 0. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `id` string, required — Readonly unique ULID identifier. - `subjectKey` string, required — The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs. - `featureKey` string, required — The feature the subject is entitled to use. - `featureId` string, required — The feature the subject is entitled to use. - `lastReset` string, date-time, required — The time the last reset happened. - `currentUsagePeriod` Period, required — A period with a start and end time. - … - `measureUsageFrom` string, date-time, required — The time from which usage is measured. If not specified on creation, defaults to entitlement creation time. - `usagePeriod` RecurringPeriod, required — Recurring period with an interval and an anchor. - … - `feature` Feature, required — Represents a feature that can be enabled or disabled for a plan. Used both for product catalog and entitlements. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `archivedAt` string, date-time — Timestamp of when the resource was archived. - `key` string, required — A key is a unique string that is used to identify a resource. - `name` string, required - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `meterSlug` string — A key is a unique string that is used to identify a resource. - `meterGroupByFilters` object — Optional meter group by filters. Useful if the meter scope is broader than what feature tracks. Example scenario would be a meter tracking all token use with groupBy fields for the model, then the feature could filter for model=gpt-4. ⚠️ __Deprecated__: Use advancedMeterGroupByFilters instead - `advancedMeterGroupByFilters` object — Optional advanced meter group by filters. You can use this to filter for values of the meter groupBy fields. - `unitCost` union — Per-unit cost configuration for a feature. Either a fixed manual amount or a dynamic LLM cost lookup. - … - `id` string, required — Readonly unique ULID identifier. - `subject` Subject, required — A subject is a unique identifier for a usage attribution by its key. Subjects only exist in the concept of metering. Subjects are optional to create and work as an enrichment for the subject key like displayName, metadata, etc. Subjects are useful when you are reporting usage events with your own database ID but want to enrich the subject with a human-readable name or metadata. For most use cases, a subject is equivalent to a customer. ⚠️ __Deprecated__: Subjects as managable entities are being depracated, use customers with subject key usage attribution instead. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `id` string, required — A unique identifier for the subject. - `key` string, required — A unique, human-readable identifier for the subject. This is typically a database ID or a customer key. - `displayName` string, nullable — A human-readable display name for the subject. - `metadata` object, nullable — Metadata for the subject. - `currentPeriodStart` string, date-time — The start of the current period for the subject. - `currentPeriodEnd` string, date-time — The end of the current period for the subject. - `stripeCustomerId` string, nullable — The Stripe customer ID for the subject. - `value` EntitlementValue, required — Entitlements are the core of OpenMeter access management. They define access to features for subjects. Entitlements can be metered, boolean, or static. - `hasAccess` boolean, required — Whether the subject has access to the feature. Shared accross all entitlement types. - `balance` number, double — Only available for metered entitlements. Metered entitlements are built around a balance calculation where feature usage is deducted from the issued grants. Balance represents the remaining balance of the entitlement, it's value never turns negative. - `usage` number, double — Only available for metered entitlements. Returns the total feature usage in the current period. - `overage` number, double — Only available for metered entitlements. Overage represents the usage that wasn't covered by grants, e.g. if the subject had a total feature usage of 100 in the period but they were only granted 80, there would be 20 overage. - `totalAvailableGrantAmount` number, double — Only available for metered entitlements. The summed amount of all grant active at query time PLUS the used amount of since inactive grants. - `config` string — Only available for static entitlements. The JSON parsable config of the entitlement. - `customer` Customer — A customer object. - `id` string, required — A unique identifier for the resource. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `key` string — An optional unique key of the customer. Either key or usageAttribution.subjectKeys must be provided. Useful to reference the customer in external systems. For example, your database ID. - `usageAttribution` CustomerUsageAttribution — Mapping to attribute metered usage to the customer. One customer can have zero or more subjects, but one subject can only belong to one customer. - … - `primaryEmail` string — The primary email address of the customer. - `currency` string — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - `billingAddress` Address — Address - … - `currentSubscriptionId` string — The ID of the Subscription if the customer has one. - `subscriptions` Subscription[] — The subscriptions of the customer. Only with the `subscriptions` expand option. - … - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - object — Payload for notification event with `entitlements.balance.threshold` type. - `id` string, required — A unique identifier for the notification event the payload belongs to. - `type` 'entitlements.balance.threshold', required — Type of the notification event. - `timestamp` string, date-time, required — Timestamp when the notification event was created in RFC 3339 format. - `data` NotificationEventBalanceThresholdPayloadData, required — Data of the payload for notification event with `entitlements.balance.threshold` type. - `entitlement` EntitlementMetered, required — Metered entitlements are useful for many different use cases, from setting up usage based access to implementing complex credit systems. Access is determined based on feature usage using a balance calculation (the "usage allowance" provided by the issued grants is "burnt down" by the usage). - `type` 'metered', required - `isSoftLimit` boolean — If softLimit=true the subject can use the feature even if the entitlement is exhausted, hasAccess will always be true. - `isUnlimited` boolean — Deprecated, ignored by the backend. Please use isSoftLimit instead; this field will be removed in the future. - `issueAfterReset` number, double — You can grant usage automatically alongside the entitlement, the example scenario would be creating a starting balance. If an amount is specified here, a grant will be created alongside the entitlement with the specified amount. That grant will have it's rollover settings configured in a way that after each reset operation, the balance will return the original amount specified here. Manually creating such a grant would mean having the "amount", "minRolloverAmount", and "maxRolloverAmount" fields all be the same. - `issueAfterResetPriority` integer — Defines the grant priority for the default grant. - `preserveOverageAtReset` boolean — If true, the overage is preserved at reset. If false, the usage is reset to 0. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `activeFrom` string, date-time, required — The cadence start of the resource. - `activeTo` string, date-time — The cadence end of the resource. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `id` string, required — Readonly unique ULID identifier. - `subjectKey` string, required — The identifier key unique to the subject. NOTE: Subjects are being deprecated, please use the new customer APIs. - `featureKey` string, required — The feature the subject is entitled to use. - `featureId` string, required — The feature the subject is entitled to use. - `lastReset` string, date-time, required — The time the last reset happened. - `currentUsagePeriod` Period, required — A period with a start and end time. - … - `measureUsageFrom` string, date-time, required — The time from which usage is measured. If not specified on creation, defaults to entitlement creation time. - `usagePeriod` RecurringPeriod, required — Recurring period with an interval and an anchor. - … - `feature` Feature, required — Represents a feature that can be enabled or disabled for a plan. Used both for product catalog and entitlements. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `archivedAt` string, date-time — Timestamp of when the resource was archived. - `key` string, required — A key is a unique string that is used to identify a resource. - `name` string, required - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `meterSlug` string — A key is a unique string that is used to identify a resource. - `meterGroupByFilters` object — Optional meter group by filters. Useful if the meter scope is broader than what feature tracks. Example scenario would be a meter tracking all token use with groupBy fields for the model, then the feature could filter for model=gpt-4. ⚠️ __Deprecated__: Use advancedMeterGroupByFilters instead - `advancedMeterGroupByFilters` object — Optional advanced meter group by filters. You can use this to filter for values of the meter groupBy fields. - `unitCost` union — Per-unit cost configuration for a feature. Either a fixed manual amount or a dynamic LLM cost lookup. - … - `id` string, required — Readonly unique ULID identifier. - `subject` Subject, required — A subject is a unique identifier for a usage attribution by its key. Subjects only exist in the concept of metering. Subjects are optional to create and work as an enrichment for the subject key like displayName, metadata, etc. Subjects are useful when you are reporting usage events with your own database ID but want to enrich the subject with a human-readable name or metadata. For most use cases, a subject is equivalent to a customer. ⚠️ __Deprecated__: Subjects as managable entities are being depracated, use customers with subject key usage attribution instead. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `id` string, required — A unique identifier for the subject. - `key` string, required — A unique, human-readable identifier for the subject. This is typically a database ID or a customer key. - `displayName` string, nullable — A human-readable display name for the subject. - `metadata` object, nullable — Metadata for the subject. - `currentPeriodStart` string, date-time — The start of the current period for the subject. - `currentPeriodEnd` string, date-time — The end of the current period for the subject. - `stripeCustomerId` string, nullable — The Stripe customer ID for the subject. - `value` EntitlementValue, required — Entitlements are the core of OpenMeter access management. They define access to features for subjects. Entitlements can be metered, boolean, or static. - `hasAccess` boolean, required — Whether the subject has access to the feature. Shared accross all entitlement types. - `balance` number, double — Only available for metered entitlements. Metered entitlements are built around a balance calculation where feature usage is deducted from the issued grants. Balance represents the remaining balance of the entitlement, it's value never turns negative. - `usage` number, double — Only available for metered entitlements. Returns the total feature usage in the current period. - `overage` number, double — Only available for metered entitlements. Overage represents the usage that wasn't covered by grants, e.g. if the subject had a total feature usage of 100 in the period but they were only granted 80, there would be 20 overage. - `totalAvailableGrantAmount` number, double — Only available for metered entitlements. The summed amount of all grant active at query time PLUS the used amount of since inactive grants. - `config` string — Only available for static entitlements. The JSON parsable config of the entitlement. - `customer` Customer — A customer object. - `id` string, required — A unique identifier for the resource. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `key` string — An optional unique key of the customer. Either key or usageAttribution.subjectKeys must be provided. Useful to reference the customer in external systems. For example, your database ID. - `usageAttribution` CustomerUsageAttribution — Mapping to attribute metered usage to the customer. One customer can have zero or more subjects, but one subject can only belong to one customer. - … - `primaryEmail` string — The primary email address of the customer. - `currency` string — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - `billingAddress` Address — Address - … - `currentSubscriptionId` string — The ID of the Subscription if the customer has one. - `subscriptions` Subscription[] — The subscriptions of the customer. Only with the `subscriptions` expand option. - … - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. - `threshold` NotificationRuleBalanceThresholdValue, required — Threshold value with multiple supported types. - `value` number, double, required — Value of the threshold. - `type` 'PERCENT' | 'NUMBER' | 'balance_value' | 'usage_percentage' | 'usage_value', required — Type of the rule in the balance threshold specification: * `balance_value`: threshold defined by the remaining balance value based on usage and the total of grants in the current usage period * `usage_percentage`: threshold defined by the usage percentage compared to the total of grants in the current usage period * `usage_value`: threshold defined by the usage value in the current usage period * `NUMBER` (**deprecated**): see `usage_value` * `PERCENT` (**deprecated**): see `usage_percentage` - object — Payload for notification event with `invoice.created` type. - `id` string, required — A unique identifier for the notification event the payload belongs to. - `type` 'invoice.created', required — Type of the notification event. - `timestamp` string, date-time, required — Timestamp when the notification event was created in RFC 3339 format. - `data` Invoice, required — Invoice represents an invoice in the system. - `id` string, required — A unique identifier for the resource. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `type` 'standard' | 'credit_note', required — InvoiceType represents the type of invoice. The type of invoice determines the purpose of the invoice and how it should be handled. - `supplier` BillingParty, required — Party represents a person or business entity. - `id` string — Unique identifier for the party (if available) - `key` string — An optional unique key of the party (if available) - `name` string — Legal name or representation of the organization. - `taxId` BillingPartyTaxIdentity — Identity stores the details required to identify an entity for tax purposes in a specific country. - … - `addresses` Address[] — Regular post addresses for where information should be sent if needed. - … - `customer` BillingInvoiceCustomerExtendedDetails, required — BillingInvoiceCustomerExtendedDetails is a collection of fields that are used to extend the billing party details for invoices. These fields contain the OpenMeter specific details for the customer, that are not strictly required for the invoice itself. - `id` string — Unique identifier for the party (if available) - `key` string — An optional unique key of the party (if available) - `name` string — Legal name or representation of the organization. - `taxId` BillingPartyTaxIdentity — Identity stores the details required to identify an entity for tax purposes in a specific country. - … - `addresses` Address[] — Regular post addresses for where information should be sent if needed. - … - `usageAttribution` CustomerUsageAttribution, required — Mapping to attribute metered usage to the customer. One customer can have zero or more subjects, but one subject can only belong to one customer. - … - `number` string, required — InvoiceNumber is a unique identifier for the invoice, generated by the invoicing app. The uniqueness depends on a lot of factors: - app setting (unique per app or unique per customer) - multiple app scenarios (multiple apps generating invoices with the same prefix) - `currency` string, required — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - `preceding` InvoiceDocumentRef[] — Key information regarding previous invoices and potentially details as to why they were corrected. - `type` 'credit_note_original_invoice', required — InvoiceDocumentRefType defines the type of document that is being referenced. - `reason` string — Human readable description on why this reference is here or needs to be used. - `description` string — Additional details about the document. - `totals` InvoiceTotals, required — Totals contains the summaries of all calculations for the invoice. - `amount` string, required — Numeric represents an arbitrary precision number. - `chargesTotal` string, required — Numeric represents an arbitrary precision number. - `discountsTotal` string, required — Numeric represents an arbitrary precision number. - `creditsTotal` string, required — Numeric represents an arbitrary precision number. - `taxesInclusiveTotal` string, required — Numeric represents an arbitrary precision number. - `taxesExclusiveTotal` string, required — Numeric represents an arbitrary precision number. - `taxesTotal` string, required — Numeric represents an arbitrary precision number. - `total` string, required — Numeric represents an arbitrary precision number. - `status` 'gathering' | 'draft' | 'issuing' | 'issued' | 'payment_processing' | 'overdue' | 'paid' | 'uncollectible' | 'voided', required — InvoiceStatus describes the status of an invoice. - `statusDetails` InvoiceStatusDetails, required — InvoiceStatusDetails represents the details of the invoice status. API users are encouraged to rely on the immutable/failed/avaliableActions fields to determine the next steps of the invoice instead of the extendedStatus field. - `immutable` boolean, required — Is the invoice editable? - `failed` boolean, required — Is the invoice in a failed state? - `extendedStatus` string, required — Extended status information for the invoice. - `availableActions` InvoiceAvailableActions, required — InvoiceAvailableActions represents the actions that can be performed on the invoice. - … - `issuedAt` string, date-time — The time the invoice was issued. Depending on the status of the invoice this can mean multiple things: - draft, gathering: The time the invoice will be issued based on the workflow settings. - issued: The time the invoice was issued. - `draftUntil` string, date-time — The time until the invoice is in draft status. On draft invoice creation it is calculated from the workflow settings. If manual approval is required, the draftUntil time is set. - `quantitySnapshotedAt` string, date-time — The time when the quantity snapshots on the invoice lines were taken. - `collectionAt` string, date-time — The time when the invoice will be/has been collected. - `dueAt` string, date-time — Due time of the fulfillment of the invoice (if available). - `period` Period — A period with a start and end time. - `from` string, date-time, required — Period start time. - `to` string, date-time, required — Period end time. - `voidedAt` string, date-time — The time the invoice was voided. If the invoice was voided, this field will be set to the time the invoice was voided. - `sentToCustomerAt` string, date-time — The time the invoice was sent to customer. - `workflow` InvoiceWorkflowSettings, required — InvoiceWorkflowSettings represents the workflow settings used by the invoice. This is a clone of the billing profile's workflow settings at the time of invoice creation with customer overrides considered. - `apps` union — ProfileAppsOrReference represents the union of ProfileApps and ProfileAppReferences for a billing profile. - … - `sourceBillingProfileId` string, required — sourceBillingProfileID is the billing profile on which the workflow was based on. The profile is snapshotted on invoice creation, after which it can be altered independently of the profile itself. - `workflow` BillingWorkflow, required — BillingWorkflow represents the settings for a billing workflow. - … - `lines` InvoiceLine[] — List of invoice lines representing each of the items sold to the customer. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `id` string, required — ID of the line. - `managedBy` 'subscription' | 'system' | 'manual', required — InvoiceLineManagedBy specifies who manages the line. - `status` 'valid' | 'detailed' | 'split', required — Line status specifies the status of the line. - `discounts` InvoiceLineDiscounts — InvoiceLineDiscounts represents the discounts applied to the invoice line by type. - … - `creditAllocations` InvoiceLineCreditAllocation[] — Credit allocations applied to this line. Credits are deducted from the line total before taxes are applied. - … - `invoice` InvoiceReference — Reference to an invoice. - … - `currency` string, required — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - `taxes` InvoiceLineTaxItem[] — Taxes applied to the invoice totals. - … - `taxConfig` TaxConfig — Set of provider specific tax configs. - … - `totals` InvoiceTotals, required — Totals contains the summaries of all calculations for the invoice. - … - `period` Period, required — A period with a start and end time. - … - `invoiceAt` string, date-time, required — The time this line item should be invoiced. - `externalIds` InvoiceLineAppExternalIds — InvoiceLineAppExternalIds contains the external IDs of the invoice in other apps such as Stripe. - … - `subscription` InvoiceLineSubscriptionReference — InvoiceLineSubscriptionReference contains the references to the subscription that this line is related to. - … - `type` 'usage_based', required — Type of the line. - `price` union — The price of the usage based rate card. - … - `featureKey` string — The feature that the usage is based on. - `children` InvoiceDetailedLine[] — The lines detailing the item or service sold. - … - `rateCard` InvoiceUsageBasedRateCard — InvoiceUsageBasedRateCard represents the rate card (intent) for an usage-based line. - … - `quantity` string — Numeric represents an arbitrary precision number. - `meteredQuantity` string — Numeric represents an arbitrary precision number. - `preLinePeriodQuantity` string — Numeric represents an arbitrary precision number. - `meteredPreLinePeriodQuantity` string — Numeric represents an arbitrary precision number. - `payment` InvoicePaymentTerms — Payment contains details as to how the invoice should be paid. - `terms` union — PaymentTerms defines the terms for payment. - … - `validationIssues` ValidationIssue[] — Validation issues reported by the invoice workflow. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `id` string, required — ID of the charge or discount. - `severity` 'critical' | 'warning', required — ValidationIssueSeverity describes the severity of a validation issue. Issues with severity "critical" will prevent the invoice from being issued. - `field` string — The field that the issue is related to, if available in JSON path format. - `code` string — Machine indentifiable code for the issue, if available. - `component` string, required — Component reporting the issue. - `message` string, required — A human-readable description of the issue. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `externalIds` InvoiceAppExternalIds — InvoiceAppExternalIds contains the external IDs of the invoice in other apps such as Stripe. - `invoicing` string — The external ID of the invoice in the invoicing app if available. - `tax` string — The external ID of the invoice in the tax app if available. - `payment` string — The external ID of the invoice in the payment app if available. - object — Payload for notification event with `invoice.updated` type. - `id` string, required — A unique identifier for the notification event the payload belongs to. - `type` 'invoice.updated', required — Type of the notification event. - `timestamp` string, date-time, required — Timestamp when the notification event was created in RFC 3339 format. - `data` Invoice, required — Invoice represents an invoice in the system. - `id` string, required — A unique identifier for the resource. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `type` 'standard' | 'credit_note', required — InvoiceType represents the type of invoice. The type of invoice determines the purpose of the invoice and how it should be handled. - `supplier` BillingParty, required — Party represents a person or business entity. - `id` string — Unique identifier for the party (if available) - `key` string — An optional unique key of the party (if available) - `name` string — Legal name or representation of the organization. - `taxId` BillingPartyTaxIdentity — Identity stores the details required to identify an entity for tax purposes in a specific country. - … - `addresses` Address[] — Regular post addresses for where information should be sent if needed. - … - `customer` BillingInvoiceCustomerExtendedDetails, required — BillingInvoiceCustomerExtendedDetails is a collection of fields that are used to extend the billing party details for invoices. These fields contain the OpenMeter specific details for the customer, that are not strictly required for the invoice itself. - `id` string — Unique identifier for the party (if available) - `key` string — An optional unique key of the party (if available) - `name` string — Legal name or representation of the organization. - `taxId` BillingPartyTaxIdentity — Identity stores the details required to identify an entity for tax purposes in a specific country. - … - `addresses` Address[] — Regular post addresses for where information should be sent if needed. - … - `usageAttribution` CustomerUsageAttribution, required — Mapping to attribute metered usage to the customer. One customer can have zero or more subjects, but one subject can only belong to one customer. - … - `number` string, required — InvoiceNumber is a unique identifier for the invoice, generated by the invoicing app. The uniqueness depends on a lot of factors: - app setting (unique per app or unique per customer) - multiple app scenarios (multiple apps generating invoices with the same prefix) - `currency` string, required — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - `preceding` InvoiceDocumentRef[] — Key information regarding previous invoices and potentially details as to why they were corrected. - `type` 'credit_note_original_invoice', required — InvoiceDocumentRefType defines the type of document that is being referenced. - `reason` string — Human readable description on why this reference is here or needs to be used. - `description` string — Additional details about the document. - `totals` InvoiceTotals, required — Totals contains the summaries of all calculations for the invoice. - `amount` string, required — Numeric represents an arbitrary precision number. - `chargesTotal` string, required — Numeric represents an arbitrary precision number. - `discountsTotal` string, required — Numeric represents an arbitrary precision number. - `creditsTotal` string, required — Numeric represents an arbitrary precision number. - `taxesInclusiveTotal` string, required — Numeric represents an arbitrary precision number. - `taxesExclusiveTotal` string, required — Numeric represents an arbitrary precision number. - `taxesTotal` string, required — Numeric represents an arbitrary precision number. - `total` string, required — Numeric represents an arbitrary precision number. - `status` 'gathering' | 'draft' | 'issuing' | 'issued' | 'payment_processing' | 'overdue' | 'paid' | 'uncollectible' | 'voided', required — InvoiceStatus describes the status of an invoice. - `statusDetails` InvoiceStatusDetails, required — InvoiceStatusDetails represents the details of the invoice status. API users are encouraged to rely on the immutable/failed/avaliableActions fields to determine the next steps of the invoice instead of the extendedStatus field. - `immutable` boolean, required — Is the invoice editable? - `failed` boolean, required — Is the invoice in a failed state? - `extendedStatus` string, required — Extended status information for the invoice. - `availableActions` InvoiceAvailableActions, required — InvoiceAvailableActions represents the actions that can be performed on the invoice. - … - `issuedAt` string, date-time — The time the invoice was issued. Depending on the status of the invoice this can mean multiple things: - draft, gathering: The time the invoice will be issued based on the workflow settings. - issued: The time the invoice was issued. - `draftUntil` string, date-time — The time until the invoice is in draft status. On draft invoice creation it is calculated from the workflow settings. If manual approval is required, the draftUntil time is set. - `quantitySnapshotedAt` string, date-time — The time when the quantity snapshots on the invoice lines were taken. - `collectionAt` string, date-time — The time when the invoice will be/has been collected. - `dueAt` string, date-time — Due time of the fulfillment of the invoice (if available). - `period` Period — A period with a start and end time. - `from` string, date-time, required — Period start time. - `to` string, date-time, required — Period end time. - `voidedAt` string, date-time — The time the invoice was voided. If the invoice was voided, this field will be set to the time the invoice was voided. - `sentToCustomerAt` string, date-time — The time the invoice was sent to customer. - `workflow` InvoiceWorkflowSettings, required — InvoiceWorkflowSettings represents the workflow settings used by the invoice. This is a clone of the billing profile's workflow settings at the time of invoice creation with customer overrides considered. - `apps` union — ProfileAppsOrReference represents the union of ProfileApps and ProfileAppReferences for a billing profile. - … - `sourceBillingProfileId` string, required — sourceBillingProfileID is the billing profile on which the workflow was based on. The profile is snapshotted on invoice creation, after which it can be altered independently of the profile itself. - `workflow` BillingWorkflow, required — BillingWorkflow represents the settings for a billing workflow. - … - `lines` InvoiceLine[] — List of invoice lines representing each of the items sold to the customer. - `name` string, required — Human-readable name for the resource. Between 1 and 256 characters. - `description` string — Optional description of the resource. Maximum 1024 characters. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `id` string, required — ID of the line. - `managedBy` 'subscription' | 'system' | 'manual', required — InvoiceLineManagedBy specifies who manages the line. - `status` 'valid' | 'detailed' | 'split', required — Line status specifies the status of the line. - `discounts` InvoiceLineDiscounts — InvoiceLineDiscounts represents the discounts applied to the invoice line by type. - … - `creditAllocations` InvoiceLineCreditAllocation[] — Credit allocations applied to this line. Credits are deducted from the line total before taxes are applied. - … - `invoice` InvoiceReference — Reference to an invoice. - … - `currency` string, required — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - `taxes` InvoiceLineTaxItem[] — Taxes applied to the invoice totals. - … - `taxConfig` TaxConfig — Set of provider specific tax configs. - … - `totals` InvoiceTotals, required — Totals contains the summaries of all calculations for the invoice. - … - `period` Period, required — A period with a start and end time. - … - `invoiceAt` string, date-time, required — The time this line item should be invoiced. - `externalIds` InvoiceLineAppExternalIds — InvoiceLineAppExternalIds contains the external IDs of the invoice in other apps such as Stripe. - … - `subscription` InvoiceLineSubscriptionReference — InvoiceLineSubscriptionReference contains the references to the subscription that this line is related to. - … - `type` 'usage_based', required — Type of the line. - `price` union — The price of the usage based rate card. - … - `featureKey` string — The feature that the usage is based on. - `children` InvoiceDetailedLine[] — The lines detailing the item or service sold. - … - `rateCard` InvoiceUsageBasedRateCard — InvoiceUsageBasedRateCard represents the rate card (intent) for an usage-based line. - … - `quantity` string — Numeric represents an arbitrary precision number. - `meteredQuantity` string — Numeric represents an arbitrary precision number. - `preLinePeriodQuantity` string — Numeric represents an arbitrary precision number. - `meteredPreLinePeriodQuantity` string — Numeric represents an arbitrary precision number. - `payment` InvoicePaymentTerms — Payment contains details as to how the invoice should be paid. - `terms` union — PaymentTerms defines the terms for payment. - … - `validationIssues` ValidationIssue[] — Validation issues reported by the invoice workflow. - `createdAt` string, date-time, required — Timestamp of when the resource was created. - `updatedAt` string, date-time, required — Timestamp of when the resource was last updated. - `deletedAt` string, date-time — Timestamp of when the resource was permanently deleted. - `id` string, required — ID of the charge or discount. - `severity` 'critical' | 'warning', required — ValidationIssueSeverity describes the severity of a validation issue. Issues with severity "critical" will prevent the invoice from being issued. - `field` string — The field that the issue is related to, if available in JSON path format. - `code` string — Machine indentifiable code for the issue, if available. - `component` string, required — Component reporting the issue. - `message` string, required — A human-readable description of the issue. - `metadata` Metadata — Set of key-value pairs. Metadata can be used to store additional information about a resource. - `externalIds` InvoiceAppExternalIds — InvoiceAppExternalIds contains the external IDs of the invoice in other apps such as Stripe. - `invoicing` string — The external ID of the invoice in the invoicing app if available. - `tax` string — The external ID of the invoice in the tax app if available. - `payment` string — The external ID of the invoice in the payment app if available. - `annotations` Annotations — Set of key-value pairs managed by the system. Cannot be modified by user. ## Other responses - `400` — The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing). - `401` — The request has not been applied because it lacks valid authentication credentials for the target resource. - `403` — The server understood the request but refuses to authorize it. - `412` — One or more conditions given in the request header fields evaluated to false when tested on the server. - `500` — The server encountered an unexpected condition that prevented it from fulfilling the request. - `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. - `default` — An unexpected error response. --- [API](https://skmtc.net/openmeterio/apis/openmeter-api.md) · [All operations](https://skmtc.net/openmeterio/apis/openmeter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmeterio/openmeter-api/versions/927d82ffe647/schema)