Preview events

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

customer_id

string<uuid>

required

Body

application/json

The events to preview

events

object[]

required

Array of usage events to include in the preview calculation. Must contain at least one event in merge mode.

Required array length: 1 - 100 elements

Show child attributes

events.event_type

string

required

Minimum string length: 1

events.timestamp

string

RFC 3339 formatted. If not provided, the current time will be used.

events.properties

object

events.transaction_id

string

Optional unique identifier for event deduplication. When provided, preview events are automatically deduplicated against historical events from the past 34 days. Duplicate transaction IDs within the same request will return an error.

Required string length: 1 - 128

mode

enum<string>

default:replace

Controls how the provided events are combined with existing usage data. Use replace to calculate the preview as if these are the only events for the customer, ignoring all historical usage. Use merge to combine these events with the customer's existing usage. Defaults to replace.

Available options:

replace,

merge

skip_zero_qty_line_items

boolean

default:false

When true, line items with zero quantity are excluded from the response.

Response

Success

data

object[]

required

Show child attributes

data.id

string<uuid>

required

data.customer_id

string<uuid>

required

data.credit_type

object

required

Show child attributes

data.credit_type.name

string

required

data.credit_type.id

string<uuid>

required

data.line_items

object[]

required

Show child attributes

data.line_items.name

string

required

data.line_items.total

number

required

data.line_items.type

string

required

The type of line item.

scheduled: Line item is associated with a scheduled charge. View the scheduled_charge_id on the line item.
commit_purchase: Line item is associated with a payment for a prepaid commit. View the commit_id on the line item.
usage: Line item is associated with a usage product or composite product. View the product_id on the line item to determine which product.
subscription: Line item is associated with a subscription. e.g. monthly recurring payment for an in-advance subscription.
applied_commit_or_credit: On metronome invoices, applied commits and credits are associated with their own line items. These line items have negative totals. Use the applied_commit_or_credit object on the line item to understand the id of the applied commit or credit, and its type. Note that the application of a postpaid commit is associated with a line item, but the total on the line item is not included in the invoice's total as postpaid commits are paid in-arrears.
cpu_conversion: Line item converting between a custom pricing unit and fiat currency, using the conversion rate set on the rate card. This line item will appear when there are products priced in custom pricing units, and there is insufficient prepaid commit/credit in that custom pricing unit to fully cover the spend. Then, the outstanding spend in custom pricing units will be converted to fiat currency using a cpu_conversion line item.

data.line_items.credit_type

object

required

Show child attributes

data.line_items.credit_type.name

string

required

data.line_items.credit_type.id

string<uuid>

required

data.line_items.quantity

number

The quantity associated with the line item.

data.line_items.unit_price

number

The unit price associated with the line item.

data.line_items.list_price

object

Only present for contract invoices and when the include_list_prices query parameter is set to true. This will include the list rate for the charge if applicable. Only present for usage and subscription line items.

Show child attributes

data.line_items.list_price.price

number

Default price. For FLAT rate_type, this must be >=0. For PERCENTAGE rate_type, this is a decimal fraction, e.g. use 0.1 for 10%; this must be >=0 and <=1.

data.line_items.list_price.use_list_prices

boolean

Only set for PERCENTAGE rate_type. Defaults to false. If true, rate is computed using list prices rather than the standard rates for this product on the contract.

data.line_items.list_price.tiers

object[]

Only set for TIERED rate_type.

Show child attributes

data.line_items.list_price.tiers.price

number

required

data.line_items.list_price.tiers.size

number

data.line_items.list_price.pricing_group_values

object

if pricing groups are used, this will contain the values used to calculate the price

Show child attributes

data.line_items.list_price.pricing_group_values.{key}

string

data.line_items.list_price.credit_type

object

Show child attributes

data.line_items.list_price.credit_type.name

string

required

data.line_items.list_price.credit_type.id

string<uuid>

required

data.line_items.product_id

string<uuid>

ID of the product associated with the line item.

data.line_items.product_custom_fields

object

Custom fields to be added eg. { "key1": "value1", "key2": "value2" }

Show child attributes

data.line_items.product_custom_fields.{key}

string

data.line_items.product_tags

string[]

The current product tags associated with the line item's product_id.

data.line_items.product_type

string

The type of the line item's product. Possible values are FixedProductListItem (for FIXED type products), UsageProductListItem (for USAGE type products), SubscriptionProductListItem (for SUBSCRIPTION type products) or CompositeProductListItem (for COMPOSITE type products). For scheduled charges, commit and credit payments, the value is FixedProductListItem.

data.line_items.is_prorated

boolean

Indicates whether the line item is prorated for SUBSCRIPTION type product.

data.line_items.starting_at

string<date-time>

The line item's start date (inclusive).

data.line_items.ending_before

string<date-time>

The line item's end date (exclusive).

data.line_items.commit_id

string<uuid>

For line items with product of USAGE, SUBSCRIPTION, or COMPOSITE types, the ID of the credit or commit that was applied to this line item. For line items with product type of FIXED, the ID of the prepaid or postpaid commit that is being paid for.

