openapi: 3.0.1 info: title: Metronome Alerts Invoices API version: 1.0.0 description: '[Alerts](https://docs.metronome.com/connecting-metronome/alerts/) monitor customer spending, balances, and other billing factors. Use these endpoints to create, retrieve, and archive customer alerts. To view sample alert payloads by alert type, navigate [here.](https://docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)' servers: - url: https://api.metronome.com description: Production server security: - bearerAuth: [] tags: - name: Invoices description: '[Invoices](https://docs.metronome.com/invoicing/) reflect how much a customer spent during a period, which is the basis for billing. Metronome automatically generates invoices based upon your pricing, packaging, and usage events. Use these endpoints to retrieve invoices.' paths: /v1/customers/{customer_id}/invoices/invoice_seats: post: x-mint: groups: - ff:seats description: 'Creates an prorated invoice for a seat addition. As an alternative to this endpoint, you can elect to use automatic seat invoicing feature. Metronome will check for new seat usage every hour and automatically invoice for any new seats. For newly created active customer plans, there will be up to 4 hour delay before the first automatic seat invoice is generated. ' operationId: chargeSeats-v1 summary: Invoice seats parameters: - $ref: '#/components/parameters/CustomerId' requestBody: description: Invoice seats parameters. List of seat charges and additional seats to charge for. content: application/json: schema: type: object required: - seat_charges properties: seat_charges: type: array items: type: object required: - charge_id - seat_count properties: charge_id: type: string format: uuid seat_count: type: integer minimum: 1 current_seat_count: type: integer example: seat_charges: - charge_id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 seat_count: 10 tags: - Invoices responses: '200': description: Success content: application/json: schema: type: object $ref: '#/components/schemas/Invoice' example: id: 6a37bb88-8538-48c5-b37b-a41c836328bd customer_id: 617e39d8-68f4-4592-b8d2-c2bf26a76989 type: SEAT_PURCHASE start_timestamp: '2021-01-01T00:00:00Z' end_timestamp: '2021-02-01T00:00:00Z' credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) plan_name: test plan plan_id: 9de042a1-b955-43ce-9ab4-e3c2004570d1 line_items: - credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) type: usage sub_line_items: - name: CPU hours quantity: 1488 subtotal: 14392 charge_id: 3f1541ac-00df-40ee-a1a3-ec3373933669 tiers: - starting_at: 0 quantity: 1000 price: 10 subtotal: 10000 - starting_at: 1001 quantity: 488 price: 9 subtotal: 4392 custom_fields: x_account_id: KyVnHhSBWl7eY2bl name: Cloud database quantity: 1 total: 14392 product_id: 5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8 custom_fields: x_account_id: KyVnHhSBWl7eY2bl invoice_adjustments: [] status: FINALIZED subtotal: 14392 total: 14392 '404': $ref: '#/components/responses/NotFound' /v1/customers/{customer_id}/invoices: get: description: "Retrieves a paginated list of invoices for a specific customer, with flexible filtering options to narrow results by status, date range, credit type, and more. This endpoint provides a comprehensive view of a customer's billing history and current charges, supporting both real-time billing dashboards and historical reporting needs.\n\n### Use this endpoint to:\n- Display historical invoice details in customer-facing dashboards or billing portals.\n- Retrieve current month draft invoices to show customers their month-to-date spend.\n- Access finalized invoices for historical billing records and payment reconciliation.\n- Validate customer pricing and credit applications for customer support queries. \n- Generate financial reports by filtering invoices within specific date ranges\n\n### Key response fields:\nArray of invoice objects containing:\n- Invoice ID and status (DRAFT, FINALIZED, VOID)\n- Invoice type (USAGE, SCHEDULED)\n- Billing period start and end dates\n- Issue date and due date\n- Total amount, subtotal, and amount due\n- Applied credits summary\n- Contract ID reference\n- External billing provider status (if integrated with Stripe, etc.)\n- Pagination metadata `next_page` cursor\n\n### Usage guidelines:\n- The endpoint returns invoice summaries; use the Get Invoice endpoint for detailed line items\n- Draft invoices are continuously updated as new usage is reported and will show real-time spend\n- Results are ordered by creation date descending by default (newest first)\n- When filtering by date range, the filter applies to the billing period, not the issue date\n- For customers with many invoices, implement pagination to ensure all results are retrieved\nExternal billing provider statuses (like Stripe payment status) are included when applicable\n- Voided invoices are included in results by default unless filtered out by status\n" operationId: listInvoices-v1 summary: List invoices x-slo-tier: 1 parameters: - $ref: '#/components/parameters/CustomerId' - $ref: '#/components/parameters/PageLimit' - $ref: '#/components/parameters/NextPage' - $ref: '#/components/parameters/InvoiceStatus' - $ref: '#/components/parameters/InvoiceType' - $ref: '#/components/parameters/SkipZeroQtyLineItems' - in: query name: sort description: Invoice sort order by issued_at, e.g. date_asc or date_desc. Defaults to date_asc. required: false schema: type: string enum: - date_asc - date_desc - in: query name: credit_type_id description: Only return invoices for the specified credit type required: false schema: type: string - in: query name: contract_id description: Only return invoices for the specified contract required: false schema: type: string format: uuid - in: query name: starting_on description: RFC 3339 timestamp (inclusive). Invoices will only be returned for billing periods that start at or after this time. required: false schema: type: string format: date-time - in: query name: ending_before description: RFC 3339 timestamp (exclusive). Invoices will only be returned for billing periods that end before this time. required: false schema: type: string format: date-time tags: - Invoices responses: '200': description: Success content: application/json: schema: type: object required: - data - next_page properties: data: type: array items: $ref: '#/components/schemas/Invoice' next_page: type: string nullable: true examples: contracts: value: data: - id: 6a37bb88-8538-48c5-b37b-a41c836328bd customer_id: 617e39d8-68f4-4592-b8d2-c2bf26a76989 type: USAGE start_timestamp: '2021-01-01T00:00:00Z' end_timestamp: '2021-02-01T00:00:00Z' credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) contract_id: 9de042a1-b955-43ce-9ab4-e3c2004570d1 line_items: - credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) name: CPU hours type: usage quantity: 1488 total: 14392 product_id: 5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8 total: 14392 status: FINALIZED next_page: null '404': $ref: '#/components/responses/NotFound' /v1/customers/{customer_id}/invoices/breakdowns: get: description: 'Retrieve granular time-series breakdowns of invoice data at hourly or daily intervals. This endpoint transforms standard invoices into detailed timelines, enabling you to track usage patterns, identify consumption spikes, and provide customers with transparency into their billing details throughout the billing period. ### Use this endpoint to: - Build usage analytics dashboards showing daily or hourly consumption trends - Identify peak usage periods for capacity planning and cost optimization - Generate detailed billing reports for finance teams and customer success - Troubleshoot billing disputes by examining usage patterns at specific times - Power real-time cost monitoring and alerting systems ### Key response fields: An array of BreakdownInvoice objects, each containing: - All standard invoice fields (ID, customer, commit, line items, totals, status) - Line items with quantities and costs for that specific period - `breakdown_start_timestamp`: Start of the specific time window - `breakdown_end_timestamp`: End of the specific time window - `next_page`: Pagination cursor for large result sets ### Usage guidelines: - Time granularity: Set `window_size` to hour or day based on your analysis needs - Response limits: Daily breakdowns return up to 35 days; hourly breakdowns return up to 24 hours per request - Date filtering: Use `starting_on` and `ending_before` to focus on specific periods - Performance: For large date ranges, use pagination to retrieve all data efficiently - Backdated usage: If usage events arrive after invoice finalization, breakdowns will reflect the updated usage - Zero quantity filtering: Use `skip_zero_qty_line_items=true` to exclude periods with no usage' operationId: listBreakdownInvoices-v1 summary: List invoice breakdowns x-slo-tier: 1 x-gateway-timeout-millis: 60100 parameters: - $ref: '#/components/parameters/CustomerId' - $ref: '#/components/parameters/NextPage' - $ref: '#/components/parameters/InvoiceStatusNonVoid' - $ref: '#/components/parameters/SkipZeroQtyLineItems' - in: query name: limit description: Max number of results that should be returned. For daily breakdowns, the response can return up to 35 days worth of breakdowns. For hourly breakdowns, the response can return up to 24 hours. If there are more results, a cursor to the next page is returned. required: false schema: type: integer minimum: 1 maximum: 100 - in: query name: window_size description: The granularity of the breakdowns to return. Defaults to day. required: false schema: type: string enum: - hour - day - HOUR - DAY - Hour - Day - in: query name: sort description: Invoice sort order by issued_at, e.g. date_asc or date_desc. Defaults to date_asc. required: false schema: type: string enum: - date_asc - date_desc - in: query name: credit_type_id description: Only return invoices for the specified credit type required: false schema: type: string - in: query name: starting_on description: RFC 3339 timestamp. Breakdowns will only be returned for time windows that start on or after this time. required: true schema: type: string format: date-time example: '2024-01-01T00:00:00Z' - in: query name: ending_before description: RFC 3339 timestamp. Breakdowns will only be returned for time windows that end on or before this time. required: true schema: type: string format: date-time example: '2024-02-01T00:00:00Z' tags: - Invoices responses: '200': description: Success content: application/json: schema: type: object required: - data - next_page properties: data: type: array items: $ref: '#/components/schemas/BreakdownInvoice' next_page: type: string nullable: true example: data: - id: 6a37bb88-8538-48c5-b37b-a41c836328bd customer_id: 617e39d8-68f4-4592-b8d2-c2bf26a76989 type: USAGE start_timestamp: '2021-01-01T00:00:00Z' end_timestamp: '2021-02-01T00:00:00Z' breakdown_start_timestamp: '2021-01-01T00:00:00Z' breakdown_end_timestamp: '2021-01-02T00:00:00Z' credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) contract_id: 9de042a1-b955-43ce-9ab4-e3c2004570d1 line_items: - credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) name: CPU hours type: usage quantity: 1488 total: 14392 product_id: 5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8 status: DRAFT subtotal: 14392 total: 14392 - id: 6a37bb88-8538-48c5-b37b-a41c836328bd customer_id: 617e39d8-68f4-4592-b8d2-c2bf26a76989 type: USAGE start_timestamp: '2021-01-01T00:00:00Z' end_timestamp: '2021-02-01T00:00:00Z' breakdown_start_timestamp: '2021-01-02T00:00:00Z' breakdown_end_timestamp: '2021-01-03T00:00:00Z' credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) contract_id: 9de042a1-b955-43ce-9ab4-e3c2004570d1 line_items: - credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) name: CPU hours type: usage quantity: 1488 total: 14392 product_id: 5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8 status: DRAFT subtotal: 14392 total: 14392 next_page: null '404': $ref: '#/components/responses/NotFound' /v1/customers/{customer_id}/invoices/{invoice_id}/pdf: get: x-mint: metadata: tag: Beta description: 'Retrieve a PDF version of a specific invoice by its unique identifier. This endpoint generates a professionally formatted invoice document suitable for sharing with customers, accounting teams, or for record-keeping purposes. ### Use this endpoint to: - Provide customers with downloadable or emailable copies of their invoices - Support accounting and finance teams with official billing documents - Maintain accurate records of billing transactions for audits and compliance ### Key response details: - The response is a binary PDF file representing the full invoice - The PDF includes all standard invoice information such as line items, totals, billing period, and customer details - The document is formatted for clarity and professionalism, suitable for official use ### Usage guidelines: - Ensure the `invoice_id` corresponds to an existing invoice for the specified `customer_id` - The PDF is generated on-demand; frequent requests for the same invoice may impact performance - Use appropriate headers to handle the binary response in your application (e.g., setting `Content-Type: application/pdf`) ' operationId: getInvoicePdf-v1 summary: Get an invoice PDF x-slo-tier: 1 parameters: - $ref: '#/components/parameters/CustomerId' - $ref: '#/components/parameters/InvoiceId' tags: - Invoices responses: '200': description: Success content: application/pdf: schema: type: object '404': $ref: '#/components/responses/NotFound' /v1/customers/{customer_id}/invoices/{invoice_id}: get: description: "Retrieve detailed information for a specific invoice by its unique identifier. This endpoint returns comprehensive invoice data including line items, applied credits, totals, and billing period details for both finalized and draft invoices.\n\n### Use this endpoint to:\n- Display historical invoice details in customer-facing dashboards or billing portals.\n- Retrieve current month draft invoices to show customers their month-to-date spend.\n- Access finalized invoices for historical billing records and payment reconciliation.\n- Validate customer pricing and credit applications for customer support queries. \n\n### Key response fields: \nInvoice status (DRAFT, FINALIZED, VOID)\nBilling period start and end dates\nTotal amount and amount due after credits\nDetailed line items broken down by:\n- Customer and contract information\n- Invoice line item type\n- Product/service name and ID\n- Quantity consumed\n- Unit and total price \n- Time period for usage-based charges\n- Applied credits or prepaid commitments\n\n\n### Usage guidelines:\n- Draft invoices update in real-time as usage is reported and may change before finalization\n- The response includes both usage-based line items (e.g., API calls, data processed) and scheduled charges (e.g., monthly subscriptions, commitment fees)\n- Credit and commitment applications are shown as separate line items with negative amounts\n- For voided invoices, the response will indicate VOID status but retain all original line item details\n" operationId: getInvoice-v1 summary: Get an invoice x-slo-tier: 1 parameters: - $ref: '#/components/parameters/CustomerId' - $ref: '#/components/parameters/InvoiceId' - $ref: '#/components/parameters/SkipZeroQtyLineItems' tags: - Invoices responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Invoice' examples: contracts: value: data: id: 6a37bb88-8538-48c5-b37b-a41c836328bd customer_id: 617e39d8-68f4-4592-b8d2-c2bf26a76989 type: USAGE start_timestamp: '2021-01-01T00:00:00Z' end_timestamp: '2021-02-01T00:00:00Z' credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) contract_id: 9de042a1-b955-43ce-9ab4-e3c2004570d1 line_items: - credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) name: CPU hours type: usage quantity: 1488 total: 14392 product_id: 5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8 total: 14392 status: FINALIZED '404': $ref: '#/components/responses/NotFound' /v1/customers/{customer_id}/invoices/spend-breakdowns: post: x-mint: groups: - ff:spend-breakdowns description: "Granularly analyze customer spend patterns by dynamically slicing and dicing costs across any dimension. This endpoint empowers you to break down spending by granular properties like user, organization, model, region, or any custom event property—even if these aren't the default groupings on your invoices. Unlike standard invoice breakdowns, this endpoint focuses purely on spend analysis, making helpful for building powerful cost analytics dashboards that show spend before credit/commit application.\n\n### Use this endpoint to:\n- Identify cost drivers: Pinpoint which users, teams, or resources are driving the most spend\n- Build usage analytics dashboards: Let customers explore their costs by any event property (user_id, org_id, model_id, region, etc.)\n- Enable showback/chargeback: Allocate costs to specific departments, projects, or cost centers\n- Detect anomalies: Find unexpected spending patterns by analyzing costs across different dimensions\n- Optimize resource usage: Help customers identify underutilized or over-provisioned resources\n- Support multi-tenancy: Show spending breakdowns for specific organizations within a single account\n- Create custom reports: Generate executive dashboards with spending by any business-relevant dimension\n\n### Key response fields:\nSpend-focused invoice data with:\n- Pure spend information: No commits or credits—just raw spending data for cleaner analysis\n- Dynamic grouping: Line items grouped by your specified group_keys (overriding default presentation groups)\n- Filtered results: Only line items matching your group_filters criteria\n- Flexible time windows: Daily, hourly, or full-period (none) breakdowns\n- Complete line item details: Including quantities, unit prices, and custom presentation group values\n\n### Usage guidelines:\n- Group key setup: All keys used in group_keys, group_filters, and pricing groups must exist in the same compound group key on the billable metric\n- Supported window sizes: hour, day, or none (for full period analysis)\n- Filtering power: Use group_filters to focus on specific values (e.g., only show data for specific user_ids)\n- Override flexibility: Change how costs are grouped without affecting actual invoicing\n\nLimitations:\n- Cannot override group keys when using:\n - MAX aggregation billable metrics\n - Tiered pricing\n - Quantity rounding\n - Commit-specific overrides\n - Overrides on presentation group values" operationId: listSpendBreakdownInvoices-v1 summary: List spend invoice breakdowns x-slo-tier: 1 parameters: - $ref: '#/components/parameters/CustomerId' - $ref: '#/components/parameters/IncludeListPrices' tags: - Invoices requestBody: content: application/json: schema: $ref: '#/components/schemas/SpendBreakdownInvoicesQueryPayload' example: starting_on: '2021-01-01T00:00:00Z' ending_before: '2021-02-01T00:00:00Z' credit_type_id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 window_size: day sort: date_desc group_keys: - region responses: '200': description: Success content: application/json: schema: type: object required: - data - next_page properties: data: type: array items: $ref: '#/components/schemas/SpendBreakdownInvoice' next_page: type: string nullable: true example: data: - id: 6a37bb88-8538-48c5-b37b-a41c836328bd customer_id: 617e39d8-68f4-4592-b8d2-c2bf26a76989 type: USAGE start_timestamp: '2021-01-01T00:00:00Z' end_timestamp: '2021-02-01T00:00:00Z' breakdown_start_timestamp: '2021-01-01T00:00:00Z' breakdown_end_timestamp: '2021-01-02T00:00:00Z' credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) contract_id: 9de042a1-b955-43ce-9ab4-e3c2004570d1 line_items: - credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) name: CPU hours type: usage quantity: 1488 total: 14392 product_id: 5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8 status: DRAFT - id: 6a37bb88-8538-48c5-b37b-a41c836328bd customer_id: 617e39d8-68f4-4592-b8d2-c2bf26a76989 type: USAGE start_timestamp: '2021-01-01T00:00:00Z' end_timestamp: '2021-02-01T00:00:00Z' breakdown_start_timestamp: '2021-01-02T00:00:00Z' breakdown_end_timestamp: '2021-01-03T00:00:00Z' credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) contract_id: 9de042a1-b955-43ce-9ab4-e3c2004570d1 line_items: - credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) name: CPU hours type: usage quantity: 1488 total: 14392 product_id: 5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8 status: DRAFT next_page: null '404': $ref: '#/components/responses/NotFound' /v1/invoices/void: post: description: 'Permanently cancels an invoice by setting its status to voided, preventing collection and removing it from customer billing. Use this to correct billing errors, cancel incorrect charges, or handle disputed invoices that should not be collected. Returns the voided invoice ID with the status change applied immediately to stop any payment processing. ' operationId: voidInvoice-v1 summary: Void an invoice requestBody: description: The invoice id to void content: application/json: schema: type: object required: - id properties: id: description: The invoice id to void type: string format: uuid example: id: 6a37bb88-8538-48c5-b37b-a41c836328bd tags: - Invoices responses: '200': description: Success content: application/json: schema: type: object properties: data: type: object required: - id properties: id: type: string format: uuid example: data: id: 6a37bb88-8538-48c5-b37b-a41c836328bd /v1/invoices/regenerate: post: description: 'This endpoint regenerates a voided invoice and recalculates the invoice based on up-to-date rates, available balances, and other fees regardless of the billing period. ### Use this endpoint to: Recalculate an invoice with updated rate terms, available balance, and fees to correct billing disputes or discrepancies ### Key response fields: The regenerated invoice id, which is distinct from the previously voided invoice. ### Usage guidelines: If an invoice is attached to a contract with a billing provider on it, the regenerated invoice will be distributed based on the configuration. ' operationId: regenerateInvoice-v1 summary: Regenerate an invoice requestBody: description: The invoice id to regenerate content: application/json: schema: type: object required: - id properties: id: description: The invoice id to regenerate type: string format: uuid example: id: 6a37bb88-8538-48c5-b37b-a41c836328bd tags: - Invoices responses: '200': description: Success content: application/json: schema: type: object properties: data: type: object required: - id properties: id: type: string format: uuid description: The new invoice id example: data: id: 6a37bb88-8538-48c5-b37b-a41c836328bd /v1/customers/{customer_id}/previewEvents: post: summary: Preview events description: 'Preview how a set of events will affect a customer''s invoices. Generates draft invoices for a customer using their current contract configuration and the provided events. This is useful for testing how new events will affect the customer''s invoices before they are actually processed. Customers on contracts with SQL billable metrics are not supported. ' operationId: previewCustomerEvents-v1 tags: - Invoices responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/Invoice' example: data: - id: 6a37bb88-8538-48c5-b37b-a41c836328bd customer_id: 617e39d8-68f4-4592-b8d2-c2bf26a76989 type: USAGE start_timestamp: '2021-01-01T00:00:00Z' end_timestamp: '2021-02-01T00:00:00Z' credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) contract_id: 9de042a1-b955-43ce-9ab4-e3c2004570d1 line_items: - credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) name: CPU hours quantity: 31416 total: 62832 type: usage product_id: 5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8 total: 62832 status: DRAFT - id: 9543ee18-7bed-4b72-9797-729758093cf1 customer_id: 617e39d8-68f4-4592-b8d2-c2bf26a76989 type: USAGE start_timestamp: '2021-01-01T00:00:00Z' end_timestamp: '2021-02-01T00:00:00Z' credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) contract_id: cb3b77c4-467c-418a-ab68-a08113760cd2 line_items: - credit_type: id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2 name: USD (cents) name: Storage GB-hours quantity: 15708 total: 31416 type: usage product_id: 7ba25fb0-33b0-4dc8-911e-4b4065ed585e total: 31416 status: DRAFT '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '404': $ref: '#/components/responses/NotFound' parameters: - $ref: '#/components/parameters/CustomerId' requestBody: description: The events to preview content: application/json: schema: $ref: '#/components/schemas/PreviewEventsPayload' example: events: - event_type: heartbeat timestamp: '2021-01-01T00:00:00Z' properties: cpu_hours: 100 memory_gb_hours: 200 mode: replace components: schemas: SpendBreakdownInvoice: required: - id - customer_id - credit_type - line_items - status - type - breakdown_start_timestamp - breakdown_end_timestamp type: object properties: id: type: string format: uuid customer_id: type: string format: uuid credit_type: $ref: '#/components/schemas/CreditType' line_items: type: array items: $ref: '#/components/schemas/InvoiceLineItem' start_timestamp: description: Beginning of the usage period this invoice covers (UTC) type: string format: date-time end_timestamp: description: End of the usage period this invoice covers (UTC) type: string format: date-time issued_at: description: When the invoice was issued (UTC) type: string format: date-time created_at: description: When the invoice was created (UTC). This field is present for correction invoices only. type: string format: date-time status: $ref: '#/components/schemas/InvoiceStatus' type: $ref: '#/components/schemas/InvoiceType' contract_id: type: string format: uuid breakdown_start_timestamp: type: string format: date-time breakdown_end_timestamp: type: string format: date-time InvoiceLineItem: required: - name - total - credit_type - type type: object properties: name: type: string quantity: type: number description: The quantity associated with the line item. total: type: number unit_price: type: number description: The unit price associated with the line item. list_price: $ref: '#/components/schemas/Rate' description: '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. ' product_id: type: string format: uuid description: ID of the product associated with the line item. product_custom_fields: $ref: '#/components/schemas/CustomField' product_tags: $ref: '#/components/schemas/Tags' description: The current product tags associated with the line item's `product_id`. product_type: type: string description: '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`. ' type: type: string description: '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. ' netsuite_item_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string is_prorated: type: boolean description: Indicates whether the line item is prorated for `SUBSCRIPTION` type product. credit_type: $ref: '#/components/schemas/CreditType' starting_at: type: string format: date-time description: The line item's start date (inclusive). ending_before: type: string format: date-time description: The line item's end date (exclusive). commit_id: type: string format: uuid description: 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. applied_commit_or_credit: $ref: '#/components/schemas/AppliedCommitOrCredit' description: 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. commit_custom_fields: $ref: '#/components/schemas/CustomField' commit_segment_id: type: string format: uuid commit_type: type: string description: '`PrepaidCommit` (for commit types `PREPAID` and `CREDIT`) or `PostpaidCommit` (for commit type `POSTPAID`).' commit_netsuite_sales_order_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string commit_netsuite_item_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string postpaid_commit: description: Only present for line items paying for a postpaid commit true-up. $ref: '#/components/schemas/PostpaidCommit' reseller_type: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 $ref: '#/components/schemas/ResellerType' custom_fields: x-cf-entity: product $ref: '#/components/schemas/CustomField' pricing_group_values: type: object description: Includes the pricing group values associated with this line item if dimensional pricing is used. additionalProperties: type: string presentation_group_values: type: object description: Includes the presentation group values associated with this line item if presentation group keys are used. additionalProperties: type: string nullable: true metadata: type: string netsuite_invoice_billing_start: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string format: date-time description: The start date for the billing period on the invoice. netsuite_invoice_billing_end: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string format: date-time description: The end date for the billing period on the invoice. professional_service_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string format: uuid professional_service_custom_fields: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 $ref: '#/components/schemas/CustomField' scheduled_charge_id: type: string format: uuid description: ID of scheduled charge. scheduled_charge_custom_fields: $ref: '#/components/schemas/CustomField' subscription_custom_fields: $ref: '#/components/schemas/CustomField' subscription_id: type: string format: uuid description: ID of the subscription that this line item is associated with. Only present on line items with product of `SUBSCRIPTION` type. tier: $ref: '#/components/schemas/TierMetadata' description: Populated if the line item has a tiered price. discount_id: type: string format: uuid description: ID of the discount applied to this line item. discount_custom_fields: x-cf-entity: discount $ref: '#/components/schemas/CustomField' origin: type: object description: Present on line items from invoices with type USAGE_CONSOLIDATED. Indicates the original customer, contract, invoice and line item from which this line item was copied. required: - line_item_id - invoice_id - customer_id - contract_id properties: line_item_id: type: string format: uuid invoice_id: type: string format: uuid customer_id: type: string format: uuid contract_id: type: string format: uuid TierMetadata: required: - level - starting_at type: object properties: size: type: string nullable: true level: type: number starting_at: type: string PreviewEventsPayload: type: object required: - events additionalProperties: false properties: events: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/PreviewEvent' description: 'Array of usage events to include in the preview calculation. Must contain at least one event in `merge` mode. ' mode: type: string enum: - replace - merge default: replace description: '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`. ' skip_zero_qty_line_items: type: boolean default: false description: When `true`, line items with zero quantity are excluded from the response. SpendBreakdownInvoicesQueryPayload: required: - starting_on - ending_before type: object additionalProperties: false properties: starting_on: type: string format: date-time description: RFC 3339 timestamp. Breakdowns will only be returned for time windows that start on or after this time. ending_before: type: string format: date-time description: RFC 3339 timestamp. Breakdowns will only be returned for time windows that end on or before this time. skip_zero_qty_line_items: type: boolean description: If set, all zero quantity line items will be filtered out of the response. credit_type_id: type: string format: uuid description: If provided, only invoices with the specified credit type id will be included in the response. sort: type: string description: Invoice sort order by issued_at, e.g. date_asc or date_desc. Defaults to date_asc. enum: - date_asc - date_desc default: date_asc window_size: type: string description: The granularity of the breakdowns to return. Defaults to "day". enum: - day - none - DAY - NONE - Day - None group_keys: type: array description: 'A list of keys that can be used to additionally segment the values of the billable metric when making usage queries. Must be valid keys that are present in the billable metrics or an empty list. The value will be ignored and the default keys will be used if: billable metric is MAX type; product uses tiered pricing model; product has quantity rounding enabled; there are contract overrides based on presentation group keys ' items: type: string group_filters: description: 'An object where the keys are the group keys and the values are arrays of group values. If the values is an empty array, the returned usage data will be aggregated across all values for that key. The value will be ignored and the default keys will be used if: billable metric is MAX type; product uses tiered pricing model; product has quantity rounding enabled; there are contract overrides based on presentation group keys ' type: object additionalProperties: type: array items: type: string limit: type: integer description: Max number of results that should be returned. For daily and "none" breakdowns, the response can return up to 35 days worth of breakdowns. If there are more results, a cursor to the next page is returned. minimum: 1 maximum: 100 default: 100 next_page: type: string description: Cursor that indicates where the next page of results should start. ExternalInvoiceStatus: type: string enum: - DRAFT - FINALIZED - PAID - PARTIALLY_PAID - UNCOLLECTIBLE - VOID - DELETED - PAYMENT_FAILED - INVALID_REQUEST_ERROR - SKIPPED - SENT - QUEUED BreakdownInvoice: allOf: - $ref: '#/components/schemas/Invoice' - type: object required: - breakdown_start_timestamp - breakdown_end_timestamp properties: breakdown_start_timestamp: type: string format: date-time breakdown_end_timestamp: type: string format: date-time MinimumConfig: type: object description: Only set for TIERED_PERCENTAGE or PERCENTAGE rate_type. required: - minimum properties: minimum: type: number Invoice: required: - id - customer_id - credit_type - line_items - status - total - type type: object properties: id: type: string format: uuid customer_id: type: string format: uuid customer_custom_fields: $ref: '#/components/schemas/CustomField' netsuite_sales_order_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string description: This field's availability is dependent on your client's configuration. salesforce_opportunity_id: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: string description: This field's availability is dependent on your client's configuration. net_payment_terms_days: type: number credit_type: $ref: '#/components/schemas/CreditType' line_items: type: array items: $ref: '#/components/schemas/InvoiceLineItem' start_timestamp: description: Beginning of the usage period this invoice covers (UTC) type: string format: date-time end_timestamp: description: End of the usage period this invoice covers (UTC) type: string format: date-time issued_at: description: When the invoice was issued (UTC) type: string format: date-time created_at: description: When the invoice was created (UTC). This field is present for correction invoices only. type: string format: date-time status: $ref: '#/components/schemas/InvoiceStatus' total: type: number type: $ref: '#/components/schemas/InvoiceType' external_invoice: $ref: '#/components/schemas/ExternalInvoice' nullable: true revenue_system_invoices: type: array items: $ref: '#/components/schemas/RevenueSystemInvoice' nullable: true contract_id: type: string format: uuid contract_custom_fields: $ref: '#/components/schemas/CustomField' amendment_id: type: string format: uuid correction_record: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 required: - reason - memo - corrected_invoice_id type: object properties: reason: type: string memo: type: string corrected_invoice_id: type: string format: uuid corrected_external_invoice: $ref: '#/components/schemas/ExternalInvoice' reseller_royalty: x-mint: groups: - client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2 type: object description: Only present for contract invoices with reseller royalties. required: - reseller_type - netsuite_reseller_id - fraction properties: reseller_type: $ref: '#/components/schemas/ResellerType' netsuite_reseller_id: type: string fraction: type: string aws_options: type: object properties: aws_account_number: type: string aws_payer_reference_id: type: string aws_offer_id: type: string gcp_options: type: object properties: gcp_account_id: type: string gcp_offer_id: type: string custom_fields: x-cf-entity: invoice type: object x-mint: groups: - client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be - client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560 - client_id:f157d376-0781-4ef3-9db9-775a9052148e - client_id:7dd2f652-7629-4925-9069-77f5c5d3db37 - client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5 - client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33 - client_id:9c7e2b27-9b4c-4b76-9df7-f9cb05665a6a - client_id:8e3a848a-4566-4cfb-be49-64d80118a7fc additionalProperties: true billable_status: x-mint: groups: - client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be - client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560 - client_id:f157d376-0781-4ef3-9db9-775a9052148e - client_id:7dd2f652-7629-4925-9069-77f5c5d3db37 - client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5 - client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33 - client_id:9c7e2b27-9b4c-4b76-9df7-f9cb05665a6a - client_id:8e3a848a-4566-4cfb-be49-64d80118a7fc type: object $ref: '#/components/schemas/BillableStatus' description: This field's availability is dependent on your client's configuration. constituent_invoices: type: array description: Required on invoices with type USAGE_CONSOLIDATED. List of constituent invoices that were consolidated to create this invoice. items: type: object required: - contract_id - invoice_id - customer_id properties: contract_id: type: string format: uuid invoice_id: type: string format: uuid customer_id: type: string format: uuid payer: type: object required: - contract_id - customer_id properties: contract_id: type: string format: uuid customer_id: type: string format: uuid description: Required for account hierarchy usage invoices. An object containing the contract and customer UUIDs that pay for this invoice. InvoiceType: type: string example: SCHEDULED or USAGE ResellerType: type: string enum: - AWS - AWS_PRO_SERVICE - GCP - GCP_PRO_SERVICE RevenueSystemInvoice: required: - revenue_system_provider - sync_status - revenue_system_external_entity_type type: object properties: revenue_system_provider: type: string revenue_system_external_entity_id: type: string sync_status: type: string revenue_system_external_entity_type: type: string error_message: type: string description: The error message from the revenue system, if available. CustomField: type: object description: 'Custom fields to be added eg. { "key1": "value1", "key2": "value2" }' additionalProperties: type: string PostpaidCommit: type: object required: - id description: ID of the commit. properties: id: type: string format: uuid BillableStatus: type: string enum: - billable - unbillable Rate: type: object required: - rate_type properties: rate_type: type: string enum: - FLAT - flat - PERCENTAGE - percentage - SUBSCRIPTION - subscription - CUSTOM - custom - TIERED - tiered - TIERED_PERCENTAGE - tiered_percentage x-mint-enum: CUSTOM: - client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be - client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560 - client_id:f157d376-0781-4ef3-9db9-775a9052148e - client_id:7dd2f652-7629-4925-9069-77f5c5d3db37 - client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5 - client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33 - client_id:97c07a0c-70db-448a-a1d4-adcd2b8bd1c7 custom: - client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be - client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560 - client_id:f157d376-0781-4ef3-9db9-775a9052148e - client_id:7dd2f652-7629-4925-9069-77f5c5d3db37 - client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5 - client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33 - client_id:97c07a0c-70db-448a-a1d4-adcd2b8bd1c7 SUBSCRIPTION: - ff:legacy-subscriptions-enabled subscription: - ff:legacy-subscriptions-enabled TIERED_PERCENTAGE: - ff:support-charge-ga tiered_percentage: - ff:support-charge-ga x-mint: groups: - client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be - client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560 - client_id:f157d376-0781-4ef3-9db9-775a9052148e - client_id:7dd2f652-7629-4925-9069-77f5c5d3db37 - client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5 - client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33 - client_id:97c07a0c-70db-448a-a1d4-adcd2b8bd1c7 price: type: number description: 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. custom_rate: x-mint: groups: - client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be - client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560 - client_id:f157d376-0781-4ef3-9db9-775a9052148e - client_id:7dd2f652-7629-4925-9069-77f5c5d3db37 - client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5 - client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33 - client_id:97c07a0c-70db-448a-a1d4-adcd2b8bd1c7 type: object additionalProperties: true description: Only set for CUSTOM rate_type. This field is interpreted by custom rate processors. quantity: type: number x-mint: groups: - ff:legacy-subscriptions-enabled description: Default quantity. For SUBSCRIPTION rate_type, this must be >=0. is_prorated: type: boolean x-mint: groups: - ff:legacy-subscriptions-enabled description: Default proration configuration. Only valid for SUBSCRIPTION rate_type. Must be set to true. tiers: type: array items: $ref: '#/components/schemas/Tier' description: Only set for TIERED rate_type. minimum_config: x-stainless-skip: true x-mint: groups: - ff:support-charge-ga $ref: '#/components/schemas/MinimumConfig' pricing_group_values: type: object description: if pricing groups are used, this will contain the values used to calculate the price additionalProperties: type: string credit_type: $ref: '#/components/schemas/CreditType' Error: required: - message type: object properties: message: type: string Tier: type: object required: - price properties: size: type: number price: type: number BillingProviderType: type: string enum: - aws_marketplace - stripe - netsuite - custom - azure_marketplace - quickbooks_online - workday - gcp_marketplace - metronome x-mint-enum: netsuite: - client_id:11db091c-975b-4908-9f67-b1ceb126acdf custom: - client_id:11db091c-975b-4908-9f67-b1ceb126acdf workday: - client_id:11db091c-975b-4908-9f67-b1ceb126acdf gcp_marketplace: - client_id:11db091c-975b-4908-9f67-b1ceb126acdf AppliedCommitOrCredit: type: object required: - id - type properties: id: type: string format: uuid type: type: string enum: - PREPAID - POSTPAID - CREDIT CreditType: required: - name - id type: object properties: name: type: string id: type: string format: uuid Tags: type: array items: type: string ExternalInvoice: required: - billing_provider_type type: object properties: billing_provider_type: $ref: '#/components/schemas/BillingProviderType' invoice_id: type: string issued_at_timestamp: type: string format: date-time external_status: $ref: '#/components/schemas/ExternalInvoiceStatus' pdf_url: x-mint: metadata: tag: Beta type: string format: uri description: A URL to the PDF of the invoice, if available from the billing provider. tax: x-mint: metadata: tag: Beta type: object description: Tax details for the invoice, if available from the billing provider. properties: total_tax_amount: type: number description: The total tax amount applied to the invoice. total_taxable_amount: type: number description: The total taxable amount of the invoice. transaction_id: type: string description: The transaction ID associated with the tax calculation. invoiced_total: x-mint: metadata: tag: Beta type: number description: The total amount invoiced, if available from the billing provider. invoiced_sub_total: x-mint: metadata: tag: Beta type: number description: The subtotal amount invoiced, if available from the billing provider. billing_provider_error: type: string description: Error message from the billing provider, if available. external_payment_id: type: string description: The ID of the payment in the external system, if available. InvoiceStatus: type: string example: DRAFT, VOID, or FINALIZED PreviewEvent: required: - event_type type: object properties: event_type: type: string minLength: 1 timestamp: type: string description: RFC 3339 formatted. If not provided, the current time will be used. properties: type: object additionalProperties: true transaction_id: type: string minLength: 1 maxLength: 128 description: '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. ' responses: NotFound: description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/Error' parameters: NextPage: name: next_page in: query description: Cursor that indicates where the next page of results should start. required: false schema: type: string CustomerId: name: customer_id in: path required: true schema: type: string format: uuid example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc IncludeListPrices: name: include_list_prices in: query description: If set, list prices will be returned for each contract usage and subscription line item. required: false schema: type: boolean InvoiceType: name: type in: query description: Filter invoices by type. Defaults to returning all invoice types. required: false schema: type: string enum: - USAGE - USAGE_CONSOLIDATED - SCHEDULED InvoiceStatusNonVoid: name: status in: query description: Invoice status, e.g. DRAFT or FINALIZED required: false schema: type: string PageLimit: name: limit in: query description: Max number of results that should be returned required: false schema: type: integer minimum: 1 maximum: 100 SkipZeroQtyLineItems: name: skip_zero_qty_line_items in: query description: If set, all zero quantity line items will be filtered out of the response required: false schema: type: boolean InvoiceStatus: name: status in: query description: Invoice status, e.g. DRAFT, FINALIZED, or VOID required: false schema: type: string InvoiceId: name: invoice_id in: path required: true schema: type: string format: uuid example: 6a37bb88-8538-48c5-b37b-a41c836328bd securitySchemes: bearerAuth: type: http scheme: bearer