{ "openapi": "3.0.1", "info": { "title": "Metronome", "version": "1.0.0" }, "servers": [ { "url": "https://api.metronome.com/v1", "description": "Production server" } ], "paths": { "/approval_requests": { "post": { "x-mint": { "groups": [ "ff:agentic-api-tokens" ] }, "x-stainless-skip": true, "operationId": "submitApprovalRequests", "summary": "Submit a write operation for human approval", "description": "Queues a write operation for human review when an agentic token is in use.\n\nWhen an agent attempts a write operation (e.g. `POST /v1/contracts/create`) using an\nagentic token, the server returns a `403 AgenticMutationBlocked` error with a pointer to\nthis endpoint. The agent should then call this endpoint with the original request details\nso a human can review and approve the action.\n\nOn success, a pending approval request is created and the response includes an\n`approval_url` linking to the Approval Dashboard where a human can review, approve, or\nreject the request. Once approved, the original operation is executed automatically and\nthe dashboard reflects the completed status.\n\nAgents should surface the `approval_url` to the human user (e.g. via chat message or UI link)\nso they can navigate directly to the approval dashboard to review the request.\n", "tags": [ "Approval Requests" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "description", "method", "path", "body" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": { "type": "string", "minLength": 1, "maxLength": 512 }, "method": { "type": "string", "enum": [ "POST", "PUT", "PATCH", "DELETE" ], "description": "The HTTP method of the operation being requested." }, "path": { "type": "string", "description": "The API path of the operation being requested (e.g. /v1/contracts/create)." }, "body": { "type": "object", "additionalProperties": true, "description": "The full request body of the operation being requested." } } }, "example": { "name": "Create enterprise contract for Acme Corp", "description": "Onboarding new enterprise customer with annual commitment", "method": "POST", "path": "/v1/contracts/create", "body": { "customer_id": "4db51251-61de-4bfe-b9ce-495e244f3491", "starting_at": "2026-06-01T00:00:00.000Z" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApprovalRequest" } } } } } } } }, "get": { "x-mint": { "groups": [ "ff:agentic-api-tokens" ] }, "x-stainless-skip": true, "operationId": "listApprovalRequests", "summary": "List approval requests", "description": "Lists all approval requests submitted by agentic tokens for your account. Returns request details including status, token name, approval URL, and the original request payload. Use status and date filters to narrow results.\n", "tags": [ "Approval Requests" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending_approval", "approved", "denied", "execution_succeeded", "execution_error", "expired" ] }, "description": "Filter by approval request status." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Number of items to return per page. Defaults to 20." }, { "name": "next_page", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor for pagination. Use the value from the previous response's next_page field." }, { "name": "created_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter to requests created before this timestamp (exclusive)." }, { "name": "created_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter to requests created on or after this timestamp (inclusive)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalRequest" } }, "next_page": { "type": "string", "nullable": true, "description": "Cursor to use for fetching the next page of results." } } } } } } } } }, "/approval_requests/{id}": { "get": { "x-mint": { "groups": [ "ff:agentic-api-tokens" ] }, "x-stainless-skip": true, "operationId": "getApprovalRequest", "summary": "Get an approval request", "description": "Retrieves the details of a single approval request by its ID.\n", "tags": [ "Approval Requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the approval request to retrieve." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApprovalRequest" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/approval_requests/{id}/approve": { "post": { "x-mint": { "groups": [ "ff:agentic-api-tokens" ] }, "x-stainless-skip": true, "operationId": "approveApprovalRequest", "summary": "Approve a pending approval request", "description": "Approves a pending approval request, allowing the queued operation to proceed.\n\nOnce approved, the original write operation will be executed automatically and the\napproval request status will transition to reflect the execution result.\n", "tags": [ "Approval Requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the approval request to approve." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApprovalRequest" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/approval_requests/{id}/deny": { "post": { "x-mint": { "groups": [ "ff:agentic-api-tokens" ] }, "x-stainless-skip": true, "operationId": "denyApprovalRequest", "summary": "Deny a pending approval request", "description": "Denies a pending approval request, preventing the queued operation from executing.\n\nOnce denied, the approval request is closed and the original write operation will\nnot be performed.\n", "tags": [ "Approval Requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The ID of the approval request to deny." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApprovalRequest" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/alerts/archive": { "post": { "description": "Permanently disable a threshold notification and remove it from active monitoring across all customers. Archived threshold notifications stop evaluating immediately and can optionally release their uniqueness key for reuse in future threshold notification configurations.\n\n### Use this endpoint to:\n- Decommission threshold notifications that are no longer needed\n- Clean up test or deprecated threshold notification configurations\n- Free up uniqueness keys for reuse with new threshold notifications\n- Stop threshold notification evaluations without losing historical configuration data\n- Disable outdated monitoring rules during pricing model transitions\n\n### Key response fields:\n- data: Object containing the archived threshold notification's ID\n\n### Usage guidelines:\n- Irreversible for evaluation: Archived threshold notifications cannot be re-enabled; create a new threshold notification to resume monitoring\n- Uniqueness key handling: Set `release_uniqueness_key` : `true` to reuse the key in future threshold notifications\n- Immediate effect: Threshold notification evaluation stops instantly across all customers\n- Historical preservation: Archive operation maintains threshold notification history and configuration for compliance and auditing\n", "operationId": "archiveAlert", "summary": "Archive a threshold notification", "tags": [ "Alerts" ], "requestBody": { "description": "The ID of the threshold notification to archive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveAlertPayload" }, "example": { "id": "8deed800-1b7a-495d-a207-6c52bac54dc9" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Id" } } }, "example": { "data": { "id": "8deed800-1b7a-495d-a207-6c52bac54dc9" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/alerts/create": { "post": { "description": "Create a new threshold notification to monitor customer spending, balances, and billing metrics in real-time. Metronome's notification system provides industry-leading speed with immediate evaluation capabilities, enabling you to proactively manage customer accounts and prevent revenue leakage.\n\nThis endpoint creates configurable threshold notifications that continuously monitor various billing thresholds including spend limits, credit balances, commitment utilization, and invoice totals. Threshold notifications can be configured globally for all customers or targeted to specific customer accounts.\n\n### Use this endpoint to:\n- Proactively monitor customer spending patterns to prevent unexpected overages or credit exhaustion\n- Automate notifications when customers approach commitment limits or credit thresholds\n- Enable real-time intervention for accounts at risk of churn or payment issues\n- Scale billing operations by automating threshold-based workflows and notifications\n\n### Key response fields: \nA successful response returns a CustomerAlert object containing:\n\n- The threshold notification configuration with its unique ID and current status\n- The customer's evaluation status (ok, in_alarm, or evaluating)\n- Threshold notification metadata including type, threshold values, and update timestamps\n\n### Usage guidelines:\n- Immediate evaluation: Set `evaluate_on_create` : `true` (default) for instant evaluation against existing customers\n- Uniqueness constraints: Each threshold notification must have a unique `uniqueness_key` within your organization. Use `release_uniqueness_key` : `true` when archiving to reuse keys\n- Notification type requirements: Different threshold notification types require specific fields (e.g., `billable_metric_id` for usage notifications, `credit_type_id` for credit-based threshold notifications)\n- Webhook delivery: Threshold notifications trigger webhook notifications for real-time integration with your systems. Configure webhook endpoints before creating threshold notifications\n- Performance at scale: Metronome's event-driven architecture processes threshold notification evaluations in real-time as usage events stream in, unlike competitors who rely on periodic polling or batch evaluation cycles\n", "operationId": "createAlert", "summary": "Create a threshold notification", "tags": [ "Alerts" ], "requestBody": { "description": "The details of the threshold notification to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerAlertPayload" }, "example": { "alert_type": "spend_threshold_reached", "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "name": "$100 spend threshold reached", "threshold": 10000, "customer_id": "4db51251-61de-4bfe-b9ce-495e244f3491", "credit_grant_type_filters": [ "enterprise" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Id" } } }, "example": { "data": { "id": "58fb0650-e54a-4d17-93cb-ba8e56c32c65" } } } } } } } }, "/billable-metrics/create": { "post": { "description": "Create billable metrics programmatically with this endpoint—an essential step in configuring your pricing and packaging in Metronome.\n\nA billable metric is a customizable query that filters and aggregates events from your event stream. These metrics are continuously tracked as usage data enters Metronome through the ingestion pipeline. The ingestion process transforms raw usage data into actionable pricing metrics, enabling accurate metering and billing for your products.\n\n### Use this endpoint to: \n- Create individual or multiple billable metrics as part of a setup workflow.\n- Automate the entire pricing configuration process, from metric creation to customer contract setup.\n- Define metrics using either standard filtering/aggregation or a custom SQL query.\n\n### Key response fields: \n- The ID of the billable metric that was created\n- The created billable metric will be available to be used in Products, usage endpoints, and alerts. \n\n### Usage guidelines: \n- Metrics defined using standard filtering and aggregation are Streaming billable metrics, which have been optimized for ultra low latency and high throughput workflows. \n- Use SQL billable metrics if you require more flexible aggregation options.\n", "operationId": "createBillableMetricV1", "summary": "Create a billable metric", "tags": [ "Billable metrics" ], "requestBody": { "description": "The details of the billable metric to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBillableMetricV1Payload" }, "example": { "name": "CPU Hours", "event_type_filter": { "in_values": [ "cpu_usage" ] }, "property_filters": [ { "name": "cpu_hours", "exists": true }, { "name": "region", "exists": true, "in_values": [ "EU", "NA" ] }, { "name": "machine_type", "exists": true, "in_values": [ "slow", "fast" ] } ], "aggregation_type": "SUM", "aggregation_key": "cpu_hours", "group_keys": [ [ "region" ], [ "machine_type" ] ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Id" } } }, "example": { "data": { "id": "58fb0650-e54a-4d17-93cb-ba8e56c32c65" } } } } } } } }, "/billable-metrics/archive": { "post": { "description": "Use this endpoint to retire billable metrics that are no longer used. After a billable metric is archived, that billable metric can no longer be used in any new Products to define how that product should be metered. If you archive a billable metric that is already associated with a Product, the Product will continue to function as usual, metering based on the definition of the archived billable metric. \n\nArchived billable metrics will be returned on the `getBillableMetric` and `listBillableMetrics` endpoints with a populated `archived_at` field.\n", "operationId": "archiveBillableMetric", "summary": "Archive a billable metric", "tags": [ "Billable metrics" ], "requestBody": { "description": "The ID of the billable metric to archive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Id" }, "example": { "id": "8deed800-1b7a-495d-a207-6c52bac54dc9" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Id" } } }, "example": { "data": { "id": "8deed800-1b7a-495d-a207-6c52bac54dc9" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customer-alerts/get": { "post": { "description": "Retrieve the real-time evaluation status for a specific threshold notification-customer pair. This endpoint provides instant visibility into whether a customer has triggered a threshold notification condition, enabling you to monitor account health and take proactive action based on current threshold notification states.\n\n### Use this endpoint to:\n- Check if a specific customer is currently violating an threshold notification (`in_alarm` status)\n- Verify threshold notification configuration details and threshold values for a customer\n- Monitor the evaluation state of newly created or recently modified threshold notification\n- Build dashboards or automated workflows that respond to specific threshold notification conditions\n- Validate threshold notification behavior before deploying to production customers\n- Integrate threshold notification status checks into customer support tools or admin interfaces\n\n### Key response fields: \nA CustomerAlert object containing:\n\n- `customer_status`: The current evaluation state\n\n- `ok` - Customer is within acceptable thresholds\n- `in_alarm` - Customer has breached the threshold for the notification\n- `evaluating` - Notification is currently being evaluated (typically during initial setup)\n- `null` - Notification has been archived\n- `triggered_by`: Additional context about what caused the notification to trigger (when applicable)\n- `updated_at`: Timestamp of when the `customer_status` was last updated\n- alert: Complete threshold notification configuration including:\n - Notification ID, name, and type\n - Current threshold values and credit type information\n - Notification status (enabled, disabled, or archived)\n - Any applied filters (credit grant types, custom fields, group values)\n\n### Usage guidelines:\n- Customer status: Returns the current evaluation state, not historical data. For threshold notification history, use webhook notifications or event logs\n- Required parameters: Both customer_id and alert_id must be valid UUIDs that exist in your organization\n- Archived notifications: Returns null for customer_status if the notification has been archived, but still includes the notification configuration details\n- Performance considerations: This endpoint queries live evaluation state, making it ideal for real-time monitoring but not for bulk status checks\n- Integration patterns: Best used for on-demand status checks in response to user actions or as part of targeted monitoring workflows\n- Error handling: Returns 404 if either the customer or alert_id doesn't exist or isn't accessible to your organization\n", "operationId": "getCustomerAlert", "summary": "Get a threshold notification", "tags": [ "Alerts" ], "requestBody": { "description": "The customer ID and notification ID of the threshold notification to get", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCustomerAlertPayload" }, "example": { "customer_id": "9b85c1c1-5238-4f2a-a409-61412905e1e1", "alert_id": "8deed800-1b7a-495d-a207-6c52bac54dc9" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAlert" } } }, "example": { "data": { "customer_status": "in_alarm", "alert": { "id": "8deed800-1b7a-495d-a207-6c52bac54dc9", "uniqueness_key": "823j7fqzo1", "name": "Low credit balance alert", "type": "low_credit_balance_reached", "status": "enabled", "credit_type": { "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "name": "USD (cents)" }, "threshold": 0, "updated_at": "2022-01-01T00:00:00Z" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customer-alerts/list": { "post": { "description": "Retrieve all threshold notification configurations and their current statuses for a specific customer in a single API call. This endpoint provides a comprehensive view of all threshold notification monitoring a customer account.\n\n### Use this endpoint to:\n- Display all active threshold notifications for a customer in dashboards or admin panels\n- Quickly identify which threshold notifications a customer is currently triggering\n- Audit threshold notification coverage for specific accounts\n- Filter threshold notifications by status (enabled, disabled, or archived)\n\n### Key response fields:\n- data: Array of CustomerAlert objects, each containing:\n - Current evaluation status (`ok`, `in_alarm`, `evaluating`, or `null`)\n - Complete threshold notification configuration and threshold details\n - Threshold notification metadata including type, name, and last update time\n- next_page: Pagination cursor for retrieving additional results\n\n### Usage guidelines:\n- Default behavior: Returns only enabled threshold notifications unless `alert_statuses` filter is specified\n- Pagination: Use the `next_page` cursor to retrieve all results for customers with many notifications\n- Performance: Efficiently retrieves multiple threshold notification statuses in a single request instead of making individual calls\n- Filtering: Pass the `alert_statuses` array to include disabled or archived threshold notifications in results\n", "operationId": "listCustomerAlerts", "summary": "Get all threshold notifications", "parameters": [ { "$ref": "#/components/parameters/NextPage" } ], "tags": [ "Alerts" ], "requestBody": { "description": "The threshold notifications query to run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCustomerAlertsPayload" }, "example": { "customer_id": "9b85c1c1-5238-4f2a-a409-61412905e1e1" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAlert" } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "customer_status": "in_alarm", "alert": { "id": "8deed800-1b7a-495d-a207-6c52bac54dc9", "name": "Low credit balance alert", "uniqueness_key": "823j7fqzo1", "type": "low_credit_balance_reached", "status": "enabled", "credit_type": { "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "name": "USD (cents)" }, "threshold": 0, "updated_at": "2022-01-01T00:00:00Z" } }, { "customer_status": "ok", "alert": { "id": "3d45fdc3-e237-4acd-a7d9-ccfeb40e71b8", "name": "Spend threshold alert", "type": "spend_threshold_reached", "status": "enabled", "credit_type": { "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "name": "USD (cents)" }, "threshold": 1000, "updated_at": "2022-01-01T00:00:00Z" } } ], "next_page": null } } } } } } }, "/customer-alerts/reset": { "post": { "description": "Force an immediate re-evaluation of a specific threshold notification for a customer, clearing any previous state and triggering a fresh assessment against current thresholds. This endpoint ensures threshold notification accuracy after configuration changes or data corrections.\n\n### Use this endpoint to:\n- Clear false positive threshold notifications after fixing data issues\n- Re-evaluate threshold notifications after adjusting customer balances or credits\n- Test threshold notification behavior during development and debugging\n- Resolve stuck threshold notification that may be in an incorrect state\n- Trigger immediate evaluation after threshold modifications\n\n### Key response fields: \n- 200 Success: Confirmation that the threshold notification has been reset and re-evaluation initiated\n- No response body is returned - the operation completes asynchronously\n\n### Usage guidelines:\n- Immediate effect: Triggers re-evaluation instantly, which may result in new webhook notifications if thresholds are breached\n- State clearing: Removes any cached evaluation state, ensuring a fresh assessment\n- Use sparingly: Intended for exceptional cases, not routine operations\n- Asynchronous processing: The reset completes immediately, but re-evaluation happens in the background\n", "operationId": "resetCustomerAlerts", "summary": "Reset a threshold notification", "tags": [ "Alerts" ], "requestBody": { "description": "The customer ID and notification ID of the threshold notification to reset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetCustomerAlertsPayload" }, "example": { "alert_id": "5e8691bf-b22a-4672-922d-f80eee940f01", "customer_id": "4c83caf3-8af4-44e2-9aeb-e290531726d9" } } } }, "responses": { "200": { "description": "Success" } } } }, "/plans": { "get": { "description": "List all available plans. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.", "operationId": "listPlans", "summary": "List plans", "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/NextPage" } ], "tags": [ "Plans" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "id": "94293d66-aa05-4a8e-881a-c90872047b67", "name": "Standard", "description": "Standard self-serve plan", "custom_fields": { "x_account_id": "KyVnHhSBWl7eY2bl" } }, { "id": "d2c06dae-9549-4d7d-bc04-b78dd3d241b8", "name": "Aperture, Inc.", "description": "Custom enterprise plan for Aperture with ramped minimums", "custom_fields": { "x_account_id": "KyVnHhSBWl7eY2byd" } } ], "next_page": null } } } } } } }, "/planDetails/{plan_id}": { "get": { "description": "Fetch high level details of a specific plan. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "getPlanDetails", "summary": "Get plan details", "parameters": [ { "$ref": "#/components/parameters/PlanId" } ], "tags": [ "Plans" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PlanDetail" } } }, "example": { "data": { "id": "d46c3bce-40a6-4fbf-9b45-fcb00d45ad5f", "name": "Plan with Minimums", "description": "A plan with minimums", "credit_grants": [ { "name": "Acme Corp Promotional Credit Grant", "amount_granted": 2400, "amount_paid": 1500, "effective_duration": 3, "priority": "1", "send_invoice": true, "reason": "Prepaid grant", "recurrence_interval": 1, "amount_granted_credit_type": { "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "name": "USD (cents)" }, "amount_paid_credit_type": { "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "name": "USD (cents)" } } ], "minimums": [ { "name": "Invoice minimum", "value": 10000, "start_period": 0, "credit_type": { "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "name": "USD (cents)" } } ], "overage_rates": [ { "start_period": 0, "to_fiat_conversion_factor": 1600, "fiat_credit_type": { "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "name": "USD (cents)" }, "credit_type": { "id": "d46c3bce-40a6-4fbf-9b45-fcb00d45ad5f", "name": "MetroBux" } } ], "custom_fields": { "x_account_id": "KyVnHhSBWl7eY2bl" } } } } } } } } }, "/planDetails/{plan_id}/customers": { "get": { "description": "Fetches a list of customers on a specific plan (by default, only currently active plans are included). This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "getPlanCustomers", "summary": "List customers on a plan", "parameters": [ { "$ref": "#/components/parameters/PlanId" }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/NextPage" }, { "$ref": "#/components/parameters/CustomerPlanStatus" } ], "tags": [ "Plans" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAndPlanDetail" } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "customer_details": { "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z", "external_id": "team@example.com", "ingest_aliases": [ "team@example.com" ], "name": "Example, Inc.", "customer_config": { "salesforce_account_id": "0015500001WO1ZiABL" }, "custom_fields": { "x_account_id": "KyVnHhSBWl7eY2bl" } }, "plan_details": { "id": "d46c3bce-40a6-4fbf-9b45-fcb00d45ad5f", "name": "Plan with Minimums", "ending_before": "2024-04-01T00:00:00Z", "starting_on": "2022-02-01T00:00:00Z", "custom_fields": { "x_account_id": "KyVnHhSBWl7eY2bl" }, "customer_plan_id": "a23b3cf4-47fb-4c3f-bb3d-9e64f7704015" } } ], "next_page": null } } } } } } }, "/planDetails/{plan_id}/charges": { "get": { "description": "Fetches a list of charges of a specific plan. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "getPlanCharges", "summary": "List plan charges", "parameters": [ { "$ref": "#/components/parameters/PlanId" }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/NextPage" } ], "tags": [ "Plans" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlanCharge" } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "id": "a23b3cf4-47fb-4c3f-bb3d-9e64f7704015", "name": "Server Hours", "product_id": "d7998a03-db47-4d3f-97e4-d26f3f418718", "product_name": "Dedicated Server", "start_period": 0, "tier_reset_frequency": 1, "credit_type": { "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "name": "USD (cents)" }, "charge_type": "usage", "prices": [ { "value": 50, "tier": 0 } ], "custom_fields": { "x_account_id": "KyVnHhSBWl7eY2bl" } } ], "next_page": "31646362333134302d363735362d346661372d396436362d383" } } } } } } }, "/client/billing-config/{billing_provider_type}/apiKey": {}, "/client/config/webhook_secret": {}, "/client/billing-config/stripe": {}, "/credits/{customer_id}/rechargeSettings/{recharge_settings_id}": { "post": { "x-mint": { "groups": [ "ff:prepaid-credits" ] }, "description": "Update an existing recharge setting for the customer. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "updateRechargeSetting", "summary": "Update the recharge setting", "tags": [ "Credit grants" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" }, { "$ref": "#/components/parameters/RechargeSettingsId" } ], "requestBody": { "description": "The recharge settings to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RechargeSettingsPayload" }, "example": { "recharge_to_amount": 1000, "recharge_threshold": 300, "enabled": true, "name": "Recharge top up grant", "grant_duration": 6, "credit_type_id": "5ae401dc-a648-4b49-9ac3-391bb5bc4d7b", "priority": 100, "prepaid_options": { "billing_provider_type": "stripe", "stripe_options": { "calculate_tax": true, "redirect_url": "https://example.com/action_required_redirect", "invoice_custom_fields": [ { "name": "x_account_id", "value": "KyVnHhSBWl7eY2bl" } ], "invoice_metadata": { "ex_metadata1": "metadata value 1", "ex_metadata22": "metadata value 2" } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id" ], "properties": { "id": { "description": "The recharge setting ID.", "type": "string", "format": "uuid" }, "recharge": { "description": "Information about the status of the recharge if recharge_now is true and the balance was below the recharge threshold.", "type": "object", "required": [ "success", "billing_provider_payment" ], "properties": { "success": { "type": "boolean", "description": "Whether the prepaid grant was successfully created." }, "credit_grant_id": { "description": "The credit grant ID.", "type": "string", "format": "uuid" }, "billing_provider_payment": { "type": "object", "required": [ "billing_provider_type" ], "properties": { "billing_provider_type": { "type": "string" }, "stripe_payment_info": { "type": "object", "description": "For Stripe payments only.", "properties": { "error_code": { "type": "string", "description": "The error code received from Stripe if one was sent." } } } } } } } } } } }, "example": { "data": { "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc" } } } } } } } }, "/credits/{customer_id}/rechargeSettings": { "post": { "x-mint": { "groups": [ "ff:prepaid-credits" ] }, "description": "Creates a new recharge setting for the customer. This is used for automatically recharging prepaid credits when the balance reaches a threshold. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "createRechargeSetting", "summary": "Create a recharge setting", "tags": [ "Credit grants" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "requestBody": { "description": "The recharge settings to set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RechargeSettingsPayload" }, "example": { "recharge_to_amount": 1000, "recharge_threshold": 300, "name": "Recharge top up grant", "priority": 100, "grant_duration": 6, "credit_type_id": "5ae401dc-a648-4b49-9ac3-391bb5bc4d7b", "prepaid_options": { "billing_provider_type": "stripe", "stripe_options": { "calculate_tax": true, "redirect_url": "https://example.com/action_required_redirect", "invoice_custom_fields": [ { "name": "x_account_id", "value": "KyVnHhSBWl7eY2bl" } ], "invoice_metadata": { "ex_metadata1": "metadata value 1", "ex_metadata22": "metadata value 2" } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id" ], "properties": { "id": { "description": "The recharge setting ID.", "type": "string", "format": "uuid" }, "recharge": { "description": "Information about the status of the recharge if recharge_now is true and the balance was below the recharge threshold.", "type": "object", "required": [ "success", "billing_provider_payment" ], "properties": { "success": { "type": "boolean", "description": "Whether the prepaid grant was successfully created." }, "credit_grant_id": { "description": "The credit grant ID.", "type": "string", "format": "uuid" }, "billing_provider_payment": { "type": "object", "required": [ "billing_provider_type" ], "properties": { "billing_provider_type": { "type": "string" }, "stripe_payment_info": { "type": "object", "description": "For Stripe payments only.", "properties": { "error_code": { "type": "string", "description": "The error code received from Stripe if one was sent." } } } } } } } } } } }, "example": { "data": { "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc" } } } } } } }, "get": { "x-mint": { "groups": [ "ff:prepaid-credits" ] }, "description": "Gets the recharge settings for the customer. This is used for automatically recharging prepaid credits when the balance reaches a threshold. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "getRechargeSettings", "summary": "Get the recharge settings", "tags": [ "Credit grants" ], "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GetRechargeSettingsPayload" } } } }, "example": { "data": [ { "name": "Recharge top up grant", "recharge_to_amount": 1000, "recharge_threshold": 300, "enabled": true, "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "priority": 100, "grant_duration": 6, "credit_type_id": "5ae401dc-a648-4b49-9ac3-391bb5bc4d7b", "prepaid_options": { "billing_provider_type": "stripe", "stripe_options": { "calculate_tax": true, "redirect_url": "https://example.com/action_required_redirect", "invoice_custom_fields": [ { "name": "x_account_id", "value": "KyVnHhSBWl7eY2bl" } ], "invoice_metadata": { "ex_metadata1": "metadata value 1", "ex_metadata22": "metadata value 2" } } } } ] } } } } } } }, "/credits/createPrepaidGrant": { "post": { "x-mint": { "groups": [ "ff:prepaid-credits" ] }, "description": "Create a new prepaid credit grant. Prepaid credit grants function like regular credit grants except they require payment through Stripe before they are released. Prepaid credit grants are automatically topped up when a customer's balance goes below a specific threshold.\nIf the prepaid grant was successfully created, the response includes the credit grant ID and information about the billing provider payment (in the `billing_provider_payment` field).\nIf the payment requires action from the customer, the response includes a payment_status field of \"requires_action\" on the `billing_provider_payment.stripe_payment_info` object.\nIf the request fails it returns a 4xx level error. Example failures include:\n- a negative grant_amount - the customer provided does not have a Stripe ID associated with their Metronome account\nThis is a Plans (deprecated) endpoint. New clients should implement using Contracts. - issues in Stripe such as no default payment method\nIf there are Stripe errors, the response includes the Stripe response in the `stripe_error` field.\n", "operationId": "createPrepaidGrant", "summary": "Create a prepaid credit grant", "tags": [ "Credit grants" ], "requestBody": { "description": "The details of the credit grant to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePrepaidCreditGrantPayload" }, "example": { "customer_id": "9b85c1c1-5238-4f2a-a409-61412905e1e1", "grant_amount": { "amount": 1000, "credit_type_id": "5ae401dc-a648-4b49-9ac3-391bb5bc4d7b" }, "name": "Acme Corp Promotional Credit Grant", "reason": "Incentivize new customer", "effective_at": "2022-02-01T00:00:00Z", "invoice_date": "2022-02-01T00:00:00Z", "expires_at": "2022-04-01T00:00:00Z", "paid_amount": { "amount": 5000, "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2" }, "priority": 0.5, "prepaid_options": { "billing_provider_type": "stripe", "stripe_options": { "calculate_tax": true, "redirect_url": "https://example.com/action_required_redirect", "invoice_custom_fields": [ { "name": "x_account_id", "value": "KyVnHhSBWl7eY2bl" } ], "invoice_metadata": { "ex_metadata1": "metadata value 1", "ex_metadata22": "metadata value 2" } } }, "credit_grant_type": "enterprise" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "billing_provider_payment" ], "properties": { "id": { "description": "The credit grant ID or an empty value if further action is required.", "type": "string", "format": "uuid" }, "billing_provider_payment": { "type": "object", "required": [ "billing_provider_type" ], "properties": { "billing_provider_type": { "type": "string" }, "stripe_payment_info": { "type": "object", "description": "For Stripe payments only. Information about the Stripe invoice.", "required": [ "payment_status" ], "properties": { "invoice_id": { "type": "string" }, "payment_status": { "type": "string", "description": "Payment status of the prepaid grant. If `requires_action`, use `next_action_type` to perform next steps.", "enum": [ "success", "fail", "requires_action" ] }, "next_action_type": { "type": "string", "description": "Type of the next action to perform. If `redirect_to_url`, the user should be sent redirected to the value of `target_redirect_url`. If `use_stripe_sdk`, then the contents of `next_action_stripe_sdk` should be passed to Stripe.js. This also applies when the payment method requires 3D Secure and no `target_redirect_url` was provided.", "enum": [ "redirect_to_url", "use_stripe_sdk" ] }, "target_redirect_url": { "type": "string", "description": "Redirect URL to the billing provider's payment page. Only present if `payment_status` is `requires_action` and `next_action_type` is `redirect_to_url`." }, "next_action_stripe_sdk": { "type": "object", "description": "The contents of this should be passed to Stripe.js to perform next steps. Only present if `payment_status` is `requires_action` and `next_action_type` is `use_stripe_sdk`.", "additionalProperties": true }, "payment_intent_client_secret": { "type": "string", "description": "The client_secret of the payment intent. Can be used to perform next steps with Stripe.js." }, "error_code": { "type": "string", "description": "The error code received from Stripe if one was sent." } } } } } } } } }, "example": { "data": { "id": "8b24d3dc-6db5-432d-9416-8439b3fbf242", "billing_provider_payment": { "billing_provider_type": "stripe", "stripe_payment_info": { "invoice_id": "in_1J5Z2n2eZvKYlo2C0Z1Z2n2e", "payment_status": "requires_action", "target_redirect_url": "https://example.com/action_required_redirect", "next_action_type": "redirect_to_url" } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrepaidGrantError" } } } } } } }, "/credits/createGrant": { "post": { "description": "Create a new credit grant. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "createGrant", "summary": "Create a credit grant", "tags": [ "Credit grants" ], "requestBody": { "description": "The details of the credit grant to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCreditGrantPayload" }, "example": { "customer_id": "9b85c1c1-5238-4f2a-a409-61412905e1e1", "grant_amount": { "amount": 1000, "credit_type_id": "5ae401dc-a648-4b49-9ac3-391bb5bc4d7b" }, "name": "Acme Corp Promotional Credit Grant", "reason": "Incentivize new customer", "effective_at": "2022-02-01T00:00:00Z", "expires_at": "2022-04-01T00:00:00Z", "paid_amount": { "amount": 5000, "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2" }, "priority": 0.5, "credit_grant_type": "trial" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Id" } } }, "example": { "data": { "id": "8b24d3dc-6db5-432d-9416-8439b3fbf242" } } } } } } } }, "/credits/editGrant": { "post": { "description": "Edit an existing credit grant. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "editGrant", "summary": "Update a credit grant", "tags": [ "Credit grants" ], "requestBody": { "description": "The id of the credit grant to edit and the updated fields. Currently only the name and expires_at fields can be updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditCreditGrantPayload" }, "example": { "id": "9b85c1c1-5238-4f2a-a409-61412905e1e1", "name": "Acme Corp Promotional Credit Grant", "expires_at": "2022-04-01T00:00:00Z" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Id" } } }, "example": { "data": { "id": "8b24d3dc-6db5-432d-9416-8439b3fbf242" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/credits/voidGrant": { "post": { "description": "Void a credit grant. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "voidGrant", "summary": "Void a credit grant", "tags": [ "Credit grants" ], "requestBody": { "description": "The ID of the grant to void", "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "void_credit_purchase_invoice": { "type": "boolean", "description": "If true, void the purchase invoice associated with the grant" }, "release_uniqueness_key": { "type": "boolean", "description": "If true, resets the uniqueness key on this grant so it can be re-used" } } }, "example": { "id": "9b85c1c1-5238-4f2a-a409-61412905e1e1" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Id" } } }, "example": { "data": { "id": "8b24d3dc-6db5-432d-9416-8439b3fbf242" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/credits/listGrants": { "post": { "description": "List credit grants. This list does not included voided grants. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "listGrants", "summary": "List credit grants", "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/NextPage" } ], "requestBody": { "description": "Filters specifying which credit grants should be included", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCreditGrantPayload" }, "example": { "credit_type_ids": [ "2714e483-4ff1-48e4-9e25-ac732e8f24f2" ], "customer_ids": [ "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "0e5b8609-d901-4992-b394-c3c2e3f37b1c" ], "not_expiring_before": "2022-02-01T00:00:00Z", "effective_before": "2022-02-01T00:00:00Z" } } } }, "tags": [ "Credit grants" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditGrant" } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "id": "9acbc1d0-2044-44c4-8577-f6078a1d8cd2", "name": "Initial credit purchase", "customer_id": "b310b282-d5cf-4e4f-915f-d8c3c4971e45", "uniqueness_key": "823j7fqzo1", "reason": "Prepayment", "effective_at": "2022-01-01T00:00:00.000Z", "expires_at": "2022-04-01T00:00:00.000Z", "priority": 0.5, "grant_amount": { "amount": 100, "credit_type": { "id": "fa2f1b3d-9d52-4951-a099-25991fd394d6", "name": "cloud consumption units" } }, "paid_amount": { "amount": 10, "credit_type": { "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "name": "USD (cents)" } }, "balance": { "including_pending": 80, "excluding_pending": 80, "effective_at": "2022-02-01T00:00:00.000Z" }, "deductions": [ { "amount": 20, "reason": "Automated invoice deduction", "running_balance": 80, "effective_at": "2022-02-01T00:00:00.000Z", "created_by": "Metronome System", "credit_grant_id": "9acbc1d0-2044-44c4-8577-f6078a1d8cd2", "invoice_id": "b6a60e95-15f4-403c-be40-f1c1d58cee20" } ], "pending_deductions": [], "custom_fields": { "x_account_id": "KyVnHhSBWl7eY2bl" }, "credit_grant_type": "enterprise" } ], "next_page": null } } } } } } }, "/credits/migrateToContracts": { "post": { "x-mint": { "groups": [ "client_id:462b838b-1582-4100-816e-f6c07bb604fe", "client_id:c187f54f-e807-4cf6-8fa1-a01f09d05412", "client_id:8e3a848a-4566-4cfb-be49-64d80118a7fc", "client_id:aa2899ec-16ad-413b-b20b-ec9ba4692d4e" ] }, "operationId": "migrateCreditGrantsToContracts", "summary": "Migrate plans credit grants to contracts credits and commits.", "description": "Migrates a given customer's plan credit grants to contract credits and commits in batches.\nCallers should check the `has_more` field of the response to determine if there are more credit grants to migrate.\n\n- Plan credit grants with no cost basis get migrated to contract credits.\n- Plan credit grants with positive cost basis get migrated to contract Commits with an empty invoice schedule so they don't get re-invoiced.\n- Deductions from existing grants are migrated to one-off contract deductions.\n- If not hour-aligned, the `effective_at` date of the migrated plan credit grant is rounded down to the nearest hour. e.g. 2024-01-01T12:34:56Z becomes 2024-01-01T12:00:00Z\n- If not hour-aligned, the `expires_at` date of the migrated plan credit grant is rounded up to the nearest hour. e.g. 2024-01-01T12:34:56Z becomes 2024-01-01T13:00:00Z\n\nThis is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n- The migrated plan credit grants are truncated to the cutover date, or voided if they fall completely after the cutover date.", "requestBody": { "description": "Parameters for migrating credit grants to contracts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_id", "cutover_date", "contract_credits_product_id", "contract_prepaid_commits_product_id" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "The customer ID to migrate credit grants for." }, "cutover_date": { "type": "string", "format": "date-time", "description": "The date to truncate existing plan credit grants to. This should likely be the end date of the customer's most recently finalized invoice." }, "contract_credits_product_id": { "type": "string", "format": "uuid", "description": "The product ID to use for contract credits." }, "contract_prepaid_commits_product_id": { "type": "string", "format": "uuid", "description": "The product ID to use for contract prepaid commits." }, "contract_credits_priority_override": { "type": "number", "description": "The priority to use for contract credits." }, "contract_prepaid_commits_priority_override": { "type": "number", "description": "The priority to use for contract prepaid commits." }, "grant_to_contract_commit_mapping": { "type": "array", "items": { "type": "object", "description": "Mapping configuration for migrating specific credit grants to contract commits", "properties": { "credit_grant_id": { "type": "string", "format": "uuid", "description": "The ID of the credit grant to migrate" }, "contract_id": { "type": "string", "format": "uuid", "description": "The ID of the contract to migrate to" }, "product_id": { "type": "string", "format": "uuid", "description": "The ID of the product to use for the contract commit" } } }, "description": "Optional mapping configuration for migrating specific credit grants to contract commits. If not provided, defaults to empty array." }, "dry_run": { "type": "boolean", "description": "If true, perform a dry run without actually executing the migration. If not provided, defaults to false." }, "batch_size": { "type": "number", "description": "The number of credit grants to migrate in this batch." } } }, "example": { "customer_id": "9b85c1c1-5238-4f2a-a409-61412905e1e1", "cutover_date": "2024-02-01T00:00:00Z", "contract_credits_product_id": "7d21bedf-0f29-4dfe-b5a9-e90888ca46cf", "contract_prepaid_commits_product_id": "098bf77f-d6bf-4d08-816f-c9434fdc90fa", "contract_credits_priority_override": 0.5, "contract_prepaid_commits_priority_override": 0.5, "grant_to_contract_commit_mapping": [ { "credit_grant_id": "123e4567-e89b-12d3-a456-426614174000", "contract_id": "987fcdeb-51a2-43d1-9b8c-765432109876", "product_id": "abc12345-6789-0123-4567-890123456789" }, { "credit_grant_id": "456e7890-e89b-12d3-a456-426614174001", "contract_id": "654fcdeb-51a2-43d1-9b8c-765432109875", "product_id": "def67890-1234-5678-9012-345678901234" } ], "dry_run": false, "batch_size": 300 } } } }, "tags": [ "Credit grants" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "credit_grants_migrated", "has_more" ], "properties": { "credit_grants_migrated": { "type": "number", "description": "The number of credit grants migrated." }, "has_more": { "type": "boolean", "description": "Whether the customer has more credit grants to migrate." } } } } } } } } }, "/credit-types/list": { "get": { "description": "List all pricing units. All fiat currency types (for example, USD or GBP) will be included, as well as any custom pricing units that were configured. Custom pricing units can be used to charge for usage in a non-fiat pricing unit, for example AI credits.\n\nNote: The USD (cents) pricing unit is 2714e483-4ff1-48e4-9e25-ac732e8f24f2.\n", "operationId": "listCreditTypes", "summary": "List pricing units", "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/NextPage" } ], "tags": [ "Settings" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "properties": { "name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "is_currency": { "type": "boolean" } } } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "name": "USD (cents)", "is_currency": true }, { "id": "fa2f1b3d-9d52-4951-a099-25991fd394d6", "name": "cloud consumption units", "is_currency": false } ], "next_page": null } } } } } } }, "/credit-types/create": { "post": { "description": "Create a custom pricing unit. Custom pricing units can be used to charge for usage in a non-fiat pricing unit, for example AI credits.\n", "operationId": "createCreditType", "summary": "Create a pricing unit", "tags": [ "Settings" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the custom pricing unit. This will appear on invoices." } } }, "example": { "name": "AI Credits" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Id" } } }, "example": { "data": { "id": "fa2f1b3d-9d52-4951-a099-25991fd394d6" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/credit-types/archive": { "post": { "description": "Archive a custom pricing unit. Once archived, it will no longer appear in pricing unit selectors by default.\n", "operationId": "archiveCreditType", "summary": "Archive a pricing unit", "tags": [ "Settings" ], "requestBody": { "description": "The ID of the pricing unit to archive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Id" }, "example": { "id": "fa2f1b3d-9d52-4951-a099-25991fd394d6" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Id" } } }, "example": { "data": { "id": "fa2f1b3d-9d52-4951-a099-25991fd394d6" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customers/{customer_id}/plans": { "get": { "description": "List the given customer's plans in reverse-chronological order. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "listCustomerPlans", "summary": "List customer plans", "parameters": [ { "$ref": "#/components/parameters/CustomerId" }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/NextPage" } ], "tags": [ "Plans" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPlan" } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "id": "7aa11640-0703-4600-8eb9-293f535a6b74", "plan_id": "94293d66-aa05-4a8e-881a-c90872047b67", "plan_name": "Standard", "plan_description": "The standard plan for all customers", "starting_on": "2021-01-01T00:00:00Z", "trial_info": { "ending_before": "2021-01-15T00:00:00Z", "spending_caps": [] }, "custom_fields": { "x_account_id": "KyVnHhSBWl7eY2bl" } } ], "next_page": null } } } } } } }, "/customers/{customer_id}/plans/add": { "post": { "description": "Associate an existing customer with a plan for a specified date range. See the [price adjustments documentation](https://plans-docs.metronome.com/pricing/managing-plans/#price-adjustments) for details on the price adjustments. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "addPlanToCustomer", "summary": "Add a plan to a customer", "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "requestBody": { "description": "The customer ID, plan ID, and date range for the plan to be applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPlanToCustomerPayload" }, "example": { "plan_id": "d2c06dae-9549-4d7d-bc04-b78dd3d241b8", "starting_on": "2021-02-01T00:00:00Z", "ending_before": "2022-02-01T00:00:00Z" } } } }, "tags": [ "Plans" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Id" } } }, "example": { "data": { "id": "8b24d3dc-6db5-432d-9416-8439b3fbf242" } } } } } } } }, "/customers/{customer_id}/plans/{customer_plan_id}/priceAdjustments": { "get": { "description": "Lists a customer plans adjustments. See the [price adjustments documentation](https://plans-docs.metronome.com/pricing/managing-plans/#price-adjustments) for details. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "getPlanPriceAdjustments", "summary": "Get the plan adjustments for a customer", "parameters": [ { "$ref": "#/components/parameters/CustomerId" }, { "$ref": "#/components/parameters/CustomerPlanId" }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/NextPage" } ], "tags": [ "Plans" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PriceAdjustment" } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "charge_id": "8b24d3dc-6db5-432d-9416-8439b3fbf242", "charge_type": "usage", "start_period": 0, "prices": [ { "adjustment_type": "fixed", "value": -0.05 }, { "adjustment_type": "quantity", "value": 2 }, { "adjustment_type": "override", "tier": 2, "value": 4 } ] }, { "charge_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "charge_type": "fixed", "start_period": 1, "prices": [ { "adjustment_type": "percentage", "value": -5 } ] } ], "next_page": "31646362333134302d363735362d346661372d396436362d383" } } } } } } }, "/customers/{customer_id}/plans/{customer_plan_id}/end": { "post": { "description": "Change the end date of a customer's plan. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "endCustomerPlan", "summary": "End a customer plan", "parameters": [ { "$ref": "#/components/parameters/CustomerId" }, { "$ref": "#/components/parameters/CustomerPlanId" } ], "requestBody": { "description": "The date at which this customer's plan should end", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndCustomerPlanPayload" }, "example": { "ending_before": "2021-02-01T00:00:00Z" } } } }, "tags": [ "Plans" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "x-stainless-empty-object": true } } } } } } }, "/ingest": { "post": { "description": "The ingest endpoint is the primary method for sending usage events to Metronome, serving as the foundation for all billing calculations in your usage-based pricing model. This high-throughput endpoint is designed for real-time streaming ingestion, supports backdating 34 days, and is built to handle mission-critical usage data with enterprise-grade reliability. Metronome supports 100,000 events per second without requiring pre-aggregation or rollups and can scale up from there. See the [Send usage events](/guides/events/send-usage-events) guide to learn more about usage events.\n\n### Use this endpoint to:\nCreate a customer usage pipeline into Metronome that drives billable metrics, credit drawdown, and invoicing. Track customer behavior, resource consumption, and feature usage\n\n### What happens when you send events:\n- Events are validated and processed in real-time\n- Events are matched to customers using customer IDs or customer ingest aliases\n- Events are matched to billable metrics and are immediately available for usage and spend calculations\n\n### Usage guidelines:\n- Historical events can be backdated up to 34 days and will immediately impact live customer spend\n- Duplicate events are automatically detected and ignored (34-day deduplication window)\n\n#### Event structure:\nUsage events are simple JSON objects designed for flexibility and ease of integration:\n```json\n{\n \"transaction_id\": \"2021-01-01T00:00:00Z_cluster42\",\n \"customer_id\": \"team@example.com\",\n \"event_type\": \"api_request\",\n \"timestamp\": \"2021-01-01T00:00:00Z\",\n \"properties\": {\n \"endpoint\": \"/v1/users\",\n \"method\": \"POST\",\n \"response_time_ms\": 45,\n \"region\": \"us-west-2\"\n }\n}\n```\n\nLearn more about [usage event structure definitions](/guides/events/design-usage-events).\n\n#### Transaction ID\n The transaction_id serves as your idempotency key, ensuring events are processed exactly once. Metronome maintains a 34-day deduplication window - significantly longer than typical 12-hour windows - enabling robust backfill scenarios without duplicate billing.\n - Best Practices:\n - Use UUIDs for one-time events: uuid4()\n - For heartbeat events, use deterministic IDs\n - Include enough context to avoid collisions across different event sources\n\n#### Customer ID\nIdentifies which customer should be billed for this usage. Supports two identification methods:\n - Metronome Customer ID: The UUID returned when creating a customer\n - Ingest Alias: Your system's identifier (email, account number, etc.) \n\nIngest aliases enable seamless integration without requiring ID mapping, and customers can have multiple aliases for flexibility.\n\n#### Event Type:\nCategorizes the event type for billable metric matching. Choose descriptive names that aligns with the product surface area.\n\n#### Properties:\nFlexible metadata also used to match billable metrics or to be used to serve as group keys to create multiple pricing dimensions or breakdown costs by novel properties for end customers or internal finance teams measuring underlying COGs.\n", "operationId": "ingest", "summary": "Ingest events", "x-nlb-domain-variable": "ingestnlbDomain", "x-vpc-connection-id-variable": "ingestvpcLinkId", "x-slo-tier": 1, "tags": [ "Usage" ], "responses": { "200": { "description": "Success" } }, "requestBody": { "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Event" } }, "example": [ { "transaction_id": "2021-01-01T00:00:00Z_cluster42", "customer_id": "team@example.com", "event_type": "heartbeat", "timestamp": "2021-01-01T00:00:00Z", "properties": { "cluster_id": "42", "cpu_seconds": 60, "region": "Europe" } } ] } } } } }, "/usage/seats": {}, "/usage/groups": { "post": { "description": "Retrieve granular usage data for a specific customer and billable metric, with the ability to break down usage by custom grouping dimensions. This endpoint enables deep usage analytics by segmenting data across attributes like region, user, model type, or any custom dimension defined in your billable metrics.\n\n### Use this endpoint to:\n- Analyze usage patterns broken down by specific attributes (region, user, department, etc.)\n- Build detailed usage dashboards with dimensional filtering\n- Identify high-usage segments for optimization opportunities\n\n### Request parameters\nUse [`group_key`](#body-group-key) and [`group_filters`](#body-group-filters) to group by one or more dimensions. This is required for compound group keys and recommended for all new integrations:\n```json\n{\n \"group_key\": [\"region\", \"team\"],\n \"group_filters\": {\n \"region\": [\"US-East\", \"US-West\"]\n }\n}\n```\nImportant: For compound group keys, you must pass the complete set of keys that make up the compound key. Partial key combinations are not supported. For example, if your billable metric has a compound group key [region, team, environment], you must pass all three keys in group_key—you cannot pass just `[region]` or `[region, team]`.\n\n### Key response fields:\nAn array of `PagedUsageAggregate` objects containing:\n- `starting_on` and `ending_before`: Time window boundaries\n- `group`: Object mapping group keys to their values\n - For simple groups, this will be a map with a single key-value pair (e.g., `{\"region\": \"US-East\"}`)\n - For compound groups, this will be a map with multiple key-value pairs (e.g., `{\"region\": \"US-East\", \"team\": \"engineering\"}`)\n- `value`: Aggregated usage for this group and time window\n- `next_page`: Pagination cursor for large datasets\n\n### Usage guidelines:\n- Required parameters: Must specify `customer_id`, `billable_metric_id`, and `window_size`\n- Time windows: Set `window_size` to hour, day, or none for different granularities\n- Group filtering: Use `group_key` and `group_filters` to specify groups and group filters. Across all arrays in `group_filters`, include at most 200 filter values total. Requests with more than 200 filter values are rejected when this limit is enforced\n- Response limit: When using compound group keys (2+ keys in `group_key`), the default and maximum page size is 100\n- Pagination: Use limit and `next_page` for large result sets\n- Null handling: Group values may be null for events missing the group key property\n", "operationId": "getPagedUsage", "summary": "Get usage data with paginated groupings", "x-slo-tier": 1, "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/NextPage" } ], "requestBody": { "description": "The usage query to run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedUsageQueryPayload" }, "examples": { "using_simple_group_key": { "summary": "Simple (single key) group_key", "value": { "customer_id": "04ca7e72-4229-4a6e-ab11-9f7376fccbcb", "billable_metric_id": "222796fd-d29c-429e-89b2-549fabda4ed6", "starting_on": "2021-01-01T00:00:00Z", "ending_before": "2021-01-03T00:00:00Z", "window_size": "day", "group_key": [ "region" ], "group_filters": { "region": [ "us-east1", "us-west1" ] } } }, "using_compound_group_key": { "summary": "Compound (multi-key) group_key with group_filters", "value": { "customer_id": "04ca7e72-4229-4a6e-ab11-9f7376fccbcb", "billable_metric_id": "222796fd-d29c-429e-89b2-549fabda4ed6", "starting_on": "2021-01-01T00:00:00Z", "ending_before": "2021-01-03T00:00:00Z", "window_size": "day", "group_key": [ "region", "team" ], "group_filters": { "region": [ "us-east1", "us-west1" ], "team": [ "ui" ] } } } } } } }, "tags": [ "Usage" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PagedUsageAggregate" } }, "next_page": { "type": "string", "nullable": true } } }, "examples": { "using_simple_group_key": { "summary": "Response using single-key group_key", "value": { "data": [ { "starting_on": "2021-01-01T00:00:00Z", "ending_before": "2021-01-02T00:00:00Z", "group_key": "region", "group_value": "us-east1", "group": { "region": "us-east1" }, "value": 1234 }, { "starting_on": "2021-01-01T00:00:00Z", "ending_before": "2021-01-02T00:00:00Z", "group_key": "region", "group_value": "us-west1", "group": { "region": "us-west1" }, "value": 567 } ], "next_page": null } }, "using_compound_group_key": { "summary": "Response using compound group_key and group_filters", "value": { "data": [ { "starting_on": "2021-01-01T00:00:00Z", "ending_before": "2021-01-02T00:00:00Z", "group_key": null, "group_value": null, "group": { "region": "us-east1", "team": "ui" }, "value": 1234 }, { "starting_on": "2021-01-01T00:00:00Z", "ending_before": "2021-01-02T00:00:00Z", "group_key": null, "group_value": null, "group": { "region": "us-west1", "team": "ui" }, "value": 890 } ], "next_page": null } } } } } } } } }, "/usage": { "post": { "description": "Retrieve aggregated usage data across multiple customers and billable metrics in a single query. This batch endpoint enables you to fetch usage patterns at scale, broken down by time windows, making it ideal for building analytics dashboards, generating reports, and monitoring platform-wide usage trends.\n\n### Use this endpoint to:\n- Generate platform-wide usage reports for internal teams\n- Monitor aggregate usage trends across your entire customer base\n- Create comparative usage analyses between customers or time periods\n- Support capacity planning with historical usage patterns\n\n### Key response fields:\nAn array of `UsageBatchAggregate` objects containing:\n\n- `customer_id`: The customer this usage belongs to\n- `billable_metric_id` and `billable_metric_name`: What was measured\n- `start_timestamp` and `end_timestamp`: Time window for this data point\n- `value`: Aggregated usage amount for the period\n- `groups` (optional): Usage broken down by group keys with values\n- `next_page`: Pagination cursor for large result sets\n\n### Usage guidelines:\n- Time windows: Set `window_size` to `hour`, `day`, or `none` (entire period)\n- Required parameters: Must specify `starting_on`, `ending_before`, and `window_size`\n- Filtering options:\n - `customer_ids`: Limit to specific customers (omit for all customers)\n - `billable_metrics`: Limit to specific metrics (omit for all metrics)\n- Pagination: Use `next_page` cursor to retrieve large datasets\n- Null values: Group values may be null when no usage matches that group\n", "operationId": "getUsageBatch", "summary": "Get batched usage data", "parameters": [ { "$ref": "#/components/parameters/NextPage" } ], "requestBody": { "description": "The usage query to run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageBatchQueryPayload" }, "example": { "window_size": "day", "starting_on": "2021-01-01T00:00:00Z", "ending_before": "2021-01-03T00:00:00Z" } } } }, "tags": [ "Usage" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBatchAggregate" } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "customer_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "billable_metric_id": "9570e4f3-d1da-4b95-ba81-bd40ee002727", "billable_metric_name": "CPU hours", "start_timestamp": "2021-01-01T00:00:00Z", "end_timestamp": "2021-01-02T00:00:00Z", "value": 1234 }, { "customer_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "billable_metric_id": "9570e4f3-d1da-4b95-ba81-bd40ee002727", "billable_metric_name": "CPU hours", "start_timestamp": "2021-01-02T00:00:00Z", "end_timestamp": "2021-01-03T00:00:00Z", "value": 1234 } ], "next_page": null } } } } } } }, "/events/search": { "post": { "description": "This endpoint retrieves events by transaction ID for events that occurred within the last 34 days. It is specifically designed for sampling-based testing workflows to detect revenue leakage. The Event Search API provides a critical observability tool that validates the integrity of your usage pipeline by allowing you to sample raw events and verify their matching against active billable metrics. \n\nWhy event observability matters for revenue leakage:\nSilent revenue loss occurs when events are dropped, delayed, or fail to match billable metrics due to:\n- Upstream system failures\n- Event format changes\n- Misconfigured billable metrics\n\n### Use this endpoint to:\n- Sample raw events and validate they match the expected billable metrics\n- Build custom leakage detection alerts to prevent silent revenue loss\n- Verify event processing accuracy during system changes or metric updates\n- Debug event matching issues in real-time\n\n### Key response fields:\n- Complete event details including transaction ID, customer ID, and properties\n- Matched Metronome customer (if any)\n- Matched billable metric information (if any)\n- Processing status and duplicate detection flags\n\n### Usage guidelines:\n⚠️ Important: This endpoint is heavily rate limited and designed for sampling workflows only. Do not use this endpoint to check every event in your system. Instead, implement a sampling strategy to randomly validate a subset of events for observability purposes.\n", "operationId": "searchEvents", "summary": "Search events", "tags": [ "Usage" ], "requestBody": { "description": "Search events request", "content": { "application/json": { "schema": { "type": "object", "required": [ "transactionIds" ], "properties": { "transactionIds": { "type": "array", "items": { "type": "string" }, "description": "The transaction IDs of the events to retrieve" } } }, "example": { "transactionIds": [ "2021-01-01T00:00:00Z_cluster42" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "transaction_id", "customer_id", "event_type", "timestamp" ], "properties": { "id": { "type": "string" }, "customer_id": { "type": "string", "description": "The ID of the customer in the ingest event body" }, "event_type": { "type": "string" }, "properties": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "string", "format": "date-time" }, "transaction_id": { "type": "string" }, "is_duplicate": { "type": "boolean" }, "processed_at": { "type": "string", "format": "date-time" }, "matched_customer": { "type": "object", "description": "The customer the event was matched to if a match was found", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "matched_billable_metrics": { "type": "array", "items": { "$ref": "#/components/schemas/BillableMetricForEventsSearch" } } } } }, "example": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "transaction_id": "2021-01-01T00:00:00Z_cluster42", "customer_id": "team@example.com", "event_type": "heartbeat", "timestamp": "2021-01-01T00:00:00Z", "properties": { "cluster_id": "42", "cpu_seconds": 60, "region": "Europe" }, "processed_at": "2021-01-01T00:00:05Z", "is_duplicate": false, "matched_customer": { "id": "98765432-10fe-cba9-8765-432109876543", "name": "Acme Corp" }, "matched_billable_metrics": [ { "id": "8deed800-1b7a-495d-a207-6c52bac54dc9", "name": "CPU Hours" } ] } ] } } } } } }, "/billable-metrics/{billable_metric_id}": { "get": { "description": "Retrieves the complete configuration for a specific billable metric by its ID. Use this to review billable metric setup before associating it with products. Returns the metric's `name`, `event_type_filter`, `property_filters`, `aggregation_type`, `aggregation_key`, `group_keys`, `custom fields`, and `SQL query` (if it's a SQL billable metric). \n\nImportant: \n- Archived billable metrics will include an `archived_at` timestamp; they no longer process new usage events but remain accessible for historical reference.\n", "operationId": "getBillableMetric", "summary": "Get a billable metric", "tags": [ "Billable metrics" ], "parameters": [ { "$ref": "#/components/parameters/BillableMetricId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/BillableMetricV1" } } }, "example": { "data": { "id": "8deed800-1b7a-495d-a207-6c52bac54dc9", "name": "CPU Hours", "event_type_filter": { "in_values": [ "cpu_usage" ] }, "property_filters": [ { "name": "cpu_hours", "exists": true }, { "name": "region", "exists": true, "in_values": [ "EU", "NA" ] }, { "name": "machine_type", "exists": true, "in_values": [ "slow", "fast" ] } ], "aggregation_type": "SUM", "aggregation_key": "cpu_hours", "group_keys": [ [ "region" ], [ "machine_type" ] ] } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "description": "Updates only the display name of an existing billable metric. Use this to correct mistakes or apply standardized naming conventions across all billable metrics. Returns the billable metric ID to confirm the update. \n\nImportant: Only the name can be modified via this endpoint; configurations cannot be changed after creation. \n\n#### Example workflow:\nIf you need to make changes to a streaming billable metric, for example, Metronome supports easily rolling out these changes using a simple workflow:\n1. Duplicate the billable metric\n2. Make required changes\n3. Save the metric\n4. Navigate to the product you have associated with the incorrect metric\n5. Schedule the product to reference the newly created metric on the appropriate date\n", "operationId": "updateBillableMetric", "summary": "Update a billable metric", "tags": [ "Billable metrics" ], "parameters": [ { "$ref": "#/components/parameters/BillableMetricId" } ], "requestBody": { "description": "The billable metric to update", "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The new name of the metric" } } }, "example": { "name": "CPU hours" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Id" } } }, "example": { "data": { "id": "8deed800-1b7a-495d-a207-6c52bac54dc9" } } } } } } } }, "/billable-metrics": { "get": { "description": "Retrieves all billable metrics with their complete configurations. Use this for programmatic discovery and management of billable metrics, such as associating metrics to products and auditing for orphaned or archived metrics. \nImportant: Archived metrics are excluded by default; use `include_archived`=`true` parameter to include them.\n", "operationId": "listAllBillableMetrics", "summary": "List all billable metrics", "tags": [ "Billable metrics" ], "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/NextPage" }, { "name": "include_archived", "in": "query", "description": "If true, the list of returned metrics will include archived metrics", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BillableMetricV1" } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "name": "data transfer (GB)", "id": "9570e4f3-d1da-4b95-ba81-bd40ee002727", "aggregation_type": "SUM", "aggregation_key": "bytes", "event_type_filter": { "in_values": [ "cpu_usage" ] }, "property_filters": [ { "name": "cpu_hours", "exists": true }, { "name": "region", "exists": true, "in_values": [ "EU", "NA" ] }, { "name": "machine_type", "exists": true, "in_values": [ "slow", "fast" ] } ], "group_keys": [ [ "region" ], [ "machine_type" ] ], "custom_fields": { "envionment": "production" } } ], "next_page": null } } } } } } }, "/customers/setBillableStatus": {}, "/customers/archive": { "post": { "description": "Use this endpoint to archive a customer while preserving auditability. Archiving a customer will automatically archive all contracts as of the current date and void all corresponding invoices. Use this endpoint if a customer is onboarded by mistake.\n\n### Usage guidelines:\n- Once a customer is archived, it cannot be unarchived.\n- Archived customers can still be viewed through the API or the UI for audit purposes. \n- Ingest aliases remain idempotent for archived customers. In order to reuse an ingest alias, first remove the ingest alias from the customer prior to archiving.\n- Any notifications associated with the customer will no longer be triggered.\n", "operationId": "archiveCustomer", "summary": "Archive a customer", "tags": [ "Customers" ], "requestBody": { "description": "The ID of the customer to archive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Id" }, "example": { "id": "8deed800-1b7a-495d-a207-6c52bac54dc9" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Id" } } }, "example": { "data": { "id": "8deed800-1b7a-495d-a207-6c52bac54dc9" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customers/{customer_id}": { "get": { "description": "Get detailed information for a specific customer by their Metronome ID. Returns customer profile data including name, creation date, ingest aliases, configuration settings, and custom fields. Use this endpoint to fetch complete customer details for billing operations or account management.\n\nNote: If searching for a customer billing configuration, use the `/getCustomerBillingConfigurations` endpoint.\n", "operationId": "getCustomer", "summary": "Get a customer", "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "tags": [ "Customers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerDetail" } } }, "example": { "data": { "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z", "external_id": "team@example.com", "ingest_aliases": [ "team@example.com" ], "name": "Example, Inc.", "customer_config": { "salesforce_account_id": "0015500001WO1ZiABL" }, "custom_fields": { "x_account_id": "KyVnHhSBWl7eY2bl" } } } } } } } } }, "/customers/{customer_id}/billable-metrics": { "get": { "description": "Get all billable metrics available for a specific customer. Supports pagination and filtering by current plan status or archived metrics. Use this endpoint to see which metrics are being tracked for billing calculations for a given customer.\n", "operationId": "listBillableMetrics", "summary": "Get billable metrics for a customer", "parameters": [ { "$ref": "#/components/parameters/CustomerId" }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/NextPage" }, { "name": "on_current_plan", "in": "query", "description": "If true, the list of metrics will be filtered to just ones that are on the customer's current plan", "required": false, "schema": { "type": "boolean" } }, { "name": "include_archived", "in": "query", "description": "If true, the list of returned metrics will include archived metrics", "required": false, "schema": { "type": "boolean" } } ], "tags": [ "Billable metrics" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BillableMetricWithDeprecatedFields" } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "name": "data transfer (GB)", "id": "9570e4f3-d1da-4b95-ba81-bd40ee002727", "group_by": [ "cluster", "region" ], "aggregate": "sum", "aggregate_keys": [ "bytes" ], "aggregation_type": "SUM", "aggregation_key": "bytes", "event_type_filter": { "in_values": [ "cpu_usage" ] }, "property_filters": [ { "name": "cpu_hours", "exists": true }, { "name": "region", "exists": true, "in_values": [ "EU", "NA" ] }, { "name": "machine_type", "exists": true, "in_values": [ "slow", "fast" ] } ], "group_keys": [ [ "region" ], [ "machine_type" ] ] }, { "name": "CPU hours", "id": "13117714-3f05-48e5-a6e9-a66093f13b4d", "aggregation_type": "SUM", "aggregation_key": "bytes", "event_type_filter": { "in_values": [ "cpu_usage" ] }, "property_filters": [ { "name": "cpu_hours", "exists": true }, { "name": "region", "exists": true, "in_values": [ "EU", "NA" ] }, { "name": "machine_type", "exists": true, "in_values": [ "slow", "fast" ] } ], "group_keys": [ [ "region" ], [ "machine_type" ] ], "archived_at": "2024-10-01T11:23:44Z" } ], "next_page": null } } } } } } }, "/customers": { "get": { "description": "Gets a paginated list of all customers in your Metronome account. Use this endpoint to browse your customer base, implement customer search functionality, or sync customer data with external systems. Returns customer details including IDs, names, and configuration settings. Supports filtering and pagination parameters for efficient data retrieval.\n", "operationId": "listCustomers", "summary": "List customers", "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/NextPage" }, { "in": "query", "name": "ingest_alias", "description": "Filter the customer list by ingest_alias", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "customer_ids", "description": "Filter the customer list by customer_id. Up to 100 ids can be provided.", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "only_archived", "description": "Filter the customer list to only return archived customers. By default, only active customers are returned.", "required": false, "schema": { "type": "boolean" } }, { "in": "query", "name": "salesforce_account_ids", "description": "Filter the customer list by salesforce_account_id. Up to 100 ids can be provided.", "required": false, "schema": { "type": "array", "maxItems": 100, "items": { "type": "string" } } } ], "tags": [ "Customers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerDetail" } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "external_id": "team@example.com", "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z", "ingest_aliases": [ "team@example.com" ], "name": "Example, Inc.", "customer_config": { "salesforce_account_id": "0015500001WO1ZiABL" }, "custom_fields": { "x_account_id": "KyVnHhSBWl7eY2bl" } } ], "next_page": null } } } } } }, "post": { "description": "Create a new customer in Metronome and optionally the billing configuration (recommended) which dictates where invoices for the customer will be sent or where payment will be collected. \n\n### Use this endpoint to:\nExecute your customer provisioning workflows for either PLG motions, where customers originate in your platform, or SLG motions, where customers originate in your sales system.\n\n### Key response fields: \nThis end-point returns the `customer_id` created by the request. This id can be used to fetch relevant billing configurations and create contracts.\n\n### Example workflow:\n- Generally, Metronome recommends first creating the customer in the downstream payment / ERP system when payment method is collected and then creating the customer in Metronome using the response (i.e. `customer_id`) from the downstream system. If you do not create a billing configuration on customer creation, you can add it later. \n- Once a customer is created, you can then create a contract for the customer. In the contract creation process, you will need to add the customer billing configuration to the contract to ensure Metronome invoices the customer correctly. This is because a customer can have multiple configurations.\n- As part of the customer creation process, set the ingest alias for the customer which will ensure usage is accurately mapped to the customer. Ingest aliases can be added or changed after the creation process as well.\n\n### Usage guidelines:\nFor details on different billing configurations for different systems, review the `/setCustomerBillingConfiguration` end-point.\n", "operationId": "createCustomer", "summary": "Create a customer", "tags": [ "Customers" ], "requestBody": { "description": "The customer to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyCreateCustomerPayload" }, "example": { "ingest_aliases": [ "team@example.com" ], "name": "Example, Inc.", "customer_billing_provider_configurations": [ { "billing_provider": "stripe", "delivery_method": "direct_to_billing_provider", "configuration": { "stripe_customer_id": "cus_123", "stripe_collection_method": "charge_automatically" } } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } } }, "example": { "data": { "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "external_id": "team@example.com", "ingest_aliases": [ "team@example.com" ], "name": "Aperture, Inc." } } } } }, "409": { "description": "A customer with this ID already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } }, "/customers/{customer_id}/setIngestAliases": { "post": { "description": "Sets the ingest aliases for a customer. Use this endpoint to associate a Metronome customer with an internal ID for easier tracking between systems. Ingest aliases can be used in the `customer_id` field when sending usage events to Metronome. \n\n### Usage guidelines:\n- This call is idempotent and fully replaces the set of ingest aliases for the given customer.\n- Switching an ingest alias from one customer to another will associate all corresponding usage to the new customer.\n- Use multiple ingest aliases to model child organizations within a single Metronome customer.\n", "operationId": "setIngestAliases", "summary": "Create or update customer ingest aliases", "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "tags": [ "Customers" ], "requestBody": { "description": "The aliases to add", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetIngestAliasesPayload" }, "example": { "ingest_aliases": [ "team@example.com" ] } } } }, "responses": { "200": { "description": "Success" } } } }, "/customers/{customer_id}/setName": { "post": { "description": "Updates the display name for a customer record. Use this to correct customer names, update business names after rebranding, or maintain accurate customer information for invoicing and reporting. Returns the updated customer object with the new name applied immediately across all billing documents and interfaces.\n", "operationId": "setCustomerName", "summary": "Update a customer name", "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "tags": [ "Customers" ], "requestBody": { "description": "The customer name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCustomerNamePayload" }, "example": { "name": "Example, Inc." } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } } }, "example": { "data": { "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "external_id": "team@example.com", "ingest_aliases": [ "team@example.com" ], "name": "Example, Inc." } } } } } } } }, "/customers/{customer_id}/updateConfig": { "post": { "description": "Update configuration settings for a specific customer, such as external system integrations (e.g., Salesforce account ID) and other customer-specific billing parameters. Use this endpoint to modify customer configurations without affecting core customer data like name or ingest aliases.\n", "operationId": "updateCustomerConfig", "summary": "Update a customer configuration", "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "tags": [ "Customers" ], "requestBody": { "description": "The configuration for a specific customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerConfigPayload" }, "example": { "salesforce_account_id": "0015500001WO1ZiABL" } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/credits/listEntries": { "post": { "description": "Fetches a list of credit ledger entries. Returns lists of ledgers per customer. Ledger entries are returned in chronological order. Ledger entries associated with voided credit grants are not included. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "listCreditLedgerEntries", "summary": "List credit ledger entries", "parameters": [ { "$ref": "#/components/parameters/NextPage" }, { "in": "query", "name": "sort", "description": "Ledgers sort order by date, asc or desc. Defaults to asc.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } } ], "tags": [ "Credit grants" ], "requestBody": { "description": "Optional filters on the ledger entries to return", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditLedgerEntriesQueryPayload" }, "example": { "starting_on": "2021-01-01T00:00:00Z", "ending_before": "2021-02-01T00:00:00Z", "customer_ids": [ "6a37bb88-8538-48c5-b37b-a41c836328bd" ], "credit_type_ids": [ "2714e483-4ff1-48e4-9e25-ac732e8f24f2" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerCreditTypeLedger" } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "customer_id": "6a37bb88-8538-48c5-b37b-a41c836328bd", "ledgers": [ { "credit_type": { "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "name": "USD (cents)" }, "starting_balance": { "including_pending": 400, "excluding_pending": 400, "effective_at": "2021-01-01T00:00:00Z" }, "ending_balance": { "including_pending": 110, "excluding_pending": 400, "effective_at": "2021-02-01T00:00:00Z" }, "entries": [], "pending_entries": [ { "amount": 290, "reason": "Automated invoice deduction", "running_balance": 110, "effective_at": "2021-02-01T00:00:00Z", "created_by": "Metronome System", "credit_grant_id": "f06b3d1b-c724-4e0b-99d1-20c0526bf21b", "invoice_id": "92fb6de8-eb2f-47e5-ae1b-b1e0fb1f388d" } ] } ] } ], "next_page": null } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customers/{customer_id}/purchasedSeats": {}, "/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.\n", "operationId": "chargeSeats", "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" } } } }, "/customers/{customer_id}/addCharge": { "post": { "description": "Add a one time charge to the specified invoice. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "addOneTimeCharge", "summary": "Add a one time charge", "parameters": [ { "$ref": "#/components/parameters/CustomerId" } ], "requestBody": { "description": "One time charge creation request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOneTimeChargePayload" }, "example": { "charge_id": "5ae4b726-1ebe-439c-9190-9831760ba195", "price": 250, "quantity": 1, "description": "One time charge", "invoice_start_timestamp": "2024-01-01T00:00:00Z", "customer_plan_id": "a23b3cf4-47fb-4c3f-bb3d-9e64f7704015" } } } }, "tags": [ "Invoices" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "x-stainless-empty-object": true } } } } } } }, "/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", "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" } }, { "in": "query", "name": "webhook_notification_id", "x-mint": { "groups": [ "ff:api-allow-webhook-notification-id" ] }, "x-stainless-skip": true, "description": "Indicates that this API request was triggered by a webhook notification with the provided ID.", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "include_retired_commit_invoices", "description": "When true, includes retired commit invoices alongside active invoices. Defaults to false.", "required": false, "schema": { "type": "boolean", "default": false } } ], "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": { "plans": { "value": { "data": [ { "id": "6a37bb88-8538-48c5-b37b-a41c836328bd", "customer_id": "617e39d8-68f4-4592-b8d2-c2bf26a76989", "type": "PLAN_ARREARS", "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", "tier_period": { "starting_at": "2021-01-01T00:00:00Z", "ending_before": "2021-02-01T00:00:00Z" }, "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 } ], "next_page": null } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customers/{customer_id}/invoices/breakdowns": {}, "/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.\n\n### Use this endpoint to:\n- Provide customers with downloadable or emailable copies of their invoices\n- Support accounting and finance teams with official billing documents\n- Maintain accurate records of billing transactions for audits and compliance\n\n### Key response details:\n- The response is a binary PDF file representing the full invoice\n- The PDF includes all standard invoice information such as line items, totals, billing period, and customer details\n- The document is formatted for clarity and professionalism, suitable for official use\n\n### Usage guidelines:\n- Ensure the `invoice_id` corresponds to an existing invoice for the specified `customer_id`\n- The PDF is generated on-demand; frequent requests for the same invoice may impact performance\n- Use appropriate headers to handle the binary response in your application (e.g., setting `Content-Type: application/pdf`)\n", "operationId": "getInvoicePdf", "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" } } } }, "/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", "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": { "plans": { "value": { "data": { "id": "6a37bb88-8538-48c5-b37b-a41c836328bd", "customer_id": "617e39d8-68f4-4592-b8d2-c2bf26a76989", "type": "PLAN_ARREARS", "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)" }, "sub_line_items": [ { "name": "CPU hours", "quantity": 1488, "subtotal": 14392, "charge_id": "3f1541ac-00df-40ee-a1a3-ec3373933669", "tier_period": { "starting_at": "2021-01-01T00:00:00Z", "ending_before": "2021-02-01T00:00:00Z" }, "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, "type": "usage", "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" } } } }, "/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", "summary": "List spend invoice breakdowns", "x-nlb-domain-variable": "breakdownsnlbDomain", "x-vpc-connection-id-variable": "breakdownsvpcLinkId", "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" } } } }, "/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.\n", "operationId": "voidInvoice", "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" } } } } } } } }, "/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.\n", "operationId": "previewCustomerEvents", "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" } } } } } }, "/customers/{customer_id}/costs": { "get": { "description": "Fetch daily pending costs for the specified customer, broken down by credit type and line items. Note: this is not supported for customers whose plan includes a UNIQUE-type billable metric. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "getCosts", "summary": "Get customer costs", "parameters": [ { "$ref": "#/components/parameters/CustomerId" }, { "$ref": "#/components/parameters/RequiredStartDate" }, { "$ref": "#/components/parameters/RequiredEndDate" }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/NextPage" } ], "tags": [ "Invoices" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Costs" } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "start_timestamp": "2024-01-01T00:00:00Z", "end_timestamp": "2024-01-02T00:00:00Z", "credit_types": { "2714e483-4ff1-48e4-9e25-ac732e8f24f2": { "name": "USD (cents)", "cost": 123.45, "line_item_breakdown": [ { "name": "CPU hours", "cost": 123.45 } ] } } } ], "next_page": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customers/{customer_id}/billing-config/{billing_provider_type}": { "get": { "description": "Fetch the billing configuration for the given customer. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "getBillingConfig", "summary": "Get a customer billing configuration", "parameters": [ { "$ref": "#/components/parameters/CustomerId" }, { "$ref": "#/components/parameters/BillingProviderType" } ], "tags": [ "Customers" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "billing_provider_customer_id": { "type": "string" }, "stripe_collection_method": { "$ref": "#/components/schemas/StripeCollectionMethod" }, "aws_product_code": { "type": "string" }, "aws_region": { "$ref": "#/components/schemas/AwsRegion" }, "aws_expiration_date": { "$ref": "#/components/schemas/AwsExpirationDate" }, "aws_is_subscription_product": { "type": "boolean", "description": "True if the aws_product_code is a SAAS subscription product, false otherwise." }, "azure_subscription_status": { "$ref": "#/components/schemas/AzureSubscriptionStatus" }, "azure_plan_id": { "type": "string", "format": "uuid" }, "azure_start_date": { "$ref": "#/components/schemas/AzureTermDate" }, "azure_expiration_date": { "$ref": "#/components/schemas/AzureTermDate" } } } } }, "example": { "data": { "billing_provider_customer_id": "cus_AJ6y20bjkOOayM", "stripe_collection_method": "charge_automatically" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "description": "Set the billing configuration for a given customer. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "setBillingConfigForCustomer", "summary": "Set a customer billing configuration", "parameters": [ { "$ref": "#/components/parameters/CustomerId" }, { "$ref": "#/components/parameters/BillingProviderType" } ], "requestBody": { "description": "The billing configuration for the customer", "content": { "application/json": { "schema": { "type": "object", "required": [ "billing_provider_customer_id" ], "properties": { "billing_provider_customer_id": { "type": "string", "description": "The customer ID in the billing provider's system. For Azure, this is the subscription ID." }, "stripe_collection_method": { "$ref": "#/components/schemas/StripeCollectionMethod" }, "aws_product_code": { "type": "string" }, "aws_region": { "$ref": "#/components/schemas/AwsRegion" } } }, "example": { "billing_provider_customer_id": "cus_AJ6y20bjkOOayM", "stripe_collection_method": "charge_automatically" } } } }, "tags": [ "Customers" ], "responses": { "200": { "description": "Success" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "description": "Delete the billing configuration for a given customer.\nNote: this is unsupported for Azure and AWS Marketplace customers. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.\n", "operationId": "deleteBillingConfigForCustomer", "summary": "Delete a customer billing configuration", "parameters": [ { "$ref": "#/components/parameters/CustomerId" }, { "$ref": "#/components/parameters/BillingProviderType" } ], "tags": [ "Customers" ], "responses": { "200": { "description": "Success" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/rotateDeltaStreamSecret": {}, "/listConfiguredBillingProviders": { "post": { "description": "Lists all configured billing providers and their delivery method configurations for your account. Returns provider details, delivery method IDs, and configuration settings needed for mapping individual customer contracts to billing integrations.\n", "operationId": "listConfiguredBillingProviders", "summary": "List account-level billing providers", "tags": [ "Settings" ], "requestBody": { "description": "Optional cursor to the next page of results", "content": { "application/json": { "schema": { "type": "object", "properties": { "next_page": { "type": "string", "format": "uuid", "nullable": true, "description": "The cursor to the next page of results" } } }, "example": { "next_page": "af26878a-de62-4a0d-9b77-3936f7c2b6d6" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BillingProviderDeliveryMethod" } }, "next_page": { "type": "string", "format": "uuid", "nullable": true } } }, "example": { "data": [ { "billing_provider": "stripe", "delivery_method_id": "4422e46f-b374-4159-97e3-300208cdb2e2", "delivery_method": "direct_to_billing_provider", "delivery_method_configuration": { "stripe_account_id": "acct_1P6FywIkTQSg6Mm3", "leave_invoices_in_draft": false, "skip_zero_dollar_invoices": false, "export_invoice_sub_line_items": false, "include_zero_quantity_sub_line_items": true, "stripe_invoice_quantity_always_string": false, "set_effective_at_date_to_inclusive_period_end": false } }, { "billing_provider": "aws_marketplace", "delivery_method_id": "5b9e3072-415b-4842-94f0-0b6700c8b6be", "delivery_method": "direct_to_billing_provider", "delivery_method_configuration": { "aws_external_id": "47b4f6b7-e297-42e8-b175-331d933b402c", "aws_iam_role_arn": "arn:aws:iam::123456789012:role/MetronomeRole", "aws_region": "us-east-1" } } ], "next_page": null } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/dashboards/getEmbeddableUrl": { "post": { "description": "Generate secure, embeddable dashboard URLs that allow you to seamlessly integrate Metronome's billing visualizations directly into your application. This endpoint creates authenticated iframe-ready URLs for customer-specific dashboards, providing a white-labeled billing experience without building custom UI.\n\n### Use this endpoint to:\n- Embed billing dashboards directly in your customer portal or admin interface\n- Provide self-service access to invoices, usage data, and credit balances\n- Build white-labeled billing experiences with minimal development effort\n\n### Key response fields:\n- A secure, time-limited URL that can be embedded in an iframe\n- The URL includes authentication tokens and configuration parameters\n- URLs are customer-specific and respect your security settings\n\n### Usage guidelines:\n- Dashboard types: Choose from `invoices`, `usage`, or `commits_and_credits`\n- Customization options:\n - `dashboard_options`: Configure dashboard behavior. Supported for the invoices dashboard only. Available keys include: `show_zero_usage_line_items` (\"true\"/\"false\"), `contract_id` (UUID, filters invoices by contract), `invoice_type` (\"USAGE\" or \"SCHEDULED\", filters by invoice type), and `invoice_status_filter` (\"VOID\", \"FINALIZED\", \"DRAFT\", \"FINALIZED_AND_DRAFT\", or \"ALL\")\n - `color_overrides`: Match your brand's color palette\n- Iframe implementation: Embed the returned URL directly in an iframe element\n- Responsive design: Dashboards automatically adapt to container dimensions\n", "operationId": "embeddableDashboard", "summary": "Get an embeddable customer dashboard", "tags": [ "Customers" ], "requestBody": { "description": "The details of the dashboard to retrieve", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddableDashboardPayload" }, "example": { "customer_id": "4db51251-61de-4bfe-b9ce-495e244f3491", "dashboard": "invoices", "dashboard_options": [ { "key": "show_zero_usage_line_items", "value": "false" }, { "key": "invoice_status_filter", "value": "FINALIZED" } ], "color_overrides": [ { "name": "Gray_dark", "value": "#ff0000" } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "url": { "type": "string" } } } } }, "example": { "data": { "url": "https://embeddable-dashboards.metronome.com/customers/invoices/v1?..." } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auditLogs": { "get": { "description": "Get a comprehensive audit trail of all operations performed in your Metronome account, whether initiated through the API, web interface, or automated processes. This endpoint provides detailed logs of who did what and when, enabling compliance reporting, security monitoring, and operational troubleshooting across all interaction channels.\n\n### Use this endpoint to:\n- Monitor all account activity for security and compliance purposes\n- Track configuration changes regardless of source (API, UI, or system)\n- Investigate issues by reviewing historical operations\n\n### Key response fields: \nAn array of AuditLog objects containing:\n- id: Unique identifier for the audit log entry\n- timestamp: When the action occurred (RFC 3339 format)\n- actor: Information about who performed the action\n- request: Details including request ID, IP address, and user agent\n- `resource_type`: The type of resource affected (e.g., customer, contract, invoice)\n- `resource_id`: The specific resource identifier\n- `action`: The operation performed\n- `next_page`: Cursor for continuous log retrieval\n\n### Usage guidelines:\n- Continuous retrieval: The next_page token enables uninterrupted log streaming—save it between requests to ensure no logs are missed\n- Empty responses: An empty data array means no new logs yet; continue polling with the same next_page token\n- Date filtering:\n - `starting_on`: Earliest logs to return (inclusive)\n - `ending_before`: Latest logs to return (exclusive)\n - Cannot be used with `next_page`\n- Resource filtering: Must specify both `resource_type` and `resource_id` together\n- Sort order: Default is `date_asc`; use `date_desc` for newest first\n", "operationId": "getAuditLogs", "summary": "Get audit logs", "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/NextPage" }, { "name": "starting_on", "in": "query", "description": "RFC 3339 timestamp of the earliest audit log to return. Cannot be used with 'next_page'.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "ending_before", "in": "query", "description": "RFC 3339 timestamp (exclusive). Cannot be used with 'next_page'.", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "sort", "in": "query", "description": "Sort order by timestamp, e.g. date_asc or date_desc. Defaults to date_asc.", "required": false, "schema": { "type": "string", "enum": [ "date_asc", "date_desc" ] } }, { "name": "resource_id", "in": "query", "description": "Optional parameter that can be used to filter which audit logs are returned. If you specify resource_id, you must also specify resource_type.", "required": false, "schema": { "type": "string" } }, { "name": "resource_type", "in": "query", "description": "Optional parameter that can be used to filter which audit logs are returned. If you specify resource_type, you must also specify resource_id.", "required": false, "schema": { "type": "string" } } ], "tags": [ "Security" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" } }, "next_page": { "type": "string", "description": "The next_page parameter is always returned to support ongoing log retrieval. It enables continuous querying, even when some requests return no new data. Save the next_page token from each response and use it for future requests to ensure no logs are missed. This setup is ideal for regular updates via automated processes, like cron jobs, to fetch logs continuously as they become available. When you receive an empty data array, it indicates a temporary absence of new logs, but subsequent requests might return new data.", "nullable": true } } } } } } } } }, "/services": { "get": { "description": "Gets Metronome's service registry with associated IP addresses for security allowlisting and firewall configuration. Use this endpoint to maintain an up-to-date list of IPs that your systems should trust for Metronome communications. Returns service names and their current IP ranges, with new IPs typically appearing 30+ days before first use to ensure smooth allowlist updates.\n", "operationId": "getServices", "summary": "Get services", "tags": [ "Security" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "services" ], "properties": { "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } } } } } } } }, "/customFields/addKey": { "post": { "description": "Creates a new custom field key for a given entity (e.g. billable metric, contract, alert).\n\nCustom fields are properties that you can add to Metronome objects to store metadata like foreign keys or other descriptors. This metadata can get transferred to or accessed by other systems to contextualize Metronome data and power business processes. For example, to service workflows like revenue recognition, reconciliation, and invoicing, custom fields help Metronome know the relationship between entities in the platform and third-party systems.\n\n### Use this endpoint to:\n- Create a new custom field key for Customer objects in Metronome. You can then use the Set Custom Field Values endpoint to set the value of this key for a specific customer. \n- Specify whether the key should enforce uniqueness. If the key is set to enforce uniqueness and you attempt to set a custom field value for the key that already exists, it will fail. \n\n### Usage guidelines:\n- Custom fields set on commits, credits, and contracts can be used to scope alert evaluation. For example, you can create a spend threshold alert that only considers spend associated with contracts with custom field key `contract_type` and value `paygo`\n- Custom fields set on products can be used in the Stripe integration to set metadata on invoices.\n- Custom fields for customers, contracts, invoices, products, commits, scheduled charges, and subscriptions are passed down to the invoice.\n", "operationId": "addCustomFieldKey", "summary": "Create a custom field key", "tags": [ "Custom fields" ], "requestBody": { "description": "Add a key to the allow list for an entity", "content": { "application/json": { "schema": { "type": "object", "required": [ "entity", "key", "enforce_uniqueness" ], "properties": { "entity": { "$ref": "#/components/schemas/ManagedEntity" }, "key": { "type": "string" }, "enforce_uniqueness": { "type": "boolean" } } }, "example": { "entity": "customer", "key": "x_account_id", "enforce_uniqueness": true } } } }, "responses": { "200": { "description": "Success" } } } }, "/customFields/removeKey": { "post": { "description": "Removes a custom field key from the allowlist for a specific entity type, preventing future use of that key across all instances of the entity. Existing values for this key on entity instances will no longer be accessible once the key is removed.\n", "operationId": "disableCustomFieldKey", "summary": "Delete a custom field key", "tags": [ "Custom fields" ], "requestBody": { "description": "Remove a key from the allow list for an entity", "content": { "application/json": { "schema": { "type": "object", "required": [ "entity", "key" ], "properties": { "entity": { "$ref": "#/components/schemas/ManagedEntity" }, "key": { "type": "string" } } }, "example": { "entity": "customer", "key": "x_account_id" } } } }, "responses": { "200": { "description": "Success" } } } }, "/customFields/setValues": { "post": { "description": "Sets custom field values on a specific Metronome entity instance. Overwrites existing values for matching keys while preserving other fields. All updates are transactional—either all values are set or none are. Custom field values are limited to 200 characters each.\n\nAdding or updating custom fields on credits, commits, or contracts does not emit `credit.edit`, `commit.edit`, or `contract.edit` events.\n", "operationId": "setCustomFields", "summary": "Set custom field values", "tags": [ "Custom fields" ], "requestBody": { "description": "The custom field values to set", "content": { "application/json": { "schema": { "type": "object", "required": [ "entity", "entity_id", "custom_fields" ], "properties": { "entity": { "$ref": "#/components/schemas/ManagedEntity" }, "entity_id": { "type": "string", "format": "uuid" }, "custom_fields": { "$ref": "#/components/schemas/CustomField" } } }, "example": { "entity": "customer", "entity_id": "99594816-e8a5-4bca-be21-8d1de0f45120", "custom_fields": { "x_account_id": "KyVnHhSBWl7eY2bl" } } } } }, "responses": { "200": { "description": "Success" } } } }, "/customFields/deleteValues": { "post": { "description": "Remove specific custom field values from a Metronome entity instance by specifying the field keys to delete. Use this endpoint to clean up unwanted custom field data while preserving other fields on the same entity. Requires the entity type, entity ID, and array of keys to remove.\n", "operationId": "deleteCustomFields", "summary": "Delete custom fields", "tags": [ "Custom fields" ], "requestBody": { "description": "Delete one or more custom fields", "content": { "application/json": { "schema": { "type": "object", "required": [ "entity", "entity_id", "keys" ], "properties": { "entity": { "$ref": "#/components/schemas/ManagedEntity" }, "entity_id": { "type": "string", "format": "uuid" }, "keys": { "type": "array", "items": { "type": "string" } } } }, "example": { "entity": "customer", "entity_id": "99594816-e8a5-4bca-be21-8d1de0f45120", "keys": [ "x_account_id" ] } } } }, "responses": { "200": { "description": "Success" } } } }, "/customFields/listKeys": { "post": { "description": "Retrieve all your active custom field keys, with optional filtering by entity type (customer, contract, product, etc.). Use this endpoint to discover what custom field keys are available before setting values on entities or to audit your custom field configuration across different entity types.\n", "operationId": "listCustomFieldKeys", "summary": "List custom field keys", "parameters": [ { "$ref": "#/components/parameters/NextPage" } ], "tags": [ "Custom fields" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "entities": { "type": "array", "description": "Optional list of entity types to return keys for", "items": { "$ref": "#/components/schemas/ManagedEntity" } } } }, "example": { "entities": [ "customer" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "entity", "key", "enforce_uniqueness" ], "properties": { "entity": { "$ref": "#/components/schemas/ManagedEntity" }, "key": { "type": "string" }, "enforce_uniqueness": { "type": "boolean" } } } }, "next_page": { "type": "string", "nullable": true } } }, "example": { "data": [ { "entity": "customer", "key": "x_account_id", "enforce_uniqueness": true } ], "next_page": null } } } } } } }, "/contracts/archive": {}, "/composite/createCustomerWithContract": { "post": { "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" ] }, "description": "Create a new customer and provision a contract. This endpoint's availability is dependent on your client's configuration.", "operationId": "createCustomerWithContract", "summary": "Create a customer and provision a contract.", "tags": [ "Contracts" ], "requestBody": { "description": "The customer and contract details to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerWithContractPayload" }, "example": { "customer": { "name": "Example, Inc.", "ingest_aliases": [ "team@example.com" ] }, "contract": { "starting_at": "2020-01-01T00:00:00.000Z" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerAndContract" } } }, "example": { "data": { "customer_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "ingest_aliases": [ "team@example.com" ], "customer_name": "Aperture, Inc.", "contract_id": "7aa11640-0703-4600-8eb9-293f535a6b74" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/threshold-billing/update-active-recharge-config": {}, "/webhooks/{webhook_id}/triggered_notifications": {}, "/webhooks/{webhook_id}/triggered_notifications/{triggered_notification_id}": {} }, "components": { "parameters": { "BillingProviderType": { "name": "billing_provider_type", "in": "path", "description": "The billing provider (e.g. stripe)", "required": true, "schema": { "$ref": "#/components/schemas/BillingProviderType" }, "example": "stripe" }, "BillingProviderSettingsType": { "name": "billing_provider_type", "in": "path", "description": "The billing provider (currently only Stripe is supported).", "required": true, "schema": { "$ref": "#/components/schemas/BillingProviderSettingsType" }, "example": "stripe" }, "BillableMetricId": { "name": "billable_metric_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "13117714-3f05-48e5-a6e9-a66093f13b4d" }, "PlanId": { "name": "plan_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc" }, "CustomerPlanId": { "name": "customer_plan_id", "in": "path", "description": "the ID of a customer-plan relationship", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "7aa11640-0703-4600-8eb9-293f535a6b74" }, "CustomerId": { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc" }, "CreditTypeId": { "name": "credit_type_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "2714e483-4ff1-48e4-9e25-ac732e8f24f2" }, "InvoiceId": { "name": "invoice_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "6a37bb88-8538-48c5-b37b-a41c836328bd" }, "NextPage": { "name": "next_page", "in": "query", "description": "Cursor that indicates where the next page of results should start.", "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 } }, "RequiredStartDate": { "name": "starting_on", "in": "query", "description": "RFC 3339 timestamp (inclusive)", "required": true, "schema": { "type": "string", "format": "date-time" }, "example": "2024-01-01T00:00:00Z" }, "RequiredEndDate": { "name": "ending_before", "in": "query", "description": "RFC 3339 timestamp (exclusive)", "required": true, "schema": { "type": "string", "format": "date-time" }, "example": "2024-02-01T00:00:00Z" }, "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" ] } }, "InvoiceStatus": { "name": "status", "in": "query", "description": "Invoice status, e.g. DRAFT, FINALIZED, or VOID", "required": false, "schema": { "type": "string" } }, "InvoiceStatusNonVoid": { "name": "status", "in": "query", "description": "Invoice status, e.g. DRAFT or FINALIZED", "required": false, "schema": { "type": "string" } }, "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" } }, "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" } }, "ProductId": { "name": "product_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc" }, "ContractId": { "name": "contract_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc" }, "PrivateBetaName": { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, "RechargeSettingsId": { "name": "recharge_settings_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc" }, "CustomerPlanStatus": { "name": "status", "in": "query", "description": "Status of customers on a given plan. Defaults to `active`.\n\n* `all` - Return current, past, and upcoming customers of the plan.\n* `active` - Return current customers of the plan.\n* `ended` - Return past customers of the plan.\n* `upcoming` - Return upcoming customers of the plan.\n\nMultiple statuses can be OR'd together using commas, e.g. `active,ended`.\n**Note:** `ended,upcoming` combination is not yet supported.", "required": false, "schema": { "type": "string", "enum": [ "all", "active", "ended", "upcoming" ] }, "explode": false } }, "responses": { "NotFound": { "description": "The specified resource was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "WebhookDelivery": { "type": "object", "required": [ "id", "webhook_id", "customer_id", "notification_id", "notification_type", "first_attempted_at", "last_attempted_at", "last_response_status_code", "num_attempts" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the triggered notification." }, "webhook_id": { "type": "string", "format": "uuid", "description": "ID of the webhook destination." }, "customer_id": { "type": "string", "format": "uuid", "nullable": true }, "notification_id": { "type": "string", "nullable": true, "description": "ID of the notification configuration, when applicable." }, "notification_type": { "type": "string" }, "first_attempted_at": { "type": "string", "format": "date-time" }, "last_attempted_at": { "type": "string", "format": "date-time" }, "last_response_status_code": { "type": "number", "multipleOf": 1 }, "num_attempts": { "type": "number", "multipleOf": 1 } } }, "WebhookDeliveryAttempt": { "type": "object", "required": [ "attempted_at", "response_status_code" ], "properties": { "attempted_at": { "type": "string", "format": "date-time" }, "response_status_code": { "type": "number", "multipleOf": 1 } } }, "WebhookDeliveryDetail": { "type": "object", "required": [ "id", "webhook_id", "customer_id", "notification_id", "notification_type", "notification_payload", "attempts" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the triggered notification." }, "webhook_id": { "type": "string", "format": "uuid", "description": "ID of the webhook destination." }, "customer_id": { "type": "string", "format": "uuid", "nullable": true }, "notification_id": { "type": "string", "nullable": true, "description": "ID of the notification configuration, when applicable." }, "notification_type": { "type": "string" }, "notification_payload": { "type": "string", "description": "The exact payload sent to the webhook destination." }, "attempts": { "type": "array", "description": "Delivery attempts ordered from oldest to newest.", "items": { "$ref": "#/components/schemas/WebhookDeliveryAttempt" } } } }, "WebhookDeliveryFilters": { "type": "object", "properties": { "customer_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "notification_types": { "type": "array", "items": { "type": "string" } }, "notification_ids": { "type": "array", "description": "IDs of notification configurations.", "items": { "type": "string" } } } }, "ListWebhookDeliveriesRequest": { "type": "object", "required": [ "start_date" ], "properties": { "start_date": { "type": "string", "format": "date-time", "description": "Inclusive start timestamp. Must be within the last 30 days." }, "end_date": { "type": "string", "format": "date-time", "description": "Exclusive end timestamp. Defaults to the current time. The requested range cannot exceed 30 days." }, "filters": { "$ref": "#/components/schemas/WebhookDeliveryFilters" }, "limit": { "type": "number", "multipleOf": 1, "minimum": 1, "maximum": 100, "default": 25, "description": "Number of deliveries to return per page." }, "next_page": { "type": "string", "description": "Cursor for the next page of results." } } }, "ListWebhookDeliveriesResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "next_page": { "type": "string", "description": "Cursor for the next page of results, when one exists." } } }, "GetWebhookDeliveryResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WebhookDeliveryDetail" } } }, "ApprovalRequest": { "type": "object", "required": [ "id", "status", "token_name", "created_at", "expires_at", "approval_url", "reviewed_by", "reviewed_at", "completed_at", "approval_request_payload", "response" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending_approval", "approved", "denied", "execution_succeeded", "execution_error", "expired" ] }, "token_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "approval_url": { "type": "string" }, "reviewed_by": { "type": "string", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "approval_request_payload": { "type": "object", "required": [ "name", "description", "method", "path", "body" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "body": { "type": "object", "additionalProperties": true } } }, "response": { "type": "object", "required": [ "response_status", "response_body" ], "properties": { "response_status": { "type": "number", "nullable": true }, "response_body": { "type": "object", "additionalProperties": true, "nullable": true } } } } }, "SetClientWebhookSecretPayload": { "required": [ "webhook_secret" ], "type": "object", "properties": { "webhook_secret": { "type": "string", "description": "The client webhook secret used to verify webhook results" } } }, "SetBillingProviderApiKeyPayload": { "required": [ "api_key" ], "type": "object", "properties": { "api_key": { "type": "string", "description": "API key to set for the billing provider." } } }, "CreateStripeBillingSettingsPayload": { "type": "object", "properties": { "stripe_api_key": { "type": "string", "description": "API key used to call the Stripe APIs" }, "anrok_api_key": { "type": "string", "description": "API key used to call the Anrok APIs", "nullable": true } }, "required": [ "stripe_api_key" ] }, "UpdateStripeBillingSettingsPayload": { "type": "object", "properties": { "stripe_api_key": { "type": "string", "description": "API key used to call the Stripe APIs" }, "anrok_api_key": { "type": "string", "description": "API key used to call the Anrok APIs", "nullable": true } } }, "ExperimentalEmbeddableDashboardPayload": { "required": [ "customer_id", "dashboard" ], "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "dashboard": { "type": "string", "description": "The type of experimental dashboard to retrieve." }, "dashboardHostUrl": { "type": "string", "description": "Host override url to the embeddable dashboards host." }, "dashboard_options": { "type": "array", "description": "Optional dashboard specific options", "items": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "description": "The option key name" }, "value": { "type": "string", "description": "The option value" } } } }, "color_overrides": { "type": "array", "description": "Optional list of colors to override", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The color to override", "enum": [ "Gray_dark", "Gray_medium", "Gray_light", "Gray_extralight", "White", "Primary_medium", "Primary_light", "UsageLine_0", "UsageLine_1", "UsageLine_2", "UsageLine_3", "UsageLine_4", "UsageLine_5", "UsageLine_6", "UsageLine_7", "UsageLine_8", "UsageLine_9", "Primary_green", "Primary_red", "Progress_bar", "Progress_bar_background", "Action", "Action_hover" ] }, "value": { "type": "string", "description": "Hex value representation of the color" } } } } } }, "EmbeddableDashboardPayload": { "required": [ "customer_id", "dashboard" ], "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "dashboard": { "type": "string", "enum": [ "invoices", "usage", "credits" ], "description": "The type of dashboard to retrieve." }, "dashboard_options": { "type": "array", "description": "Optional dashboard specific options", "items": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "description": "The option key name", "enum": [ "show_zero_usage_line_items", "contract_id", "invoice_type", "invoice_status_filter", "hide_voided_invoices", "billable_status_filter", "hide_grant_name", "credit_ledger_credit_type_id" ], "x-mint-enum": { "billable_status_filter": [ "client_id:11db091c-975b-4908-9f67-b1ceb126acdf" ] } }, "value": { "type": "string", "description": "The option value. For show_zero_usage_line_items: \"true\" or \"false\" (default \"false\"). For contract_id: a UUID filtering invoices to a specific contract. For invoice_type: \"USAGE\" or \"SCHEDULED\". For invoice_status_filter: \"VOID\", \"FINALIZED\", \"DRAFT\", \"FINALIZED_AND_DRAFT\", or \"ALL\". For hide_voided_invoices (deprecated): \"true\" or \"false\". For hide_grant_name (credits dashboard): \"true\" or \"false\". For credit_ledger_credit_type_id (credits dashboard): a UUID filtering to a specific credit type." } } } }, "color_overrides": { "type": "array", "description": "Optional list of colors to override", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The color to override", "enum": [ "Gray_dark", "Gray_medium", "Gray_light", "Gray_extralight", "White", "Primary_medium", "Primary_light", "UsageLine_0", "UsageLine_1", "UsageLine_2", "UsageLine_3", "UsageLine_4", "UsageLine_5", "UsageLine_6", "UsageLine_7", "UsageLine_8", "UsageLine_9", "Primary_green", "Primary_red", "Progress_bar", "Progress_bar_background", "Action", "Action_hover" ] }, "value": { "type": "string", "description": "Hex value representation of the color" } } } }, "bm_group_key_overrides": { "type": "array", "description": "Optional list of billable metric group key overrides", "items": { "type": "object", "required": [ "group_key_name" ], "properties": { "group_key_name": { "type": "string", "description": "The name of the billable metric group key." }, "display_name": { "type": "string", "description": "The display name for the billable metric group key" }, "value_display_names": { "type": "object", "additionalProperties": true, "description": " pairs of the billable metric group key values and their display names. e.g. {\"a\": \"Asia\", \"b\": \"Euro\"}" } } } } } }, "CreateCustomerAlertPayload": { "required": [ "alert_type", "name", "threshold" ], "type": "object", "properties": { "alert_type": { "type": "string", "enum": [ "low_credit_balance_reached", "spend_threshold_reached", "monthly_invoice_total_spend_threshold_reached", "low_remaining_days_in_plan_reached", "low_remaining_credit_percentage_reached", "usage_threshold_reached", "invoice_total_reached" ], "description": "Type of the threshold notification" }, "name": { "type": "string", "description": "Name of the threshold notification" }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKey" }, "threshold": { "type": "number", "description": "Threshold value of the notification policy. Depending upon the notification type, this number may represent a financial amount, the days remaining, or a percentage reached." }, "credit_type_id": { "type": "string", "format": "uuid", "description": "ID of the credit's currency, defaults to USD. If the specific notification type requires a pricing unit/currency, find the ID in the [Metronome app](https://app.metronome.com/offering/pricing-units)." }, "customer_id": { "type": "string", "format": "uuid", "description": "If provided, will create this threshold notification for this specific customer. To create a notification for all customers, do not specify a `customer_id`." }, "plan_id": { "type": "string", "format": "uuid", "description": "If provided, will create this threshold notification for this specific plan. To create a notification for all customers, do not specify a `plan_id`." }, "billable_metric_id": { "type": "string", "format": "uuid", "description": "For threshold notifications of type `usage_threshold_reached`, specifies which billable metric to track the usage for." }, "credit_grant_type_filters": { "type": "array", "items": { "type": "string" }, "description": "An array of strings, representing a way to filter the credit grant this threshold notification applies to, by looking at the credit_grant_type field on the credit grant. This field is only defined for CreditPercentage and CreditBalance notifications" }, "evaluate_on_create": { "type": "boolean", "description": "If true, the threshold notification will evaluate immediately on customers that already meet the notification threshold. If false, it will only evaluate on future customers that trigger the threshold. Defaults to true." }, "custom_field_filters": { "type": "array", "description": "A list of custom field filters for threshold notification types that support advanced filtering. Only present for contract invoices.", "items": { "$ref": "#/components/schemas/CustomFieldFilterType" } }, "group_key_filter": { "x-stainless-skip": true, "x-mint": { "groups": [ "client_id:462b838b-1582-4100-816e-f6c07bb604fe", "client_id:c187f54f-e807-4cf6-8fa1-a01f09d05412", "client_id:aa2899ec-16ad-413b-b20b-ec9ba4692d4e", "client_id:2f0c6751-0b61-46f2-8664-2eb1be6136cf", "client_id:b2c5d30a-6078-4cd4-9e98-340ca0883789", "client_id:67c6fe5e-5715-4b05-aa2a-b3885cd68b81", "client_id:f9b1ebc0-19f5-43cd-ba0b-7cf7da34fe7c", "client_id:98ac66cc-88b4-447f-a2e6-a84ebc81e36a" ] }, "$ref": "#/components/schemas/GroupKeyFilterType" }, "invoice_types_filter": { "$ref": "#/components/schemas/InvoiceTypesFilterType" } } }, "GetCustomerAlertPayload": { "required": [ "customer_id", "alert_id" ], "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "The Metronome ID of the customer" }, "alert_id": { "type": "string", "format": "uuid", "description": "The Metronome ID of the threshold notification" }, "plans_or_contracts": { "x-mint": { "groups": [ "ff:plans-contracts-parallel-alerts" ] }, "type": "string", "enum": [ "PLANS", "CONTRACTS" ], "description": "When parallel threshold notifications are enabled during migration, this flag denotes whether to fetch notifications for plans or contracts." }, "webhook_notification_id": { "x-mint": { "groups": [ "ff:api-allow-webhook-notification-id" ] }, "x-stainless-skip": true, "type": "string", "description": "Indicates that this API request was triggered by a webhook notification with the provided ID." } } }, "ListCustomerAlertsPayload": { "required": [ "customer_id" ], "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "The Metronome ID of the customer" }, "alert_statuses": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "enabled", "disabled", "archived", "ENABLED", "DISABLED", "ARCHIVED", "Enabled", "Disabled", "Archived" ] }, "description": "Optionally filter by threshold notification status. If absent, only enabled notifications will be returned." } } }, "ResetCustomerAlertsPayload": { "required": [ "customer_id", "alert_id" ], "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "The Metronome ID of the customer" }, "alert_id": { "type": "string", "format": "uuid", "description": "The Metronome ID of the threshold notification" } } }, "ArchiveAlertPayload": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The Metronome ID of the threshold notification" }, "release_uniqueness_key": { "type": "boolean", "description": "If true, resets the uniqueness key on this threshold notification so it can be re-used" } } }, "CreatePlanSalesforceResponse": { "required": [ "metronome_customer_id" ], "type": "object", "properties": { "metronome_customer_id": { "type": "string", "format": "uuid" } } }, "CustomerAlert": { "required": [ "customer_status", "alert" ], "type": "object", "properties": { "customer_status": { "type": "string", "enum": [ "ok", "in_alarm", "evaluating" ], "nullable": true, "description": "The status of the threshold notification. If the notification is archived, null will be returned." }, "triggered_by": { "type": "string", "nullable": true, "description": "If present, indicates the reason the threshold notification was triggered." }, "alert": { "$ref": "#/components/schemas/Alert" } } }, "Alert": { "required": [ "id", "name", "type", "status", "threshold", "updated_at" ], "type": "object", "properties": { "id": { "type": "string", "description": "the Metronome ID of the threshold notification" }, "name": { "type": "string", "description": "Name of the threshold notification" }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKey" }, "type": { "type": "string", "enum": [ "low_credit_balance_reached", "spend_threshold_reached", "monthly_invoice_total_spend_threshold_reached", "low_remaining_days_in_plan_reached", "low_remaining_credit_percentage_reached", "usage_threshold_reached", "invoice_total_reached" ], "description": "Type of the threshold notification" }, "status": { "type": "string", "enum": [ "enabled", "archived", "disabled" ], "description": "Status of the threshold notification" }, "credit_type": { "$ref": "#/components/schemas/CreditType", "nullable": true }, "threshold": { "type": "number", "description": "Threshold value of the notification policy" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp for when the threshold notification's customer status was last updated" }, "credit_grant_type_filters": { "type": "array", "items": { "type": "string" }, "description": "An array of strings, representing a way to filter the credit grant this threshold notification applies to, by looking at the credit_grant_type field on the credit grant. This field is only defined for CreditPercentage and CreditBalance notifications" }, "custom_field_filters": { "type": "array", "description": "A list of custom field filters for notification types that support advanced filtering", "items": { "$ref": "#/components/schemas/CustomFieldFilterType" } }, "group_key_filter": { "x-mint": { "groups": [ "client_id:462b838b-1582-4100-816e-f6c07bb604fe", "client_id:c187f54f-e807-4cf6-8fa1-a01f09d05412", "client_id:aa2899ec-16ad-413b-b20b-ec9ba4692d4e", "client_id:2f0c6751-0b61-46f2-8664-2eb1be6136cf", "client_id:b2c5d30a-6078-4cd4-9e98-340ca0883789", "client_id:67c6fe5e-5715-4b05-aa2a-b3885cd68b81", "client_id:f9b1ebc0-19f5-43cd-ba0b-7cf7da34fe7c", "client_id:98ac66cc-88b4-447f-a2e6-a84ebc81e36a" ] }, "$ref": "#/components/schemas/GroupKeyFilterType" }, "invoice_types_filter": { "$ref": "#/components/schemas/InvoiceTypesFilterType" } } }, "CustomerBillingProviderConfigurationLookup": { "type": "object", "description": "The billing provider configuration associated with a contract. Provide either an ID or the provider and delivery method.", "properties": { "billing_provider_configuration_id": { "type": "string", "format": "uuid", "description": "The Metronome ID of the billing provider configuration. Use when a customer has multiple configurations with the same billing provider and delivery method. Otherwise, specify the billing_provider and delivery_method." }, "billing_provider": { "$ref": "#/components/schemas/ContractsBillingProviderType", "description": "Do not specify if using billing_provider_configuration_id." }, "delivery_method": { "$ref": "#/components/schemas/BillingProviderDeliveryMethodType", "description": "Do not specify if using billing_provider_configuration_id." } } }, "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" ] } }, "TaxProviderType": { "type": "string", "enum": [ "anrok", "avalara", "stripe" ] }, "GABillingProviderType": { "type": "string", "enum": [ "aws_marketplace", "azure_marketplace", "gcp_marketplace" ] }, "ContractsBillingProviderType": { "type": "string", "enum": [ "aws_marketplace", "azure_marketplace", "gcp_marketplace", "stripe", "netsuite" ] }, "BillingProviderDeliveryMethodType": { "type": "string", "enum": [ "direct_to_billing_provider", "aws_sqs", "tackle", "aws_sns" ] }, "GABillingProviderDeliveryMethodType": { "type": "string", "enum": [ "direct_to_billing_provider", "aws_sqs", "aws_sns" ] }, "BillingProviderSettingsType": { "type": "string", "enum": [ "stripe" ] }, "EndCustomerPlanPayload": { "type": "object", "properties": { "ending_before": { "description": "RFC 3339 timestamp for when the plan ends (exclusive) for this customer. Must be at 0:00 UTC (midnight). If not provided, the plan end date will be cleared.", "type": "string", "format": "date-time" }, "void_invoices": { "description": "If true, plan end date can be before the last finalized invoice date. Any invoices generated after the plan end date will be voided.", "type": "boolean" }, "void_stripe_invoices": { "description": "Only applicable when void_invoices is set to true. If true, for every invoice that is voided we will also attempt to void/delete the stripe invoice (if any). Stripe invoices will be voided if finalized or deleted if still in draft state.", "type": "boolean" } } }, "AddPlanToCustomerPayload": { "required": [ "plan_id", "starting_on" ], "type": "object", "properties": { "plan_id": { "type": "string", "format": "uuid" }, "starting_on": { "description": "RFC 3339 timestamp for when the plan becomes active for this customer. Must be at 0:00 UTC (midnight).", "type": "string", "format": "date-time" }, "ending_before": { "description": "RFC 3339 timestamp for when the plan ends (exclusive) for this customer. Must be at 0:00 UTC (midnight).", "type": "string", "format": "date-time" }, "net_payment_terms_days": { "description": "Number of days after issuance of invoice after which the invoice is due (e.g. Net 30).", "type": "number" }, "price_adjustments": { "type": "array", "description": "A list of price adjustments can be applied on top of the pricing in the plans. See the [price adjustments documentation](https://plans-docs.metronome.com/pricing/managing-plans/#price-adjustments) for details.", "items": { "type": "object", "required": [ "charge_id", "adjustment_type", "start_period" ], "properties": { "charge_id": { "type": "string", "format": "uuid" }, "adjustment_type": { "type": "string", "enum": [ "percentage", "fixed", "override", "quantity" ] }, "value": { "type": "number", "description": "The amount of change to a price. Percentage and fixed adjustments can be positive or negative. Percentage-based adjustments should be decimals, e.g. -0.05 for a 5% discount." }, "quantity": { "type": "number", "description": "the overridden quantity for a fixed charge" }, "tier": { "type": "number", "description": "Used in pricing tiers. Indicates at what metric value the price applies." }, "start_period": { "type": "number", "description": "Used in price ramps. Indicates how many billing periods pass before the charge applies." } } } }, "trial_spec": { "required": [ "length_in_days" ], "type": "object", "description": "A custom trial can be set for the customer's plan. See the [trial configuration documentation](https://docs.metronome.com/provisioning/configure-trials/) for details.", "properties": { "length_in_days": { "type": "number", "description": "Length of the trial period in days." }, "spending_cap": { "type": "object", "required": [ "credit_type_id", "amount" ], "properties": { "credit_type_id": { "type": "string", "description": "The credit type ID for the spending cap." }, "amount": { "type": "number", "description": "The credit amount in the given denomination based on the credit type, e.g. US cents." } } } } }, "overage_rate_adjustments": { "type": "array", "description": "An optional list of overage rates that override the rates of the original plan configuration. These new rates will apply to all pricing ramps.", "items": { "type": "object", "required": [ "custom_credit_type_id", "fiat_currency_credit_type_id", "to_fiat_conversion_factor" ], "properties": { "custom_credit_type_id": { "type": "string", "format": "uuid" }, "fiat_currency_credit_type_id": { "type": "string", "format": "uuid" }, "to_fiat_conversion_factor": { "type": "number", "description": "The overage cost in fiat currency for each credit of the custom credit type." } } } } } }, "AddPlanFromSalesforceExperimentalPayload": { "required": [ "plan_id", "starting_on", "version", "salesforce_records", "salesforce_account_id", "customer_name", "deal_type" ], "type": "object", "properties": { "plan_id": { "type": "string", "format": "uuid" }, "starting_on": { "description": "RFC 3339 timestamp for when the plan becomes active for this customer. Must be at 0:00 UTC (midnight).", "type": "string", "format": "date-time" }, "ending_before": { "description": "RFC 3339 timestamp for when the plan ends (exclusive) for this customer. Must be at 0:00 UTC (midnight).", "type": "string", "format": "date-time" }, "net_payment_terms_days": { "description": "Number of days after issuance of invoice after which the invoice is due (e.g. Net 30).", "type": "number" }, "customer_id": { "description": "The identifer of the customer", "type": "string", "format": "uuid" }, "customer_name": { "description": "The name of the customer", "type": "string" }, "salesforce_account_id": { "description": "Salesforce Account ID", "type": "string" }, "version": { "description": "Version of the payload being sent from Salesforce", "type": "number" }, "salesforce_records": { "type": "array", "description": "Records being sent from Salesforce to generate the contract", "items": { "type": "object" } }, "deal_type": { "type": "string", "description": "Defines the kind of contract being created", "enum": [ "new", "renewal", "amendment" ] } } }, "AddOneTimeChargePayload": { "required": [ "charge_id", "price", "quantity", "invoice_start_timestamp", "customer_plan_id", "description" ], "type": "object", "properties": { "charge_id": { "description": "The Metronome ID of the charge to add to the invoice. Note that the charge must be on a product that is not on the current plan, and the product must have only fixed charges.", "type": "string", "format": "uuid" }, "price": { "description": "The price of the charge. This price will match the currency on the invoice, e.g. USD cents.", "type": "number" }, "quantity": { "type": "number" }, "description": { "type": "string" }, "customer_plan_id": { "description": "The Metronome ID of the customer plan to add the charge to.", "type": "string", "format": "uuid" }, "invoice_start_timestamp": { "description": "The start_timestamp of the invoice to add the charge to.", "type": "string", "format": "date-time" } } }, "CreateBillableMetricPayload": { "type": "object", "required": [ "name", "aggregate", "filter" ], "properties": { "name": { "type": "string" }, "aggregate": { "type": "string", "enum": [ "count", "Count", "COUNT", "latest", "Latest", "LATEST", "max", "Max", "MAX", "sum", "Sum", "SUM", "unique", "Unique", "UNIQUE" ] }, "aggregate_key": { "type": "string" }, "filter": { "type": "object", "description": "JSON Schema filter to apply to the metric", "additionalProperties": true }, "group_keys": { "type": "array", "items": { "type": "string" } }, "group_values": { "type": "array", "items": { "type": "string" } } } }, "SetIngestAliasesPayload": { "required": [ "ingest_aliases" ], "type": "object", "properties": { "ingest_aliases": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "maxItems": 2000 } } }, "LegacyCreateCustomerPayload": { "required": [ "name" ], "type": "object", "properties": { "ingest_aliases": { "type": "array", "description": "Aliases that can be used to refer to this customer in usage events", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "maxItems": 2000 }, "external_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "(deprecated, use ingest_aliases instead) an alias that can be used to refer to this customer in usage events" }, "name": { "type": "string", "description": "This will be truncated to 160 characters if the provided name is longer." }, "billing_config": { "required": [ "billing_provider_type", "billing_provider_customer_id" ], "type": "object", "properties": { "billing_provider_type": { "$ref": "#/components/schemas/BillingProviderType" }, "billing_provider_customer_id": { "type": "string" }, "stripe_collection_method": { "$ref": "#/components/schemas/StripeCollectionMethod" }, "aws_product_code": { "type": "string" }, "aws_region": { "$ref": "#/components/schemas/AwsRegion" }, "aws_is_subscription_product": { "description": "True if the aws_product_code is a SAAS subscription product, false otherwise.", "type": "boolean" } } }, "custom_fields": { "x-cf-entity": "customer", "$ref": "#/components/schemas/CustomField" } } }, "CreateCustomerPayload": { "required": [ "name" ], "type": "object", "properties": { "ingest_aliases": { "type": "array", "description": "Aliases that can be used to refer to this customer in usage events", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "maxItems": 2000 }, "name": { "type": "string", "description": "This will be truncated to 160 characters if the provided name is longer." }, "billing_config": { "required": [ "billing_provider_type", "billing_provider_customer_id" ], "type": "object", "properties": { "billing_provider_type": { "$ref": "#/components/schemas/BillingProviderType" }, "billing_provider_customer_id": { "type": "string" }, "stripe_collection_method": { "$ref": "#/components/schemas/StripeCollectionMethod" }, "aws_product_code": { "type": "string" }, "aws_region": { "$ref": "#/components/schemas/AwsRegion" }, "aws_is_subscription_product": { "description": "True if the aws_product_code is a SAAS subscription product, false otherwise.", "type": "boolean" } } }, "custom_fields": { "x-cf-entity": "customer", "$ref": "#/components/schemas/CustomField" } } }, "SetCustomerNamePayload": { "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string", "description": "The new name for the customer. This will be truncated to 160 characters if the provided name is longer." } } }, "CustomerConfigPayload": { "type": "object", "properties": { "salesforce_account_id": { "type": "string", "description": "The Salesforce account ID for the customer", "nullable": true }, "leave_stripe_invoices_in_draft": { "type": "boolean", "description": "Leave in draft or set to auto-advance on invoices sent to Stripe. Falls back to the client-level config if unset, which defaults to true if unset.", "nullable": true } } }, "CustomerConfig": { "required": [ "salesforce_account_id" ], "type": "object", "properties": { "salesforce_account_id": { "type": "string", "description": "The Salesforce account ID for the customer", "nullable": true } } }, "Customer": { "required": [ "external_id", "ingest_aliases", "id", "name" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "the Metronome ID of the customer" }, "external_id": { "type": "string", "description": "(deprecated, use ingest_aliases instead) the first ID (Metronome or ingest alias) that can be used in usage events" }, "ingest_aliases": { "type": "array", "description": "aliases for this customer that can be used instead of the Metronome customer ID in usage events", "items": { "type": "string" } }, "name": { "type": "string" }, "custom_fields": { "x-cf-entity": "customer", "$ref": "#/components/schemas/CustomField" } } }, "CustomerDetail": { "required": [ "external_id", "id", "name", "created_at", "updated_at", "customer_config", "ingest_aliases", "custom_fields" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "the Metronome ID of the customer" }, "external_id": { "type": "string", "description": "(deprecated, use ingest_aliases instead) the first ID (Metronome or ingest alias) that can be used in usage events" }, "ingest_aliases": { "type": "array", "description": "aliases for this customer that can be used instead of the Metronome customer ID in usage events", "items": { "type": "string" } }, "name": { "type": "string" }, "customer_config": { "$ref": "#/components/schemas/CustomerConfig" }, "custom_fields": { "x-cf-entity": "customer", "$ref": "#/components/schemas/CustomField" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when the customer was created." }, "archived_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when the customer was archived. Null if the customer is active.", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when the customer was last updated." }, "current_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" ] }, "required": [ "value" ], "type": "object", "description": "This field's availability is dependent on your client's configuration.", "properties": { "value": { "$ref": "#/components/schemas/BillableStatus" }, "effective_at": { "type": "string", "format": "date-time", "nullable": true } } } } }, "CustomerPlanDetail": { "required": [ "id", "name", "custom_fields", "starting_on", "customer_plan_id" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "starting_on": { "type": "string", "format": "date-time", "description": "The start date of the plan" }, "ending_before": { "type": "string", "format": "date-time", "description": "The end date of the plan", "nullable": true }, "custom_fields": { "x-cf-entity": "plan", "$ref": "#/components/schemas/CustomField" }, "customer_plan_id": { "type": "string", "format": "uuid" } } }, "CustomerAndPlanDetail": { "required": [ "customer_details", "plan_details" ], "type": "object", "properties": { "customer_details": { "$ref": "#/components/schemas/CustomerDetail" }, "plan_details": { "$ref": "#/components/schemas/CustomerPlanDetail" } } }, "BillableStatus": { "type": "string", "enum": [ "billable", "unbillable" ] }, "CreateCreditGrantPayload": { "required": [ "customer_id", "grant_amount", "name", "expires_at", "paid_amount", "priority" ], "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "the Metronome ID of the customer" }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKey" }, "grant_amount": { "description": "the amount of credits granted", "type": "object", "required": [ "amount", "credit_type_id" ], "properties": { "amount": { "type": "number" }, "credit_type_id": { "description": "the ID of the pricing unit to be used. Defaults to USD (cents) if not passed.", "type": "string", "format": "uuid" } } }, "paid_amount": { "description": "the amount paid for this credit grant", "type": "object", "required": [ "amount", "credit_type_id" ], "properties": { "amount": { "type": "number" }, "credit_type_id": { "description": "the ID of the pricing unit to be used. Defaults to USD (cents) if not passed.", "type": "string", "format": "uuid" } } }, "name": { "type": "string", "description": "the name of the credit grant as it will appear on invoices" }, "effective_at": { "type": "string", "format": "date-time", "description": "The credit grant will only apply to usage or charges dated on or after this timestamp" }, "expires_at": { "type": "string", "format": "date-time", "description": "The credit grant will only apply to usage or charges dated before this timestamp" }, "invoice_date": { "type": "string", "format": "date-time", "description": "The date to issue an invoice for the paid_amount." }, "priority": { "type": "number" }, "reason": { "type": "string" }, "credit_grant_type": { "type": "string" }, "product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The product(s) which these credits will be applied to. (If unspecified, the credits will be applied to charges for all products.). The array ordering specified here will be used to determine the order in which credits will be applied to invoice line items" }, "rollover_settings": { "$ref": "#/components/schemas/CreditGrantRolloverSettings" }, "custom_fields": { "description": "Custom fields to attach to the credit grant.", "$ref": "#/components/schemas/CustomField" } } }, "CreditGrantRolloverSettings": { "type": "object", "description": "Configure a rollover for this credit grant so if it expires it rolls over a configured amount to a new credit grant. This feature is currently opt-in only. Contact Metronome to be added to the beta.", "required": [ "expires_at", "priority", "rollover_amount" ], "properties": { "expires_at": { "type": "string", "format": "date-time", "description": "The date to expire the rollover credits." }, "priority": { "type": "number", "description": "The priority to give the rollover credit grant that gets created when a rollover happens." }, "rollover_amount": { "description": "Specify how much to rollover to the rollover credit grant", "oneOf": [ { "$ref": "#/components/schemas/RolloverAmountMaxPercentage" }, { "$ref": "#/components/schemas/RolloverAmountMaxAmount" } ] } } }, "RolloverAmountMaxPercentage": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "MAX_PERCENTAGE" ], "description": "Rollover up to a percentage of the original credit grant amount." }, "value": { "type": "number", "description": "The maximum percentage (0-1) of the original credit grant to rollover.", "minimum": 0, "maximum": 1 } } }, "RolloverAmountMaxAmount": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "MAX_AMOUNT" ], "description": "Rollover up to a fixed amount of the original credit grant amount." }, "value": { "type": "number", "description": "The maximum amount to rollover." } } }, "NameValuePair": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" } } }, "GetRechargeSettingsPayload": { "type": "object", "required": [ "id", "recharge_to_amount", "recharge_threshold", "credit_type_id", "grant_duration", "prepaid_options", "name", "priority" ], "properties": { "recharge_to_amount": { "type": "number", "description": "the amount to recharge to", "minimum": 0 }, "recharge_threshold": { "type": "number", "description": "the threshold at which to recharge", "minimum": 0 }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid", "description": "the Metronome ID of the recharge settings" }, "name": { "type": "string", "description": "the name of the credit grant as it will appear on invoices" }, "priority": { "type": "number" }, "reason": { "type": "string", "description": "Reason for the credit grant. This may be shown to your users." }, "credit_grant_type": { "type": "string", "description": "Internal-only identifier used to categorize your credit grant. Your users won't see this." }, "product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The product(s) which these credits will be applied to. (If unspecified, the credits will be applied to charges for all products.). The array ordering specified here will be used to determine the order in which credits will be applied to invoice line items" }, "grant_duration": { "type": "number", "description": "the duration (in months) for which the credits will be granted" }, "credit_type_id": { "type": "string", "format": "uuid", "description": "the Metronome ID of the credit type to recharge" }, "prepaid_options": { "$ref": "#/components/schemas/PrepaidGrantOptions" }, "status": { "$ref": "#/components/schemas/RechargeSettingsStatus" } } }, "RechargeSettingsStatus": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "active", "disabled", "processing", "disabled_error" ], "description": "the status of the recharge" }, "stripe_error_code": { "type": "string", "description": "the error code returned by Stripe if the reason why the recharge failed" }, "last_credit_grant": { "type": "string", "format": "uuid", "description": "the Metronome ID of the last credit grant that was created by this recharge" } } }, "RechargeSettingsPayload": { "type": "object", "required": [ "recharge_to_amount", "recharge_threshold", "credit_type_id", "grant_duration", "prepaid_options", "name", "priority" ], "properties": { "recharge_to_amount": { "type": "number", "description": "the amount to recharge to", "minimum": 0 }, "recharge_threshold": { "type": "number", "description": "the threshold at which to recharge", "minimum": 0 }, "enabled": { "type": "boolean" }, "recharge_now": { "type": "boolean", "description": "If true, a recharge will be triggered immediately if the credit balance is under the recharge_threshold and the result of the recharge will be returned in the response. The settings will be updated regardless of the result of the recharge but the settings will have enabled set to 'false' if the recharge fails. An requires action result will be considered a failure for the purposes of this flag." }, "name": { "type": "string", "description": "the name of the credit grant as it will appear on invoices" }, "priority": { "type": "number" }, "reason": { "type": "string", "description": "Reason for the credit grant. This may be shown to your users." }, "credit_grant_type": { "type": "string", "description": "Internal-only identifier used to categorize your credit grant. Your users won't see this." }, "product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The product(s) which these credits will be applied to. (If unspecified, the credits will be applied to charges for all products.). The array ordering specified here will be used to determine the order in which credits will be applied to invoice line items" }, "grant_duration": { "type": "number", "description": "the duration (in months) for which the credits will be granted" }, "credit_type_id": { "type": "string", "format": "uuid", "description": "the Metronome ID of the credit type to recharge" }, "prepaid_options": { "$ref": "#/components/schemas/PrepaidRechargeGrantOptions" } } }, "CreatePrepaidCreditGrantPayload": { "type": "object", "required": [ "prepaid_options", "customer_id", "grant_amount", "name", "expires_at", "invoice_date", "paid_amount", "priority" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "the Metronome ID of the customer" }, "grant_amount": { "description": "the amount of credits granted", "type": "object", "required": [ "amount", "credit_type_id" ], "properties": { "amount": { "type": "number" }, "credit_type_id": { "description": "the ID of the pricing unit to be used", "type": "string", "format": "uuid" } } }, "paid_amount": { "description": "the amount paid for this credit grant; must be greater than 0", "type": "object", "required": [ "amount", "credit_type_id" ], "properties": { "amount": { "type": "number" }, "credit_type_id": { "description": "the ID of the pricing unit to be used", "type": "string", "format": "uuid" } } }, "name": { "type": "string", "description": "the name of the credit grant as it will appear on invoices" }, "effective_at": { "type": "string", "format": "date-time", "description": "The credit grant will only apply to usage or charges dated on or after this timestamp" }, "expires_at": { "type": "string", "format": "date-time", "description": "The credit grant will only apply to usage or charges dated before this timestamp" }, "invoice_date": { "type": "string", "format": "date-time", "description": "The date to issue an invoice for the paid_amount." }, "priority": { "type": "number" }, "reason": { "type": "string", "description": "Reason for the credit grant. This may be shown to your users." }, "credit_grant_type": { "type": "string", "description": "Internal-only identifier used to categorize your credit grant. Your users won't see this." }, "product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The product(s) which these credits will be applied to. (If unspecified, the credits will be applied to charges for all products.). The array ordering specified here will be used to determine the order in which credits will be applied to invoice line items" }, "prepaid_options": { "$ref": "#/components/schemas/PrepaidGrantOptions" } } }, "PrepaidGrantOptions": { "type": "object", "description": "Options for prepaid credits. If specified, the credits will not be released until payment is received.", "required": [ "billing_provider_type" ], "properties": { "billing_provider_type": { "type": "string", "description": "The type of billing provider to use for the prepaid invoice. Currently only 'stripe' is supported." }, "stripe_options": { "type": "object", "description": "Options for prepaid credits using Stripe", "properties": { "calculate_tax": { "type": "boolean", "description": "Whether to calculate tax for the prepaid invoice Defaults to false if not provided." }, "tax_platform": { "$ref": "#/components/schemas/TaxPlatform", "description": "The tax platform used for calculating tax. Defaults to 'stripe' if not provided." }, "skip_tax_on_tax_platform_error": { "type": "boolean", "description": "Whether to skip tax calculation if the tax platform returns an error. Defaults to true if not provided." }, "precalculated_tax": { "type": "number", "description": "The tax amount to use for the prepaid invoice. If provided, this will be used instead of calculating tax. Not applicable for recharge settings. Decimal numbers are not supported and the value is the smallest denomination of the currency (e.g. cents)." }, "tax_product_id": { "type": "string", "description": "Optional Stripe product ID to use for the tax line item in Stripe. If omitted a random Stripe product will be created and used for the invoice." }, "redirect_url": { "type": "string", "description": "The URL to redirect the user to after they have corrected a billing issue" }, "invoice_custom_fields": { "type": "array", "description": "Custom fields to add to the prepaid invoice", "items": { "$ref": "#/components/schemas/NameValuePair" } }, "invoice_metadata": { "type": "object", "additionalProperties": true, "description": "Invoice metadata to add to the prepaid invoice" }, "payment_method_id": { "type": "string", "description": "Optional Stripe payment method ID to use." }, "product_id": { "type": "string", "description": "Optional Stripe product ID for the invoice line item. This will be passed to Stripe on the associated credit grant invoice line item and other tax platforms if applicable." }, "radar_session_id": { "type": "string", "description": "Optional Radar session ID to send to Stripe when creating the payment intent." } } } } }, "PrepaidRechargeGrantOptions": { "type": "object", "description": "Options for prepaid credits. If specified, the credits will not be released until payment is received.", "required": [ "billing_provider_type" ], "properties": { "billing_provider_type": { "type": "string", "description": "The type of billing provider to use for the prepaid invoice. Currently only 'stripe' is supported." }, "stripe_options": { "type": "object", "description": "Options for prepaid credits using Stripe", "properties": { "calculate_tax": { "type": "boolean", "description": "Whether to calculate tax for the prepaid invoice Defaults to false if not provided." }, "tax_platform": { "$ref": "#/components/schemas/TaxPlatform", "description": "The tax platform used for calculating tax. Defaults to 'stripe' if not provided." }, "skip_tax_on_tax_platform_error": { "type": "boolean", "description": "Whether to skip tax calculation if the tax platform returns an error. Defaults to true if not provided." }, "tax_product_id": { "type": "string", "description": "Optional Stripe product ID to use for the tax line item. If omitted a random Stripe product will be created and used for the invoice." }, "redirect_url": { "type": "string", "description": "The URL to redirect the user to after they have corrected a billing issue" }, "invoice_custom_fields": { "type": "array", "description": "Custom fields to add to the prepaid invoice", "items": { "$ref": "#/components/schemas/NameValuePair" } }, "invoice_metadata": { "type": "object", "additionalProperties": true, "description": "Invoice metadata to add to the prepaid invoice" }, "payment_method_id": { "type": "string", "description": "Optional Stripe payment method ID to use." }, "product_id": { "type": "string", "description": "Optional Stripe product ID to use for the grant." } } } } }, "TaxPlatform": { "type": "string", "enum": [ "stripe", "anrok" ] }, "EditCreditGrantPayload": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "the ID of the credit grant" }, "name": { "type": "string", "description": "the updated name for the credit grant" }, "expires_at": { "type": "string", "format": "date-time", "description": "the updated expiration date for the credit grant" }, "credit_grant_type": { "type": "string", "description": "the updated credit grant type" } } }, "CreditGrant": { "required": [ "id", "name", "customer_id", "effective_at", "expires_at", "priority", "grant_amount", "paid_amount", "balance", "deductions", "pending_deductions", "custom_fields" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "the Metronome ID of the credit grant" }, "name": { "type": "string" }, "customer_id": { "type": "string", "format": "uuid", "description": "the Metronome ID of the customer" }, "invoice_id": { "type": "string", "nullable": true, "format": "uuid", "description": "the Metronome ID of the invoice with the purchase charge for this credit grant, if applicable" }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKey", "nullable": true }, "reason": { "type": "string", "nullable": true }, "credit_grant_type": { "type": "string", "nullable": true }, "effective_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "priority": { "type": "number" }, "grant_amount": { "description": "the amount of credits initially granted", "type": "object", "required": [ "amount", "credit_type" ], "properties": { "amount": { "type": "number" }, "credit_type": { "description": "the credit type for the amount granted", "$ref": "#/components/schemas/CreditType" } } }, "paid_amount": { "description": "the amount paid for this credit grant", "type": "object", "required": [ "amount", "credit_type" ], "properties": { "amount": { "type": "number" }, "credit_type": { "description": "the credit type for the amount paid", "$ref": "#/components/schemas/CreditType" } } }, "balance": { "description": "The effective balance of the grant as of the end of the customer's current billing period. Expiration deductions will be included only if the grant expires before the end of the current billing period.", "type": "object", "required": [ "excluding_pending", "including_pending", "effective_at" ], "properties": { "excluding_pending": { "type": "number", "description": "The grant's current balance including all posted deductions. If the grant has expired, this amount will be 0." }, "including_pending": { "type": "number", "description": "The grant's current balance including all posted and pending deductions. If the grant expires before the end of the customer's current billing period, this amount will be 0." }, "effective_at": { "type": "string", "format": "date-time", "description": "The end_date of the customer's current billing period." } } }, "deductions": { "type": "array", "items": { "$ref": "#/components/schemas/CreditLedgerEntry" } }, "pending_deductions": { "type": "array", "items": { "$ref": "#/components/schemas/CreditLedgerEntry" } }, "products": { "description": "The products which these credits will be applied to. (If unspecified, the credits will be applied to charges for all products.)", "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "custom_fields": { "x-cf-entity": "credit_grant", "$ref": "#/components/schemas/CustomField" } } }, "ListCreditGrantPayload": { "type": "object", "properties": { "credit_type_ids": { "description": "An array of credit type IDs. This must not be specified if credit_grant_ids is specified.", "type": "array", "items": { "type": "string", "format": "uuid" }, "example": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc, 0e5b8609-d901-4992-b394-c3c2e3f37b1c" }, "customer_ids": { "description": "An array of Metronome customer IDs. This must not be specified if credit_grant_ids is specified.", "type": "array", "items": { "type": "string", "format": "uuid" }, "example": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc, 0e5b8609-d901-4992-b394-c3c2e3f37b1c" }, "credit_grant_ids": { "description": "An array of credit grant IDs. If this is specified, neither credit_type_ids nor customer_ids may be specified.", "type": "array", "items": { "type": "string", "format": "uuid" }, "example": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc, 0e5b8609-d901-4992-b394-c3c2e3f37b1c" }, "not_expiring_before": { "description": "Only return credit grants that expire at or after this timestamp.", "type": "string", "format": "date-time", "example": "2022-02-01T00:00:00Z" }, "effective_before": { "description": "Only return credit grants that are effective before this timestamp (exclusive).", "type": "string", "format": "date-time", "example": "2022-02-01T00:00:00Z" } } }, "CustomFieldFilterType": { "type": "object", "required": [ "entity", "key", "value" ], "properties": { "entity": { "type": "string", "enum": [ "Contract", "Commit", "ContractCredit", "ContractCreditOrCommit" ], "x-mint-enum": { "ContractCreditOrCommit": [ "ff:alert-specifiers-enabled" ] } }, "key": { "type": "string" }, "value": { "type": "string" } } }, "BalanceCustomFieldFilterType": { "type": "object", "required": [ "entity", "key", "value" ], "properties": { "entity": { "type": "string", "enum": [ "Commit", "ContractCredit", "ContractCreditOrCommit" ], "x-mint-enum": { "ContractCreditOrCommit": [ "ff:alert-specifiers-enabled" ] } }, "key": { "type": "string" }, "value": { "type": "string" } } }, "GroupKeyFilterType": { "type": "object", "description": "Scopes threshold notification evaluation to a specific presentation group key on individual line items. Only present for spend notifications.", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "GroupValueFilterType": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "AlertSpecifierInclusiveCustomFieldFilter": { "type": "object", "required": [ "entity", "key" ], "properties": { "entity": { "type": "string", "enum": [ "Contract", "Commit", "ContractCredit", "ContractCreditOrCommit" ], "x-mint-enum": { "ContractCreditOrCommit": [ "ff:alert-specifiers-enabled" ] } }, "key": { "type": "string" }, "value": { "type": "string" } } }, "AlertSpecifier": { "type": "object", "properties": { "custom_field_filters": { "type": "array", "description": "A list of custom field filters for notification types that support advanced filtering", "items": { "$ref": "#/components/schemas/AlertSpecifierInclusiveCustomFieldFilter" } }, "exclude": { "type": "array", "description": "If provided, the specifier will not apply to balances that matches the inclusion criteria and any of the excluding values.", "items": { "$ref": "#/components/schemas/ExcludeAlertSpecifier" } } } }, "AlertSpecifierFilter": { "type": "object", "required": [ "custom_field_filters" ], "properties": { "custom_field_filters": { "type": "array", "description": "A list of custom field filters for notification types that support advanced filtering", "items": { "$ref": "#/components/schemas/CustomFieldFilterType" } }, "exclude": { "type": "array", "description": "If provided, the specifier will not apply to balances that matches the inclusion criteria and any of the excluding values.", "items": { "$ref": "#/components/schemas/ExcludeAlertSpecifier" } } } }, "ExcludeAlertSpecifier": { "type": "object", "properties": { "custom_field_filters": { "type": "array", "description": "A list of custom field filters for notification types that support advanced filtering", "items": { "$ref": "#/components/schemas/CustomFieldFilterType" } } } }, "InvoiceTypesFilterType": { "type": "array", "description": "Only supported for invoice_total_reached threshold notifications. A list of invoice types to evaluate.", "items": { "$ref": "#/components/schemas/InvoiceType" } }, "CreditType": { "required": [ "name", "id" ], "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "string", "format": "uuid" } } }, "CreditTypeConversionInput": { "type": "object", "required": [ "custom_credit_type_id", "fiat_per_custom_credit" ], "properties": { "custom_credit_type_id": { "type": "string", "format": "uuid" }, "fiat_per_custom_credit": { "type": "number" } } }, "CreditTypeConversion": { "required": [ "fiat_per_custom_credit", "custom_credit_type" ], "type": "object", "properties": { "fiat_per_custom_credit": { "type": "string" }, "custom_credit_type": { "$ref": "#/components/schemas/CreditType" } } }, "Event": { "required": [ "customer_id", "event_type", "timestamp", "transaction_id" ], "type": "object", "properties": { "transaction_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "customer_id": { "type": "string", "minLength": 1, "maxLength": 1024 }, "event_type": { "type": "string", "minLength": 1, "maxLength": 1024 }, "timestamp": { "type": "string", "description": "RFC 3339 formatted" }, "properties": { "type": "object", "additionalProperties": true } } }, "SignedEvent": { "required": [ "jws_data" ], "type": "object", "properties": { "jws_data": { "type": "string", "minLength": 1 } } }, "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.\n" } } }, "Error": { "required": [ "message" ], "type": "object", "properties": { "message": { "type": "string" } } }, "PrepaidGrantError": { "required": [ "message" ], "type": "object", "properties": { "message": { "type": "string" }, "stripe_error": { "type": "object", "description": "The error returned by Stripe when attempting to create a prepaid grant.", "additionalProperties": true } } }, "CreditBalance": { "type": "object", "required": [ "balance", "credit_type" ], "properties": { "credit_type": { "$ref": "#/components/schemas/CreditType" }, "balance": { "type": "number", "example": 100 }, "pending_delta": { "type": "number", "example": -100 } } }, "CreditLedgerEntry": { "type": "object", "required": [ "amount", "reason", "running_balance", "effective_at", "created_by", "credit_grant_id" ], "properties": { "amount": { "type": "number", "description": "an amount representing the change to the customer's credit balance" }, "reason": { "type": "string", "example": "Automated invoice deduction" }, "running_balance": { "type": "number", "description": "the running balance for this credit type at the time of the ledger entry, including all preceding charges" }, "effective_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "credit_grant_id": { "type": "string", "format": "uuid", "description": "the credit grant this entry is related to" }, "invoice_id": { "type": "string", "format": "uuid", "nullable": true, "description": "if this entry is a deduction, the Metronome ID of the invoice where the credit deduction was consumed; if this entry is a grant, the Metronome ID of the invoice where the grant's paid_amount was charged" } } }, "CreditTypeLedger": { "type": "object", "required": [ "credit_type", "starting_balance", "ending_balance", "entries", "pending_entries" ], "properties": { "credit_type": { "$ref": "#/components/schemas/CreditType" }, "starting_balance": { "type": "object", "required": [ "excluding_pending", "including_pending", "effective_at" ], "properties": { "excluding_pending": { "type": "number", "description": "the starting balance, including all posted grants, deductions, and expirations that happened at or before the effective_at timestamp" }, "including_pending": { "type": "number", "description": "the excluding_pending balance plus any pending activity that has not been posted at the time of the query" }, "effective_at": { "type": "string", "format": "date-time", "description": "the starting_on request parameter (if supplied) or the first credit grant's effective_at date" } } }, "ending_balance": { "description": "the effective balances at the end of the specified time window", "type": "object", "required": [ "excluding_pending", "including_pending", "effective_at" ], "properties": { "excluding_pending": { "type": "number", "description": "the ending balance, including the balance of all grants that have not expired before the effective_at date and deductions that happened before the effective_at date" }, "including_pending": { "type": "number", "description": "the excluding_pending balance plus any pending invoice deductions and expirations that will happen by the effective_at date" }, "effective_at": { "type": "string", "format": "date-time", "description": "the ending_before request parameter (if supplied) or the current billing period's end date" } } }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/CreditLedgerEntry" } }, "pending_entries": { "type": "array", "items": { "$ref": "#/components/schemas/CreditLedgerEntry" } } } }, "CustomerCreditTypeLedger": { "type": "object", "required": [ "customer_id", "ledgers" ], "properties": { "customer_id": { "type": "string", "format": "uuid" }, "ledgers": { "type": "array", "items": { "$ref": "#/components/schemas/CreditTypeLedger" } } } }, "CreditLedgerEntriesQueryPayload": { "type": "object", "properties": { "customer_ids": { "type": "array", "description": "A list of Metronome customer IDs to fetch ledger entries for. If absent, ledger entries for all customers will be returned.", "items": { "type": "string", "format": "uuid" } }, "credit_type_ids": { "type": "array", "description": "A list of Metronome credit type IDs to fetch ledger entries for. If absent, ledger entries for all credit types will be returned.", "items": { "type": "string", "format": "uuid" } }, "starting_on": { "type": "string", "description": "If supplied, only ledger entries effective at or after this time will be returned.", "format": "date-time" }, "ending_before": { "type": "string", "description": "If supplied, ledger entries will only be returned with an effective_at before this time. This timestamp must not be in the future. If no timestamp is supplied, all entries up to the start of the customer's next billing period will be returned.", "format": "date-time" } } }, "CustomerPlan": { "required": [ "id", "plan_id", "plan_name", "plan_description", "starting_on", "custom_fields" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "the ID of the customer plan" }, "plan_id": { "type": "string", "format": "uuid", "description": "the ID of the plan" }, "plan_name": { "type": "string" }, "plan_description": { "type": "string" }, "starting_on": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "net_payment_terms_days": { "type": "number" }, "trial_info": { "type": "object", "required": [ "ending_before", "spending_caps" ], "properties": { "ending_before": { "type": "string", "format": "date-time" }, "spending_caps": { "type": "array", "items": { "type": "object", "required": [ "amount", "amount_remaining", "credit_type" ], "properties": { "credit_type": { "$ref": "#/components/schemas/CreditType" }, "amount": { "type": "number", "example": 123.45 }, "amount_remaining": { "type": "number", "example": 123 } } } } } }, "custom_fields": { "x-cf-entity": "customer_plan", "$ref": "#/components/schemas/CustomField" } } }, "PriceAdjustment": { "type": "object", "required": [ "charge_id", "charge_type", "start_period", "prices" ], "properties": { "charge_id": { "type": "string", "format": "uuid" }, "charge_type": { "$ref": "#/components/schemas/ChargeType" }, "start_period": { "type": "number" }, "quantity": { "type": "number" }, "prices": { "type": "array", "items": { "required": [ "adjustment_type" ], "type": "object", "properties": { "adjustment_type": { "type": "string", "enum": [ "fixed", "quantity", "percentage", "override" ], "description": "Determines how the value will be applied." }, "value": { "type": "number" }, "quantity": { "type": "number" }, "tier": { "type": "number", "description": "Used in pricing tiers. Indicates at what metric value the price applies." } } } } } }, "Id": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, "Plan": { "required": [ "id", "name", "description" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "custom_fields": { "x-cf-entity": "plan", "$ref": "#/components/schemas/CustomField" } } }, "PlanDetail": { "required": [ "id", "name", "custom_fields" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "minimums": { "type": "array", "items": { "required": [ "name", "value", "start_period", "credit_type" ], "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "number" }, "start_period": { "type": "number", "description": "Used in price ramps. Indicates how many billing periods pass before the charge applies." }, "credit_type": { "$ref": "#/components/schemas/CreditType" } } } }, "overage_rates": { "type": "array", "items": { "required": [ "to_fiat_conversion_factor", "start_period", "fiat_credit_type", "credit_type" ], "type": "object", "properties": { "to_fiat_conversion_factor": { "type": "number" }, "start_period": { "type": "number", "description": "Used in price ramps. Indicates how many billing periods pass before the charge applies." }, "fiat_credit_type": { "$ref": "#/components/schemas/CreditType" }, "credit_type": { "$ref": "#/components/schemas/CreditType" } } } }, "credit_grants": { "type": "array", "items": { "required": [ "name", "amount_granted", "amount_paid", "priority", "effective_duration", "send_invoice", "amount_granted_credit_type", "amount_paid_credit_type" ], "type": "object", "properties": { "name": { "type": "string" }, "amount_granted": { "type": "number" }, "amount_paid": { "type": "number" }, "effective_duration": { "type": "number" }, "priority": { "type": "string" }, "send_invoice": { "type": "boolean" }, "reason": { "type": "string" }, "recurrence_duration": { "type": "number" }, "recurrence_interval": { "type": "number" }, "amount_paid_credit_type": { "$ref": "#/components/schemas/CreditType" }, "amount_granted_credit_type": { "$ref": "#/components/schemas/CreditType" } } } }, "custom_fields": { "x-cf-entity": "plan", "$ref": "#/components/schemas/CustomField" } } }, "PlanCharge": { "required": [ "id", "name", "product_id", "product_name", "prices", "charge_type", "credit_type", "custom_fields" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "charge_type": { "$ref": "#/components/schemas/ChargeType" }, "product_id": { "type": "string" }, "product_name": { "type": "string" }, "quantity": { "type": "number" }, "start_period": { "type": "number", "description": "Used in price ramps. Indicates how many billing periods pass before the charge applies." }, "tier_reset_frequency": { "type": "number", "description": "Used in pricing tiers. Indicates how often the tier resets. Default is 1 - the tier count resets every billing period." }, "credit_type": { "$ref": "#/components/schemas/CreditType" }, "unit_conversion": { "required": [ "division_factor" ], "type": "object", "description": "Specifies how quantities for usage based charges will be converted.", "properties": { "division_factor": { "type": "number", "description": "The conversion factor" }, "rounding_behavior": { "type": "string", "enum": [ "floor", "ceiling" ], "description": "Whether usage should be rounded down or up to the nearest whole number. If null, quantity will be rounded to 20 decimal places." } } }, "prices": { "type": "array", "items": { "required": [ "value", "tier" ], "type": "object", "properties": { "value": { "type": "number" }, "tier": { "type": "number", "description": "Used in pricing tiers. Indicates at what metric value the price applies." }, "quantity": { "type": "number" }, "collection_schedule": { "type": "string" }, "collection_interval": { "type": "number" } } } }, "custom_fields": { "x-cf-entity": "charge", "$ref": "#/components/schemas/CustomField" } } }, "BillableMetricBase": { "required": [ "name", "id" ], "type": "object", "properties": { "group_by": { "type": "array", "description": "(DEPRECATED) use group_keys instead", "items": { "type": "string", "description": "A list of keys that can be used to additionally segment the values of the billable metric when making usage queries" } }, "group_keys": { "$ref": "#/components/schemas/GroupKeysArray" }, "name": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "aggregate": { "type": "string", "description": "(DEPRECATED) use aggregation_type instead" }, "aggregate_keys": { "type": "array", "description": "(DEPRECATED) use aggregation_key instead", "items": { "type": "string" } }, "filter": { "type": "object", "description": "(DEPRECATED) use property_filters & event_type_filter instead", "additionalProperties": true }, "aggregation_key": { "$ref": "#/components/schemas/AggregationKey" }, "event_type_filter": { "$ref": "#/components/schemas/EventTypeFilter" }, "property_filters": { "$ref": "#/components/schemas/PropertyFiltersArray" }, "custom_fields": { "x-cf-entity": "billable_metric", "$ref": "#/components/schemas/CustomField" }, "sql": { "type": "string", "description": "The SQL query associated with the billable metric" }, "archived_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when the billable metric was archived. If not provided, the billable metric is not archived." } } }, "BillableMetricWithDeprecatedFields": { "allOf": [ { "$ref": "#/components/schemas/BillableMetricBase" }, { "type": "object", "properties": { "aggregation_type": { "$ref": "#/components/schemas/AggregationType" } } } ] }, "BillableMetricForEventsSearch": { "allOf": [ { "$ref": "#/components/schemas/BillableMetricBase" }, { "type": "object", "properties": { "aggregation_type": { "$ref": "#/components/schemas/AggregationTypeForEventsSearch" } } } ] }, "UsageQueryPayload": { "required": [ "window_size" ], "type": "object", "properties": { "window_size": { "type": "string", "description": "A window_size of \"day\" or \"hour\" will return the usage for the specified period segmented into daily or hourly aggregates. A window_size of \"none\" will return a single usage aggregate for the entirety of the specified period.", "enum": [ "hour", "day", "none", "HOUR", "DAY", "NONE", "Hour", "Day", "None" ] }, "starting_on": { "type": "string", "format": "date-time", "description": "Must be aligned to UTC midnight, e.g. `2024-01-01T00:00:00Z`." }, "ending_before": { "type": "string", "format": "date-time", "description": "Must be aligned to UTC midnight and at least one day after `starting_on`." }, "group_by": { "type": "object", "required": [ "key", "values" ], "properties": { "key": { "type": "string", "description": "The name of the group_by key to use" }, "values": { "type": "array", "description": "Values of the group_by key to return in the query", "minItems": 1, "maxItems": 200, "items": { "type": "string", "minLength": 1 } } } }, "current_period": { "type": "boolean", "description": "If true, will return the usage for the current billing period. Will return an error if the customer does not have an active plan, or if starting_on and ending_before are specified when this is true." } } }, "SeatsUsageQueryPayload": { "required": [ "seat_metric_id", "customer_id", "window_size", "usage_type" ], "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "seat_metric_id": { "type": "string", "format": "uuid" }, "usage_type": { "type": "string", "description": "The type of usage to return, max or latest value.", "enum": [ "max", "latest", "MAX", "LATEST", "Max", "Latest" ] }, "window_size": { "type": "string", "description": "A window_size of \"day\" or \"hour\" will return the usage for the specified period segmented into daily or hourly aggregates. A window_size of \"none\" will return a single usage aggregate for the entirety of the specified period.", "enum": [ "hour", "day", "none", "HOUR", "DAY", "NONE", "Hour", "Day", "None" ] }, "starting_on": { "type": "string", "format": "date-time", "description": "Must be aligned to UTC midnight, e.g. `2024-01-01T00:00:00Z`." }, "ending_before": { "type": "string", "format": "date-time", "description": "Must be aligned to UTC midnight and at least one day after `starting_on`." }, "current_period": { "type": "boolean", "description": "If true, will return the usage for the current billing period. Will return an error if the customer does not have an active plan, or if starting_on and ending_before are specified when this is true." } } }, "GroupKey": { "type": "array", "description": "Group key to group usage by. Supports both simple (single key) and compound (multiple keys) group keys.\n\nFor simple group keys, provide a single key e.g. `[\"region\"]`.\nFor compound group keys, provide multiple keys e.g. `[\"region\", \"team\"]`.\n\nFor streaming metrics, the keys must be defined as a simple or compound group key on the billable metric.\nFor compound group keys, all keys must match an exact compound group key definition — partial matches are not allowed.\n\nCannot be used together with `group_by`.\n", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "example": [ "region", "team" ] }, "GroupFilter": { "type": "object", "description": "Object mapping group keys to arrays of values to filter on. Only usage matching these filter values will be returned.\nKeys must be present in group_key. Omit a key or use an empty array to include all values for that dimension.\nThe combined number of entries across all value arrays may not exceed 200.\n", "additionalProperties": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "example": { "region": [ "us-east1", "us-west1" ], "team": [ "UI" ] } }, "PagedUsageQueryPayload": { "required": [ "billable_metric_id", "customer_id", "window_size" ], "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "billable_metric_id": { "type": "string", "format": "uuid" }, "window_size": { "type": "string", "description": "A window_size of \"day\" or \"hour\" will return the usage for the specified period segmented into daily or hourly aggregates. A window_size of \"none\" will return a single usage aggregate for the entirety of the specified period.", "enum": [ "hour", "day", "none", "HOUR", "DAY", "NONE", "Hour", "Day", "None" ] }, "starting_on": { "type": "string", "format": "date-time", "description": "Must be aligned to UTC midnight, e.g. `2024-01-01T00:00:00Z`." }, "ending_before": { "type": "string", "format": "date-time", "description": "Must be aligned to UTC midnight and at least one day after `starting_on`." }, "group_by": { "type": "object", "description": "Use group_key and group_filters instead. Use a single group key to group by. Compound group keys are not supported.", "deprecated": true, "required": [ "key" ], "properties": { "key": { "type": "string", "description": "The name of the group_by key to use" }, "values": { "type": "array", "description": "Values of the group_by key to return in the query. Accepts at most 200 values. Omit this if you'd like all values for the key returned.", "minItems": 1, "items": { "type": "string", "minLength": 1 } } } }, "group_key": { "$ref": "#/components/schemas/GroupKey" }, "group_filters": { "$ref": "#/components/schemas/GroupFilter" }, "current_period": { "type": "boolean", "description": "If true, will return the usage for the current billing period. Will return an error if the customer does not have an active plan, or if starting_on and ending_before are specified when this is true." } } }, "GroupedUsageQueryPayload": { "required": [ "billable_metric_id", "customer_id", "window_size" ], "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "billable_metric_id": { "type": "string", "format": "uuid" }, "window_size": { "type": "string", "description": "A window_size of \"day\" or \"hour\" will return the usage for the specified period segmented into daily or hourly aggregates. A window_size of \"none\" will return a single usage aggregate for the entirety of the specified period.", "enum": [ "day", "none" ] }, "starting_on": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "groupings": { "type": "array", "items": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "The name of the group_by key to use" }, "values": { "type": "array", "description": "Values of the group_by key to return in the query. Omit this if you'd like all values for the key returned.", "minItems": 1, "items": { "type": "string", "minLength": 1 } } } } }, "current_period": { "type": "boolean", "description": "If true, will return the usage for the current billing period. Will return an error if the customer is currently uncontracted or starting_on and ending_before are specified when this is true." } } }, "UsageBatchQueryPayload": { "required": [ "window_size", "starting_on", "ending_before" ], "type": "object", "properties": { "customer_ids": { "type": "array", "description": "A list of Metronome customer IDs to fetch usage for. If absent, usage for all customers will be returned.", "items": { "type": "string", "format": "uuid" } }, "billable_metrics": { "type": "array", "description": "A list of billable metrics to fetch usage for. If absent, all billable metrics will be returned.", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "group_by": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "The name of the group_by key to use" }, "values": { "type": "array", "description": "Values of the group_by key to return in the query. If this field is omitted, all available values will be returned, up to a maximum of 200.", "minItems": 1, "maxItems": 200, "items": { "type": "string", "minLength": 1 } } } } } } }, "window_size": { "type": "string", "description": "A window_size of \"day\" or \"hour\" will return the usage for the specified period segmented into daily or hourly aggregates. A window_size of \"none\" will return a single usage aggregate for the entirety of the specified period.", "enum": [ "hour", "day", "none", "HOUR", "DAY", "NONE", "Hour", "Day", "None" ] }, "starting_on": { "type": "string", "format": "date-time", "description": "Must be aligned to UTC midnight, e.g. `2024-01-01T00:00:00Z`." }, "ending_before": { "type": "string", "format": "date-time", "description": "Must be aligned to UTC midnight and at least one day after `starting_on`." } } }, "UsageAggregate": { "required": [ "start_timestamp", "end_timestamp", "value" ], "type": "object", "properties": { "start_timestamp": { "type": "string", "format": "date-time" }, "end_timestamp": { "type": "string", "format": "date-time" }, "value": { "type": "number", "nullable": true }, "groups": { "type": "object", "additionalProperties": { "type": "number", "nullable": true }, "description": "Values will be either a number or null. Null indicates that there were no matches for the group_by value." } } }, "SeatsUsageAggregate": { "required": [ "starting_on", "ending_before", "value" ], "type": "object", "properties": { "starting_on": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "value": { "type": "number", "nullable": true } } }, "PagedUsageAggregate": { "required": [ "starting_on", "ending_before", "group_key", "group_value", "value" ], "type": "object", "properties": { "starting_on": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "group_key": { "type": "string", "nullable": true, "description": "Use `group` instead. The group key for single-key grouping.", "deprecated": true }, "group_value": { "type": "string", "nullable": true, "description": "Use `group` instead. The group value for single-key grouping.", "deprecated": true }, "group": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Map of group key to their value for this usage aggregate.\nFor simple group keys, this should be a single key e.g. `{\"region\": \"US-East\"}`\nFor compound group keys, this should contain the values of each group key that forms the compound e.g. `{\"region\": \"US-East\", \"team\": \"engineering\"}`\n" }, "value": { "type": "number", "nullable": true } } }, "GroupedUsageAggregate": { "required": [ "starting_on", "ending_before", "value" ], "type": "object", "properties": { "starting_on": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "groupings": { "type": "array", "items": { "type": "object", "required": [ "group_key", "group_value" ], "properties": { "group_key": { "type": "string" }, "group_value": { "type": "string" } } } }, "value": { "type": "number", "nullable": true } } }, "UsageBatchAggregate": { "required": [ "customer_id", "billable_metric_id", "billable_metric_name", "start_timestamp", "end_timestamp", "value" ], "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "billable_metric_id": { "type": "string", "format": "uuid" }, "billable_metric_name": { "type": "string" }, "start_timestamp": { "type": "string", "format": "date-time" }, "end_timestamp": { "type": "string", "format": "date-time" }, "value": { "type": "number", "nullable": true }, "groups": { "type": "object", "additionalProperties": { "type": "number", "nullable": true }, "description": "Values will be either a number or null. Null indicates that there were no matches for the group_by value." } } }, "LineItemBreakdown": { "type": "object", "required": [ "name", "cost" ], "properties": { "name": { "type": "string" }, "cost": { "type": "number" }, "group_key": { "type": "string" }, "group_value": { "type": "string", "nullable": true } } }, "CostsPerCreditType": { "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "cost": { "type": "number" }, "line_item_breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/LineItemBreakdown" } } } } }, "Costs": { "required": [ "start_timestamp", "end_timestamp", "credit_types" ], "type": "object", "properties": { "start_timestamp": { "type": "string", "format": "date-time" }, "end_timestamp": { "type": "string", "format": "date-time" }, "credit_types": { "type": "object", "$ref": "#/components/schemas/CostsPerCreditType" } } }, "InvoiceStatus": { "type": "string", "example": "DRAFT, VOID, or FINALIZED" }, "InvoiceType": { "type": "string", "example": "SCHEDULED or USAGE" }, "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" }, "net_payment_terms_days": { "type": "number" }, "credit_type": { "$ref": "#/components/schemas/CreditType" }, "invoice_adjustments": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceAdjustment" } }, "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" }, "subtotal": { "type": "number" }, "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 }, "plan_id": { "type": "string", "format": "uuid" }, "plan_name": { "type": "string" }, "plan_custom_fields": { "$ref": "#/components/schemas/CustomField" }, "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" } } }, "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": "Indicates if the invoice has been or will be sent to the configured customer billing provider. Defaults to `billable`." }, "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." } } }, "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" } } } ] }, "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" }, "breakdown_start_timestamp": { "type": "string", "format": "date-time" }, "breakdown_end_timestamp": { "type": "string", "format": "date-time" } } }, "ExternalInvoiceStatus": { "type": "string", "enum": [ "DRAFT", "FINALIZED", "PAID", "PARTIALLY_PAID", "UNCOLLECTIBLE", "VOID", "DELETED", "PAYMENT_FAILED", "INVALID_REQUEST_ERROR", "SKIPPED", "SENT", "QUEUED" ] }, "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." } } }, "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": { "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." } } }, "InvoiceLineItem": { "required": [ "name", "total", "credit_type", "type" ], "type": "object", "properties": { "name": { "type": "string" }, "group_key": { "type": "string" }, "group_value": { "type": "string", "nullable": true }, "quantity": { "type": "number", "description": "The quantity associated with the line item." }, "total": { "type": "number" }, "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.\n" }, "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`.\n" }, "type": { "type": "string", "description": "The type of line item.\n\n- `scheduled`: Line item is associated with a scheduled charge. View the scheduled_charge_id on the line item.\n- `commit_purchase`: Line item is associated with a payment for a prepaid commit. View the commit_id on the line item.\n- `usage`: Line item is associated with a usage product or composite product. View the product_id on the line item to determine which product.\n- `subscription`: Line item is associated with a subscription. e.g. monthly recurring payment for an in-advance subscription.\n- `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.\n- `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.\n" }, "credit_type": { "$ref": "#/components/schemas/CreditType" }, "sub_line_items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceSubLineItem" } }, "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." }, "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" } } }, "InvoiceSubLineItem": { "required": [ "name", "quantity", "subtotal", "custom_fields" ], "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "number", "description": "the unit price for this charge, present only if the charge is not tiered and the quantity is nonzero" }, "quantity": { "type": "number" }, "subtotal": { "type": "number" }, "charge_id": { "type": "string", "format": "uuid" }, "credit_grant_id": { "type": "string", "format": "uuid" }, "tier_period": { "type": "object", "required": [ "starting_at" ], "description": "when the current tier started and ends (for tiered charges only)", "properties": { "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" } } }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceTier" } }, "custom_fields": { "x-cf-entity": "charge", "$ref": "#/components/schemas/CustomField" }, "start_date": { "type": "string", "format": "date-time", "description": "The start date for the charge (for seats charges only)." }, "end_date": { "type": "string", "format": "date-time", "description": "The end date for the charge (for seats charges only)." } } }, "InvoiceTier": { "required": [ "starting_at", "quantity", "price", "subtotal" ], "type": "object", "properties": { "starting_at": { "type": "number", "description": "at what metric amount this tier begins" }, "quantity": { "type": "number" }, "price": { "type": "number" }, "subtotal": { "type": "number" } } }, "InvoiceAdjustment": { "required": [ "name", "total", "credit_type" ], "type": "object", "properties": { "name": { "type": "string", "example": "Monthly minimum ($1,000)" }, "total": { "type": "number" }, "credit_type": { "$ref": "#/components/schemas/CreditType" }, "credit_grant_id": { "type": "string" }, "credit_grant_custom_fields": { "x-cf-entity": "credit_grant", "$ref": "#/components/schemas/CustomField" } } }, "ProServiceInvoiceLineItem": { "description": "Describes the line item for a professional service charge on an invoice.", "type": "object", "required": [ "professional_service_id" ], "properties": { "professional_service_id": { "type": "string", "format": "uuid" }, "amendment_id": { "type": "string", "format": "uuid", "description": "If the professional_service_id was added on an amendment, this is required." }, "unit_price": { "type": "number", "description": "If specified, this overrides the unit price on the pro service term. Must also provide quantity (but not amount) if providing unit_price." }, "quantity": { "type": "number", "description": "Quantity for the charge. Will be multiplied by unit_price to determine the amount." }, "amount": { "type": "number", "description": "Amount for the term on the new invoice." }, "netsuite_invoice_billing_start": { "type": "string", "format": "date-time", "description": "The start date for the billing period on the invoice." }, "netsuite_invoice_billing_end": { "type": "string", "format": "date-time", "description": "The end date for the billing period on the invoice." }, "metadata": { "type": "string", "description": "For client use." } } }, "BillingProviderInvoice": { "required": [ "invoice_id", "billing_provider" ], "type": "object", "properties": { "invoice_id": { "type": "string", "format": "uuid", "description": "The invoice id in Metronome" }, "billing_provider": { "$ref": "#/components/schemas/BillingProviderType" }, "billing_provider_invoice_id": { "type": "string", "description": "The invoice id in the billing provider's system. Optional if status is INVALID_REQUEST_ERROR or SKIPPED and billing_provider_error is present." }, "billing_provider_sales_order_id": { "type": "string", "description": "The sales order id in the billing provider's system. Optional if status is INVALID_REQUEST_ERROR or SKIPPED and billing_provider_error is present." }, "external_status": { "$ref": "#/components/schemas/ExternalInvoiceStatus", "description": "The status of the billing provider invoice. Defaults to SENT if not provided." }, "issued_at": { "type": "string", "format": "date-time" }, "billing_provider_error": { "type": "string", "description": "Optional message describing the status of the invoice. Cannot be passed with a billing_provider_invoice_id or billing_provider_sales_order_id." }, "workato_job_id": { "type": "string", "description": "Optional workato job id responsible for creating this billing provider invoice" } } }, "StripeCollectionMethod": { "type": "string", "description": "The collection method for the customer's invoices.", "enum": [ "charge_automatically", "send_invoice" ] }, "AwsExpirationDate": { "type": "string", "format": "date-time", "description": "Contract expiration date for the customer. The expected format is RFC 3339 and can be retrieved from [AWS's GetEntitlements API](https://docs.aws.amazon.com/marketplaceentitlement/latest/APIReference/API_GetEntitlements.html)." }, "AzureSubscriptionStatus": { "type": "string", "enum": [ "Subscribed", "Unsubscribed", "Suspended", "PendingFulfillmentStart" ] }, "AzureTermDate": { "type": "string", "format": "date-time", "description": "Subscription term start/end date for the customer. The expected format is RFC 3339 and can be retrieved from [Azure's Get Subscription API](https://learn.microsoft.com/en-us/partner-center/marketplace/partner-center-portal/pc-saas-fulfillment-subscription-api#get-subscription)." }, "AwsRegion": { "type": "string", "enum": [ "af-south-1", "ap-east-1", "ap-northeast-1", "ap-northeast-2", "ap-northeast-3", "ap-south-1", "ap-southeast-1", "ap-southeast-2", "ca-central-1", "cn-north-1", "cn-northwest-1", "eu-central-1", "eu-north-1", "eu-south-1", "eu-west-1", "eu-west-2", "eu-west-3", "me-south-1", "sa-east-1", "us-east-1", "us-east-2", "us-gov-east-1", "us-gov-west-1", "us-west-1", "us-west-2" ] }, "ChargeType": { "type": "string", "enum": [ "usage", "fixed", "composite", "minimum", "seat" ] }, "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\n", "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\n", "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." } } }, "IntegrationCloudwatchLogPayload": { "required": [ "service_name", "metric_name", "dimensions" ], "type": "object", "properties": { "service_name": { "type": "string" }, "metric_name": { "type": "string" }, "dimensions": { "type": "array", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "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.\n" }, "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`.\n" }, "skip_zero_qty_line_items": { "type": "boolean", "default": false, "description": "When `true`, line items with zero quantity are excluded from the response." } } }, "ManagedEntity": { "type": "string", "enum": [ "alert", "billable_metric", "charge", "credit_grant", "customer_plan", "customer", "discount", "invoice", "plan", "professional_service", "product", "scheduled_charge", "subscription", "package_commit", "package_credit", "package_subscription", "package_scheduled_charge" ], "x-mint-enum": { "professional_service": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] } }, "ManagedVendor": { "type": "string", "enum": [ "anrok", "avalara", "chargebee", "netsuite", "stripe" ], "x-mint-enum": { "anrok": [ "ff:stripe-auto-charge" ], "avalara": [ "ff:stripe-auto-charge" ] } }, "CustomField": { "type": "object", "description": "Custom fields to be added eg. { \"key1\": \"value1\", \"key2\": \"value2\" }", "additionalProperties": { "type": "string" } }, "Tags": { "type": "array", "items": { "type": "string" } }, "CustomFieldMapping": { "type": "object", "required": [ "entity", "key", "vendor", "vendor_entity", "vendor_field" ], "properties": { "entity": { "$ref": "#/components/schemas/ManagedEntity" }, "key": { "type": "string" }, "vendor": { "$ref": "#/components/schemas/ManagedVendor" }, "vendor_entity": { "type": "string" }, "vendor_field": { "type": "string" } } }, "AuditLog": { "type": "object", "required": [ "id", "timestamp", "request" ], "properties": { "id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "actor": { "$ref": "#/components/schemas/Actor" }, "request": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "ip": { "type": "string" }, "user_agent": { "type": "string" } } }, "resource_type": { "type": "string" }, "resource_id": { "type": "string" }, "action": { "type": "string" }, "status": { "type": "string", "enum": [ "success", "failure", "pending" ] }, "description": { "type": "string" } } }, "Actor": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" } } }, "Service": { "type": "object", "required": [ "name", "usage", "ips" ], "properties": { "name": { "type": "string" }, "usage": { "type": "string", "enum": [ "makes_connections_from", "accepts_connections_at" ] }, "ips": { "type": "array", "items": { "type": "string" } } } }, "ProductListItemState": { "type": "object", "required": [ "name", "created_at", "created_by" ], "properties": { "name": { "type": "string" }, "starting_at": { "type": "string", "format": "date-time" }, "netsuite_internal_item_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." }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "netsuite_overage_item_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." }, "billable_metric_id": { "type": "string" }, "composite_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "quantity_conversion": { "$ref": "#/components/schemas/QuantityConversion" }, "quantity_rounding": { "$ref": "#/components/schemas/QuantityRounding" }, "composite_tags": { "type": "array", "items": { "type": "string" } }, "is_refundable": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "boolean", "description": "This field's availability is dependent on your client's configuration." }, "tags": { "type": "array", "items": { "type": "string" } }, "composite_scope": { "type": "string", "enum": [ "CUSTOMER", "CONTRACT" ], "x-mint": { "groups": [ "ff:composite-support-charge-m1-enabled" ] }, "x-stainless-skip": true, "description": "Determines what spend contributes to calculating this charge." }, "exclude_free_usage": { "type": "boolean" }, "include_composite_spend": { "type": "boolean", "description": "Only for composite products. If true, allows a composite to incorporate spend from other composite products. Defaults to false" }, "pricing_group_key": { "$ref": "#/components/schemas/PricingGroupKey" }, "presentation_group_key": { "$ref": "#/components/schemas/PresentationGroupKey" } } }, "ListProductsPayload": { "type": "object", "properties": { "archive_filter": { "type": "string", "enum": [ "ARCHIVED", "NOT_ARCHIVED", "ALL" ], "description": "Filter options for the product list. If not provided, defaults to not archived." } } }, "ProductListItem": { "type": "object", "required": [ "id", "type", "initial", "current", "updates" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "USAGE", "SUBSCRIPTION", "COMPOSITE", "FIXED", "PRO_SERVICE" ] }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "initial": { "$ref": "#/components/schemas/ProductListItemState" }, "current": { "$ref": "#/components/schemas/ProductListItemState" }, "updates": { "type": "array", "items": { "$ref": "#/components/schemas/ProductListItemUpdate" } }, "custom_fields": { "x-cf-entity": "contract_product", "$ref": "#/components/schemas/CustomField" } } }, "CreateProductListItemPayload": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "description": "displayed on invoices" }, "type": { "type": "string", "enum": [ "FIXED", "fixed", "USAGE", "usage", "COMPOSITE", "composite", "SUBSCRIPTION", "subscription", "PROFESSIONAL_SERVICE", "professional_service", "PRO_SERVICE", "pro_service" ], "x-mint-enum": { "PROFESSIONAL_SERVICE": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ], "professional_service": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ], "PRO_SERVICE": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ], "pro_service": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] } }, "netsuite_internal_item_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." }, "netsuite_overage_item_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." }, "billable_metric_id": { "type": "string", "format": "uuid", "description": "Required for USAGE products" }, "sql_breakdown_granularity": { "type": "string", "enum": [ "HOUR", "hour", "SERVICE_PERIOD", "service_period" ], "description": "Defines the breakdown behavior when calculating usage from SQL Billable Metrics. If set to 'service_period' (default), the usage will be evaluated once for all events the invoice service period and the usage will be applied at the last instant of the invoice. If set to 'hour', it will be broken down and evaluated for each hour. For most use cases, 'hour' is recommended. The setting has no effect for Streaming Billable Metrics." }, "composite_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Required for COMPOSITE products" }, "composite_tags": { "type": "array", "items": { "type": "string" }, "description": "Required for COMPOSITE products" }, "is_refundable": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "boolean", "description": "This field's availability is dependent on your client's configuration. Defaults to true." }, "composite_scope": { "type": "string", "enum": [ "customer", "CUSTOMER", "contract", "CONTRACT" ], "description": "Determines what spend contributes to calculating this charge. When composite scope is contract, calculates composite charge based on applicable spend per contract. When composite scope is customer, calculates composite charge based on applicable spend across all customer contracts. Defaults to contract.", "x-mint": { "groups": [ "ff:composite-support-charge-m1-enabled" ] }, "x-stainless-skip": true }, "exclude_free_usage": { "type": "boolean", "description": "Beta feature only available for composite products. If true, products with $0 will not be included when computing composite usage. Defaults to false" }, "include_composite_spend": { "type": "boolean", "description": "Only for composite products. If true, allows a composite to incorporate spend from other composite products. Defaults to false" }, "tags": { "type": "array", "items": { "type": "string" } }, "pricing_group_key": { "$ref": "#/components/schemas/PricingGroupKey" }, "presentation_group_key": { "$ref": "#/components/schemas/PresentationGroupKey" }, "quantity_conversion": { "$ref": "#/components/schemas/QuantityConversion" }, "quantity_rounding": { "$ref": "#/components/schemas/QuantityRounding" }, "custom_fields": { "$ref": "#/components/schemas/CustomField" } } }, "ProductListItemUpdate": { "type": "object", "required": [ "created_at", "created_by" ], "properties": { "name": { "type": "string" }, "starting_at": { "type": "string", "format": "date-time" }, "is_refundable": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "billable_metric_id": { "type": "string", "format": "uuid" }, "quantity_conversion": { "$ref": "#/components/schemas/QuantityConversion" }, "quantity_rounding": { "$ref": "#/components/schemas/QuantityRounding" }, "netsuite_internal_item_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." }, "netsuite_overage_item_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." }, "composite_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "composite_tags": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "exclude_free_usage": { "type": "boolean" }, "include_composite_spend": { "type": "boolean", "description": "Only for composite products. If true, allows a composite to incorporate spend from other composite products. Defaults to false" }, "pricing_group_key": { "$ref": "#/components/schemas/PricingGroupKey" }, "presentation_group_key": { "$ref": "#/components/schemas/PresentationGroupKey" } } }, "UpdateProductListItemPayload": { "type": "object", "required": [ "product_id", "starting_at" ], "properties": { "product_id": { "type": "string", "format": "uuid", "description": "ID of the product to update" }, "name": { "type": "string", "description": "displayed on invoices. If not provided, defaults to product's current name." }, "starting_at": { "type": "string", "format": "date-time", "description": "Timestamp representing when the update should go into effect. It must be on an hour boundary (e.g. 1:00, not 1:30)." }, "is_refundable": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "boolean", "description": "Defaults to product's current refundability status. This field's availability is dependent on your client's configuration." }, "exclude_free_usage": { "type": "boolean", "description": "Beta feature only available for composite products. If true, products with $0 will not be included when computing composite usage. Defaults to false" }, "include_composite_spend": { "type": "boolean", "description": "Only for composite products. If true, allows a composite to incorporate spend from other composite products. Defaults to false" }, "billable_metric_id": { "type": "string", "format": "uuid", "description": "Available for USAGE products only. If not provided, defaults to product's current billable metric." }, "sql_breakdown_granularity": { "type": "string", "enum": [ "HOUR", "hour", "SERVICE_PERIOD", "service_period" ], "description": "Defines the breakdown behavior when calculating usage from SQL Billable Metrics. If set to 'service_period' (default), the usage will be evaluated once for all events the invoice service period and the usage will be applied at the last instant of the invoice. If set to 'hour', it will be broken down and evaluated for each hour. For most use cases, 'hour' is recommended. The setting has no effect for Streaming Billable Metrics." }, "netsuite_internal_item_id": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "string", "description": "If not provided, defaults to product's current netsuite_internal_item_id. This field's availability is dependent on your client's configuration." }, "netsuite_overage_item_id": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "string", "description": "Available for USAGE and COMPOSITE products only. If not provided, defaults to product's current netsuite_overage_item_id. This field's availability is dependent on your client's configuration." }, "composite_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Available for COMPOSITE products only. If not provided, defaults to product's current composite_product_ids." }, "quantity_conversion": { "$ref": "#/components/schemas/QuantityConversion" }, "quantity_rounding": { "$ref": "#/components/schemas/QuantityRounding" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "If not provided, defaults to product's current tags" }, "composite_tags": { "type": "array", "items": { "type": "string" }, "description": "Available for COMPOSITE products only. If not provided, defaults to product's current composite_tags." }, "pricing_group_key": { "$ref": "#/components/schemas/PricingGroupKey" }, "presentation_group_key": { "$ref": "#/components/schemas/PresentationGroupKey" } } }, "ArchiveProductListItemPayload": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "string", "format": "uuid", "description": "ID of the product to be archived" } } }, "RateCard": { "type": "object", "required": [ "id", "name", "created_at", "created_by" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "description": { "type": "string" }, "fiat_credit_type": { "$ref": "#/components/schemas/CreditType" }, "credit_type_conversions": { "type": "array", "items": { "$ref": "#/components/schemas/CreditTypeConversion" } }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/RateCardAlias" } }, "custom_fields": { "x-cf-entity": "rate_card", "$ref": "#/components/schemas/CustomField" } } }, "RateCardAlias": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" } } }, "PackageAlias": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" } } }, "QuantityConversion": { "type": "object", "nullable": true, "description": "Optional. Only valid for USAGE products. If provided, the quantity will be converted using the provided conversion factor and operation. For example, if the operation is \"multiply\" and the conversion factor is 100, then the quantity will be multiplied by 100. This can be used in cases where data is sent in one unit and priced in another. For example, data could be sent in MB and priced in GB. In this case, the conversion factor would be 1024 and the operation would be \"divide\".", "required": [ "conversion_factor", "operation" ], "properties": { "name": { "type": "string", "description": "Optional name for this conversion." }, "conversion_factor": { "type": "number", "description": "The factor to multiply or divide the quantity by." }, "operation": { "type": "string", "enum": [ "multiply", "divide", "MULTIPLY", "DIVIDE" ], "description": "The operation to perform on the quantity" } } }, "QuantityRounding": { "type": "object", "nullable": true, "description": "Optional. Only valid for USAGE products. If provided, the quantity will be rounded using the provided rounding method and decimal places. For example, if the method is \"round up\" and the decimal places is 0, then the quantity will be rounded up to the nearest integer.", "required": [ "rounding_method", "decimal_places" ], "properties": { "rounding_method": { "type": "string", "enum": [ "round_up", "round_down", "round_half_up", "ROUND_UP", "ROUND_DOWN", "ROUND_HALF_UP" ] }, "decimal_places": { "type": "number", "minimum": 0 } } }, "ProrationRoundingConfig": { "type": "object", "required": [ "rounding_method", "decimal_places" ], "properties": { "rounding_method": { "type": "string", "enum": [ "HALF_UP", "FLOOR", "CEILING", "half_up", "floor", "ceiling" ] }, "decimal_places": { "type": "number", "minimum": -5, "maximum": 5, "description": "Number of decimal places to round to. Applied directly to the stored monetary representation. Negative values round to powers of 10 (e.g., -2 rounds to nearest 100 in the stored unit. For USD, this means rounding to the nearest dollar)." } } }, "NullableRateCardEntry": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "uuid" }, "product_id": { "type": "string", "format": "uuid" }, "rate_type": { "type": "string", "enum": [ "FLAT", "PERCENTAGE", "SUBSCRIPTION", "CUSTOM", "TIERED", "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" ], "SUBSCRIPTION": [ "ff:legacy-subscriptions-enabled" ], "subscription": [ "ff:legacy-subscriptions-enabled" ], "TIERED_PERCENTAGE": [ "ff:support-charge-ga" ], "tiered_percentage": [ "ff:support-charge-ga" ] } }, "price": { "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": "number" }, "credit_type": { "$ref": "#/components/schemas/CreditType" }, "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 }, "starting_at": { "type": "string", "format": "date-time" }, "entitled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "ending_before": { "type": "string", "format": "date-time" }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/Tier" } } } }, "Tier": { "type": "object", "required": [ "price" ], "properties": { "size": { "type": "number" }, "price": { "type": "number" } } }, "MinimumConfig": { "type": "object", "description": "Only set for TIERED_PERCENTAGE or PERCENTAGE rate_type. Any commit-specific overrides will not apply if there is a minimum set on the rate/applied override.", "required": [ "minimum" ], "properties": { "minimum": { "type": "number" } } }, "CommitRate": { "type": "object", "description": "A distinct rate on the rate card. You can choose to use this rate rather than list rate when consuming a credit or commit.", "required": [ "rate_type" ], "properties": { "rate_type": { "type": "string", "enum": [ "FLAT", "flat", "PERCENTAGE", "percentage", "SUBSCRIPTION", "subscription", "TIERED", "tiered", "TIERED_PERCENTAGE", "tiered_percentage", "CUSTOM", "custom" ], "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": [ "client_id:11db091c-975b-4908-9f67-b1ceb126acdf" ], "subscription": [ "client_id:11db091c-975b-4908-9f67-b1ceb126acdf" ], "percentage": [ "client_id:11db091c-975b-4908-9f67-b1ceb126acdf" ], "PERCENTAGE": [ "client_id:11db091c-975b-4908-9f67-b1ceb126acdf" ], "TIERED_PERCENTAGE": [ "ff:support-charge-ga" ], "tiered_percentage": [ "ff:support-charge-ga" ] } }, "price": { "type": "number", "description": "Commit rate 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." }, "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" } } }, "RateCardEntry": { "type": "object", "required": [ "id", "product_id", "rate_type", "starting_at", "entitled", "created_at", "created_by" ], "properties": { "id": { "type": "string", "format": "uuid" }, "product_id": { "type": "string", "format": "uuid" }, "rate_type": { "type": "string", "enum": [ "FLAT", "PERCENTAGE", "SUBSCRIPTION", "CUSTOM", "TIERED", "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" ] } }, "price": { "type": "number" }, "credit_type": { "$ref": "#/components/schemas/CreditType" }, "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 }, "quantity": { "x-mint": { "groups": [ "ff:legacy-subscriptions-enabled" ] }, "type": "number" }, "is_prorated": { "x-mint": { "groups": [ "ff:legacy-subscriptions-enabled" ] }, "type": "boolean" }, "starting_at": { "type": "string", "format": "date-time" }, "entitled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "ending_before": { "type": "string", "format": "date-time" }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/Tier" } }, "commit_rate": { "$ref": "#/components/schemas/CommitRate" }, "minimum_config": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:support-charge-ga" ] }, "$ref": "#/components/schemas/MinimumConfig" } } }, "CreateRateCardPayload": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Used only in UI/API. It is not exposed to end customers." }, "description": { "type": "string" }, "fiat_credit_type_id": { "type": "string", "format": "uuid", "example": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "description": "The Metronome ID of the credit type to associate with the rate card, defaults to USD (cents) if not passed." }, "credit_type_conversions": { "type": "array", "items": { "$ref": "#/components/schemas/CreditTypeConversionInput" }, "description": "Required when using custom pricing units in rates." }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/RateCardAlias" }, "description": "Reference this alias when creating a contract. If the same alias is assigned to multiple rate cards, it will reference the rate card to which it was most recently assigned. It is not exposed to end customers." }, "custom_fields": { "$ref": "#/components/schemas/CustomField" } } }, "UpdateRateCardPayload": { "type": "object", "required": [ "rate_card_id" ], "properties": { "rate_card_id": { "type": "string", "format": "uuid", "description": "ID of the rate card to update" }, "name": { "type": "string", "description": "Used only in UI/API. It is not exposed to end customers." }, "description": { "type": "string" }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/RateCardAlias" }, "description": "Reference this alias when creating a contract. If the same alias is assigned to multiple rate cards, it will reference the rate card to which it was most recently assigned. It is not exposed to end customers." }, "add_credit_type_conversions": { "type": "array", "items": { "$ref": "#/components/schemas/CreditTypeConversionInput" }, "description": "Add credit type conversions for using custom pricing units in rates. Existing conversions cannot be modified." } } }, "AddRatePayload": { "type": "object", "required": [ "rate_card_id", "product_id", "starting_at", "entitled", "rate_type" ], "properties": { "rate_card_id": { "type": "string", "format": "uuid", "description": "ID of the rate card to update" }, "product_id": { "type": "string", "format": "uuid", "description": "ID of the product to add a rate for" }, "pricing_group_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional. List of pricing group key value pairs which will be used to calculate the price." }, "billing_frequency": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUAL", "WEEKLY", "monthly", "quarterly", "annual", "weekly" ], "description": "Optional. Frequency to bill subscriptions with. Required for subscription type products with Flat rate." }, "starting_at": { "type": "string", "format": "date-time", "description": "inclusive effective date" }, "ending_before": { "type": "string", "format": "date-time", "description": "exclusive end date" }, "entitled": { "type": "boolean" }, "rate_type": { "type": "string", "enum": [ "FLAT", "flat", "PERCENTAGE", "percentage", "SUBSCRIPTION", "subscription", "TIERED", "tiered", "TIERED_PERCENTAGE", "tiered_percentage", "CUSTOM", "custom" ], "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" ] } }, "price": { "type": "number", "description": "Default price. For FLAT and SUBSCRIPTION 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." }, "credit_type_id": { "type": "string", "format": "uuid", "example": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "description": "The Metronome ID of the credit type to associate with price, defaults to USD (cents) if not passed. Used by all rate_types except type PERCENTAGE. PERCENTAGE rates use the credit type of associated rates." }, "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" }, "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:9c7e2b27-9b4c-4b76-9df7-f9cb05665a6a" ] }, "type": "object", "additionalProperties": true, "description": "Only set for CUSTOM rate_type. This field is interpreted by custom rate processors." }, "commit_rate": { "$ref": "#/components/schemas/CommitRate" } } }, "RatePayload": { "type": "object", "required": [ "product_id", "starting_at", "entitled", "rate_type" ], "properties": { "product_id": { "type": "string", "format": "uuid", "description": "ID of the product to add a rate for" }, "pricing_group_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional. List of pricing group key value pairs which will be used to calculate the price." }, "billing_frequency": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUAL", "WEEKLY", "monthly", "quarterly", "annual", "weekly" ], "description": "Optional. Frequency to bill subscriptions with. Required for subscription type products with Flat rate." }, "starting_at": { "type": "string", "format": "date-time", "description": "inclusive effective date" }, "ending_before": { "type": "string", "format": "date-time", "description": "exclusive end date" }, "entitled": { "type": "boolean" }, "rate_type": { "type": "string", "enum": [ "FLAT", "flat", "PERCENTAGE", "percentage", "SUBSCRIPTION", "subscription", "TIERED", "tiered", "TIERED_PERCENTAGE", "tiered_percentage", "CUSTOM", "custom" ], "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" ] } }, "price": { "type": "number", "description": "Default price. For FLAT and SUBSCRIPTION 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." }, "credit_type_id": { "type": "string", "format": "uuid", "example": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "description": "\"The Metronome ID of the credit type to associate with price, defaults to USD (cents) if not passed. Used by all rate_types except type PERCENTAGE. PERCENTAGE rates use the credit type of associated rates.\"" }, "quantity": { "type": "number", "description": "Default quantity. For SUBSCRIPTION rate_type, this must be >=0." }, "is_prorated": { "type": "boolean", "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" }, "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:9c7e2b27-9b4c-4b76-9df7-f9cb05665a6a" ] }, "type": "object", "additionalProperties": true, "description": "Only set for CUSTOM rate_type. This field is interpreted by custom rate processors." }, "commit_rate": { "$ref": "#/components/schemas/CommitRate" } } }, "SetRateCardProductsOrderPayload": { "type": "object", "required": [ "rate_card_id", "product_order" ], "properties": { "rate_card_id": { "type": "string", "format": "uuid", "description": "ID of the rate card to update" }, "product_order": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "MoveRateCardProductsPayload": { "type": "object", "required": [ "rate_card_id", "product_moves" ], "properties": { "rate_card_id": { "type": "string", "format": "uuid", "description": "ID of the rate card to update" }, "product_moves": { "type": "array", "items": { "type": "object", "required": [ "product_id", "position" ], "properties": { "product_id": { "type": "string", "format": "uuid", "description": "ID of the product to move" }, "position": { "type": "number", "description": "0-based index of the new position of the product", "minimum": 0 } } } } } }, "GetContractRateSchedulePayload": { "type": "object", "required": [ "customer_id", "contract_id" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer for whose contract to get the rate schedule for." }, "contract_id": { "type": "string", "format": "uuid", "description": "ID of the contract to get the rate schedule for." }, "at": { "type": "string", "format": "date-time", "description": "optional timestamp which overlaps with the returned rate schedule segments. When not specified, the current timestamp will be used." }, "selectors": { "description": "List of rate selectors, rates matching ANY of the selectors will be included in the response. Passing no selectors will result in all rates being returned.", "type": "array", "items": { "$ref": "#/components/schemas/RateSelectorWithProductTags" } } } }, "GetRateSchedulePayload": { "type": "object", "required": [ "rate_card_id", "starting_at" ], "properties": { "rate_card_id": { "type": "string", "format": "uuid", "description": "ID of the rate card to get the schedule for" }, "starting_at": { "type": "string", "format": "date-time", "description": "inclusive starting point for the rates schedule" }, "ending_before": { "type": "string", "format": "date-time", "description": "optional exclusive end date for the rates schedule. When not specified rates will show all future schedule segments." }, "selectors": { "description": "List of rate selectors, rates matching ANY of the selector will be included in the response Passing no selectors will result in all rates being returned.", "type": "array", "items": { "$ref": "#/components/schemas/RateSelector" } } } }, "GetRatesPayload": { "type": "object", "required": [ "rate_card_id", "at" ], "properties": { "rate_card_id": { "type": "string", "format": "uuid", "description": "ID of the rate card to get the schedule for" }, "at": { "type": "string", "format": "date-time", "description": "inclusive starting point for the rates schedule" }, "selectors": { "description": "List of rate selectors, rates matching ANY of the selector will be included in the response Passing no selectors will result in all rates being returned.", "type": "array", "items": { "$ref": "#/components/schemas/RateSelectorWithProductTags" } } } }, "RateSelector": { "type": "object", "properties": { "billing_frequency": { "description": "Subscription rates matching the billing frequency will be included in the response.", "type": "string", "enum": [ "MONTHLY", "Monthly", "monthly", "QUARTERLY", "Quarterly", "quarterly", "ANNUAL", "Annual", "annual", "WEEKLY", "Weekly", "weekly" ] }, "product_id": { "description": "Rates matching the product id will be included in the response.", "type": "string", "format": "uuid" }, "pricing_group_values": { "description": "List of pricing group key value pairs, rates matching all of the key / value pairs will be included in the response.", "type": "object", "additionalProperties": { "type": "string" } }, "partial_pricing_group_values": { "description": "List of pricing group key value pairs, rates containing the matching key / value pairs will be included in the response.", "type": "object", "additionalProperties": { "type": "string" } } } }, "RateSelectorWithProductTags": { "type": "object", "properties": { "billing_frequency": { "description": "Subscription rates matching the billing frequency will be included in the response.", "type": "string", "enum": [ "MONTHLY", "Monthly", "monthly", "QUARTERLY", "Quarterly", "quarterly", "ANNUAL", "Annual", "annual", "WEEKLY", "Weekly", "weekly" ] }, "product_id": { "description": "Rates matching the product id will be included in the response.", "type": "string", "format": "uuid" }, "product_tags": { "description": "List of product tags, rates matching any of the tags will be included in the response.", "type": "array", "items": { "type": "string" } }, "pricing_group_values": { "description": "List of pricing group key value pairs, rates matching all of the key / value pairs will be included in the response.", "type": "object", "additionalProperties": { "type": "string" } }, "partial_pricing_group_values": { "description": "List of pricing group key value pairs, rates containing the matching key / value pairs will be included in the response.", "type": "object", "additionalProperties": { "type": "string" } } } }, "RateSchedule": { "type": "object", "required": [ "product_id", "product_name", "product_tags", "product_custom_fields", "starting_at", "entitled", "rate" ], "properties": { "product_id": { "type": "string", "format": "uuid" }, "product_name": { "type": "string" }, "product_tags": { "type": "array", "items": { "type": "string" } }, "product_custom_fields": { "$ref": "#/components/schemas/CustomField" }, "pricing_group_values": { "type": "object", "additionalProperties": { "type": "string" } }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "entitled": { "type": "boolean" }, "rate": { "$ref": "#/components/schemas/Rate" }, "commit_rate": { "$ref": "#/components/schemas/CommitRate" }, "billing_frequency": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUAL", "WEEKLY" ] } } }, "ContractRateSchedule": { "type": "object", "required": [ "rate_card_id", "product_id", "product_name", "product_tags", "product_custom_fields", "starting_at", "entitled", "list_rate" ], "properties": { "rate_card_id": { "type": "string", "format": "uuid" }, "product_id": { "type": "string", "format": "uuid" }, "product_name": { "type": "string" }, "product_tags": { "type": "array", "items": { "type": "string" } }, "product_custom_fields": { "$ref": "#/components/schemas/CustomField" }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "entitled": { "type": "boolean" }, "pricing_group_values": { "type": "object", "additionalProperties": { "type": "string" } }, "list_rate": { "$ref": "#/components/schemas/Rate" }, "override_rate": { "$ref": "#/components/schemas/Rate" }, "commit_rate": { "$ref": "#/components/schemas/CommitRate" }, "billing_frequency": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUAL", "WEEKLY" ] } } }, "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" } } }, "RateWithCommitRate": { "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." }, "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" }, "commit_rate": { "$ref": "#/components/schemas/CommitRate" } } }, "OverrideSpecifierInput": { "type": "object", "properties": { "commit_ids": { "type": "array", "items": { "type": "string" }, "description": "Can only be used for commit specific overrides. Must be used in conjunction with one of `product_id`, `product_tags`, `pricing_group_values`, or `presentation_group_values`. If provided, the override will only apply to the specified commits. If not provided, the override will apply to all commits." }, "recurring_commit_ids": { "type": "array", "items": { "type": "string" }, "description": "Can only be used for commit specific overrides. Must be used in conjunction with one of `product_id`, `product_tags`, `pricing_group_values`, or `presentation_group_values`. If provided, the override will only apply to commits created by the specified recurring commit ids." }, "any_commit_or_credit_ids": { "type": "array", "items": { "type": "string" }, "description": "Can only be used for commit specific overrides. Must be used in conjunction with one of `product_id`, `product_tags`, `pricing_group_values`, or `presentation_group_values`. Must be used instead of both `commit_ids` and `recurring_commit_ids` If provided, the override will apply to any specified commit, credit, recurring commit or recurring credit IDs." }, "product_id": { "type": "string", "format": "uuid", "description": "If provided, the override will only apply to the product with the specified ID." }, "product_tags": { "type": "array", "items": { "type": "string" }, "description": "If provided, the override will only apply to products with all the specified tags." }, "pricing_group_values": { "type": "object", "description": "A map of pricing group names to values. The override will only apply to products with the specified pricing group values.", "additionalProperties": { "type": "string" } }, "presentation_group_values": { "type": "object", "description": "A map of group names to values. The override will only apply to line items with the specified presentation group values.", "additionalProperties": { "type": "string" } }, "billing_frequency": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUAL", "monthly", "quarterly", "annual", "WEEKLY", "weekly" ] }, "exclude": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:exclude-specifiers-ga" ] }, "type": "array", "description": "If provided, the specifier will not apply to product usage that matches the inclusion criteria and any of the excluding values.", "items": { "$ref": "#/components/schemas/ExcludeSpecifier" } } } }, "OverrideSpecifier": { "type": "object", "properties": { "product_id": { "type": "string", "format": "uuid" }, "product_tags": { "type": "array", "items": { "type": "string" } }, "pricing_group_values": { "type": "object", "additionalProperties": { "type": "string" } }, "presentation_group_values": { "type": "object", "additionalProperties": { "type": "string", "nullable": true } }, "commit_ids": { "type": "array", "items": { "type": "string" } }, "recurring_commit_ids": { "type": "array", "items": { "type": "string" } }, "any_commit_or_credit_ids": { "type": "array", "items": { "type": "string" } }, "billing_frequency": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUAL", "WEEKLY", "monthly", "quarterly", "annual", "weekly" ] }, "exclude": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:exclude-specifiers-ga" ] }, "type": "array", "description": "If provided, the specifier will not apply to product usage that matches the inclusion criteria and any of the excluding values.", "items": { "$ref": "#/components/schemas/ExcludeSpecifier" } } } }, "OverwriteRate": { "type": "object", "required": [ "rate_type" ], "properties": { "rate_type": { "type": "string", "enum": [ "FLAT", "flat", "PERCENTAGE", "percentage", "SUBSCRIPTION", "subscription", "TIERED", "tiered", "TIERED_PERCENTAGE", "tiered_percentage", "CUSTOM", "custom" ], "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" ] } }, "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." }, "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" }, "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." }, "credit_type": { "$ref": "#/components/schemas/CreditType" } } }, "OverwriteRateInput": { "type": "object", "required": [ "rate_type" ], "properties": { "rate_type": { "type": "string", "enum": [ "FLAT", "flat", "PERCENTAGE", "percentage", "SUBSCRIPTION", "subscription", "TIERED", "tiered", "TIERED_PERCENTAGE", "tiered_percentage", "CUSTOM", "custom" ], "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" ] } }, "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." }, "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" }, "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." }, "credit_type_id": { "type": "string", "format": "uuid" } } }, "OverrideTier": { "type": "object", "required": [ "multiplier" ], "properties": { "size": { "type": "number" }, "multiplier": { "type": "number" } } }, "OverrideTierInput": { "type": "object", "required": [ "multiplier" ], "properties": { "size": { "type": "number" }, "multiplier": { "type": "number" } } }, "ContractWithoutAmendments": { "type": "object", "required": [ "starting_at", "commits", "overrides", "scheduled_charges", "transitions", "created_at", "created_by", "usage_statement_schedule" ], "properties": { "name": { "type": "string" }, "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." }, "rate_card_id": { "type": "string", "format": "uuid" }, "starting_at": { "type": "string", "format": "date-time" }, "commits": { "type": "array", "items": { "$ref": "#/components/schemas/Commit" } }, "credits": { "type": "array", "items": { "$ref": "#/components/schemas/Credit" } }, "recurring_commits": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringCommit" } }, "recurring_credits": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringCredit" } }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/Override" } }, "discounts": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's", "items": { "$ref": "#/components/schemas/Discount" } }, "professional_services": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/ProService" } }, "scheduled_charges": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledCharge" } }, "scheduled_charges_on_usage_invoices": { "$ref": "#/components/schemas/ScheduledChargesOnUsageInvoices" }, "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/ContractTransition" } }, "reseller_royalties": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/ResellerRoyalty" } }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "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." }, "net_payment_terms_days": { "type": "number" }, "ending_before": { "type": "string", "format": "date-time" }, "total_contract_value": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "number", "description": "This field's availability is dependent on your client's configuration." }, "usage_filter": { "$ref": "#/components/schemas/UsageFilter" }, "usage_statement_schedule": { "$ref": "#/components/schemas/UsageStatementSchedule" }, "spend_threshold_configuration": { "$ref": "#/components/schemas/SpendThresholdConfiguration" }, "prepaid_balance_threshold_configuration": { "$ref": "#/components/schemas/PrepaidBalanceThresholdConfiguration" }, "spend_trackers": { "x-mint": { "groups": [ "ff:tb-spend-trackers" ] }, "type": "array", "description": "Spend trackers attached to this contract.", "items": { "type": "object", "required": [ "alias", "credit_type_id", "reset_frequency", "applicable_spend_specifiers" ], "properties": { "alias": { "type": "string", "description": "Human-readable identifier, unique per contract." }, "credit_type_id": { "type": "string", "format": "uuid" }, "reset_frequency": { "type": "string", "enum": [ "BILLING_PERIOD" ] }, "applicable_spend_specifiers": { "type": "array", "items": { "type": "object", "required": [ "spend_type", "sources" ], "properties": { "spend_type": { "type": "string", "enum": [ "COMMIT_PURCHASE" ] }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "THRESHOLD_RECHARGE", "MANUAL" ] } }, "discounted": { "type": "string", "enum": [ "ANY", "DISCOUNTED_ONLY", "UNDISCOUNTED_ONLY" ] } } } }, "accumulated_spend": { "type": "object", "required": [ "amount", "period_starting_at", "period_ending_before" ], "properties": { "amount": { "type": "number" }, "period_starting_at": { "type": "string", "format": "date-time" }, "period_ending_before": { "type": "string", "format": "date-time" } } } } } }, "hierarchy_configuration": { "$ref": "#/components/schemas/HierarchyConfiguration" } } }, "HasMore": { "type": "object", "description": "Indicates whether there are more items than the limit for this endpoint. Use the respective list endpoints to get the full lists.", "required": [ "commits", "credits" ], "properties": { "commits": { "type": "boolean", "description": "Whether there are more commits on this contract than the limit for this endpoint. Use the /contracts/customerCommits/list endpoint to get the full list of commits." }, "credits": { "type": "boolean", "description": "Whether there are more credits on this contract than the limit for this endpoint. Use the /contracts/customerCredits/list endpoint to get the full list of credits." } } }, "CreateContractResponse": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contract": { "type": "object", "description": "The created contract.", "required": [ "id", "customer_id", "starting_at", "commits", "overrides", "scheduled_charges", "transitions", "created_at", "created_by", "usage_statement_schedule", "usage_filter" ], "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "name": { "type": "string" }, "package_id": { "type": "string", "format": "uuid", "description": "ID of the package this contract was created from, if applicable." }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKey", "description": "Optional uniqueness key to prevent duplicate contract creations." }, "rate_card_id": { "type": "string", "format": "uuid" }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "net_payment_terms_days": { "type": "number" }, "multiplier_override_prioritization": { "type": "string", "enum": [ "LOWEST_MULTIPLIER", "lowest_multiplier", "EXPLICIT", "explicit" ], "description": "Defaults to LOWEST_MULTIPLIER, which applies the greatest discount to list prices automatically. EXPLICIT prioritization requires specifying priorities for each multiplier; the one with the lowest priority value will be prioritized first." }, "scheduled_charges_on_usage_invoices": { "$ref": "#/components/schemas/ScheduledChargesOnUsageInvoices" }, "custom_fields": { "x-cf-entity": "contract", "$ref": "#/components/schemas/CustomField" }, "usage_statement_schedule": { "$ref": "#/components/schemas/UsageStatementSchedule" }, "usage_filter": { "type": "array", "items": { "type": "object", "required": [ "group_key", "group_values", "starting_at" ], "properties": { "group_key": { "type": "string" }, "group_values": { "type": "array", "items": { "type": "string" } }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" } } } }, "commits": { "type": "array", "items": { "$ref": "#/components/schemas/Commit" } }, "credits": { "type": "array", "items": { "$ref": "#/components/schemas/Credit" } }, "has_more": { "$ref": "#/components/schemas/HasMore" }, "recurring_commits": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringCommit" } }, "recurring_credits": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringCredit" } }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/Override" } }, "scheduled_charges": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledCharge" } }, "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/ContractTransition" } }, "subscriptions": { "$ref": "#/components/schemas/Subscriptions" }, "customer_billing_provider_configuration": { "$ref": "#/components/schemas/CustomerBillingProviderConfiguration" }, "spend_threshold_configuration": { "$ref": "#/components/schemas/SpendThresholdConfiguration" }, "prepaid_balance_threshold_configuration": { "$ref": "#/components/schemas/PrepaidBalanceThresholdConfiguration" }, "hierarchy_configuration": { "$ref": "#/components/schemas/HierarchyConfiguration" } } } } }, "Contract": { "type": "object", "required": [ "id", "customer_id", "initial", "current", "amendments" ], "properties": { "id": { "type": "string", "format": "uuid" }, "archived_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when the contract was archived. If not returned, the contract is not archived." }, "customer_id": { "type": "string", "format": "uuid" }, "package_id": { "type": "string", "format": "uuid", "description": "ID of the package this contract was created from, if applicable." }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKey" }, "initial": { "$ref": "#/components/schemas/ContractWithoutAmendments" }, "current": { "$ref": "#/components/schemas/ContractWithoutAmendments" }, "amendments": { "type": "array", "items": { "$ref": "#/components/schemas/ContractAmendment" } }, "custom_fields": { "x-cf-entity": "contract", "$ref": "#/components/schemas/CustomField" }, "customer_billing_provider_configuration": { "$ref": "#/components/schemas/CustomerBillingProviderConfiguration" }, "scheduled_charges_on_usage_invoices": { "$ref": "#/components/schemas/ScheduledChargesOnUsageInvoices" }, "subscriptions": { "$ref": "#/components/schemas/Subscriptions" }, "spend_threshold_configuration": { "$ref": "#/components/schemas/SpendThresholdConfiguration" }, "prepaid_balance_threshold_configuration": { "$ref": "#/components/schemas/PrepaidBalanceThresholdConfiguration" }, "spend_trackers": { "x-mint": { "groups": [ "ff:tb-spend-trackers" ] }, "type": "array", "description": "Spend trackers attached to this contract.", "items": { "type": "object", "required": [ "alias", "credit_type_id", "reset_frequency", "applicable_spend_specifiers" ], "properties": { "alias": { "type": "string", "description": "Human-readable identifier, unique per contract." }, "credit_type_id": { "type": "string", "format": "uuid" }, "reset_frequency": { "type": "string", "enum": [ "BILLING_PERIOD" ] }, "applicable_spend_specifiers": { "type": "array", "items": { "type": "object", "required": [ "spend_type", "sources" ], "properties": { "spend_type": { "type": "string", "enum": [ "COMMIT_PURCHASE" ] }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "THRESHOLD_RECHARGE", "MANUAL" ] } }, "discounted": { "type": "string", "enum": [ "ANY", "DISCOUNTED_ONLY", "UNDISCOUNTED_ONLY" ] } } } }, "accumulated_spend": { "type": "object", "required": [ "amount", "period_starting_at", "period_ending_before" ], "properties": { "amount": { "type": "number" }, "period_starting_at": { "type": "string", "format": "date-time" }, "period_ending_before": { "type": "string", "format": "date-time" } } } } } } } }, "CreateContractPayload": { "type": "object", "required": [ "customer_id", "starting_at" ], "properties": { "customer_id": { "type": "string", "format": "uuid" }, "package_id": { "type": "string", "format": "uuid", "description": "If provided, provisions a customer on a package instead of creating a traditional contract. When specified, only customer_id, starting_at, package_id, uniqueness_key, transition, and custom_fields are allowed." }, "package_alias": { "type": "string", "description": "Selects the package linked to the specified alias as of the contract's start date. Mutually exclusive with package_id." }, "package_customizations": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:package-customizations" ] }, "$ref": "#/components/schemas/PackageCustomizations" }, "name": { "type": "string" }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKey" }, "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" }, "rate_card_id": { "type": "string", "format": "uuid" }, "rate_card_alias": { "type": "string", "description": "Selects the rate card linked to the specified alias as of the contract's start date." }, "total_contract_value": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "number", "description": "This field's availability is dependent on your client's configuration." }, "starting_at": { "type": "string", "format": "date-time", "description": "inclusive contract start time" }, "ending_before": { "type": "string", "format": "date-time", "description": "exclusive contract end time" }, "commits": { "type": "array", "items": { "$ref": "#/components/schemas/CommitInput" } }, "credits": { "type": "array", "items": { "$ref": "#/components/schemas/CreditInput" } }, "recurring_commits": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringCommitInput" } }, "recurring_credits": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringCreditInput" } }, "multiplier_override_prioritization": { "type": "string", "enum": [ "LOWEST_MULTIPLIER", "lowest_multiplier", "EXPLICIT", "explicit" ], "description": "Defaults to LOWEST_MULTIPLIER, which applies the greatest discount to list prices automatically. EXPLICIT prioritization requires specifying priorities for each multiplier; the one with the lowest priority value will be prioritized first. If tiered overrides are used, prioritization must be explicit." }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/OverrideInput" } }, "discounts": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/DiscountInput" } }, "professional_services": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/ProServiceInput" } }, "reseller_royalties": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/ResellerRoyaltyInput" } }, "scheduled_charges": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledChargeInput" } }, "scheduled_charges_on_usage_invoices": { "$ref": "#/components/schemas/ScheduledChargesOnUsageInvoices" }, "transition": { "$ref": "#/components/schemas/ContractTransitionInput" }, "usage_filter": { "$ref": "#/components/schemas/BaseUsageFilter" }, "usage_statement_schedule": { "$ref": "#/components/schemas/UsageStatementScheduleInput" }, "custom_fields": { "x-cf-entity": "contract", "$ref": "#/components/schemas/CustomField" }, "billing_provider_configuration": { "$ref": "#/components/schemas/CustomerBillingProviderConfigurationLookup" }, "spend_threshold_configuration": { "$ref": "#/components/schemas/SpendThresholdConfiguration" }, "prepaid_balance_threshold_configuration": { "$ref": "#/components/schemas/PrepaidBalanceThresholdConfiguration" }, "spend_trackers": { "x-mint": { "groups": [ "ff:tb-spend-trackers" ] }, "type": "array", "items": { "$ref": "#/components/schemas/SpendTrackerInput" }, "description": "Spend trackers to attach to this contract. Aliases must be unique within a contract." }, "subscriptions": { "$ref": "#/components/schemas/SubscriptionsInput" }, "hierarchy_configuration": { "$ref": "#/components/schemas/ContractHierarchyConfigurationInput" } } }, "Subscriptions": { "type": "array", "description": "List of subscriptions on the contract.", "items": { "$ref": "#/components/schemas/Subscription" } }, "Subscription": { "required": [ "subscription_rate", "collection_schedule", "proration", "quantity_schedule", "starting_at", "quantity_management_mode", "billing_periods" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subscription_rate": { "$ref": "#/components/schemas/SubscriptionRate" }, "name": { "type": "string" }, "description": { "type": "string" }, "collection_schedule": { "type": "string", "enum": [ "ADVANCE", "ARREARS", "advance", "arrears" ] }, "proration": { "$ref": "#/components/schemas/SubscriptionProration" }, "quantity_schedule": { "type": "array", "description": "List of quantity schedule items for the subscription. Only includes the current quantity and future quantity changes.", "items": { "$ref": "#/components/schemas/SubscriptionQuantitySchedule" } }, "billing_periods": { "$ref": "#/components/schemas/SubscriptionBillingPeriods" }, "quantity_management_mode": { "type": "string", "enum": [ "SEAT_BASED", "seat_based", "QUANTITY_ONLY", "quantity_only" ], "description": "Determines how the subscription's quantity is controlled. Defaults to QUANTITY_ONLY. **QUANTITY_ONLY**: The subscription quantity is specified directly on the subscription. `initial_quantity` must be provided with this option. Compatible with recurring commits/credits that use POOLED allocation. **SEAT_BASED**: Use when you want to pass specific seat identifiers (e.g. add user_123) to increment and decrement a subscription quantity, rather than directly providing the quantity. You must use a **SEAT_BASED** subscription to use a linked recurring credit with an allocation per seat. `seat_config` must be provided with this option." }, "seat_config": { "$ref": "#/components/schemas/SubscriptionSeatConfig" }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "fiat_credit_type_id": { "type": "string", "format": "uuid" }, "custom_credit_type_id": { "type": "string", "format": "uuid", "description": "If provided, the subscription's price will be in terms of this custom pricing unit instead of the fiat currency.", "x-mint": { "groups": [ "ff:enable-subscriptions-in-cpu" ] } }, "billing_cycle_config": { "$ref": "#/components/schemas/SubscriptionBillingCycleConfig" }, "custom_fields": { "x-cf-entity": "subscription", "$ref": "#/components/schemas/CustomField" }, "product_custom_fields": { "$ref": "#/components/schemas/CustomField", "description": "Custom fields from the subscription product referenced by `subscription_rate.product`. These are distinct from the subscription instance's `custom_fields`." }, "status": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:payment-gated-subscriptions-enabled" ] }, "type": "string", "enum": [ "NOT_STARTED", "INCOMPLETE", "ACTIVE", "UNPAID", "ENDED" ] }, "paid_quantity": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:payment-gated-subscriptions-enabled" ] }, "type": "number" }, "payment_gate_config": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:payment-gated-subscriptions-enabled" ] }, "$ref": "#/components/schemas/SubscriptionPaymentGateConfig" } } }, "SubscriptionPaymentGateConfig": { "type": "object", "x-stainless-skip": true, "x-mint": { "groups": [ "ff:payment-gated-subscriptions-enabled" ] }, "required": [ "payment_gate_type" ], "properties": { "payment_gate_type": { "type": "string", "enum": [ "STRIPE" ], "description": "Successful Stripe payment gates access to the subscription." }, "tax_type": { "type": "string", "enum": [ "NONE", "STRIPE" ], "description": "Determines whether Stripe calculates tax for the payment-gated subscription." } } }, "SubscriptionBillingCycleConfig": { "type": "object", "required": [ "anchor_date", "invoice_placement" ], "properties": { "anchor_date": { "type": "string", "format": "date-time", "description": "The date this subscription's billing cycle is anchored to." }, "invoice_placement": { "type": "string", "enum": [ "ON_SCHEDULED_INVOICE", "ON_USAGE_INVOICE" ], "description": "Controls whether this subscription consolidates onto usage invoices or gets its own scheduled invoice." } } }, "SubscriptionBillingPeriods": { "type": "object", "description": "Previous, current, and next billing periods for the subscription.", "properties": { "previous": { "$ref": "#/components/schemas/SubscriptionBillingPeriod" }, "current": { "$ref": "#/components/schemas/SubscriptionBillingPeriod" }, "next": { "$ref": "#/components/schemas/SubscriptionBillingPeriod" } } }, "SubscriptionBillingPeriod": { "type": "object", "required": [ "starting_at", "ending_before" ], "properties": { "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" } } }, "SubscriptionSeatConfig": { "type": "object", "required": [ "seat_group_key" ], "properties": { "seat_group_key": { "type": "string", "description": "The property name, sent on usage events, that identifies the seat ID associated with the usage event. For example, the property name might be seat_id or user_id. The property must be set as a group key on billable metrics and a presentation/pricing group key on contract products. This allows linked recurring credits with an allocation per seat to be consumed by only one seat's usage." } } }, "SubscriptionRate": { "type": "object", "required": [ "billing_frequency", "product" ], "properties": { "billing_frequency": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUAL", "WEEKLY", "monthly", "quarterly", "annual", "weekly" ] }, "product": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } }, "SubscriptionProration": { "type": "object", "required": [ "is_prorated", "invoice_behavior" ], "properties": { "is_prorated": { "type": "boolean" }, "invoice_behavior": { "type": "string", "enum": [ "BILL_IMMEDIATELY", "BILL_ON_NEXT_COLLECTION_DATE", "bill_immediately", "bill_on_next_collection_date" ] }, "rounding": { "$ref": "#/components/schemas/ProrationRoundingConfig" } } }, "SubscriptionQuantitySchedule": { "type": "object", "required": [ "quantity", "starting_at" ], "properties": { "quantity": { "type": "number" }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" } } }, "PackageCustomizations": { "type": "object", "x-stainless-skip": true, "x-mint": { "groups": [ "ff:package-customizations" ] }, "description": "Adjustments applied on top of the package's baseline configuration when provisioning the contract. Availability is gated.", "properties": { "modify_subscriptions": { "type": "array", "description": "Per-subscription overrides for the subscriptions defined on the package template. Each entry targets one template subscription and sets its starting quantity or seats.", "items": { "$ref": "#/components/schemas/PackageSubscriptionCustomization" } }, "add_overrides": { "type": "array", "description": "Rate overrides layered onto the contract on top of the package's baseline configuration. Same shape as create_contract's overrides.", "items": { "$ref": "#/components/schemas/OverrideInput" } }, "add_commits": { "type": "array", "description": "Commits added to the contract on top of the package's baseline configuration. Same shape as create_contract's commits.", "items": { "$ref": "#/components/schemas/CommitInput" } }, "add_credits": { "type": "array", "description": "Credits added to the contract on top of the package's baseline configuration. Same shape as create_contract's credits.", "items": { "$ref": "#/components/schemas/CreditInput" } }, "add_recurring_commits": { "type": "array", "description": "Recurring commits added to the contract on top of the package's baseline configuration. Same shape as create_contract's recurring_commits.", "items": { "$ref": "#/components/schemas/RecurringCommitInput" } }, "add_recurring_credits": { "type": "array", "description": "Recurring credits added to the contract on top of the package's baseline configuration. Same shape as create_contract's recurring_credits.", "items": { "$ref": "#/components/schemas/RecurringCreditInput" } }, "add_scheduled_charges": { "type": "array", "description": "Scheduled charges added to the contract on top of the package's baseline configuration. Same shape as create_contract's scheduled_charges.", "items": { "$ref": "#/components/schemas/ScheduledChargeInput" } }, "add_spend_trackers": { "x-mint": { "groups": [ "ff:tb-spend-trackers" ] }, "type": "array", "description": "Spend trackers added to the contract on top of the package's baseline configuration. Same shape as create_contract's spend_trackers; aliases must be unique within a contract.", "items": { "$ref": "#/components/schemas/SpendTrackerInput" } }, "add_subscriptions": { "description": "New subscriptions added to the contract on top of the package's baseline configuration. Distinct from modify_subscriptions, which adjusts subscriptions defined on the package template. Same shape as create_contract's subscriptions.", "$ref": "#/components/schemas/SubscriptionsInput" }, "set_spend_threshold_configuration": { "description": "Spend threshold configuration for the contract, using set (create-or-replace) semantics: supply the complete configuration and it replaces the package's baseline in full. Same shape as create_contract's spend_threshold_configuration.", "$ref": "#/components/schemas/SpendThresholdConfiguration" }, "set_prepaid_balance_threshold_configuration": { "description": "Prepaid balance (credit balance recharge) threshold configuration for the contract, using set (create-or-replace) semantics: supply the complete configuration and it replaces the package's baseline in full. Same shape as create_contract's prepaid_balance_threshold_configuration.", "$ref": "#/components/schemas/PrepaidBalanceThresholdConfiguration" }, "modify_usage_statement_schedule": { "type": "object", "description": "Per-contract adjustments to the usage statement schedule defined on the package.", "properties": { "billing_anchor_date": { "type": "string", "format": "date-time", "description": "Billing cycle anchor date, required when the package's usage statement schedule uses a CUSTOM_DATE anchor and disallowed otherwise. Must be on or before the contract's starting_at." } } } } }, "PackageSubscriptionCustomization": { "type": "object", "x-stainless-skip": true, "x-mint": { "groups": [ "ff:package-customizations" ] }, "properties": { "template_subscription_id": { "type": "string", "format": "uuid", "description": "ID of the template subscription on the package to customize. Provide exactly one of template_subscription_id or subscription_alias." }, "subscription_alias": { "type": "string", "description": "Human-readable alias of the template subscription on the package to customize, as an alternative to template_subscription_id. Provide exactly one of the two." }, "initial_quantity": { "type": "number", "description": "The initial quantity for the subscription. Must be a non-negative value. Provide for a QUANTITY_ONLY subscription." }, "initial_seat_ids": { "type": "array", "items": { "type": "string" }, "description": "Seat identifiers to assign at the start of a SEAT_BASED subscription." }, "initial_unassigned_seats": { "type": "number", "description": "Number of unassigned seats to provision at the start of a SEAT_BASED subscription." }, "subscription_anchor_date": { "type": "string", "format": "date-time", "description": "Billing cycle anchor date for this subscription, required when the template's billing_cycle_anchor is CUSTOM_DATE and disallowed otherwise. Must be on or before the subscription's starting_at." } } }, "SubscriptionsInput": { "type": "array", "description": "Optional list of [subscriptions](https://docs.metronome.com/manage-product-access/create-subscription/) to add to the contract.", "items": { "$ref": "#/components/schemas/SubscriptionInput" } }, "SubscriptionInput": { "required": [ "subscription_rate", "collection_schedule", "proration" ], "type": "object", "properties": { "subscription_rate": { "$ref": "#/components/schemas/SubscriptionRateInput" }, "name": { "type": "string" }, "description": { "type": "string" }, "collection_schedule": { "type": "string", "enum": [ "ADVANCE", "ARREARS", "advance", "arrears" ] }, "proration": { "$ref": "#/components/schemas/SubscriptionProrationInput" }, "initial_quantity": { "type": "number", "description": "The initial quantity for the subscription. It must be non-negative value. Required if quantity_management_mode is QUANTITY_ONLY." }, "starting_at": { "type": "string", "format": "date-time", "description": "Inclusive start time for the subscription. If not provided, defaults to contract start date" }, "ending_before": { "type": "string", "format": "date-time", "description": "Exclusive end time for the subscription. If not provided, subscription inherits contract end date." }, "custom_fields": { "x-cf-entity": "subscription", "$ref": "#/components/schemas/CustomField" }, "temporary_id": { "type": "string", "description": "A temporary ID used to reference the subscription in recurring commit/credit subscription configs created within the same payload." }, "quantity_management_mode": { "type": "string", "enum": [ "SEAT_BASED", "seat_based", "QUANTITY_ONLY", "quantity_only" ], "description": "Determines how the subscription's quantity is controlled. Defaults to QUANTITY_ONLY. **QUANTITY_ONLY**: The subscription quantity is specified directly on the subscription. `initial_quantity` must be provided with this option. Compatible with recurring commits/credits that use POOLED allocation. **SEAT_BASED**: Use when you want to pass specific seat identifiers (e.g. add user_123) to increment and decrement a subscription quantity, rather than directly providing the quantity. You must use a **SEAT_BASED** subscription to use a linked recurring credit with an allocation per seat. `seat_config` must be provided with this option." }, "seat_config": { "$ref": "#/components/schemas/SubscriptionSeatConfigInput" }, "billing_cycle_config": { "$ref": "#/components/schemas/SubscriptionBillingCycleConfigInput" }, "payment_gate_config": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:payment-gated-subscriptions-enabled" ] }, "$ref": "#/components/schemas/SubscriptionPaymentGateConfigInput" } } }, "SubscriptionPaymentGateConfigInput": { "type": "object", "x-stainless-skip": true, "x-mint": { "groups": [ "ff:payment-gated-subscriptions-enabled" ] }, "required": [ "payment_gate_type" ], "properties": { "payment_gate_type": { "type": "string", "enum": [ "STRIPE", "stripe" ], "description": "Gate access to the subscription based on successful collection of payment. Select STRIPE for Metronome to facilitate payment via Stripe." }, "tax_type": { "type": "string", "enum": [ "NONE", "STRIPE", "none", "stripe" ], "description": "Stripe tax is only supported for Stripe payment gateway. Select NONE if you do not wish Metronome to calculate tax on your behalf. Leaving this field blank will default to NONE." } } }, "SubscriptionBillingCycleConfigInput": { "type": "object", "properties": { "anchor_date": { "type": "string", "format": "date-time", "description": "The date to anchor the billing cycle to. If omitted, defaults to the contract's usage invoice billing cycle anchor date." }, "invoice_placement": { "type": "string", "enum": [ "ON_SCHEDULED_INVOICE", "ON_USAGE_INVOICE", "on_scheduled_invoice", "on_usage_invoice" ], "description": "Controls whether this subscription consolidates onto usage invoices or gets its own scheduled invoice. Defaults to ON_USAGE_INVOICE if omitted." } } }, "SubscriptionSeatConfigInput": { "type": "object", "required": [ "seat_group_key", "initial_seat_ids" ], "properties": { "seat_group_key": { "type": "string", "description": "The property name, sent on usage events, that identifies the seat ID associated with the usage event. For example, the property name might be seat_id or user_id. The property must be set as a group key on billable metrics and a presentation/pricing group key on contract products. This allows linked recurring credits with an allocation per seat to be consumed by only one seat's usage." }, "initial_seat_ids": { "type": "array", "items": { "type": "string" }, "description": "The initial assigned seats on this subscription." }, "initial_unassigned_seats": { "type": "number", "description": "The initial amount of unassigned seats on this subscription." } } }, "SubscriptionRateInput": { "type": "object", "required": [ "billing_frequency", "product_id" ], "properties": { "billing_frequency": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUAL", "WEEKLY", "monthly", "quarterly", "annual", "weekly" ], "description": "Frequency to bill subscription with. Together with product_id, must match existing rate on the rate card." }, "product_id": { "type": "string", "format": "uuid", "description": "Must be subscription type product" } } }, "SubscriptionProrationInput": { "type": "object", "properties": { "is_prorated": { "type": "boolean", "description": "Indicates if the partial period will be prorated or charged a full amount." }, "invoice_behavior": { "type": "string", "enum": [ "BILL_IMMEDIATELY", "BILL_ON_NEXT_COLLECTION_DATE", "bill_immediately", "bill_on_next_collection_date" ], "description": "Indicates how mid-period quantity adjustments are invoiced.\n**BILL_IMMEDIATELY**: Only available when collection schedule is `ADVANCE`. The quantity increase will be billed immediately on the scheduled date.\n**BILL_ON_NEXT_COLLECTION_DATE**: The quantity increase will be billed for in-arrears at the end of the period.\n" }, "rounding": { "$ref": "#/components/schemas/ProrationRoundingConfig" } } }, "SpendTrackerApplicableSpendSpecifierInput": { "type": "object", "required": [ "spend_type", "sources" ], "properties": { "spend_type": { "type": "string", "enum": [ "COMMIT_PURCHASE" ] }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "THRESHOLD_RECHARGE", "MANUAL" ] } }, "discounted": { "type": "string", "enum": [ "ANY", "DISCOUNTED_ONLY", "UNDISCOUNTED_ONLY" ], "description": "Filter by whether the spend was discounted. Defaults to ANY if omitted." } } }, "SpendTrackerInput": { "type": "object", "required": [ "alias", "credit_type_id", "reset_frequency", "applicable_spend_specifiers" ], "properties": { "alias": { "type": "string", "description": "Human-readable identifier, unique per contract." }, "credit_type_id": { "type": "string", "format": "uuid" }, "reset_frequency": { "type": "string", "enum": [ "BILLING_PERIOD" ] }, "applicable_spend_specifiers": { "type": "array", "items": { "$ref": "#/components/schemas/SpendTrackerApplicableSpendSpecifierInput" } } } }, "SpendTrackerAttributesInput": { "type": "object", "required": [ "counts_as_discounted" ], "properties": { "counts_as_discounted": { "type": "boolean", "description": "If true, this commit will be included in spend trackers with discounted set to DISCOUNTED_ONLY" } } }, "SpendTrackerAttributes": { "type": "object", "required": [ "counts_as_discounted" ], "properties": { "counts_as_discounted": { "type": "boolean", "description": "If true, this commit is included in spend trackers with discounted set to DISCOUNTED_ONLY" } } }, "PrepaidBalanceDiscountCapInput": { "type": "object", "required": [ "spend_tracker_alias", "amount" ], "properties": { "spend_tracker_alias": { "type": "string", "description": "Alias of the spend tracker this cap is measured against." }, "amount": { "type": "number", "description": "Accumulated spend ceiling above which the discount stops applying." } } }, "PrepaidBalanceThresholdConfiguration": { "type": "object", "required": [ "is_enabled", "threshold_amount", "recharge_to_amount", "commit", "payment_gate_config" ], "properties": { "is_enabled": { "type": "boolean", "description": "When set to false, the contract will not be evaluated against the threshold_amount. Toggling to true will result an immediate evaluation, regardless of prior state." }, "threshold_amount": { "description": "Specify the threshold amount for the contract. Each time the contract's prepaid balance lowers to this amount, a threshold charge will be initiated.", "type": "number" }, "recharge_to_amount": { "description": "Specify the amount the balance should be recharged to.", "type": "number" }, "custom_credit_type_id": { "description": "If provided, the threshold, recharge-to amount, and the resulting threshold commit amount will be in terms of this credit type instead of the fiat currency.", "type": "string", "format": "uuid" }, "commit": { "$ref": "#/components/schemas/PrepaidBalanceThresholdCommit" }, "payment_gate_config": { "$ref": "#/components/schemas/PaymentGateConfig" }, "discount_configuration": { "x-mint": { "groups": [ "ff:threshold-billing-discounts" ] }, "$ref": "#/components/schemas/DiscountConfiguration" }, "threshold_balance_specifiers": { "type": "array", "description": "Determines which balances are excluded from remaining balance calculation for threshold billing.", "items": { "$ref": "#/components/schemas/ThresholdBalanceSpecifier" } } } }, "ContractHierarchyConfigurationInput": { "type": "object", "properties": { "parent": { "$ref": "#/components/schemas/ContractParentHierarchyConfigurationInput" }, "payer": { "type": "string", "enum": [ "SELF", "PARENT", "self", "parent" ], "description": "Indicates which customer should pay for the child's invoice charges\n\n**SELF**: The child pays for its own invoice charges\n\n**PARENT**: The parent pays for the child's invoice charges" }, "usage_statement_behavior": { "type": "string", "enum": [ "CONSOLIDATE", "SEPARATE", "consolidate", "separate" ], "description": "Indicates the behavior of the child's invoice statements on the parent's invoices.\n\n**CONSOLIDATE**: Child's invoice statements will be added to parent's consolidated invoices\n\n**SEPARATE**: Child's invoice statements will appear not appear on parent's consolidated invoices" }, "parent_behavior": { "type": "object", "properties": { "invoice_consolidation_type": { "type": "string", "enum": [ "CONCATENATE", "NONE", "concatenate", "none" ], "description": "Indicates the desired behavior of consolidated invoices generated by the parent in a customer hierarchy\n\n**CONCATENATE**: Statements on the invoices of child customers will be appended to the consolidated invoice\n\n**NONE**: Do not generate consolidated invoices" } } } } }, "ContractParentHierarchyConfigurationInput": { "type": "object", "required": [ "contract_id", "customer_id" ], "properties": { "contract_id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" } } }, "HierarchyConfiguration": { "oneOf": [ { "$ref": "#/components/schemas/ParentHierarchyConfiguration" }, { "$ref": "#/components/schemas/ChildHierarchyConfiguration" } ], "description": "Either a **parent** configuration with a list of children or a **child** configuration with a single parent.\n" }, "ParentHierarchyConfiguration": { "type": "object", "required": [ "children" ], "properties": { "children": { "type": "array", "items": { "$ref": "#/components/schemas/HierarchyLink" }, "description": "List of contracts that belong to this parent." }, "parent_behavior": { "type": "object", "properties": { "invoice_consolidation_type": { "type": "string", "enum": [ "CONCATENATE", "NONE" ], "description": "Indicates the desired behavior of consolidated invoices generated by the parent in a customer hierarchy\n\n**CONCATENATE**: Statements on the invoices of child customers will be appended to the consolidated invoice\n\n**NONE**: Do not generate consolidated invoices" } } } } }, "ChildHierarchyConfiguration": { "type": "object", "required": [ "parent" ], "properties": { "parent": { "$ref": "#/components/schemas/HierarchyLink", "description": "The single parent contract/customer for this child." }, "payer": { "type": "string", "enum": [ "SELF", "PARENT" ], "description": "Indicates which customer should pay for the child's invoice charges\n\n**SELF**: The child pays for its own invoice charges\n\n**PARENT**: The parent pays for the child's invoice charges" }, "usage_statement_behavior": { "type": "string", "enum": [ "CONSOLIDATE", "SEPARATE" ], "description": "Indicates the behavior of the child's invoice statements on the parent's invoices.\n\n**CONSOLIDATE**: Child's invoice statements will be added to parent's consolidated invoices\n\n**SEPARATE**: Child's invoice statements will appear not appear on parent's consolidated invoices" } } }, "HierarchyLink": { "type": "object", "required": [ "contract_id", "customer_id" ], "properties": { "contract_id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" } } }, "SpendThresholdConfiguration": { "type": "object", "required": [ "is_enabled", "threshold_amount", "commit", "payment_gate_config" ], "properties": { "is_enabled": { "type": "boolean", "description": "When set to false, the contract will not be evaluated against the threshold_amount. Toggling to true will result an immediate evaluation, regardless of prior state." }, "threshold_amount": { "description": "Specify the threshold amount for the contract. Each time the contract's usage hits this amount, a threshold charge will be initiated.", "type": "number" }, "commit": { "$ref": "#/components/schemas/SpendThresholdCommit" }, "payment_gate_config": { "$ref": "#/components/schemas/PaymentGateConfig" }, "discount_configuration": { "x-mint": { "groups": [ "ff:threshold-billing-discounts" ] }, "$ref": "#/components/schemas/DiscountConfiguration" } } }, "PaymentGateConfig": { "type": "object", "required": [ "payment_gate_type" ], "properties": { "payment_gate_type": { "type": "string", "enum": [ "NONE", "STRIPE", "EXTERNAL" ], "description": "Gate access to the commit balance based on successful collection of payment. Select STRIPE for Metronome to facilitate payment via Stripe. Select EXTERNAL to facilitate payment using your own payment integration. Select NONE if you do not wish to payment gate the commit balance." }, "tax_type": { "type": "string", "enum": [ "NONE", "STRIPE", "ANROK", "PRECALCULATED" ], "description": "Stripe tax is only supported for Stripe payment gateway. Select NONE if you do not wish Metronome to calculate tax on your behalf. Leaving this field blank will default to NONE." }, "stripe_config": { "description": "Only applicable if using STRIPE as your payment gate type.", "type": "object", "required": [ "payment_type" ], "properties": { "payment_type": { "type": "string", "enum": [ "INVOICE", "PAYMENT_INTENT" ], "description": "If left blank, will default to INVOICE" }, "invoice_metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type." } } }, "precalculated_tax_config": { "description": "Only applicable if using PRECALCULATED as your tax type.", "type": "object", "required": [ "tax_amount" ], "properties": { "tax_amount": { "type": "number", "description": "Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule" }, "tax_name": { "type": "string", "description": "Name of the tax to be applied. This may be used in an invoice line item description." } } } } }, "BaseThresholdCommit": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "string", "description": "The commit product that will be used to generate the line item for commit payment." }, "name": { "type": "string", "description": "Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name." }, "description": { "type": "string" }, "priority": { "type": "number", "description": "The priority of the commit, used to determine drawdown order. Lower priority commits are consumed first. Defaults to 100 if not specified." } } }, "PrepaidBalanceThresholdCommit": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseThresholdCommit" }, { "type": "object", "properties": { "duration": { "$ref": "#/components/schemas/RelativeDate", "description": "The length of time the created commit will be valid, starting from the end of the invoice's service period. If not provided, defaults to one year." }, "rollover_fraction": { "type": "number", "description": "Fraction of the created commit's unused balance that will roll over. Must be between 0 and 1." }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "commit_rate", "LIST_RATE", "list_rate" ], "description": "Whether the created commits will be charged at commit rate or list rate." }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Which products the threshold commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products." }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "Which tags the threshold commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products." }, "specifiers": { "x-mint": { "groups": [ "ff:commit-specifiers" ] }, "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with `applicable_product_ids` or `applicable_product_tags`.", "items": { "$ref": "#/components/schemas/CommitSpecifierInput" } } } } ] }, "SpendThresholdCommit": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/BaseThresholdCommit" } ] }, "ScheduledChargesOnUsageInvoices": { "type": "string", "description": "Determines which scheduled and commit charges to consolidate onto the Contract's usage invoice. The charge's `timestamp` must match the usage invoice's `ending_before` date for consolidation to occur. This field cannot be modified after a Contract has been created. If this field is omitted, charges will appear on a separate invoice from usage charges.", "enum": [ "ALL" ] }, "UsageStatementScheduleInput": { "type": "object", "required": [ "frequency" ], "properties": { "frequency": { "type": "string", "enum": [ "MONTHLY", "monthly", "QUARTERLY", "quarterly", "ANNUAL", "annual", "WEEKLY", "weekly" ] }, "day": { "type": "string", "description": "If not provided, defaults to the first day of the month.", "enum": [ "FIRST_OF_MONTH", "first_of_month", "CONTRACT_START", "contract_start", "CUSTOM_DATE", "custom_date" ] }, "billing_anchor_date": { "type": "string", "format": "date-time", "description": "Required when using CUSTOM_DATE. This option lets you set a historical billing anchor date, aligning future billing cycles with a chosen cadence. For example, if a contract starts on 2024-09-15 and you set the anchor date to 2024-09-10 with a MONTHLY frequency, the first usage statement will cover 09-15 to 10-10. Subsequent statements will follow the 10th of each month." }, "invoice_generation_starting_at": { "type": "string", "format": "date-time", "description": "The date Metronome should start generating usage invoices. If unspecified, contract start date will be used. This is useful to set if you want to import historical invoices via our 'Create Historical Invoices' API rather than having Metronome automatically generate them." } } }, "UsageStatementSchedule": { "type": "object", "required": [ "frequency", "billing_anchor_date" ], "properties": { "frequency": { "type": "string", "enum": [ "MONTHLY", "monthly", "QUARTERLY", "quarterly", "ANNUAL", "annual", "WEEKLY", "weekly" ] }, "billing_anchor_date": { "type": "string", "format": "date-time", "description": "Contract usage statements follow a selected cadence based on this date." } } }, "BaseUsageFilter": { "type": "object", "required": [ "group_key", "group_values" ], "properties": { "group_key": { "type": "string" }, "group_values": { "type": "array", "items": { "type": "string" } }, "starting_at": { "type": "string", "format": "date-time" } } }, "BaseUsageFilterWithRequiredStartingAt": { "type": "object", "required": [ "group_key", "group_values", "starting_at" ], "properties": { "group_key": { "type": "string" }, "group_values": { "type": "array", "items": { "type": "string" } }, "starting_at": { "type": "string", "format": "date-time" } } }, "UsageFilter": { "type": "object", "required": [ "initial", "current", "updates" ], "properties": { "initial": { "$ref": "#/components/schemas/BaseUsageFilter" }, "current": { "nullable": true, "$ref": "#/components/schemas/BaseUsageFilter" }, "updates": { "type": "array", "items": { "$ref": "#/components/schemas/BaseUsageFilterWithRequiredStartingAt" } } } }, "SetUsageFilterPayload": { "type": "object", "required": [ "customer_id", "contract_id", "group_key", "group_values", "starting_at" ], "properties": { "customer_id": { "type": "string", "format": "uuid" }, "contract_id": { "type": "string", "format": "uuid" }, "group_key": { "type": "string" }, "group_values": { "type": "array", "items": { "type": "string" } }, "starting_at": { "type": "string", "format": "date-time" } } }, "ContractTransition": { "type": "object", "required": [ "type", "from_contract_id", "to_contract_id" ], "properties": { "type": { "type": "string", "enum": [ "RENEWAL" ] }, "from_contract_id": { "type": "string", "format": "uuid" }, "to_contract_id": { "type": "string", "format": "uuid" } } }, "ContractAmendment": { "type": "object", "required": [ "id", "starting_at", "commits", "overrides", "scheduled_charges", "created_at", "created_by" ], "properties": { "id": { "type": "string", "format": "uuid" }, "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." }, "starting_at": { "type": "string", "format": "date-time" }, "commits": { "type": "array", "items": { "$ref": "#/components/schemas/Commit" } }, "credits": { "type": "array", "items": { "$ref": "#/components/schemas/Credit" } }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/Override" } }, "discounts": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/Discount" } }, "professional_services": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/ProService" } }, "scheduled_charges": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledCharge" } }, "reseller_royalties": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/ResellerRoyaltyOrUpdate" } }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "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." } } }, "ArchiveContractPayload": { "type": "object", "required": [ "customer_id", "contract_id", "void_invoices" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer whose contract is to be archived" }, "contract_id": { "type": "string", "format": "uuid", "description": "ID of the contract to archive" }, "void_invoices": { "type": "boolean", "description": "If false, the existing finalized invoices will remain after the contract is archived." } } }, "AmendContractPayload": { "type": "object", "required": [ "customer_id", "contract_id", "starting_at" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer whose contract is to be amended" }, "contract_id": { "type": "string", "format": "uuid", "description": "ID of the contract to amend" }, "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." }, "total_contract_value": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "number", "description": "This field's availability is dependent on your client's configuration." }, "starting_at": { "type": "string", "format": "date-time", "description": "inclusive start time for the amendment" }, "commits": { "type": "array", "items": { "$ref": "#/components/schemas/CommitInput" } }, "credits": { "type": "array", "items": { "$ref": "#/components/schemas/CreditInput" } }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/OverrideInput" } }, "discounts": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/DiscountInput" } }, "professional_services": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/ProServiceInput" } }, "reseller_royalties": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/ResellerRoyaltyOrUpdateInput" } }, "scheduled_charges": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledChargeInput" } }, "custom_fields": { "x-cf-entity": "contract", "$ref": "#/components/schemas/CustomField" } } }, "CommitInput": { "type": "object", "required": [ "type", "product_id" ], "properties": { "type": { "type": "string", "enum": [ "PREPAID", "prepaid", "POSTPAID", "postpaid" ] }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "commit_rate", "LIST_RATE", "list_rate" ] }, "name": { "type": "string", "minLength": 1, "description": "displayed on invoices" }, "product_id": { "type": "string", "format": "uuid" }, "access_schedule": { "$ref": "#/components/schemas/ScheduleDurationInput", "description": "Required: Schedule for distributing the commit to the customer. For \"POSTPAID\" commits only one schedule item is allowed and amount must match invoice_schedule total." }, "invoice_schedule": { "$ref": "#/components/schemas/SchedulePointInTimeInput", "description": "Required for \"POSTPAID\" commits: the true up invoice will be generated at this time and only one schedule item is allowed; the total must match access_schedule amount. Optional for \"PREPAID\" commits: if not provided, this will be a \"complimentary\" commit with no invoice." }, "amount": { "type": "number", "description": "(DEPRECATED) Use access_schedule and invoice_schedule instead." }, "description": { "type": "string", "description": "Used only in UI/API. It is not exposed to end customers." }, "rollover_fraction": { "type": "number", "description": "Fraction of unused segments that will be rolled over. Must be between 0 and 1." }, "priority": { "type": "number", "description": "If multiple commits are applicable, the one with the lower priority will apply first." }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Which products the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products." }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "Which tags the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products." }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with `applicable_product_ids` or `applicable_product_tags`.", "items": { "$ref": "#/components/schemas/CommitSpecifierInput" } }, "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." }, "custom_fields": { "x-cf-entity": "commit", "$ref": "#/components/schemas/CustomField" }, "temporary_id": { "type": "string", "description": "A temporary ID for the commit that can be used to reference the commit for commit specific overrides." }, "hierarchy_configuration": { "$ref": "#/components/schemas/CommitHierarchyConfiguration", "description": "Optional configuration for commit hierarchy access control" }, "spend_tracker_attributes": { "x-mint": { "groups": [ "ff:tb-spend-trackers" ] }, "allOf": [ { "$ref": "#/components/schemas/SpendTrackerAttributesInput" } ], "description": "Optional attributes for spend tracker integration. Immutable after creation." } } }, "CommitHierarchyConfiguration": { "type": "object", "required": [ "child_access" ], "properties": { "child_access": { "oneOf": [ { "$ref": "#/components/schemas/CommitHierarchyChildAccessAll" }, { "$ref": "#/components/schemas/CommitHierarchyChildAccessNone" }, { "$ref": "#/components/schemas/CommitHierarchyChildAccessContractIds" } ] } } }, "CommitHierarchyChildAccessAll": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "ALL", "all" ] } } }, "CommitHierarchyChildAccessNone": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "NONE", "none" ] } } }, "CommitHierarchyChildAccessContractIds": { "type": "object", "required": [ "type", "contract_ids" ], "properties": { "type": { "type": "string", "enum": [ "CONTRACT_IDS", "contract_ids" ] }, "contract_ids": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uuid" } } } }, "CreditInput": { "type": "object", "required": [ "product_id", "access_schedule" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "displayed on invoices" }, "product_id": { "type": "string", "format": "uuid" }, "access_schedule": { "$ref": "#/components/schemas/ScheduleDurationInput", "description": "Schedule for distributing the credit to the customer." }, "description": { "type": "string", "description": "Used only in UI/API. It is not exposed to end customers." }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Which products the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products." }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "Which tags the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products." }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with `applicable_product_ids` or `applicable_product_tags`.", "items": { "$ref": "#/components/schemas/CommitSpecifierInput" } }, "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." }, "priority": { "type": "number", "description": "If multiple credits are applicable, the one with the lower priority will apply first." }, "custom_fields": { "x-cf-entity": "contract_credit", "$ref": "#/components/schemas/CustomField" }, "rollover_fraction": { "type": "number", "description": "Fraction of unused segments that will be rolled over. Must be between 0 and 1." }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "commit_rate", "LIST_RATE", "list_rate" ] }, "hierarchy_configuration": { "$ref": "#/components/schemas/CommitHierarchyConfiguration", "description": "Optional configuration for credit hierarchy access control" } } }, "RecurringCommitOrCreditInputBase": { "type": "object", "required": [ "product_id", "access_amount", "priority", "commit_duration", "starting_at" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "displayed on invoices. will be passed through to the individual commits" }, "product_id": { "type": "string", "format": "uuid" }, "access_amount": { "type": "object", "required": [ "unit_price" ], "properties": { "access_type": { "type": "string", "enum": [ "SPEND", "QUANTITY", "spend", "quantity" ], "description": "Indicates how the balance of child commits is drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used." }, "unit_price": { "type": "number" }, "quantity": { "type": "number", "description": "This field is required unless a subscription is attached via `subscription_config`." }, "credit_type_id": { "type": "string", "format": "uuid", "description": "Defaults to USD (cents) if not passed" } }, "description": "The amount of commit to grant." }, "description": { "type": "string", "description": "Will be passed down to the individual commits" }, "rollover_fraction": { "type": "number", "description": "Will be passed down to the individual commits. This controls how much of an individual unexpired commit will roll over upon contract transition. Must be between 0 and 1." }, "priority": { "type": "number", "description": "Will be passed down to the individual commits" }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Will be passed down to the individual commits" }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "Will be passed down to the individual commits" }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with `applicable_product_ids` or `applicable_product_tags`.", "items": { "$ref": "#/components/schemas/CommitSpecifierInput" } }, "netsuite_sales_order_id": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "string", "description": "Will be passed down to the individual commits" }, "temporary_id": { "type": "string", "description": "A temporary ID that can be used to reference the recurring commit for commit specific overrides." }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "commit_rate", "LIST_RATE", "list_rate" ], "description": "Whether the created commits will use the commit rate or list rate" }, "starting_at": { "type": "string", "format": "date-time", "description": "determines the start time for the first commit" }, "ending_before": { "type": "string", "format": "date-time", "description": "Determines when the contract will stop creating recurring commits. optional" }, "commit_duration": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "periods", "PERIODS" ] } }, "description": "Defines the length of the access schedule for each created commit/credit. The value represents the number of units. Unit defaults to \"PERIODS\", where the length of a period is determined by the recurrence_frequency." }, "recurrence_frequency": { "type": "string", "enum": [ "MONTHLY", "monthly", "QUARTERLY", "quarterly", "ANNUAL", "annual", "WEEKLY", "weekly", "DAILY", "daily" ], "description": "The frequency at which the recurring commits will be created. If not provided: - The commits will be created on the usage invoice frequency. If provided: - The period defined in the duration will correspond to this frequency. - Commits will be created aligned with the recurring commit's starting_at rather than the usage invoice dates. - Daily recurring commits have a limit of one per contract, and are unable to be created with seat-based subscriptions" }, "proration": { "type": "string", "enum": [ "NONE", "none", "FIRST", "first", "LAST", "last", "FIRST_AND_LAST", "first_and_last" ], "description": "Determines whether the first and last commit will be prorated. If not provided, the default is FIRST_AND_LAST (i.e. prorate both the first and last commits)." }, "subscription_config": { "description": "Attach a subscription to the recurring commit/credit.", "$ref": "#/components/schemas/RecurringCommitSubscriptionConfigInput" }, "hierarchy_configuration": { "$ref": "#/components/schemas/CommitHierarchyConfiguration", "description": "Optional configuration for recurring commit/credit hierarchy access control" } } }, "RecurringCommitInput": { "allOf": [ { "$ref": "#/components/schemas/RecurringCommitOrCreditInputBase" }, { "type": "object", "properties": { "invoice_amount": { "type": "object", "required": [ "unit_price", "quantity", "credit_type_id" ], "properties": { "unit_price": { "type": "number" }, "quantity": { "type": "number" }, "credit_type_id": { "type": "string", "format": "uuid" } }, "description": "The amount the customer should be billed for the commit. Not required." }, "proration_rounding": { "type": "object", "description": "Optional rounding configuration for prorated recurring commit amounts.", "properties": { "access": { "$ref": "#/components/schemas/ProrationRoundingConfig" }, "invoice": { "$ref": "#/components/schemas/ProrationRoundingConfig" } } } } } ] }, "RecurringCreditInput": { "allOf": [ { "$ref": "#/components/schemas/RecurringCommitOrCreditInputBase" }, { "type": "object", "properties": { "proration_rounding": { "type": "object", "description": "Optional rounding configuration for prorated recurring credit amounts.", "properties": { "access": { "$ref": "#/components/schemas/ProrationRoundingConfig" } } } } } ] }, "CreateCustomerCommitPayload": { "type": "object", "required": [ "customer_id", "type", "priority", "product_id", "access_schedule" ], "properties": { "customer_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "PREPAID", "prepaid", "POSTPAID", "postpaid" ] }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "commit_rate", "LIST_RATE", "list_rate" ] }, "name": { "type": "string", "minLength": 1, "description": "displayed on invoices" }, "description": { "type": "string", "description": "Used only in UI/API. It is not exposed to end customers." }, "priority": { "type": "number", "description": "If multiple credits or commits are applicable, the one with the lower priority will apply first." }, "product_id": { "type": "string", "format": "uuid", "description": "ID of the fixed product associated with the commit. This is required because products are used to invoice the commit amount." }, "access_schedule": { "$ref": "#/components/schemas/ScheduleDurationInput", "description": "Schedule for distributing the commit to the customer. For \"POSTPAID\" commits only one schedule item is allowed and amount must match invoice_schedule total." }, "invoice_schedule": { "$ref": "#/components/schemas/SchedulePointInTimeInput", "description": "Required for \"POSTPAID\" commits: the true up invoice will be generated at this time and only one schedule item is allowed; the total must match accesss_schedule amount. Optional for \"PREPAID\" commits: if not provided, this will be a \"complimentary\" commit with no invoice." }, "invoice_contract_id": { "type": "string", "format": "uuid", "description": "The contract that this commit will be billed on. This is required for \"POSTPAID\" commits and for \"PREPAID\" commits unless there is no invoice schedule above (i.e., the commit is 'free'), or if do_not_invoice is set to true." }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Which products the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products." }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "Which tags the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products." }, "applicable_contract_ids": { "type": "array", "items": { "type": "string" }, "description": "Which contract the commit applies to. If not provided, the commit applies to all contracts." }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with `applicable_product_ids` or `applicable_product_tags`.", "items": { "$ref": "#/components/schemas/CommitSpecifierInput" } }, "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." }, "custom_fields": { "x-cf-entity": "commit", "$ref": "#/components/schemas/CustomField" }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKeyForCommitsAndCredits" } } }, "CreateCustomerCreditPayload": { "type": "object", "required": [ "customer_id", "priority", "product_id", "access_schedule" ], "properties": { "customer_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "description": "displayed on invoices" }, "description": { "type": "string", "description": "Used only in UI/API. It is not exposed to end customers." }, "priority": { "type": "number", "description": "If multiple credits or commits are applicable, the one with the lower priority will apply first." }, "product_id": { "type": "string", "format": "uuid" }, "access_schedule": { "$ref": "#/components/schemas/ScheduleDurationInput", "description": "Schedule for distributing the credit to the customer." }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Which products the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products." }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "Which tags the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products." }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with `applicable_product_ids` or `applicable_product_tags`.", "items": { "$ref": "#/components/schemas/CommitSpecifierInput" } }, "applicable_contract_ids": { "type": "array", "items": { "type": "string" }, "description": "Which contract the credit applies to. If not provided, the credit applies to all contracts." }, "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." }, "custom_fields": { "x-cf-entity": "contract_credit", "$ref": "#/components/schemas/CustomField" }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "commit_rate", "LIST_RATE", "list_rate" ] }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKeyForCommitsAndCredits" } } }, "RecurringCommitOrCreditBase": { "type": "object", "required": [ "id", "product", "access_amount", "priority", "commit_duration", "starting_at", "rate_type", "anchor_date" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contract": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } }, "name": { "type": "string", "description": "Displayed on invoices. Will be passed through to the individual commits" }, "product": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "access_amount": { "type": "object", "required": [ "unit_price", "credit_type_id" ], "properties": { "access_type": { "type": "string", "enum": [ "SPEND", "QUANTITY" ], "description": "Indicates how the balance of child commits is drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used." }, "unit_price": { "type": "number" }, "quantity": { "type": "number" }, "credit_type_id": { "type": "string", "format": "uuid", "description": "This ID identifies the credit type for the access amount. Quantity-based recurring commits and credits return the null credit type UUID." } }, "description": "The amount of commit to grant." }, "description": { "type": "string", "description": "Will be passed down to the individual commits" }, "rollover_fraction": { "type": "number", "description": "Will be passed down to the individual commits. This controls how much of an individual unexpired commit will roll over upon contract transition. Must be between 0 and 1." }, "priority": { "type": "number", "description": "Will be passed down to the individual commits" }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Will be passed down to the individual commits" }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "Will be passed down to the individual commits" }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown.", "items": { "$ref": "#/components/schemas/CommitSpecifier" } }, "netsuite_sales_order_id": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "string", "description": "Will be passed down to the individual commits" }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "commit_rate", "LIST_RATE", "list_rate" ], "description": "Whether the created commits will use the commit rate or list rate" }, "starting_at": { "type": "string", "format": "date-time", "description": "Determines the start time for the first commit" }, "ending_before": { "type": "string", "format": "date-time", "description": "Determines when the contract will stop creating recurring commits. Optional" }, "commit_duration": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "periods", "PERIODS" ] } }, "description": "The amount of time the created commits will be valid for" }, "recurrence_frequency": { "type": "string", "enum": [ "MONTHLY", "monthly", "QUARTERLY", "quarterly", "ANNUAL", "annual", "WEEKLY", "weekly", "DAILY", "daily" ], "description": "The frequency at which the recurring commits will be created. If not provided: - The commits will be created on the usage invoice frequency. If provided: - The period defined in the duration will correspond to this frequency. - Commits will be created aligned with the recurring commit's starting_at rather than the usage invoice dates. - Daily recurring commits have a limit of one per contract, and are unable to be created with seat-based subscriptions" }, "anchor_date": { "type": "string", "format": "date-time", "description": "The date this recurring commit's billing periods are anchored to." }, "proration": { "type": "string", "enum": [ "NONE", "none", "FIRST", "first", "LAST", "last", "FIRST_AND_LAST", "first_and_last" ], "description": "Determines whether the first and last commit will be prorated. If not provided, the default is FIRST_AND_LAST (i.e. prorate both the first and last commits)." }, "subscription_config": { "description": "Attach a subscription to the recurring commit/credit.", "$ref": "#/components/schemas/RecurringCommitSubscriptionConfig" }, "hierarchy_configuration": { "$ref": "#/components/schemas/CommitHierarchyConfiguration", "description": "Optional configuration for recurring commit/credit hierarchy access control" } } }, "RecurringCommit": { "allOf": [ { "$ref": "#/components/schemas/RecurringCommitOrCreditBase" }, { "type": "object", "properties": { "invoice_amount": { "type": "object", "required": [ "unit_price", "quantity", "credit_type_id" ], "properties": { "unit_price": { "type": "number" }, "quantity": { "type": "number" }, "credit_type_id": { "type": "string", "format": "uuid" } }, "description": "The amount the customer should be billed for the commit. Not required." }, "proration_rounding": { "type": "object", "nullable": true, "description": "Rounding configuration for prorated recurring commit amounts.", "properties": { "access": { "$ref": "#/components/schemas/ProrationRoundingConfig" }, "invoice": { "$ref": "#/components/schemas/ProrationRoundingConfig" } } } } } ] }, "RecurringCredit": { "allOf": [ { "$ref": "#/components/schemas/RecurringCommitOrCreditBase" }, { "type": "object", "properties": { "proration_rounding": { "type": "object", "nullable": true, "description": "Rounding configuration for prorated recurring credit amounts.", "properties": { "access": { "$ref": "#/components/schemas/ProrationRoundingConfig" } } } } } ] }, "Commit": { "type": "object", "required": [ "id", "type", "product", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contract": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } }, "type": { "type": "string", "enum": [ "PREPAID", "POSTPAID" ] }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "LIST_RATE" ] }, "name": { "type": "string" }, "priority": { "type": "number", "description": "If multiple credits or commits are applicable, the one with the lower priority will apply first." }, "cost_basis": { "x-mint": { "groups": [ "ff:commit-cost-basis" ] }, "type": "number", "description": "The ratio of the amount paid for the commit to the amount of credit granted." }, "product": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "access_schedule": { "$ref": "#/components/schemas/ScheduleDuration", "description": "The schedule that the customer will gain access to the credits purposed with this commit." }, "invoice_schedule": { "$ref": "#/components/schemas/SchedulePointInTime", "description": "The schedule that the customer will be invoiced for this commit." }, "invoice_contract": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } }, "description": "The contract that this commit will be billed on." }, "recurring_commit_id": { "type": "string", "format": "uuid", "description": "The ID of the recurring commit that this commit was generated from, if applicable." }, "subscription_config": { "type": "object", "properties": { "subscription_id": { "type": "string", "format": "uuid" }, "allocation": { "$ref": "#/components/schemas/SubscriptionConfigAllocation" }, "apply_seat_increase_config": { "$ref": "#/components/schemas/ApplySeatIncreaseConfigForRecurringCommit" }, "access_policy": { "x-stainless-skip": true, "type": "string", "enum": [ "BILLING_PERIOD_PAID", "INITIAL_BILLING_PERIOD_PAID_ONLY" ], "x-mint": { "groups": [ "ff:payment-gated-subscriptions-enabled" ] }, "description": "Controls when a customer can access this commit when the attached subscription is payment-gated. `BILLING_PERIOD_PAID` releases the commit after payment for its billing period. `INITIAL_BILLING_PERIOD_PAID_ONLY` releases the commit after the first payment." } }, "description": "The subscription configuration for this commit, if it was generated from a recurring commit with a subscription attached." }, "rolled_over_from": { "type": "object", "required": [ "contract_id", "commit_id" ], "properties": { "commit_id": { "type": "string", "format": "uuid" }, "contract_id": { "type": "string", "format": "uuid" } } }, "description": { "type": "string" }, "rollover_fraction": { "type": "number" }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "applicable_product_tags": { "type": "array", "items": { "type": "string" } }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown.", "items": { "$ref": "#/components/schemas/CommitSpecifier" } }, "applicable_contract_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "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." }, "amount": { "type": "number", "description": "(DEPRECATED) Use access_schedule + invoice_schedule instead." }, "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." }, "ledger": { "type": "array", "items": { "$ref": "#/components/schemas/CommitLedger" }, "description": "A list of ordered events that impact the balance of a commit. For example, an invoice deduction or a rollover." }, "balance": { "$ref": "#/components/schemas/BalanceForCommitsAndCredits" }, "custom_fields": { "x-cf-entity": "commit", "$ref": "#/components/schemas/CustomField" }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKeyForCommitsAndCredits" }, "archived_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when the commit was archived. If not provided, the commit is not archived." }, "hierarchy_configuration": { "$ref": "#/components/schemas/CommitHierarchyConfiguration", "description": "Optional configuration for commit hierarchy access control" }, "spend_tracker_attributes": { "x-mint": { "groups": [ "ff:tb-spend-trackers" ] }, "$ref": "#/components/schemas/SpendTrackerAttributes", "description": "Optional attributes controlling how this commit interacts with spend trackers." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the commit was created.\n- Recurring commits: latter of commit service period date and parent commit start date\n- Rollover commits: when the new contract started\n" }, "created_by": { "type": "string", "description": "The actor who created this commit. Omitted for system-generated commits such as recurring commits, rollover commits, and threshold commits." } } }, "HistoricalBalance": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Commit" }, { "$ref": "#/components/schemas/HistoricalBalanceFields" } ] }, { "allOf": [ { "$ref": "#/components/schemas/Credit" }, { "$ref": "#/components/schemas/HistoricalBalanceFields" } ] } ] }, "HistoricalBalanceFields": { "type": "object", "required": [ "retired_at", "balance" ], "properties": { "retired_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when the balance became historical." }, "balance": { "type": "number", "description": "The current computed balance of the historical commit or credit. This may change when invoices are voided and regenerated." } } }, "Credit": { "type": "object", "required": [ "id", "type", "product" ], "properties": { "id": { "type": "string", "format": "uuid" }, "contract": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } }, "type": { "type": "string", "enum": [ "CREDIT" ] }, "name": { "type": "string" }, "priority": { "type": "number", "description": "If multiple credits or commits are applicable, the one with the lower priority will apply first." }, "product": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "access_schedule": { "$ref": "#/components/schemas/ScheduleDuration", "description": "The schedule that the customer will gain access to the credits." }, "description": { "type": "string" }, "recurring_credit_id": { "type": "string", "format": "uuid", "description": "The ID of the recurring credit that this credit was generated from, if applicable." }, "subscription_config": { "type": "object", "properties": { "subscription_id": { "type": "string", "format": "uuid" }, "allocation": { "$ref": "#/components/schemas/SubscriptionConfigAllocation" }, "apply_seat_increase_config": { "$ref": "#/components/schemas/ApplySeatIncreaseConfigForRecurringCommit" }, "access_policy": { "x-stainless-skip": true, "type": "string", "enum": [ "BILLING_PERIOD_PAID", "INITIAL_BILLING_PERIOD_PAID_ONLY" ], "x-mint": { "groups": [ "ff:payment-gated-subscriptions-enabled" ] }, "description": "Controls when a customer can access this credit when the attached subscription is payment-gated. `BILLING_PERIOD_PAID` releases the credit after payment for its billing period. `INITIAL_BILLING_PERIOD_PAID_ONLY` releases the credit after the first payment." } }, "description": "The subscription configuration for this credit, if it was generated from a recurring credit with a subscription attached." }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "applicable_product_tags": { "type": "array", "items": { "type": "string" } }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown.", "items": { "$ref": "#/components/schemas/CommitSpecifier" } }, "applicable_contract_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "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." }, "ledger": { "type": "array", "items": { "$ref": "#/components/schemas/CreditLedger" }, "description": "A list of ordered events that impact the balance of a credit. For example, an invoice deduction or an expiration." }, "balance": { "$ref": "#/components/schemas/BalanceForCommitsAndCredits" }, "custom_fields": { "x-cf-entity": "contract_credit", "$ref": "#/components/schemas/CustomField" }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "LIST_RATE" ] }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKeyForCommitsAndCredits" }, "hierarchy_configuration": { "$ref": "#/components/schemas/CommitHierarchyConfiguration", "description": "Optional configuration for credit hierarchy access control" }, "rolled_over_from": { "type": "object", "required": [ "contract_id", "credit_id" ], "properties": { "credit_id": { "type": "string", "format": "uuid" }, "contract_id": { "type": "string", "format": "uuid" } } }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the credit was created.\n- Recurring credit: latter of credit service period date and parent credit start date\n- Rollover credit: when the new contract started\n" }, "created_by": { "type": "string", "description": "The actor who created this credit. Omitted for system-generated credits such as recurring credits." } } }, "SeatBalance": { "type": "object", "required": [ "seat_id", "balances" ], "properties": { "seat_id": { "type": "string", "description": "The unique identifier for the seat" }, "balances": { "type": "array", "items": { "$ref": "#/components/schemas/SeatBalanceByCreditType" } }, "commits": { "type": "array", "nullable": true, "description": "Array of commits applicable to this seat with their balances", "items": { "$ref": "#/components/schemas/SeatCommitBalance" } }, "credits": { "type": "array", "description": "Array of credits applicable to this seat with their balances", "items": { "$ref": "#/components/schemas/SeatCreditBalance" } } } }, "SeatBalanceByCreditType": { "type": "object", "required": [ "credit_type_id", "balance", "starting_balance" ], "properties": { "access_type": { "type": "string", "enum": [ "SPEND", "QUANTITY" ], "description": "Indicates how the balance is drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used." }, "credit_type_id": { "type": "string", "format": "uuid", "description": "This ID identifies the credit type for the balance. Quantity-based balances return the null credit type UUID." }, "balance": { "type": "number", "description": "The total balance across all commits and credits for this seat, of this credit type." }, "starting_balance": { "type": "number", "description": "The total initial balances of all commits and credits for this seat, of this credit type." } } }, "SeatCommitBalance": { "type": "object", "required": [ "id", "balance", "start_date" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The commit or credit ID" }, "access_type": { "type": "string", "enum": [ "SPEND", "QUANTITY" ], "description": "Indicates how the balance is drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used." }, "credit_type_id": { "type": "string", "format": "uuid", "description": "The credit type for this commit. Quantity-based commits return the null credit type UUID." }, "balance": { "type": "number", "description": "The current balance for this commit for this specific seat" }, "start_date": { "type": "string", "format": "date-time", "description": "The datetime when the commit becomes active" }, "end_date": { "type": "string", "format": "date-time", "nullable": true, "description": "The datetime when the commit expires" }, "ledger_entries": { "type": "array", "items": { "$ref": "#/components/schemas/SeatBalanceCommitLedger" }, "description": "Transaction history for this commit for this seat (only included if include_ledgers=true)" } } }, "SeatCreditBalance": { "type": "object", "required": [ "id", "balance", "start_date" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The credit ID" }, "access_type": { "type": "string", "enum": [ "SPEND", "QUANTITY" ], "description": "Indicates how the balance is drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used." }, "credit_type_id": { "type": "string", "format": "uuid", "description": "The credit type for this credit. Quantity-based credits return the null credit type UUID." }, "balance": { "type": "number", "description": "The current balance for this credit for this specific seat" }, "start_date": { "type": "string", "format": "date-time", "description": "The datetime when the credit becomes active" }, "end_date": { "type": "string", "format": "date-time", "nullable": true, "description": "The datetime when the credit expires" }, "ledger_entries": { "type": "array", "items": { "$ref": "#/components/schemas/SeatBalanceCreditLedger" }, "description": "Transaction history for this credit for this seat (only included if include_ledgers=true)" } } }, "SeatBalanceCommitLedger": { "type": "object", "required": [ "type", "amount", "timestamp" ], "properties": { "type": { "$ref": "#/components/schemas/SeatBalanceCommitLedgerEntryType", "description": "Commit ledger type" }, "amount": { "type": "number", "description": "Amount of the ledger entry" }, "timestamp": { "type": "string", "format": "date-time", "description": "The datetime when the ledger is created" } } }, "SeatBalanceCreditLedger": { "type": "object", "required": [ "type", "amount", "timestamp" ], "properties": { "type": { "$ref": "#/components/schemas/SeatBalanceCreditLedgerEntryType", "description": "Credit ledger type" }, "amount": { "type": "number", "description": "Amount of the ledger entry" }, "timestamp": { "type": "string", "format": "date-time", "description": "The datetime when the ledger is created" } } }, "CommitLedger": { "oneOf": [ { "$ref": "#/components/schemas/PrepaidCommitSegmentStartLedgerEntry" }, { "$ref": "#/components/schemas/PrepaidCommitAutomatedInvoiceDeductionLedgerEntry" }, { "$ref": "#/components/schemas/PrepaidCommitRolloverLedgerEntry" }, { "$ref": "#/components/schemas/PrepaidCommitExpirationLedgerEntry" }, { "$ref": "#/components/schemas/PrepaidCommitCanceledLedgerEntry", "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] } }, { "$ref": "#/components/schemas/PrepaidCommitCreditedLedgerEntry", "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] } }, { "$ref": "#/components/schemas/PrepaidCommitSeatBasedAdjustmentLedgerEntry" }, { "$ref": "#/components/schemas/PostpaidCommitInitialBalanceLedgerEntry" }, { "$ref": "#/components/schemas/PostpaidCommitAutomatedInvoiceDeductionLedgerEntry" }, { "$ref": "#/components/schemas/PostpaidCommitRolloverLedgerEntry" }, { "$ref": "#/components/schemas/PostpaidCommitTrueupLedgerEntry" }, { "$ref": "#/components/schemas/PrepaidCommitManualLedgerEntry" }, { "$ref": "#/components/schemas/PostpaidCommitManualLedgerEntry" }, { "$ref": "#/components/schemas/PostpaidCommitExpirationLedgerEntry" } ] }, "CreditLedger": { "oneOf": [ { "$ref": "#/components/schemas/CreditSegmentStartLedgerEntry" }, { "$ref": "#/components/schemas/CreditAutomatedInvoiceDeductionLedgerEntry" }, { "$ref": "#/components/schemas/CreditExpirationLedgerEntry" }, { "$ref": "#/components/schemas/CreditCanceledLedgerEntry", "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] } }, { "$ref": "#/components/schemas/CreditCreditedLedgerEntry", "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] } }, { "$ref": "#/components/schemas/CreditManualLedgerEntry" }, { "$ref": "#/components/schemas/CreditSeatBasedAdjustmentLedgerEntry" }, { "$ref": "#/components/schemas/CreditRolloverLedgerEntry" } ] }, "CreditRolloverLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "new_contract_id", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "CREDIT_ROLLOVER" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" }, "new_contract_id": { "type": "string", "format": "uuid" } } }, "PrepaidCommitSegmentStartLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "PREPAID_COMMIT_SEGMENT_START" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" } } }, "PrepaidCommitAutomatedInvoiceDeductionLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "invoice_id", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "contract_id": { "x-mint": { "groups": [ "client_id:11db091c-975b-4908-9f67-b1ceb126acdf" ] }, "type": "string", "format": "uuid" } } }, "PrepaidCommitRolloverLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "new_contract_id", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "PREPAID_COMMIT_ROLLOVER" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" }, "new_contract_id": { "type": "string", "format": "uuid" } } }, "PrepaidCommitExpirationLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "PREPAID_COMMIT_EXPIRATION" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" } } }, "PrepaidCommitCanceledLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "invoice_id", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "PREPAID_COMMIT_CANCELED" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "contract_id": { "x-mint": { "groups": [ "client_id:11db091c-975b-4908-9f67-b1ceb126acdf" ] }, "type": "string", "format": "uuid" } } }, "PrepaidCommitCreditedLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "invoice_id", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "PREPAID_COMMIT_CREDITED" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "contract_id": { "x-mint": { "groups": [ "client_id:11db091c-975b-4908-9f67-b1ceb126acdf" ] }, "type": "string", "format": "uuid" } } }, "PrepaidCommitSeatBasedAdjustmentLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "PREPAID_COMMIT_SEAT_BASED_ADJUSTMENT" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" } } }, "PostpaidCommitAutomatedInvoiceDeductionLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "invoice_id", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "POSTPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "contract_id": { "x-mint": { "groups": [ "client_id:11db091c-975b-4908-9f67-b1ceb126acdf" ] }, "type": "string", "format": "uuid" } } }, "PostpaidCommitInitialBalanceLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount" ], "properties": { "type": { "type": "string", "enum": [ "POSTPAID_COMMIT_INITIAL_BALANCE" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" } } }, "PostpaidCommitRolloverLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "new_contract_id", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "POSTPAID_COMMIT_ROLLOVER" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" }, "new_contract_id": { "type": "string", "format": "uuid" } } }, "PostpaidCommitTrueupLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "invoice_id" ], "properties": { "type": { "type": "string", "enum": [ "POSTPAID_COMMIT_TRUEUP" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "invoice_id": { "type": "string", "format": "uuid" }, "contract_id": { "x-mint": { "groups": [ "client_id:11db091c-975b-4908-9f67-b1ceb126acdf" ] }, "type": "string", "format": "uuid" } } }, "PrepaidCommitManualLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "reason" ], "properties": { "type": { "type": "string", "enum": [ "PREPAID_COMMIT_MANUAL" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "reason": { "type": "string" } } }, "PostpaidCommitExpirationLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount" ], "properties": { "type": { "type": "string", "enum": [ "POSTPAID_COMMIT_EXPIRATION" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" } } }, "PostpaidCommitManualLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "reason" ], "properties": { "type": { "type": "string", "enum": [ "POSTPAID_COMMIT_MANUAL" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "reason": { "type": "string" } } }, "CreditSegmentStartLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "CREDIT_SEGMENT_START" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" } } }, "CreditAutomatedInvoiceDeductionLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "invoice_id", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "CREDIT_AUTOMATED_INVOICE_DEDUCTION" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "contract_id": { "x-mint": { "groups": [ "client_id:11db091c-975b-4908-9f67-b1ceb126acdf" ] }, "type": "string", "format": "uuid" } } }, "CreditExpirationLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "CREDIT_EXPIRATION" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" } } }, "CreditCanceledLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "invoice_id", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "CREDIT_CANCELED" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "contract_id": { "x-mint": { "groups": [ "client_id:11db091c-975b-4908-9f67-b1ceb126acdf" ] }, "type": "string", "format": "uuid" } } }, "CreditCreditedLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "invoice_id", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "CREDIT_CREDITED" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid" }, "contract_id": { "x-mint": { "groups": [ "client_id:11db091c-975b-4908-9f67-b1ceb126acdf" ] }, "type": "string", "format": "uuid" } } }, "CreditManualLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "reason" ], "properties": { "type": { "type": "string", "enum": [ "CREDIT_MANUAL" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "reason": { "type": "string" } } }, "CreditSeatBasedAdjustmentLedgerEntry": { "type": "object", "required": [ "type", "timestamp", "amount", "segment_id" ], "properties": { "type": { "type": "string", "enum": [ "CREDIT_SEAT_BASED_ADJUSTMENT" ] }, "timestamp": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "segment_id": { "type": "string", "format": "uuid" } } }, "ApplySeatIncreaseConfigForRecurringCommit": { "type": "object", "required": [ "is_prorated" ], "properties": { "is_prorated": { "type": "boolean", "description": "Indicates whether a mid-period seat increase should be prorated." } } }, "SubscriptionConfigAllocation": { "type": "string", "enum": [ "INDIVIDUAL", "POOLED" ] }, "SubscriptionConfigAllocationInput": { "type": "string", "enum": [ "INDIVIDUAL", "POOLED" ], "description": "If set to POOLED, allocation added per seat is pooled across the account. If set to INDIVIDUAL, each seat in the subscription will have its own allocation." }, "RecurringCommitSubscriptionConfig": { "type": "object", "required": [ "allocation", "apply_seat_increase_config", "subscription_id" ], "properties": { "allocation": { "$ref": "#/components/schemas/SubscriptionConfigAllocation" }, "apply_seat_increase_config": { "$ref": "#/components/schemas/ApplySeatIncreaseConfigForRecurringCommit" }, "subscription_id": { "type": "string", "format": "uuid" }, "access_policy": { "x-stainless-skip": true, "type": "string", "enum": [ "BILLING_PERIOD_PAID", "INITIAL_BILLING_PERIOD_PAID_ONLY" ], "x-mint": { "groups": [ "ff:payment-gated-subscriptions-enabled" ] }, "description": "Controls when a customer can access recurring commit or credit child balances when the attached subscription is payment-gated. `BILLING_PERIOD_PAID` releases each balance after payment for its billing period. `INITIAL_BILLING_PERIOD_PAID_ONLY` releases all balances after the first payment." } } }, "RecurringCommitSubscriptionConfigInput": { "type": "object", "required": [ "apply_seat_increase_config", "subscription_id" ], "properties": { "allocation": { "$ref": "#/components/schemas/SubscriptionConfigAllocationInput" }, "apply_seat_increase_config": { "$ref": "#/components/schemas/ApplySeatIncreaseConfigForRecurringCommit" }, "subscription_id": { "type": "string", "description": "ID of the subscription to configure on the recurring commit/credit." }, "access_policy": { "x-stainless-skip": true, "type": "string", "enum": [ "BILLING_PERIOD_PAID", "INITIAL_BILLING_PERIOD_PAID_ONLY" ], "x-mint": { "groups": [ "ff:payment-gated-subscriptions-enabled" ] }, "description": "Controls when a customer can access recurring commit or credit child balances when the attached subscription is payment-gated. `BILLING_PERIOD_PAID` releases each balance after payment for its billing period. `INITIAL_BILLING_PERIOD_PAID_ONLY` releases all balances after the first payment." } } }, "ExcludeSpecifier": { "type": "object", "properties": { "product_tags": { "type": "array", "items": { "type": "string" }, "description": "If provided, the specifier will not apply to products with all the specified tags." } } }, "CommitSpecifier": { "type": "object", "properties": { "product_id": { "type": "string", "format": "uuid", "description": "If provided, the specifier will only apply to the product with the specified ID." }, "product_tags": { "type": "array", "items": { "type": "string" }, "description": "If provided, the specifier will only apply to products with all the specified tags." }, "pricing_group_values": { "type": "object", "additionalProperties": { "type": "string" } }, "presentation_group_values": { "type": "object", "additionalProperties": { "type": "string" } }, "exclude": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:exclude-specifiers-ga" ] }, "type": "array", "description": "If provided, the specifier will not apply to product usage that matches the inclusion criteria and any of the excluding values.", "items": { "$ref": "#/components/schemas/ExcludeSpecifier" } } } }, "CommitSpecifierInput": { "type": "object", "properties": { "product_id": { "type": "string", "format": "uuid", "description": "If provided, the specifier will only apply to the product with the specified ID." }, "product_tags": { "type": "array", "items": { "type": "string" }, "description": "If provided, the specifier will only apply to products with all the specified tags." }, "pricing_group_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "If provided, the specifier will apply to product usage with these set of pricing group values." }, "presentation_group_values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "If provided, the specifier will apply to product usage with these set of presentation group values." }, "exclude": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:exclude-specifiers-ga" ] }, "type": "array", "description": "If provided, the specifier will not apply to product usage that matches the inclusion criteria and any of the excluding values.", "items": { "$ref": "#/components/schemas/ExcludeSpecifier" } } } }, "OverrideInput": { "type": "object", "required": [ "starting_at" ], "properties": { "starting_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when the override will start applying (inclusive)" }, "ending_before": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when the override will stop applying (exclusive)" }, "entitled": { "type": "boolean" }, "type": { "type": "string", "enum": [ "OVERWRITE", "overwrite", "MULTIPLIER", "multiplier", "TIERED", "tiered" ], "description": "Overwrites are prioritized over multipliers and tiered overrides." }, "multiplier": { "type": "number", "description": "Required for MULTIPLIER type. Must be >=0." }, "priority": { "type": "number", "description": "Required for EXPLICIT multiplier prioritization scheme and all TIERED overrides. Under EXPLICIT prioritization, overwrites are prioritized first, and then tiered and multiplier overrides are prioritized by their priority value (lowest first). Must be > 0." }, "overwrite_rate": { "$ref": "#/components/schemas/OverwriteRateInput", "description": "Required for OVERWRITE type." }, "product_id": { "type": "string", "format": "uuid", "description": "ID of the product whose rate is being overridden. Cannot be used in conjunction with override_specifiers." }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "tags identifying products whose rates are being overridden. Cannot be used in conjunction with override_specifiers." }, "override_specifiers": { "type": "array", "items": { "$ref": "#/components/schemas/OverrideSpecifierInput" }, "description": "Cannot be used in conjunction with product_id or applicable_product_tags. If provided, the override will apply to all products with the specified specifiers." }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/OverrideTierInput" }, "description": "Required for TIERED type. Must have at least one tier." }, "is_commit_specific": { "type": "boolean", "description": "Indicates whether the override should only apply to commits. Defaults to `false`. If `true` you can specify relevant commits in `override_specifiers` by passing `commit_ids`, `recurring_commit_ids`, or `any_commit_or_credit_ids`. If you do not specify any of these fields, the override will apply when consuming any prepaid commit, postpaid commit, or credit" }, "target": { "type": "string", "enum": [ "COMMIT_RATE", "commit_rate", "LIST_RATE", "list_rate" ], "description": "Indicates whether the override applies to commit rates or list rates. Can only be used for overrides that have `is_commit_specific` set to `true`. Defaults to `\"LIST_RATE\"`." } } }, "Override": { "type": "object", "required": [ "id", "created_at", "starting_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "product": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "applicable_product_tags": { "type": "array", "items": { "type": "string" } }, "override_specifiers": { "type": "array", "items": { "$ref": "#/components/schemas/OverrideSpecifier" } }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "entitled": { "type": "boolean" }, "type": { "type": "string", "enum": [ "OVERWRITE", "MULTIPLIER", "TIERED" ] }, "priority": { "type": "number" }, "multiplier": { "type": "number" }, "overwrite_rate": { "$ref": "#/components/schemas/OverwriteRate" }, "override_tiers": { "type": "array", "items": { "$ref": "#/components/schemas/OverrideTier" } }, "is_commit_specific": { "type": "boolean" }, "target": { "type": "string", "enum": [ "COMMIT_RATE", "LIST_RATE" ] }, "rate_type": { "type": "string", "enum": [ "FLAT", "flat", "PERCENTAGE", "percentage", "SUBSCRIPTION", "subscription", "TIERED", "tiered", "TIERED_PERCENTAGE", "tiered_percentage", "CUSTOM", "custom" ], "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" ] } }, "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." }, "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." }, "value": { "type": "object", "additionalProperties": true, "description": "Only set for CUSTOM rate_type. This field is interpreted by custom rate processors." }, "credit_type": { "$ref": "#/components/schemas/CreditType" } } }, "DiscountInput": { "type": "object", "required": [ "product_id", "schedule" ], "properties": { "product_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "description": "displayed on invoices" }, "schedule": { "$ref": "#/components/schemas/SchedulePointInTimeInput" }, "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." }, "custom_fields": { "x-cf-entity": "discount", "$ref": "#/components/schemas/CustomField" } } }, "Discount": { "type": "object", "required": [ "id", "product", "schedule" ], "properties": { "id": { "type": "string", "format": "uuid" }, "product": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "schedule": { "$ref": "#/components/schemas/SchedulePointInTime" }, "name": { "type": "string", "minLength": 1 }, "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." }, "custom_fields": { "x-cf-entity": "discount", "$ref": "#/components/schemas/CustomField" } } }, "PrepaidBalanceDiscountCap": { "type": "object", "required": [ "spend_tracker_alias", "amount" ], "properties": { "spend_tracker_alias": { "type": "string", "description": "Alias of the spend tracker this cap is measured against." }, "amount": { "type": "number", "description": "Accumulated spend ceiling above which the discount stops applying." } } }, "DiscountConfiguration": { "type": "object", "required": [ "payment_fraction" ], "properties": { "payment_fraction": { "type": "number", "description": "The fraction of the original amount that the customer pays after applying the discount. For example, 0.85 means the customer pays 85% of the original amount (a 15% discount)." }, "cap": { "x-mint": { "groups": [ "ff:threshold-billing-discounts" ] }, "allOf": [ { "$ref": "#/components/schemas/PrepaidBalanceDiscountCap" } ], "description": "If provided, the discount stops applying once the spend tracker has accumulated this much spend in the billing period." } } }, "ProServiceInput": { "type": "object", "required": [ "product_id", "unit_price", "quantity", "max_amount" ], "properties": { "description": { "type": "string" }, "product_id": { "type": "string", "format": "uuid" }, "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." }, "unit_price": { "type": "number", "description": "Unit price for the charge. Will be multiplied by quantity to determine the amount and must be specified." }, "quantity": { "type": "number", "description": "Quantity for the charge. Will be multiplied by unit_price to determine the amount." }, "max_amount": { "type": "number", "description": "Maximum amount for the term." }, "custom_fields": { "x-cf-entity": "professional_service", "$ref": "#/components/schemas/CustomField" } } }, "ProService": { "type": "object", "required": [ "id", "product_id", "unit_price", "quantity", "max_amount" ], "properties": { "id": { "type": "string", "format": "uuid" }, "description": { "type": "string" }, "product_id": { "type": "string", "format": "uuid" }, "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." }, "unit_price": { "type": "number", "description": "Unit price for the charge. Will be multiplied by quantity to determine the amount and must be specified." }, "quantity": { "type": "number", "description": "Quantity for the charge. Will be multiplied by unit_price to determine the amount." }, "max_amount": { "type": "number", "description": "Maximum amount for the term." }, "custom_fields": { "x-cf-entity": "professional_service", "$ref": "#/components/schemas/CustomField" } } }, "ScheduledChargeInput": { "type": "object", "required": [ "product_id", "schedule" ], "properties": { "product_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "description": "displayed on invoices" }, "schedule": { "$ref": "#/components/schemas/SchedulePointInTimeInput" }, "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." }, "custom_fields": { "x-cf-entity": "scheduled_charge", "$ref": "#/components/schemas/CustomField" } } }, "ScheduledCharge": { "type": "object", "required": [ "id", "product", "schedule" ], "properties": { "id": { "type": "string", "format": "uuid" }, "product": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "schedule": { "$ref": "#/components/schemas/SchedulePointInTime" }, "name": { "type": "string", "minLength": 1, "description": "displayed on invoices" }, "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." }, "custom_fields": { "x-cf-entity": "scheduled_charge", "$ref": "#/components/schemas/CustomField" }, "archived_at": { "type": "string", "format": "date-time" } } }, "ScheduleDurationInput": { "type": "object", "required": [ "schedule_items" ], "properties": { "access_type": { "type": "string", "enum": [ "SPEND", "spend", "QUANTITY", "quantity" ], "description": "Determines how the balance is drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used. Defaults to `SPEND` if omitted." }, "credit_type_id": { "type": "string", "format": "uuid", "description": "Defaults to USD (cents) if not passed" }, "schedule_items": { "type": "array", "items": { "type": "object", "required": [ "amount", "starting_at", "ending_before" ], "properties": { "amount": { "type": "number" }, "starting_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp (inclusive)" }, "ending_before": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp (exclusive)" } } } } } }, "ScheduleDuration": { "type": "object", "required": [ "schedule_items" ], "properties": { "access_type": { "type": "string", "enum": [ "SPEND", "QUANTITY" ], "description": "Indicates how the balance is drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used." }, "credit_type": { "$ref": "#/components/schemas/CreditType" }, "schedule_items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "starting_at", "ending_before" ], "properties": { "id": { "type": "string", "format": "uuid" }, "amount": { "type": "number" }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" } } } } } }, "SchedulePointInTimeInput": { "type": "object", "description": "Must provide either schedule_items or recurring_schedule.", "properties": { "credit_type_id": { "type": "string", "format": "uuid", "description": "Defaults to USD (cents) if not passed." }, "schedule_items": { "type": "array", "description": "Either provide amount or provide both unit_price and quantity.", "items": { "type": "object", "required": [ "timestamp" ], "properties": { "unit_price": { "type": "number", "description": "Unit price for the charge. Will be multiplied by quantity to determine the amount and must be specified with quantity. If specified amount cannot be provided." }, "quantity": { "type": "number", "description": "Quantity for the charge. Will be multiplied by unit_price to determine the amount and must be specified with unit_price. If specified amount cannot be provided." }, "amount": { "type": "number", "description": "Amount for the charge. Can be provided instead of unit_price and quantity. If amount is sent, the unit_price is assumed to be the amount and quantity is inferred to be 1." }, "timestamp": { "type": "string", "format": "date-time", "description": "timestamp of the scheduled event" } } } }, "recurring_schedule": { "type": "object", "description": "Enter the unit price and quantity for the charge or instead only send the amount. If amount is sent, the unit price is assumed to be the amount and quantity is inferred to be 1.", "required": [ "starting_at", "ending_before", "frequency", "amount_distribution" ], "properties": { "starting_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp (inclusive)." }, "ending_before": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp (exclusive)." }, "frequency": { "$ref": "#/components/schemas/RecurringScheduleFrequency" }, "unit_price": { "type": "number", "description": "Unit price for the charge. Will be multiplied by quantity to determine the amount and must be specified with quantity. If specified amount cannot be provided." }, "quantity": { "type": "number", "description": "Quantity for the charge. Will be multiplied by unit_price to determine the amount and must be specified with unit_price. If specified amount cannot be provided." }, "amount": { "type": "number", "description": "Amount for the charge. Can be provided instead of unit_price and quantity. If amount is sent, the unit_price is assumed to be the amount and quantity is inferred to be 1." }, "amount_distribution": { "type": "string", "enum": [ "DIVIDED", "divided", "DIVIDED_ROUNDED", "divided_rounded", "EACH", "each" ] } } }, "do_not_invoice": { "type": "boolean", "description": "This field is only applicable to commit invoice schedules. If true, this schedule will not generate an invoice.", "default": false } } }, "SchedulePointInTime": { "type": "object", "properties": { "credit_type": { "$ref": "#/components/schemas/CreditType" }, "schedule_items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount", "unit_price", "quantity", "timestamp" ], "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid", "nullable": true }, "amount": { "type": "number" }, "unit_price": { "type": "number" }, "quantity": { "type": "number" }, "timestamp": { "type": "string", "format": "date-time" } } } }, "do_not_invoice": { "type": "boolean", "description": "This field is only applicable to commit invoice schedules. If true, this schedule will not generate an invoice.", "default": false } } }, "ThresholdBalanceSpecifier": { "type": "object", "required": [ "exclude" ], "properties": { "exclude": { "type": "array", "description": "If any of the exclude specifier is met, the balance is not considered when evaluating threshold billing", "items": { "$ref": "#/components/schemas/ExcludeThresholdBalanceSpecifier" } } } }, "ExcludeThresholdBalanceSpecifier": { "type": "object", "required": [ "custom_field_filters" ], "properties": { "custom_field_filters": { "type": "array", "description": "If provided, balances with all the custom fields will not be considered when evaluating threshold billing", "items": { "$ref": "#/components/schemas/BalanceCustomFieldFilterType" } } } }, "ResellerType": { "type": "string", "enum": [ "AWS", "AWS_PRO_SERVICE", "GCP", "GCP_PRO_SERVICE" ] }, "ResellerRoyaltyInput": { "type": "object", "required": [ "reseller_type", "starting_at", "fraction", "netsuite_reseller_id" ], "properties": { "reseller_type": { "$ref": "#/components/schemas/ResellerType" }, "fraction": { "type": "number" }, "netsuite_reseller_id": { "type": "string" }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Must provide at least one of applicable_product_ids or applicable_product_tags." }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "Must provide at least one of applicable_product_ids or applicable_product_tags." }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "reseller_contract_value": { "type": "number" }, "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" } } } } }, "ResellerRoyaltyOrUpdateInput": { "type": "object", "required": [ "reseller_type" ], "properties": { "reseller_type": { "$ref": "#/components/schemas/ResellerType" }, "fraction": { "type": "number" }, "netsuite_reseller_id": { "type": "string" }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Must provide at least one of applicable_product_ids or applicable_product_tags." }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "Must provide at least one of applicable_product_ids or applicable_product_tags." }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "description": "Use null to indicate that the existing end timestamp should be removed.", "type": "string", "nullable": true, "format": "date-time" }, "reseller_contract_value": { "type": "number" }, "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" } } } } }, "ResellerRoyalty": { "type": "object", "required": [ "reseller_type", "starting_at", "fraction", "netsuite_reseller_id" ], "properties": { "reseller_type": { "$ref": "#/components/schemas/ResellerType" }, "fraction": { "type": "number" }, "applicable_product_tags": { "type": "array", "items": { "type": "string" } }, "applicable_product_ids": { "type": "array", "items": { "type": "string" } }, "netsuite_reseller_id": { "type": "string" }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "reseller_contract_value": { "type": "number" }, "aws_account_number": { "type": "string" }, "aws_payer_reference_id": { "type": "string" }, "aws_offer_id": { "type": "string" }, "gcp_account_id": { "type": "string" }, "gcp_offer_id": { "type": "string" } } }, "ResellerRoyaltyOrUpdate": { "type": "object", "required": [ "reseller_type" ], "properties": { "reseller_type": { "$ref": "#/components/schemas/ResellerType" }, "fraction": { "type": "number" }, "netsuite_reseller_id": { "type": "string" }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time", "nullable": true }, "reseller_contract_value": { "type": "number" }, "aws_account_number": { "type": "string" }, "aws_payer_reference_id": { "type": "string" }, "aws_offer_id": { "type": "string" }, "gcp_account_id": { "type": "string" }, "gcp_offer_id": { "type": "string" } } }, "ContractTransitionInput": { "type": "object", "required": [ "type", "from_contract_id" ], "properties": { "type": { "type": "string", "enum": [ "RENEWAL", "renewal" ], "description": "This field's available values may vary based on your client's configuration." }, "from_contract_id": { "type": "string", "format": "uuid" }, "future_invoice_behavior": { "type": "object", "properties": { "trueup": { "type": "string", "enum": [ "remove", "as_is", "REMOVE", "AS_IS" ], "nullable": true, "description": "Controls whether future trueup invoices are billed or removed. Default behavior is AS_IS if not specified." } } } } }, "AddManualBalanceLedgerEntryPayload": { "type": "object", "required": [ "customer_id", "id", "segment_id", "amount", "reason" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer whose balance is to be updated." }, "contract_id": { "type": "string", "format": "uuid", "description": "ID of the contract to update. Leave blank to update a customer level balance." }, "id": { "type": "string", "format": "uuid", "description": "ID of the balance (commit or credit) to update." }, "segment_id": { "type": "string", "format": "uuid", "description": "ID of the segment to update." }, "amount": { "type": "number", "description": "Amount to add to the segment. A negative number will draw down from the balance." }, "per_group_amounts": { "type": "object", "additionalProperties": { "type": "number" }, "description": "If using individually configured commits/credits attached to seat managed subscriptions, the amount to add for each seat. Must sum to total amount." }, "reason": { "type": "string", "description": "Reason for the manual adjustment. This will be displayed in the ledger." }, "timestamp": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when the manual adjustment takes place. If not provided, it will default to the start of the segment." }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKey" } } }, "UpdateInvoiceIssueDatePayload": { "type": "object", "required": [ "invoice_id", "issue_date" ], "properties": { "invoice_id": { "type": "string", "format": "uuid", "description": "ID of the invoice to update. The invoice must still be in DRAFT status." }, "issue_date": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp. This will be the new issue date of the invoice. It must not be after the end date of the contract." } } }, "UpdateContractEndDatePayload": { "type": "object", "required": [ "customer_id", "contract_id" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer whose contract is to be updated" }, "contract_id": { "type": "string", "format": "uuid", "description": "ID of the contract to update" }, "ending_before": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when the contract will end (exclusive). If not provided, the contract will be updated to be open-ended." }, "allow_ending_before_finalized_invoice": { "type": "boolean", "description": "If true, allows setting the contract end date earlier than the end_timestamp of existing finalized invoices. Finalized invoices will be unchanged; if you want to incorporate the new end date, you can void and regenerate finalized usage invoices. Defaults to true." } } }, "UpdateCommitEndDatePayload": { "type": "object", "required": [ "customer_id", "commit_id" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer whose commit is to be updated" }, "commit_id": { "type": "string", "format": "uuid", "description": "ID of the commit to update. Only supports \"PREPAID\" commits." }, "access_ending_before": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when access to the commit will end and it will no longer be possible to draw it down (exclusive). If not provided, the access will not be updated." }, "invoices_ending_before": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when the commit will stop being invoiced (exclusive). If not provided, the invoice schedule will not be updated." } } }, "UpdateCreditEndDatePayload": { "type": "object", "required": [ "customer_id", "credit_id", "access_ending_before" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer whose credit is to be updated" }, "credit_id": { "type": "string", "format": "uuid", "description": "ID of the commit to update" }, "access_ending_before": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when access to the credit will end and it will no longer be possible to draw it down (exclusive)." } } }, "ExternalPaymentGateThresholdCommitPayload": { "type": "object", "required": [ "workflow_id", "outcome" ], "properties": { "workflow_id": { "type": "string", "format": "uuid", "description": "ID of the workflow to continue" }, "outcome": { "type": "string", "enum": [ "paid", "PAID", "failed", "FAILED" ], "description": "The outcome of the external payment gate" } } }, "DisableCommitTrueupPayload": { "type": "object", "required": [ "customer_id", "commit_id", "contract_id" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer whose commit is to be updated" }, "commit_id": { "type": "string", "format": "uuid", "description": "ID of the commit to update" }, "contract_id": { "type": "string", "format": "uuid", "description": "ID of the contract that the commit is on" }, "amendment_id": { "type": "string", "format": "uuid", "description": "If applicable, the amendment ID that the commit is on" } } }, "CustomerAndContract": { "required": [ "ingest_aliases", "customer_id", "customer_name", "contract_id" ], "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "the Metronome ID of the customer" }, "ingest_aliases": { "type": "array", "description": "aliases for this customer that can be used instead of the Metronome customer ID in usage events", "items": { "type": "string" } }, "customer_name": { "type": "string" }, "custom_fields": { "x-cf-entity": "customer", "$ref": "#/components/schemas/CustomField" }, "contract_id": { "type": "string", "format": "uuid" } } }, "SetCustomerBillableStatusPayload": { "type": "object", "required": [ "customer_id", "billable_status", "effective_at" ], "properties": { "customer_id": { "type": "string", "format": "uuid" }, "billable_status": { "$ref": "#/components/schemas/BillableStatus" }, "effective_at": { "type": "string", "format": "date-time", "description": "For usage invoices, any invoices where the service periods starts on or after this date will be included. For all other invoice types, only invoices where the issue_date falls on or after this date will be included." } } }, "CreateCustomerWithContractPayload": { "type": "object", "required": [ "contract", "customer" ], "properties": { "customer": { "$ref": "#/components/schemas/CreateCustomerPayload" }, "contract": { "type": "object", "required": [ "starting_at" ], "properties": { "name": { "type": "string" }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKey" }, "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" }, "rate_card_id": { "type": "string", "format": "uuid" }, "rate_card_alias": { "type": "string", "description": "Selects the rate card linked to the specified alias as of the contract's start date." }, "total_contract_value": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "number", "description": "This field's availability is dependent on your client's configuration." }, "starting_at": { "type": "string", "format": "date-time", "description": "inclusive contract start time" }, "ending_before": { "type": "string", "format": "date-time", "description": "exclusive contract end time" }, "commits": { "type": "array", "items": { "$ref": "#/components/schemas/CommitInput" } }, "credits": { "type": "array", "items": { "$ref": "#/components/schemas/CreditInput" } }, "recurring_commits": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringCommitInput" } }, "recurring_credits": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringCreditInput" } }, "multiplier_override_prioritization": { "type": "string", "enum": [ "LOWEST_MULTIPLIER", "lowest_multiplier", "EXPLICIT", "explicit" ], "description": "Defaults to LOWEST_MULTIPLIER, which applies the greatest discount to list prices automatically. EXPLICIT prioritization requires specifying priorities for each multiplier; the one with the lowest priority value will be prioritized first." }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/OverrideInput" } }, "discounts": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/DiscountInput" } }, "reseller_royalties": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/ResellerRoyaltyInput" } }, "professional_services": { "x-mint": { "groups": [ "client_id:e3147d6d-4101-4cd1-9888-ce3afeeac5b2" ] }, "type": "array", "description": "This field's availability is dependent on your client's configuration.", "items": { "$ref": "#/components/schemas/ProServiceInput" } }, "scheduled_charges": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledChargeInput" } }, "scheduled_charges_on_usage_invoices": { "$ref": "#/components/schemas/ScheduledChargesOnUsageInvoices" }, "usage_filter": { "$ref": "#/components/schemas/BaseUsageFilter" }, "usage_statement_schedule": { "$ref": "#/components/schemas/UsageStatementScheduleInput" }, "custom_fields": { "x-cf-entity": "contract_credit", "$ref": "#/components/schemas/CustomField" }, "billing_provider_configuration": { "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" ] }, "$ref": "#/components/schemas/CustomerBillingProviderConfigurationLookup" }, "spend_threshold_configuration": { "$ref": "#/components/schemas/SpendThresholdConfiguration" }, "prepaid_balance_threshold_configuration": { "$ref": "#/components/schemas/PrepaidBalanceThresholdConfiguration" }, "spend_trackers": { "x-mint": { "groups": [ "ff:tb-spend-trackers" ] }, "type": "array", "items": { "$ref": "#/components/schemas/SpendTrackerInput" }, "description": "Spend trackers to attach to this contract. Aliases must be unique within a contract." }, "subscriptions": { "$ref": "#/components/schemas/SubscriptionsInput" }, "hierarchy_configuration": { "$ref": "#/components/schemas/ContractHierarchyConfigurationInput" } } } } }, "CustomerBillingProviderConfiguration": { "type": "object", "required": [ "id", "billing_provider", "customer_id", "configuration", "delivery_method_id", "delivery_method", "delivery_method_configuration", "archived_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of this configuration; can be provided as the billing_provider_configuration_id when creating a contract." }, "billing_provider": { "$ref": "#/components/schemas/BillingProviderType", "description": "The billing provider set for this configuration." }, "customer_id": { "type": "string", "format": "uuid" }, "configuration": { "type": "object", "additionalProperties": true, "description": "Configuration for the billing provider. The structure of this object is specific to the billing provider." }, "delivery_method_id": { "type": "string", "format": "uuid", "description": "ID of the delivery method to use for this customer." }, "delivery_method": { "$ref": "#/components/schemas/BillingProviderDeliveryMethodType", "description": "The method to use for delivering invoices to this customer." }, "delivery_method_configuration": { "type": "object", "additionalProperties": true, "description": "Configuration for the delivery method. The structure of this object is specific to the delivery method." }, "archived_at": { "type": "string", "format": "date-time", "nullable": true } } }, "UnbillableInvoiceRule": { "type": "object", "description": "An individual rule that, when evaluated to true, indicates that any invoices for this billing provider will not be sent to its associated destination for the associated contract. Rules only apply to the specified `invoice_type` (or all invoices if omitted) and `fiat_credit_type_id` (or all invoices if omitted). Rule precedence is evaluated from more specific to less specific. This method will fail with a 400 if multiple rules with the same specificity are included.", "required": [ "invoice_type" ], "properties": { "invoice_type": { "type": "string", "enum": [ "USAGE", "SCHEDULED", "usage", "scheduled" ], "description": "The type of invoice this rule applies to." }, "fiat_credit_type_id": { "type": "string", "format": "uuid", "description": "Restricts the rule to invoices in this fiat currency. Omit for a catch-all rule that applies to every currency of the `invoice_type`. Required when `max_amount` is set." }, "max_amount": { "type": "number", "description": "A positive decimal, in the units of `fiat_credit_type_id`. Only invoices whose total is at or below this amount are suppressed; a higher total is still sent to the billing provider. When omitted, every matching invoice is suppressed regardless of amount." } }, "example": { "invoice_type": "USAGE", "fiat_credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2", "max_amount": 1000 } }, "CustomerBillingProviderConfigurationInput": { "type": "object", "properties": { "billing_provider": { "$ref": "#/components/schemas/BillingProviderType", "description": "The billing provider set for this configuration." }, "customer_id": { "type": "string", "format": "uuid" }, "tax_provider": { "x-mint": { "metadata": { "tag": "Beta" } }, "$ref": "#/components/schemas/TaxProviderType", "description": "Specifies which tax provider Metronome should use for tax calculation when billing through Stripe. This is only supported for Stripe billing provider configurations." }, "configuration": { "type": "object", "additionalProperties": true, "description": "Configuration for the billing provider. The structure of this object is specific to the billing provider and delivery method combination. Defaults to an empty object, however, for most billing provider + delivery method combinations, it will not be a valid configuration. For AWS marketplace configurations, the aws_is_subscription_product flag can be used to indicate a product with usage-based pricing. More information can be found [here](https://docs.metronome.com/invoice-customers/solutions/marketplaces/invoice-aws/#provision-aws-marketplace-customers-in-metronome).", "example": [ { "aws_customer_id": "cust_1234", "aws_product_code": "my_product", "aws_region": "us-west-1" }, { "azure_subscription_id": "my_subscription" }, { "gcp_entitlement_id": "my_entitlement", "gcp_service_name": "my_service" }, { "stripe_collection_method": "charge_automatically", "leave_stripe_invoices_in_draft": true }, { "netsuite_customer_id": "12345" } ] }, "delivery_method_id": { "type": "string", "format": "uuid", "description": "ID of the delivery method to use for this customer. If not provided, the `delivery_method` must be provided." }, "delivery_method": { "$ref": "#/components/schemas/BillingProviderDeliveryMethodType", "description": "The method to use for delivering invoices to this customer. If not provided, the `delivery_method_id` must be provided." } }, "required": [ "billing_provider", "customer_id" ] }, "CustomerBillingProviderArchivePayload": { "type": "object", "required": [ "customer_billing_provider_configuration_ids", "customer_id" ], "properties": { "customer_billing_provider_configuration_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Array of billing provider configuration IDs to archive" }, "customer_id": { "type": "string", "format": "uuid", "description": "The customer ID the billing provider configurations belong to" } } }, "CustomerBillingProviderConfigurationOutput": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the created configuration" }, "billing_provider": { "type": "string", "$ref": "#/components/schemas/BillingProviderType", "description": "The billing provider set for this configuration." }, "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer this configuration is associated with." }, "configuration": { "type": "object", "additionalProperties": true, "description": "Configuration for the billing provider. The structure of this object is specific to the billing provider and delivery method combination." }, "delivery_method_id": { "type": "string", "format": "uuid", "description": "ID of the delivery method used for this customer configuration." }, "tax_provider": { "$ref": "#/components/schemas/TaxProviderType", "description": "The tax provider set for this configuration." } } }, "BillingProviderDeliveryMethod": { "type": "object", "required": [ "billing_provider", "delivery_method_id", "delivery_method", "delivery_method_configuration" ], "properties": { "billing_provider": { "$ref": "#/components/schemas/BillingProviderType", "description": "The billing provider set for this configuration." }, "delivery_method_id": { "type": "string", "format": "uuid", "description": "ID of the delivery method to use for this customer." }, "delivery_method": { "$ref": "#/components/schemas/BillingProviderDeliveryMethodType", "description": "The method to use for delivering invoices to this customer." }, "delivery_method_configuration": { "type": "object", "additionalProperties": true, "description": "Configuration for the delivery method. The structure of this object is specific to the delivery method. Some configuration may be omitted for security reasons." } } }, "UpdateCustomerNamedSchedulePayload": { "type": "object", "required": [ "customer_id", "schedule_name", "starting_at", "value" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer whose named schedule is to be updated" }, "schedule_name": { "type": "string", "description": "The identifier for the schedule to be updated" }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "value": { "description": "The value to set for the named schedule. The structure of this object is specific to the named schedule." } } }, "GetCustomerNamedSchedulePayload": { "type": "object", "required": [ "customer_id", "schedule_name" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer whose named schedule is to be retrieved" }, "schedule_name": { "type": "string", "description": "The identifier for the schedule to be retrieved" }, "covering_date": { "type": "string", "format": "date-time", "description": "If provided, at most one schedule segment will be returned (the one that covers this date). If not provided, all segments will be returned." } } }, "UpdateContractNamedSchedulePayload": { "type": "object", "required": [ "customer_id", "contract_id", "schedule_name", "starting_at", "value" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer whose named schedule is to be updated" }, "contract_id": { "type": "string", "format": "uuid", "description": "ID of the contract whose named schedule is to be updated" }, "schedule_name": { "type": "string", "description": "The identifier for the schedule to be updated" }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "value": { "description": "The value to set for the named schedule. The structure of this object is specific to the named schedule." }, "properties": { "type": "object", "additionalProperties": { "type": "string" }, "description": "A set of key-value pairs that qualifies which schedule should be applied when looking up a schedule by name.", "x-stainless-skip": true, "x-mint": { "groups": [ "ff:fancy-schedules-enabled" ] } } } }, "GetContractNamedSchedulePayload": { "type": "object", "required": [ "customer_id", "contract_id", "schedule_name" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer whose named schedule is to be retrieved" }, "contract_id": { "type": "string", "format": "uuid", "description": "ID of the contract whose named schedule is to be retrieved" }, "schedule_name": { "type": "string", "description": "The identifier for the schedule to be retrieved" }, "covering_date": { "type": "string", "format": "date-time", "description": "If provided, at most one schedule segment will be returned (the one that covers this date). If not provided, all segments will be returned." }, "properties": { "type": "object", "additionalProperties": { "type": "string" }, "description": "A set of key-value pairs that qualifies which schedule should be applied when looking up a schedule by name.", "x-stainless-skip": true, "x-mint": { "groups": [ "ff:fancy-schedules-enabled" ] } } } }, "ListContractsNamedSchedulesPayload": { "type": "object", "x-stainless-skip": true, "x-mint": { "groups": [ "ff:fancy-schedules-enabled" ] }, "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string", "format": "uuid", "description": "ID of the customer to list contract named schedules for" }, "contract_id": { "type": "string", "format": "uuid", "description": "Optional ID of a contract to scope the results to a single contract" }, "schedule_name": { "type": "string", "description": "Optional filter to scope the results to a single schedule name" }, "properties": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional key-value filters. A schedule matches when it contains at least this subset of properties." }, "covering_date": { "type": "string", "format": "date-time", "description": "If provided, result contains at most one segment covering this date for each schedule." }, "limit": { "type": "integer", "description": "Maximum number of named schedules to return." }, "next_page": { "type": "string", "description": "Cursor for pagination. Use the value from a previous response's next_page." } } }, "ListContractsNamedSchedulesPage": { "type": "object", "x-stainless-skip": true, "x-mint": { "groups": [ "ff:fancy-schedules-enabled" ] }, "required": [ "data", "next_page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerContractNamedSchedule" } }, "next_page": { "type": "string", "nullable": true, "description": "Cursor for the next page of results." } } }, "CustomerContractNamedSchedule": { "type": "object", "x-stainless-skip": true, "x-mint": { "groups": [ "ff:fancy-schedules-enabled" ] }, "required": [ "contract_id", "schedule_name", "segments" ], "properties": { "contract_id": { "type": "string", "format": "uuid", "description": "ID of the contract this named schedule belongs to." }, "schedule_name": { "type": "string", "description": "Name of the schedule." }, "properties": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Properties on this named schedule." }, "segments": { "type": "array", "items": { "type": "object", "required": [ "starting_at", "value" ], "properties": { "value": {}, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" } } } } } }, "UpdateRateCardNamedSchedulePayload": { "type": "object", "required": [ "rate_card_id", "schedule_name", "starting_at", "value" ], "properties": { "rate_card_id": { "type": "string", "format": "uuid", "description": "ID of the rate card whose named schedule is to be updated" }, "schedule_name": { "type": "string", "description": "The identifier for the schedule to be updated" }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "value": { "description": "The value to set for the named schedule. The structure of this object is specific to the named schedule." } } }, "GetRateCardNamedSchedulePayload": { "type": "object", "required": [ "rate_card_id", "schedule_name" ], "properties": { "rate_card_id": { "type": "string", "format": "uuid", "description": "ID of the rate card whose named schedule is to be retrieved" }, "schedule_name": { "type": "string", "description": "The identifier for the schedule to be retrieved" }, "covering_date": { "type": "string", "format": "date-time", "description": "If provided, at most one schedule segment will be returned (the one that covers this date). If not provided, all segments will be returned." } } }, "NamedSchedule": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "starting_at", "value" ], "properties": { "value": {}, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" } } } } } }, "UniquenessKey": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Prevents the creation of duplicates. If a request to create a record is made with a previously used uniqueness key, a new record will not be created and the request will fail with a 409 error." }, "UniquenessKeyForCommitsAndCredits": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Prevents the creation of duplicates. If a request to create a commit or credit is made with a uniqueness key that was previously used to create a commit or credit, a new record will not be created and the request will fail with a 409 error." }, "BalanceForCommitsAndCredits": { "type": "number", "description": "The current balance of the credit or commit. This balance reflects the amount of credit or commit that the customer has access to use at this moment - thus, expired and upcoming credit or commit segments contribute 0 to the balance. The balance will match the sum of all ledger entries with the exception of the case where the sum of negative manual ledger entries exceeds the positive amount remaining on the credit or commit - in that case, the balance will be 0. All manual ledger entries associated with active credit or commit segments are included in the balance, including future-dated manual ledger entries." }, "BillableMetricV1": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the billable metric" }, "name": { "type": "string", "description": "The display name of the billable metric." }, "event_type_filter": { "$ref": "#/components/schemas/EventTypeFilter" }, "property_filters": { "$ref": "#/components/schemas/PropertyFiltersArray" }, "aggregation_type": { "$ref": "#/components/schemas/AggregationType" }, "aggregation_key": { "$ref": "#/components/schemas/AggregationKey" }, "group_keys": { "$ref": "#/components/schemas/GroupKeysArray" }, "custom_fields": { "$ref": "#/components/schemas/CustomField" }, "sql": { "type": "string", "description": "The SQL query associated with the billable metric" }, "archived_at": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp indicating when the billable metric was archived. If not provided, the billable metric is not archived." } } }, "CreateBillableMetricV1Payload": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The display name of the billable metric." }, "sql": { "type": "string", "description": "The SQL query associated with the billable metric. This field is mutually exclusive with aggregation_type, event_type_filter, property_filters, aggregation_key, and group_keys. If provided, these other fields must be omitted." }, "event_type_filter": { "$ref": "#/components/schemas/EventTypeFilter" }, "property_filters": { "$ref": "#/components/schemas/PropertyFiltersArray" }, "aggregation_type": { "$ref": "#/components/schemas/AggregationType" }, "aggregation_key": { "$ref": "#/components/schemas/AggregationKey", "description": "Specifies the type of aggregation performed on matching events. Required if `sql` is not provided." }, "group_keys": { "$ref": "#/components/schemas/GroupKeysArray" }, "custom_fields": { "description": "Custom fields to attach to the billable metric.", "$ref": "#/components/schemas/CustomField" } } }, "PropertyFiltersArray": { "type": "array", "items": { "$ref": "#/components/schemas/PropertyFilter" }, "description": "A list of filters to match events to this billable metric. Each filter defines a rule on an event property. All rules must pass for the event to match the billable metric." }, "AggregationType": { "type": "string", "enum": [ "count", "Count", "COUNT", "latest", "Latest", "LATEST", "max", "Max", "MAX", "sum", "Sum", "SUM", "unique", "Unique", "UNIQUE" ], "description": "Specifies the type of aggregation performed on matching events." }, "AggregationTypeForEventsSearch": { "type": "string", "enum": [ "count", "Count", "COUNT", "latest", "Latest", "LATEST", "max", "Max", "MAX", "sum", "Sum", "SUM", "unique", "Unique", "UNIQUE", "custom_sql" ], "description": "Specifies the type of aggregation performed on matching events. Includes \"custom_sql\" for events search endpoint responses." }, "AggregationKey": { "type": "string", "description": "A key that specifies which property of the event is used to aggregate data. This key must be one of the property filter names and is not applicable when the aggregation type is 'count'." }, "GroupKeysArray": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "Property names that are used to group usage costs on an invoice. Each entry represents a set of properties used to slice events into distinct buckets." }, "EventTypeFilter": { "type": "object", "properties": { "in_values": { "type": "array", "items": { "type": "string" }, "description": "A list of event types that are explicitly included in the billable metric. If specified, only events of these types will match the billable metric. Must be non-empty if present." }, "not_in_values": { "type": "array", "items": { "type": "string" }, "description": "A list of event types that are explicitly excluded from the billable metric. If specified, events of these types will not match the billable metric. Must be non-empty if present." } }, "description": "An optional filtering rule to match the 'event_type' property of an event." }, "PropertyFilter": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the event property." }, "exists": { "type": "boolean", "description": "Determines whether the property must exist in the event. If true, only events with this property will pass the filter. If false, only events without this property will pass the filter. If null or omitted, the existence of the property is optional." }, "in_values": { "type": "array", "items": { "type": "string" }, "description": "Specifies the allowed values for the property to match an event. An event will pass the filter only if its property value is included in this list. If undefined, all property values will pass the filter. Must be non-empty if present." }, "not_in_values": { "type": "array", "items": { "type": "string" }, "description": "Specifies the values that prevent an event from matching the filter. An event will not pass the filter if its property value is included in this list. If null or empty, all property values will pass the filter. Must be non-empty if present." } } }, "CreateHistoricalContractUsageInvoiceRequestPayload": { "type": "object", "required": [ "invoices", "preview" ], "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalContractUsageInvoiceInputPayload" } }, "preview": { "type": "boolean" } } }, "HistoricalContractUsageInvoiceInputPayload": { "type": "object", "required": [ "customer_id", "contract_id", "credit_type_id", "inclusive_start_date", "exclusive_end_date", "issue_date", "usage_line_items" ], "properties": { "customer_id": { "type": "string", "format": "uuid" }, "contract_id": { "type": "string", "format": "uuid" }, "credit_type_id": { "type": "string", "format": "uuid" }, "inclusive_start_date": { "type": "string", "format": "date-time" }, "exclusive_end_date": { "type": "string", "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" ] }, "format": "date-time" }, "issue_date": { "type": "string", "format": "date-time" }, "breakdown_granularity": { "type": "string", "enum": [ "hour", "day", "HOUR", "DAY", "Hour", "Day" ] }, "usage_line_items": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalContractUsageInvoiceLineItemInput" } }, "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" ] }, "$ref": "#/components/schemas/BillableStatus", "description": "This field's availability is dependent on your client's configuration." }, "custom_fields": { "$ref": "#/components/schemas/CustomField" } } }, "HistoricalContractUsageInvoiceLineItemInput": { "type": "object", "required": [ "product_id", "inclusive_start_date", "exclusive_end_date" ], "properties": { "product_id": { "type": "string", "format": "uuid" }, "inclusive_start_date": { "type": "string", "format": "date-time" }, "exclusive_end_date": { "type": "string", "format": "date-time" }, "quantity": { "type": "number" }, "pricing_group_values": { "type": "object", "additionalProperties": { "type": "string" } }, "presentation_group_values": { "type": "object", "additionalProperties": { "type": "string" } }, "subtotals_with_quantity": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalContractUsageInvoiceLineItemBreakdownSubtotal" } } } }, "HistoricalContractUsageInvoiceLineItemBreakdownSubtotal": { "type": "object", "required": [ "inclusive_start_date", "exclusive_end_date", "quantity" ], "properties": { "inclusive_start_date": { "type": "string", "format": "date-time" }, "exclusive_end_date": { "type": "string", "format": "date-time" }, "quantity": { "type": "number" } } }, "PricingGroupKey": { "type": "array", "items": { "type": "string" }, "description": "For USAGE products only. If set, pricing for this product will be determined for each pricing_group_key value, as opposed to the product as a whole. The superset of values in the pricing group key and presentation group key must be set as one compound group key on the billable metric." }, "PresentationGroupKey": { "type": "array", "items": { "type": "string" }, "description": "For USAGE products only. Groups usage line items on invoices. The superset of values in the pricing group key and presentation group key must be set as one compound group key on the billable metric." }, "RecurringScheduleFrequency": { "type": "string", "enum": [ "MONTHLY", "monthly", "QUARTERLY", "quarterly", "SEMI_ANNUAL", "semi_annual", "ANNUAL", "annual" ] }, "SubscriptionQuantityHistory": { "type": "object", "properties": { "subscription_id": { "type": "string", "format": "uuid" }, "fiat_credit_type_id": { "type": "string", "format": "uuid" }, "custom_credit_type_id": { "type": "string", "format": "uuid", "description": "The pricing unit for history prices when present. Otherwise prices use fiat_credit_type_id.", "x-mint": { "groups": [ "ff:enable-subscriptions-in-cpu" ] } }, "history": { "type": "array", "items": { "type": "object", "required": [ "starting_at", "data" ], "properties": { "starting_at": { "type": "string", "format": "date-time" }, "data": { "type": "array", "items": { "type": "object", "required": [ "quantity", "unit_price", "total" ], "properties": { "quantity": { "type": "number" }, "total": { "type": "number" }, "unit_price": { "type": "number" } } } } } } } } }, "SubscriptionSeatsScheduleEntry": { "type": "object", "required": [ "starting_at", "ending_before", "total_quantity", "assigned_seat_ids" ], "properties": { "starting_at": { "type": "string", "format": "date-time", "description": "The start time of this seat schedule period" }, "ending_before": { "type": "string", "format": "date-time", "nullable": true, "description": "The end time of this seat schedule period (null if ongoing)" }, "total_quantity": { "type": "integer", "minimum": 0, "description": "Total number of assigned and unassigned seats in this period" }, "assigned_seat_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of seat IDs that are assigned in this period" } } }, "UpdateActiveRechargeConfig": { "type": "object", "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string", "format": "uuid" }, "recharge_to_amount": { "type": "number", "description": "the amount to recharge to", "minimum": 0 }, "recharge_threshold": { "type": "number", "description": "the threshold at which to recharge", "minimum": 0 }, "enabled": { "type": "boolean" } } }, "CreatePackagePayload": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "contract_name": { "type": "string" }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKey" }, "net_payment_terms_days": { "type": "number" }, "rate_card_id": { "type": "string", "format": "uuid" }, "rate_card_alias": { "type": "string", "description": "Selects the rate card linked to the specified alias as of the contract's start date." }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/PackageAlias" }, "description": "Reference this alias when creating a contract. If the same alias is assigned to multiple packages, it will reference the package to which it was most recently assigned. It is not exposed to end customers." }, "duration": { "$ref": "#/components/schemas/RelativeDate" }, "commits": { "type": "array", "items": { "$ref": "#/components/schemas/CommitTemplateInput" } }, "credits": { "type": "array", "items": { "$ref": "#/components/schemas/CreditTemplateInput" } }, "recurring_commits": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringCommitTemplateInput" } }, "recurring_credits": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringCreditTemplateInput" } }, "multiplier_override_prioritization": { "type": "string", "enum": [ "LOWEST_MULTIPLIER", "lowest_multiplier", "EXPLICIT", "explicit" ], "description": "Defaults to LOWEST_MULTIPLIER, which applies the greatest discount to list prices automatically. EXPLICIT prioritization requires specifying priorities for each multiplier; the one with the lowest priority value will be prioritized first. If tiered overrides are used, prioritization must be explicit." }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/OverrideTemplateInput" } }, "scheduled_charges": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledChargeTemplateInput" } }, "scheduled_charges_on_usage_invoices": { "$ref": "#/components/schemas/ScheduledChargesOnUsageInvoices" }, "usage_statement_schedule": { "$ref": "#/components/schemas/UsageStatementScheduleTemplateInput" }, "billing_provider": { "$ref": "#/components/schemas/ContractsBillingProviderType" }, "delivery_method": { "$ref": "#/components/schemas/BillingProviderDeliveryMethodType" }, "spend_threshold_configuration": { "$ref": "#/components/schemas/SpendThresholdConfiguration" }, "prepaid_balance_threshold_configuration": { "$ref": "#/components/schemas/PrepaidBalanceThresholdConfiguration" }, "spend_trackers": { "type": "array", "items": { "$ref": "#/components/schemas/SpendTrackerInput" }, "x-mint": { "groups": [ "ff:tb-spend-trackers" ] } }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionTemplateInput" } } } }, "UsageStatementScheduleTemplateInput": { "type": "object", "required": [ "frequency" ], "properties": { "frequency": { "type": "string", "enum": [ "MONTHLY", "monthly", "QUARTERLY", "quarterly", "ANNUAL", "annual", "WEEKLY", "weekly" ] }, "day": { "type": "string", "description": "If not provided, defaults to the first day of the month.", "enum": [ "FIRST_OF_MONTH", "first_of_month", "CONTRACT_START", "contract_start", "CUSTOM_DATE", "custom_date" ], "x-mint-enum": { "CUSTOM_DATE": [ "ff:package-customizations" ], "custom_date": [ "ff:package-customizations" ] } }, "invoice_generation_starting_at_offset": { "$ref": "#/components/schemas/RelativeDate", "description": "The offset at which Metronome should start generating usage invoices, relative to the contract start date. If unspecified, contract start date will be used. This is useful to set if you want to import historical invoices via our 'Create Historical Invoices' API rather than having Metronome automatically generate them." } } }, "RelativeDate": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "integer" }, "unit": { "type": "string", "enum": [ "DAYS", "WEEKS", "MONTHS", "YEARS" ] } } }, "SubscriptionTemplateInput": { "type": "object", "required": [ "subscription_rate", "collection_schedule", "proration" ], "properties": { "subscription_rate": { "$ref": "#/components/schemas/SubscriptionRateInput" }, "name": { "type": "string" }, "description": { "type": "string" }, "subscription_alias": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:package-customizations" ] }, "type": "string", "description": "Optional human-readable, per-package-unique alias for this subscription template. Lets a contract customization reference the subscription by alias instead of its template id." }, "collection_schedule": { "type": "string", "enum": [ "ADVANCE", "ARREARS", "advance", "arrears" ] }, "proration": { "$ref": "#/components/schemas/SubscriptionProrationInput" }, "initial_quantity": { "type": "number", "description": "The initial quantity for the subscription. It must be non-negative value. Required if quantity_management_mode is QUANTITY_ONLY." }, "starting_at_offset": { "$ref": "#/components/schemas/RelativeDate", "description": "Relative date from contract start date corresponding to the inclusive start time for the subscription. If not provided, defaults to contract start date" }, "duration": { "$ref": "#/components/schemas/RelativeDate", "description": "Lifetime of the subscription from its start. If not provided, subscription inherits contract end date." }, "temporary_id": { "type": "string", "description": "A temporary ID used to reference the subscription in recurring commit/credit subscription configs created within the same payload." }, "quantity_management_mode": { "type": "string", "enum": [ "SEAT_BASED", "seat_based", "QUANTITY_ONLY", "quantity_only" ], "description": "Determines how the subscription's quantity is controlled. Defaults to QUANTITY_ONLY. **QUANTITY_ONLY**: The subscription quantity is specified directly on the subscription. `initial_quantity` must be provided with this option. Compatible with recurring commits/credits that use POOLED allocation. **SEAT_BASED**: Use when you want to pass specific seat identifiers (e.g. add user_123) to increment and decrement a subscription quantity, rather than directly providing the quantity. You must use a **SEAT_BASED** subscription to use a linked recurring credit with an allocation per seat. `seat_config` must be provided with this option." }, "seat_config": { "$ref": "#/components/schemas/SubscriptionSeatConfigTemplateInput" }, "custom_fields": { "x-cf-entity": "package_subscription", "$ref": "#/components/schemas/CustomField" }, "billing_cycle_config": { "$ref": "#/components/schemas/SubscriptionBillingCycleConfigTemplateInput" }, "payment_gate_config": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:payment-gated-subscriptions-enabled" ] }, "$ref": "#/components/schemas/SubscriptionPaymentGateConfigInput" } } }, "SubscriptionBillingCycleConfigTemplateInput": { "type": "object", "properties": { "invoice_placement": { "type": "string", "enum": [ "ON_SCHEDULED_INVOICE", "ON_USAGE_INVOICE", "on_scheduled_invoice", "on_usage_invoice" ], "description": "Controls whether subscriptions consolidate onto usage invoices. Defaults to ON_USAGE_INVOICE if omitted." }, "billing_cycle_anchor": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:package-customizations" ] }, "type": "string", "enum": [ "SUBSCRIPTION_START", "FIRST_OF_MONTH", "CUSTOM_DATE", "USAGE_STATEMENT_ANCHOR", "subscription_start", "first_of_month", "custom_date", "usage_statement_anchor" ], "description": "Controls which date each subscription materialized from this template anchors its billing cycle to. CUSTOM_DATE requires a subscription_anchor_date supplied per contract via package customizations. Defaults to USAGE_STATEMENT_ANCHOR (the contract's usage statement anchor) if omitted." } } }, "SubscriptionSeatConfigTemplateInput": { "type": "object", "required": [ "seat_group_key" ], "properties": { "seat_group_key": { "type": "string", "description": "The property name, sent on usage events, that identifies the seat ID associated with the usage event. For example, the property name might be seat_id or user_id. The property must be set as a group key on billable metrics and a presentation/pricing group key on contract products. This allows linked recurring credits with an allocation per seat to be consumed by only one seat's usage." }, "initial_unassigned_seats": { "type": "number", "description": "The initial amount of unassigned seats on this subscription." } } }, "ScheduledChargeTemplateInput": { "type": "object", "required": [ "product_id", "schedule" ], "properties": { "product_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "description": "displayed on invoices" }, "schedule": { "$ref": "#/components/schemas/RelativeSchedulePointInTimeInput" }, "custom_fields": { "x-cf-entity": "package_scheduled_charge", "$ref": "#/components/schemas/CustomField" } } }, "RecurringCommitOrCreditTemplateInputBase": { "type": "object", "required": [ "product_id", "access_amount", "priority", "commit_duration", "starting_at_offset" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "displayed on invoices. will be passed through to the individual commits" }, "product_id": { "type": "string", "format": "uuid" }, "access_amount": { "type": "object", "required": [ "unit_price" ], "properties": { "access_type": { "type": "string", "enum": [ "SPEND", "QUANTITY", "spend", "quantity" ], "description": "Indicates how the balance of child commits is drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used." }, "unit_price": { "type": "number" }, "quantity": { "type": "number", "description": "This field is required unless a subscription is attached via `subscription_config`." }, "credit_type_id": { "type": "string", "format": "uuid", "description": "Defaults to USD (cents) if not passed" } }, "description": "The amount of commit to grant." }, "description": { "type": "string", "description": "Will be passed down to the individual commits" }, "rollover_fraction": { "type": "number", "description": "Will be passed down to the individual commits. This controls how much of an individual unexpired commit will roll over upon contract transition. Must be between 0 and 1." }, "priority": { "type": "number", "description": "Will be passed down to the individual commits" }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Will be passed down to the individual commits" }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "Will be passed down to the individual commits" }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with `applicable_product_ids` or `applicable_product_tags`.", "items": { "$ref": "#/components/schemas/CommitSpecifierInput" } }, "temporary_id": { "type": "string", "description": "A temporary ID that can be used to reference the recurring commit for commit specific overrides." }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "commit_rate", "LIST_RATE", "list_rate" ], "description": "Whether the created commits will use the commit rate or list rate" }, "starting_at_offset": { "$ref": "#/components/schemas/RelativeDate", "description": "Offset relative to the contract start date that determines the start time for the first commit" }, "duration": { "$ref": "#/components/schemas/RelativeDate", "description": "Offset relative to the recurring credit start that determines when the contract will stop creating recurring commits. optional" }, "commit_duration": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "periods", "PERIODS" ] } }, "description": "Defines the length of the access schedule for each created commit/credit. The value represents the number of units. Unit defaults to \"PERIODS\", where the length of a period is determined by the recurrence_frequency." }, "recurrence_frequency": { "type": "string", "enum": [ "MONTHLY", "monthly", "QUARTERLY", "quarterly", "ANNUAL", "annual", "WEEKLY", "weekly", "DAILY", "daily" ], "description": "The frequency at which the recurring commits will be created. If not provided: - The commits will be created on the usage invoice frequency. If provided: - The period defined in the duration will correspond to this frequency. - Commits will be created aligned with the recurring commit's starting_at rather than the usage invoice dates. - Daily recurring commits have a limit of one per contract, and are unable to be created with seat-based subscriptions" }, "proration": { "type": "string", "enum": [ "NONE", "none", "FIRST", "first", "LAST", "last", "FIRST_AND_LAST", "first_and_last" ], "description": "Determines whether the first and last commit will be prorated. If not provided, the default is FIRST_AND_LAST (i.e. prorate both the first and last commits)." }, "subscription_config": { "description": "Attach a subscription to the recurring commit/credit.", "$ref": "#/components/schemas/RecurringCommitSubscriptionConfigInput" } } }, "RecurringCommitTemplateInput": { "allOf": [ { "$ref": "#/components/schemas/RecurringCommitOrCreditTemplateInputBase" }, { "type": "object", "properties": { "invoice_amount": { "type": "object", "required": [ "unit_price", "quantity", "credit_type_id" ], "properties": { "unit_price": { "type": "number" }, "quantity": { "type": "number" }, "credit_type_id": { "type": "string", "format": "uuid" } }, "description": "The amount the customer should be billed for the commit. Not required." }, "proration_rounding": { "type": "object", "description": "Optional rounding configuration for prorated recurring commit amounts.", "properties": { "access": { "$ref": "#/components/schemas/ProrationRoundingConfig" }, "invoice": { "$ref": "#/components/schemas/ProrationRoundingConfig" } } } } } ] }, "RecurringCreditTemplateInput": { "allOf": [ { "$ref": "#/components/schemas/RecurringCommitOrCreditTemplateInputBase" }, { "type": "object", "properties": { "proration_rounding": { "type": "object", "description": "Optional rounding configuration for prorated recurring credit amounts.", "properties": { "access": { "$ref": "#/components/schemas/ProrationRoundingConfig" } } } } } ] }, "RelativeScheduleDurationInput": { "type": "object", "required": [ "schedule_items" ], "properties": { "access_type": { "type": "string", "enum": [ "SPEND", "spend", "QUANTITY", "quantity" ], "description": "Determines how the balance is drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used. Defaults to `SPEND` if omitted." }, "credit_type_id": { "type": "string", "format": "uuid", "description": "Defaults to USD (cents) if not passed" }, "schedule_items": { "type": "array", "items": { "type": "object", "required": [ "amount", "starting_at_offset", "duration" ], "properties": { "amount": { "type": "number" }, "starting_at_offset": { "$ref": "#/components/schemas/RelativeDate", "description": "Date relative to the contract start date indicating the start of this schedule segment." }, "duration": { "$ref": "#/components/schemas/RelativeDate", "description": "Offset relative to the start of this segment indicating when it should end." } } } } } }, "RelativeSchedulePointInTimeInput": { "type": "object", "description": "Must provide schedule_items.", "required": [ "schedule_items" ], "properties": { "credit_type_id": { "type": "string", "format": "uuid", "description": "Defaults to USD (cents) if not passed." }, "schedule_items": { "type": "array", "description": "Either provide amount or provide both unit_price and quantity.", "items": { "type": "object", "required": [ "unit_price", "quantity", "date_offset" ], "properties": { "unit_price": { "type": "number", "description": "Unit price for the charge. Will be multiplied by quantity to determine the amount." }, "quantity": { "type": "number", "description": "Quantity for the charge. Will be multiplied by unit_price to determine the amount." }, "date_offset": { "$ref": "#/components/schemas/RelativeDate", "description": "Date relative to the contract start date." } } } } } }, "CommitTemplateInput": { "type": "object", "required": [ "type", "product_id", "access_schedule" ], "properties": { "type": { "type": "string", "enum": [ "PREPAID", "prepaid", "POSTPAID", "postpaid" ] }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "commit_rate", "LIST_RATE", "list_rate" ] }, "name": { "type": "string", "minLength": 1, "description": "displayed on invoices" }, "product_id": { "type": "string", "format": "uuid" }, "access_schedule": { "$ref": "#/components/schemas/RelativeScheduleDurationInput", "description": "Required: Schedule for distributing the commit to the customer. For \"POSTPAID\" commits only one schedule item is allowed and amount must match invoice_schedule total." }, "invoice_schedule": { "allOf": [ { "$ref": "#/components/schemas/RelativeSchedulePointInTimeInput" }, { "type": "object", "properties": { "do_not_invoice": { "type": "boolean", "description": "If true, this schedule will not generate an invoice.", "default": false } } } ], "description": "Required for \"POSTPAID\" commits: the true up invoice will be generated at this time and only one schedule item is allowed; the total must match access_schedule amount. Optional for \"PREPAID\" commits: if not provided, this will be a \"complimentary\" commit with no invoice." }, "description": { "type": "string", "description": "Used only in UI/API. It is not exposed to end customers." }, "rollover_fraction": { "type": "number", "description": "Fraction of unused segments that will be rolled over. Must be between 0 and 1." }, "priority": { "type": "number", "description": "If multiple commits are applicable, the one with the lower priority will apply first." }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Which products the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products." }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "Which tags the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products." }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with `applicable_product_ids` or `applicable_product_tags`.", "items": { "$ref": "#/components/schemas/CommitSpecifierInput" } }, "temporary_id": { "type": "string", "description": "A temporary ID for the commit that can be used to reference the commit for commit specific overrides." }, "custom_fields": { "x-cf-entity": "package_commit", "$ref": "#/components/schemas/CustomField" } } }, "CreditTemplateInput": { "type": "object", "required": [ "product_id", "access_schedule" ], "properties": { "name": { "type": "string", "minLength": 1, "description": "displayed on invoices" }, "product_id": { "type": "string", "format": "uuid" }, "access_schedule": { "$ref": "#/components/schemas/RelativeScheduleDurationInput", "description": "Schedule for distributing the credit to the customer." }, "description": { "type": "string", "description": "Used only in UI/API. It is not exposed to end customers." }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Which products the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products." }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "Which tags the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products." }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with `applicable_product_ids` or `applicable_product_tags`.", "items": { "$ref": "#/components/schemas/CommitSpecifierInput" } }, "priority": { "type": "number", "description": "If multiple credits are applicable, the one with the lower priority will apply first." }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "commit_rate", "LIST_RATE", "list_rate" ] }, "custom_fields": { "x-cf-entity": "package_credit", "$ref": "#/components/schemas/CustomField" } } }, "OverrideTemplateInput": { "type": "object", "required": [ "starting_at_offset", "override_specifiers" ], "properties": { "starting_at_offset": { "$ref": "#/components/schemas/RelativeDate", "description": "Offset relative to contract start date indicating when the override will start applying (inclusive)" }, "duration": { "$ref": "#/components/schemas/RelativeDate", "description": "Offset relative to override start indicating when the override will stop applying (exclusive)" }, "entitled": { "type": "boolean" }, "type": { "type": "string", "enum": [ "OVERWRITE", "overwrite", "MULTIPLIER", "multiplier", "TIERED", "tiered" ], "description": "Overwrites are prioritized over multipliers and tiered overrides." }, "multiplier": { "type": "number", "description": "Required for MULTIPLIER type. Must be >=0." }, "priority": { "type": "number", "description": "Required for EXPLICIT multiplier prioritization scheme and all TIERED overrides. Under EXPLICIT prioritization, overwrites are prioritized first, and then tiered and multiplier overrides are prioritized by their priority value (lowest first). Must be > 0." }, "overwrite_rate": { "$ref": "#/components/schemas/OverwriteRateInput", "description": "Required for OVERWRITE type." }, "override_specifiers": { "type": "array", "items": { "$ref": "#/components/schemas/OverrideSpecifierInput" }, "description": "Specifies which products the override will apply to." }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/OverrideTierInput" }, "description": "Required for TIERED type. Must have at least one tier." }, "is_commit_specific": { "type": "boolean", "description": "Indicates whether the override should only apply to commits. Defaults to `false`. If `true` you can specify relevant commits in `override_specifiers` by passing `commit_ids`, `recurring_commit_ids`, or `any_commit_or_credit_ids`. If you do not specify any of these fields, the override will apply when consuming any prepaid commit, postpaid commit, or credit" }, "target": { "type": "string", "enum": [ "COMMIT_RATE", "commit_rate", "LIST_RATE", "list_rate" ], "description": "Indicates whether the override applies to commit rates or list rates. Can only be used for overrides that have `is_commit_specific` set to `true`. Defaults to `\"LIST_RATE\"`." } } }, "Package": { "type": "object", "required": [ "id", "commits", "overrides", "scheduled_charges", "created_at", "created_by", "usage_statement_schedule" ], "properties": { "id": { "type": "string", "format": "uuid" }, "uniqueness_key": { "$ref": "#/components/schemas/UniquenessKey" }, "name": { "type": "string" }, "rate_card_id": { "type": "string", "format": "uuid" }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/PackageAlias" } }, "duration": { "$ref": "#/components/schemas/RelativeDate" }, "commits": { "type": "array", "items": { "$ref": "#/components/schemas/CommitTemplate" } }, "credits": { "type": "array", "items": { "$ref": "#/components/schemas/CreditTemplate" } }, "overrides": { "type": "array", "items": { "$ref": "#/components/schemas/OverrideTemplate" } }, "scheduled_charges": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledChargeTemplate" } }, "scheduled_charges_on_usage_invoices": { "$ref": "#/components/schemas/ScheduledChargesOnUsageInvoices" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "net_payment_terms_days": { "type": "number" }, "usage_statement_schedule": { "$ref": "#/components/schemas/UsageStatementScheduleTemplate" }, "multiplier_override_prioritization": { "type": "string", "enum": [ "LOWEST_MULTIPLIER", "EXPLICIT" ], "description": "Defaults to LOWEST_MULTIPLIER, which applies the greatest discount to list prices automatically. EXPLICIT prioritization requires specifying priorities for each multiplier; the one with the lowest priority value will be prioritized first." }, "billing_provider": { "$ref": "#/components/schemas/BillingProviderType" }, "delivery_method": { "$ref": "#/components/schemas/BillingProviderDeliveryMethodType" }, "recurring_commits": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringCommitTemplate" } }, "recurring_credits": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringCreditTemplate" } }, "spend_threshold_configuration": { "$ref": "#/components/schemas/SpendThresholdConfiguration" }, "prepaid_balance_threshold_configuration": { "$ref": "#/components/schemas/PrepaidBalanceThresholdConfiguration" }, "spend_trackers": { "type": "array", "x-mint": { "groups": [ "ff:tb-spend-trackers" ] }, "items": { "$ref": "#/components/schemas/SpendTrackerTemplate" } }, "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionTemplate" } }, "contract_name": { "type": "string", "description": "The name to use for contracts created from this package." }, "archived_at": { "type": "string", "format": "date-time" } } }, "CommitTemplate": { "type": "object", "required": [ "id", "type", "product" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "PREPAID", "POSTPAID" ] }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "LIST_RATE" ] }, "name": { "type": "string" }, "priority": { "type": "number", "description": "If multiple credits or commits are applicable, the one with the lower priority will apply first." }, "custom_fields": { "x-cf-entity": "package_commit", "$ref": "#/components/schemas/CustomField" }, "product": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "access_schedule": { "$ref": "#/components/schemas/RelativeScheduleDuration", "description": "The schedule that the customer will gain access to the credits purposed with this commit." }, "invoice_schedule": { "allOf": [ { "$ref": "#/components/schemas/RelativeSchedulePointInTime" }, { "type": "object", "required": [ "do_not_invoice" ], "properties": { "do_not_invoice": { "type": "boolean", "description": "If true, this schedule will not generate an invoice.", "default": false } } } ], "description": "The schedule that the customer will be invoiced for this commit." }, "description": { "type": "string" }, "rollover_fraction": { "type": "number" }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "applicable_product_tags": { "type": "array", "items": { "type": "string" } }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown.", "items": { "$ref": "#/components/schemas/CommitSpecifier" } } } }, "CreditTemplate": { "type": "object", "required": [ "id", "type", "product" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "priority": { "type": "number" }, "custom_fields": { "x-cf-entity": "package_credit", "$ref": "#/components/schemas/CustomField" }, "product": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "applicable_product_tags": { "type": "array", "items": { "type": "string" } }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown.", "items": { "$ref": "#/components/schemas/CommitSpecifier" } }, "access_schedule": { "$ref": "#/components/schemas/RelativeScheduleDuration" }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "LIST_RATE" ] } } }, "OverrideSpecifierTemplate": { "type": "object", "properties": { "product_id": { "type": "string", "format": "uuid" }, "product_tags": { "type": "array", "items": { "type": "string" } }, "pricing_group_values": { "type": "object", "additionalProperties": { "type": "string" } }, "presentation_group_values": { "type": "object", "additionalProperties": { "type": "string", "nullable": true } }, "commit_template_ids": { "type": "array", "items": { "type": "string" } }, "recurring_commit_template_ids": { "type": "array", "items": { "type": "string" } }, "any_commit_or_credit_template_ids": { "type": "array", "items": { "type": "string" } }, "billing_frequency": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUAL", "WEEKLY" ] }, "exclude": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:exclude-specifiers-ga" ] }, "type": "array", "description": "If provided, the specifier will not apply to product usage that matches the inclusion criteria and any of the excluding values.", "items": { "$ref": "#/components/schemas/ExcludeSpecifier" } } } }, "OverrideTemplate": { "type": "object", "required": [ "id", "starting_at_offset", "override_specifiers" ], "properties": { "id": { "type": "string", "format": "uuid" }, "product": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "applicable_product_tags": { "type": "array", "items": { "type": "string" } }, "override_specifiers": { "type": "array", "items": { "$ref": "#/components/schemas/OverrideSpecifierTemplate" } }, "starting_at_offset": { "$ref": "#/components/schemas/RelativeDate" }, "duration": { "$ref": "#/components/schemas/RelativeDate" }, "entitled": { "type": "boolean" }, "type": { "type": "string", "enum": [ "OVERWRITE", "MULTIPLIER", "TIERED" ] }, "priority": { "type": "number" }, "multiplier": { "type": "number" }, "overwrite_rate": { "$ref": "#/components/schemas/OverwriteRate" }, "override_tiers": { "type": "array", "items": { "$ref": "#/components/schemas/OverrideTier" } }, "is_commit_specific": { "type": "boolean" }, "target": { "type": "string", "enum": [ "COMMIT_RATE", "LIST_RATE" ] } } }, "ScheduledChargeTemplate": { "type": "object", "required": [ "id", "product", "schedule" ], "properties": { "id": { "type": "string", "format": "uuid" }, "custom_fields": { "x-cf-entity": "package_scheduled_charge", "$ref": "#/components/schemas/CustomField" }, "product": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "schedule": { "$ref": "#/components/schemas/RelativeSchedulePointInTime" }, "name": { "type": "string" }, "description": { "type": "string" } } }, "RecurringCommitOrCreditTemplateBase": { "type": "object", "required": [ "id", "product", "access_amount", "priority", "commit_duration", "starting_at_offset", "rate_type" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "product": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "access_amount": { "type": "object", "required": [ "unit_price", "credit_type_id" ], "properties": { "access_type": { "type": "string", "enum": [ "SPEND", "QUANTITY" ], "description": "Indicates how the balance of child commits is drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used." }, "unit_price": { "type": "number" }, "quantity": { "type": "number" }, "credit_type_id": { "type": "string", "format": "uuid", "description": "This ID identifies the credit type for the access amount. Quantity-based recurring commits and credits return the null credit type UUID." } }, "description": "The amount of commit to grant." }, "description": { "type": "string" }, "rollover_fraction": { "type": "number", "description": "Will be passed down to the individual commits. This controls how much of an individual unexpired commit will roll over upon contract transition. Must be between 0 and 1." }, "priority": { "type": "number" }, "applicable_product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Will be passed down to the individual commits" }, "applicable_product_tags": { "type": "array", "items": { "type": "string" }, "description": "Will be passed down to the individual commits" }, "specifiers": { "type": "array", "description": "List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown.", "items": { "$ref": "#/components/schemas/CommitSpecifier" } }, "rate_type": { "type": "string", "enum": [ "COMMIT_RATE", "LIST_RATE" ], "description": "Whether the created commits will use the commit rate or list rate" }, "starting_at_offset": { "$ref": "#/components/schemas/RelativeDate", "description": "Offset relative to the contract start date that determines the start time for the first commit" }, "duration": { "$ref": "#/components/schemas/RelativeDate", "description": "Offset relative to the recurring credit start that determines when the contract will stop creating recurring commits. optional" }, "commit_duration": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "PERIODS" ] } }, "description": "The amount of time each of the created commits will be valid for" }, "recurrence_frequency": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUAL", "WEEKLY", "DAILY" ], "description": "The frequency at which the recurring commits will be created. If not provided: - The commits will be created on the usage invoice frequency. If provided: - The period defined in the duration will correspond to this frequency. - Commits will be created aligned with the recurring commit's starting_at rather than the usage invoice dates. - Daily recurring commits have a limit of one per contract, and are unable to be created with seat-based subscriptions" }, "proration": { "type": "string", "enum": [ "NONE", "FIRST", "LAST", "FIRST_AND_LAST" ], "description": "Determines whether the first and last commit will be prorated. If not provided, the default is FIRST_AND_LAST (i.e. prorate both the first and last commits)." }, "subscription_config": { "description": "Attach a subscription to the recurring commit/credit.", "$ref": "#/components/schemas/RecurringCommitSubscriptionConfigTemplate" } } }, "RecurringCommitTemplate": { "allOf": [ { "$ref": "#/components/schemas/RecurringCommitOrCreditTemplateBase" }, { "type": "object", "properties": { "invoice_amount": { "type": "object", "required": [ "unit_price", "quantity", "credit_type_id" ], "properties": { "unit_price": { "type": "number" }, "quantity": { "type": "number" }, "credit_type_id": { "type": "string", "format": "uuid" } }, "description": "The amount the customer should be billed for the commit." }, "proration_rounding": { "type": "object", "nullable": true, "description": "Rounding configuration for prorated recurring commit amounts.", "properties": { "access": { "$ref": "#/components/schemas/ProrationRoundingConfig" }, "invoice": { "$ref": "#/components/schemas/ProrationRoundingConfig" } } } } } ] }, "RecurringCreditTemplate": { "allOf": [ { "$ref": "#/components/schemas/RecurringCommitOrCreditTemplateBase" }, { "type": "object", "properties": { "proration_rounding": { "type": "object", "nullable": true, "description": "Rounding configuration for prorated recurring credit amounts.", "properties": { "access": { "$ref": "#/components/schemas/ProrationRoundingConfig" } } } } } ] }, "SubscriptionTemplate": { "type": "object", "required": [ "subscription_rate", "collection_schedule", "proration" ], "properties": { "id": { "type": "string", "format": "uuid" }, "custom_fields": { "x-cf-entity": "package_subscription", "$ref": "#/components/schemas/CustomField" }, "subscription_rate": { "$ref": "#/components/schemas/SubscriptionRate" }, "name": { "type": "string" }, "description": { "type": "string" }, "subscription_alias": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:package-customizations" ] }, "type": "string", "description": "Human-readable, per-package-unique alias for this subscription template, if one was set at package creation. Can be used to reference the subscription in contract customizations." }, "collection_schedule": { "type": "string", "enum": [ "ADVANCE", "ARREARS", "advance", "arrears" ] }, "proration": { "$ref": "#/components/schemas/SubscriptionProration" }, "initial_quantity": { "type": "number" }, "quantity_management_mode": { "type": "string", "enum": [ "SEAT_BASED", "seat_based", "QUANTITY_ONLY", "quantity_only" ], "description": "Determines how the subscription's quantity is controlled. Defaults to QUANTITY_ONLY. **QUANTITY_ONLY**: The subscription quantity is specified directly on the subscription. `initial_quantity` must be provided with this option. Compatible with recurring commits/credits that use POOLED allocation. **SEAT_BASED**: Use when you want to pass specific seat identifiers (e.g. add user_123) to increment and decrement a subscription quantity, rather than directly providing the quantity. You must use a SEAT_BASED subscription to use a linked recurring credit with an allocation per seat. `seat_config` must be provided with this option." }, "seat_config": { "$ref": "#/components/schemas/SubscriptionSeatConfig" }, "starting_at_offset": { "$ref": "#/components/schemas/RelativeDate" }, "duration": { "$ref": "#/components/schemas/RelativeDate" }, "fiat_credit_type_id": { "type": "string", "format": "uuid" }, "custom_credit_type_id": { "type": "string", "format": "uuid", "description": "If provided, the subscription's price will be in terms of this custom pricing unit instead of the fiat currency.", "x-mint": { "groups": [ "ff:enable-subscriptions-in-cpu" ] } }, "billing_cycle_config": { "$ref": "#/components/schemas/SubscriptionBillingCycleConfigTemplate" }, "payment_gate_config": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:payment-gated-subscriptions-enabled" ] }, "$ref": "#/components/schemas/SubscriptionPaymentGateConfig" } } }, "SubscriptionBillingCycleConfigTemplate": { "type": "object", "properties": { "invoice_placement": { "type": "string", "enum": [ "ON_SCHEDULED_INVOICE", "ON_USAGE_INVOICE" ] }, "billing_cycle_anchor": { "x-stainless-skip": true, "x-mint": { "groups": [ "ff:package-customizations" ] }, "type": "string", "enum": [ "SUBSCRIPTION_START", "FIRST_OF_MONTH", "CUSTOM_DATE", "USAGE_STATEMENT_ANCHOR" ], "description": "Which date each subscription materialized from this template anchors its billing cycle to. USAGE_STATEMENT_ANCHOR (the default) tracks the contract's usage statement anchor." } } }, "UsageStatementScheduleTemplate": { "type": "object", "required": [ "frequency" ], "properties": { "frequency": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUAL", "WEEKLY" ] }, "day": { "type": "string", "enum": [ "FIRST_OF_MONTH", "CONTRACT_START", "CUSTOM_DATE" ], "x-mint-enum": { "CUSTOM_DATE": [ "ff:package-customizations" ] } } } }, "RelativeScheduleDuration": { "type": "object", "required": [ "credit_type", "schedule_items" ], "properties": { "access_type": { "type": "string", "enum": [ "SPEND", "QUANTITY" ], "description": "Indicates how the balance is drawn down. `SPEND` deducts the dollar cost of usage. `QUANTITY` deducts the number of units used." }, "credit_type": { "$ref": "#/components/schemas/CreditType" }, "schedule_items": { "type": "array", "items": { "type": "object", "required": [ "id", "starting_at_offset", "duration", "amount" ], "properties": { "id": { "type": "string", "format": "uuid" }, "starting_at_offset": { "$ref": "#/components/schemas/RelativeDate" }, "duration": { "$ref": "#/components/schemas/RelativeDate" }, "amount": { "type": "number" } } } } } }, "RelativeSchedulePointInTime": { "type": "object", "required": [ "credit_type", "schedule_items" ], "properties": { "credit_type": { "$ref": "#/components/schemas/CreditType" }, "schedule_items": { "type": "array", "items": { "type": "object", "required": [ "id", "unit_price", "quantity", "date_offset" ], "properties": { "id": { "type": "string", "format": "uuid" }, "unit_price": { "type": "number" }, "quantity": { "type": "number" }, "date_offset": { "$ref": "#/components/schemas/RelativeDate" } } } } } }, "RecurringCommitSubscriptionConfigTemplate": { "type": "object", "required": [ "allocation", "apply_seat_increase_config", "subscription_template_id" ], "properties": { "allocation": { "$ref": "#/components/schemas/SubscriptionConfigAllocation" }, "apply_seat_increase_config": { "$ref": "#/components/schemas/ApplySeatIncreaseConfigForRecurringCommit" }, "subscription_template_id": { "type": "string", "format": "uuid" }, "access_policy": { "x-stainless-skip": true, "type": "string", "enum": [ "BILLING_PERIOD_PAID", "INITIAL_BILLING_PERIOD_PAID_ONLY" ], "x-mint": { "groups": [ "ff:payment-gated-subscriptions-enabled" ] }, "description": "Controls when a customer can access recurring commit or credit child balances when the subscription is payment-gated. `BILLING_PERIOD_PAID` releases each balance after payment for its billing period. `INITIAL_BILLING_PERIOD_PAID_ONLY` releases all balances after the first payment." } } }, "SpendTrackerApplicableSpendSpecifier": { "type": "object", "required": [ "spend_type", "sources" ], "properties": { "spend_type": { "type": "string", "enum": [ "COMMIT_PURCHASE" ] }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "THRESHOLD_RECHARGE", "MANUAL" ] } }, "discounted": { "type": "string", "enum": [ "ANY", "DISCOUNTED_ONLY", "UNDISCOUNTED_ONLY" ] } } }, "SpendTrackerTemplate": { "type": "object", "required": [ "alias", "credit_type_id", "reset_frequency", "applicable_spend_specifiers" ], "properties": { "alias": { "type": "string", "description": "Human-readable identifier, unique per contract." }, "credit_type_id": { "type": "string", "format": "uuid" }, "reset_frequency": { "type": "string", "enum": [ "BILLING_PERIOD" ] }, "applicable_spend_specifiers": { "type": "array", "items": { "$ref": "#/components/schemas/SpendTrackerApplicableSpendSpecifier" } } } }, "SeatBalanceCommitLedgerEntryType": { "type": "string", "enum": [ "PREPAID_COMMIT_SEGMENT_START", "PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION", "PREPAID_COMMIT_ROLLOVER", "PREPAID_COMMIT_EXPIRATION", "PREPAID_COMMIT_CANCELED", "PREPAID_COMMIT_CREDITED", "PREPAID_COMMIT_MANUAL", "PREPAID_COMMIT_SEAT_BASED_ADJUSTMENT" ] }, "SeatBalanceCreditLedgerEntryType": { "type": "string", "enum": [ "CREDIT_SEGMENT_START", "CREDIT_AUTOMATED_INVOICE_DEDUCTION", "CREDIT_EXPIRATION", "CREDIT_CANCELED", "CREDIT_CREDITED", "CREDIT_MANUAL", "CREDIT_SEAT_BASED_ADJUSTMENT", "CREDIT_ROLLOVER" ] }, "ContractProjectionSummary": { "type": "object", "required": [ "customer_id", "contract_id", "starting_at" ], "properties": { "customer_id": { "type": "string", "format": "uuid" }, "contract_id": { "type": "string", "format": "uuid" }, "starting_at": { "type": "string", "format": "date-time" }, "ending_before": { "type": "string", "format": "date-time" }, "archived_at": { "type": "string", "format": "date-time" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "Customers", "description": "[Customers](https://docs.metronome.com/provisioning/create-customers/) in Metronome represent your users for all billing and reporting. Use these endpoints to create, retrieve, update, and archive customers and their billing configuration." }, { "name": "Billable metrics", "description": "[Billable metrics](https://docs.metronome.com/understanding-metronome/how-metronome-works#billable-metrics) in Metronome represent the various consumption components that Metronome meters and aggregates." }, { "name": "Usage", "description": "[Usage events](https://docs.metronome.com/connecting-metronome/send-usage-data/) are the basis for billable metrics. Use these endpoints to send usage events to Metronome and retrieve aggregated event data." }, { "name": "Plans", "description": "[Plans](https://docs.metronome.com/pricing-and-packaging/create-plans/) determine the base pricing for a customer. Use these endpoints to add a plan to a customer, end a customer plan, retrieve plans, and retrieve plan details. Create plans in the [Metronome app](https://app.metronome.com/plans)." }, { "name": "Contracts", "description": "A contract defines a customer’s products, pricing, discounts, commitments, and more. Use these endpoints to create and update contracts data." }, { "name": "Credit grants", "description": "[Credit grants](https://docs.metronome.com/invoicing/how-billing-works/manage-credits/) adjust a customer balance for prepayments, reimbursements, promotions, and so on. Use these endpoints to create, retrieve, update, and delete credit grants." }, { "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." }, { "name": "Alerts", "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)" }, { "name": "Custom fields", "description": "[Custom fields](https://docs.metronome.com/integrations/custom-fields/) enable adding additional data to Metronome entities. Use these endpoints to create, retrieve, update, and delete custom fields." }, { "name": "Security", "description": "[Security](https://docs.metronome.com/developer-resources/security/) endpoints allow you to retrieve security-related data." }, { "name": "Settings", "description": "Use these endpoints to configure a billing API key, a webhook secret, or invoice finalization behavior." } ], "security": [ { "bearerAuth": [] } ] }