data.line_items.applied_commit_or_credit

object

Details about the credit or commit that was applied to this line item. Only present on line items with product of USAGE, SUBSCRIPTION or COMPOSITE types.

Show child attributes

data.line_items.applied_commit_or_credit.id

string<uuid>

required

data.line_items.applied_commit_or_credit.type

enum<string>

required

Available options:

PREPAID,

POSTPAID,

CREDIT

data.line_items.commit_custom_fields

object

Custom fields to be added eg. { "key1": "value1", "key2": "value2" }

Show child attributes

data.line_items.commit_custom_fields.{key}

string

data.line_items.commit_segment_id

string<uuid>

data.line_items.commit_type

string

PrepaidCommit (for commit types PREPAID and CREDIT) or PostpaidCommit (for commit type POSTPAID).

data.line_items.postpaid_commit

object

Only present for line items paying for a postpaid commit true-up.

Show child attributes

data.line_items.postpaid_commit.id

string<uuid>

required

data.line_items.custom_fields

object

Custom fields to be added eg. { "key1": "value1", "key2": "value2" }

Show child attributes

data.line_items.custom_fields.{key}

string

data.line_items.pricing_group_values

object

Includes the pricing group values associated with this line item if dimensional pricing is used.

Show child attributes

data.line_items.pricing_group_values.{key}

string

data.line_items.presentation_group_values

object

Includes the presentation group values associated with this line item if presentation group keys are used.

Show child attributes

data.line_items.presentation_group_values.{key}

string | null

data.line_items.metadata

string

data.line_items.scheduled_charge_id

string<uuid>

ID of scheduled charge.

data.line_items.scheduled_charge_custom_fields

object

Custom fields to be added eg. { "key1": "value1", "key2": "value2" }

Show child attributes

data.line_items.scheduled_charge_custom_fields.{key}

string

data.line_items.subscription_custom_fields

object

Custom fields to be added eg. { "key1": "value1", "key2": "value2" }

Show child attributes

data.line_items.subscription_custom_fields.{key}

string

data.line_items.tier

object

Populated if the line item has a tiered price.

Show child attributes

data.line_items.tier.level

number

required

data.line_items.tier.starting_at

string

required

data.line_items.tier.size

string | null

data.line_items.discount_id

string<uuid>

ID of the discount applied to this line item.

data.line_items.discount_custom_fields

object

Custom fields to be added eg. { "key1": "value1", "key2": "value2" }

Show child attributes

data.line_items.discount_custom_fields.{key}

string

data.status

string

required

Example:

"DRAFT, VOID, or FINALIZED"

data.total

number

required

data.type

string

required

Example:

"SCHEDULED or USAGE"

data.customer_custom_fields

object

Custom fields to be added eg. { "key1": "value1", "key2": "value2" }

Show child attributes

data.customer_custom_fields.{key}

string

data.net_payment_terms_days

number

data.start_timestamp

string<date-time>

Beginning of the usage period this invoice covers (UTC)

data.end_timestamp

string<date-time>

End of the usage period this invoice covers (UTC)

data.issued_at

string<date-time>

When the invoice was issued (UTC)

data.created_at

string<date-time>

When the invoice was created (UTC). This field is present for correction invoices only.

data.external_invoice

object

Show child attributes

data.external_invoice.billing_provider_type

enum<string>

required

Available options:

aws_marketplace,

stripe,

azure_marketplace,

quickbooks_online,

metronome

data.external_invoice.invoice_id

string

data.external_invoice.issued_at_timestamp

string<date-time>

data.external_invoice.external_status

enum<string>

Available options:

DRAFT,

FINALIZED,

PAID,

PARTIALLY_PAID,

UNCOLLECTIBLE,

VOID,

DELETED,

PAYMENT_FAILED,

INVALID_REQUEST_ERROR,

SKIPPED,

SENT,

QUEUED

data.external_invoice.pdf_url

string<uri>

A URL to the PDF of the invoice, if available from the billing provider.

data.external_invoice.tax

object

Tax details for the invoice, if available from the billing provider.

Show child attributes

data.external_invoice.tax.total_tax_amount

number

The total tax amount applied to the invoice.

data.external_invoice.tax.total_taxable_amount

number

The total taxable amount of the invoice.

data.external_invoice.tax.transaction_id

string

The transaction ID associated with the tax calculation.

data.external_invoice.invoiced_total

number

The total amount invoiced, if available from the billing provider.

data.external_invoice.invoiced_sub_total

number

The subtotal amount invoiced, if available from the billing provider.

data.external_invoice.billing_provider_error

string

Error message from the billing provider, if available.

data.external_invoice.external_payment_id

string

The ID of the payment in the external system, if available.

data.contract_id

string<uuid>

data.contract_custom_fields

object

Custom fields to be added eg. { "key1": "value1", "key2": "value2" }

Show child attributes

data.contract_custom_fields.{key}

string

data.amendment_id

string<uuid>

GET STARTED

ESSENTIALS

ENDPOINTS

Authorizations

Path Parameters

Body

Response