✨ New Metronome docs are live! Need old docs?
curl --request POST \
--url https://api.metronome.com/v1/contracts/createHistoricalInvoices \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"invoices": [
{
"customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
"contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"inclusive_start_date": "2020-01-01T00:00:00.000Z",
"exclusive_end_date": "2020-02-01T00:00:00.000Z",
"issue_date": "2020-02-01T00:00:00.000Z",
"usage_line_items": [
{
"product_id": "f14d6729-6a44-4b13-9908-9387f1918790",
"inclusive_start_date": "2020-01-01T00:00:00.000Z",
"exclusive_end_date": "2020-02-01T00:00:00.000Z",
"quantity": 100
}
]
}
],
"preview": false
}'
{
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_custom_fields": {},
"net_payment_terms_days": 123,
"credit_type": {
"name": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"line_items": [
{
"name": "<string>",
"quantity": 123,
"total": 123,
"unit_price": 123,
"list_price": {
"rate_type": "FLAT",
"price": 123,
"use_list_prices": true,
"tiers": [
{
"size": 123,
"price": 123
}
],
"pricing_group_values": {},
"credit_type": {
"name": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
},
"product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"product_custom_fields": {},
"product_tags": [
"<string>"
],
"product_type": "<string>",
"type": "<string>",
"is_prorated": true,
"credit_type": {
"name": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"starting_at": "2023-11-07T05:31:56Z",
"ending_before": "2023-11-07T05:31:56Z",
"commit_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"applied_commit_or_credit": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "PREPAID"
},
"commit_custom_fields": {},
"commit_segment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"commit_type": "<string>",
"postpaid_commit": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"custom_fields": {},
"pricing_group_values": {},
"presentation_group_values": {},
"metadata": "<string>",
"scheduled_charge_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"scheduled_charge_custom_fields": {},
"subscription_custom_fields": {},
"tier": {
"size": "<string>",
"level": 123,
"starting_at": "<string>"
},
"discount_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"discount_custom_fields": {}
}
],
"start_timestamp": "2023-11-07T05:31:56Z",
"end_timestamp": "2023-11-07T05:31:56Z",
"issued_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"status": "DRAFT, VOID, or FINALIZED",
"total": 123,
"type": "PLAN_ARREARS, SCHEDULED, USAGE, CORRECTION, CREDIT_PURCHASE, or SEAT_PURCHASE",
"external_invoice": {
"billing_provider_type": "aws_marketplace",
"invoice_id": "<string>",
"issued_at_timestamp": "2023-11-07T05:31:56Z",
"external_status": "DRAFT"
},
"contract_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"contract_custom_fields": {},
"amendment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"custom_fields": {}
}
]
}
Create historical usage invoices for past billing periods on specific contracts. Use this endpoint to generate retroactive invoices with custom usage line items, quantities, and date ranges. Supports preview mode to validate invoice data before creation. Ideal for billing migrations or correcting past billing periods.
curl --request POST \
--url https://api.metronome.com/v1/contracts/createHistoricalInvoices \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"invoices": [
{
"customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
"contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
"credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"inclusive_start_date": "2020-01-01T00:00:00.000Z",
"exclusive_end_date": "2020-02-01T00:00:00.000Z",
"issue_date": "2020-02-01T00:00:00.000Z",
"usage_line_items": [
{
"product_id": "f14d6729-6a44-4b13-9908-9387f1918790",
"inclusive_start_date": "2020-01-01T00:00:00.000Z",
"exclusive_end_date": "2020-02-01T00:00:00.000Z",
"quantity": 100
}
]
}
],
"preview": false
}'
{
"data": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"customer_custom_fields": {},
"net_payment_terms_days": 123,
"credit_type": {
"name": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"line_items": [
{
"name": "<string>",
"quantity": 123,
"total": 123,
"unit_price": 123,
"list_price": {
"rate_type": "FLAT",
"price": 123,
"use_list_prices": true,
"tiers": [
{
"size": 123,
"price": 123
}
],
"pricing_group_values": {},
"credit_type": {
"name": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
},
"product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"product_custom_fields": {},
"product_tags": [
"<string>"
],
"product_type": "<string>",
"type": "<string>",
"is_prorated": true,
"credit_type": {
"name": "<string>",
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"starting_at": "2023-11-07T05:31:56Z",
"ending_before": "2023-11-07T05:31:56Z",
"commit_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"applied_commit_or_credit": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"type": "PREPAID"
},
"commit_custom_fields": {},
"commit_segment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"commit_type": "<string>",
"postpaid_commit": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
},
"custom_fields": {},
"pricing_group_values": {},
"presentation_group_values": {},
"metadata": "<string>",
"scheduled_charge_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"scheduled_charge_custom_fields": {},
"subscription_custom_fields": {},
"tier": {
"size": "<string>",
"level": 123,
"starting_at": "<string>"
},
"discount_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"discount_custom_fields": {}
}
],
"start_timestamp": "2023-11-07T05:31:56Z",
"end_timestamp": "2023-11-07T05:31:56Z",
"issued_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"status": "DRAFT, VOID, or FINALIZED",
"total": 123,
"type": "PLAN_ARREARS, SCHEDULED, USAGE, CORRECTION, CREDIT_PURCHASE, or SEAT_PURCHASE",
"external_invoice": {
"billing_provider_type": "aws_marketplace",
"invoice_id": "<string>",
"issued_at_timestamp": "2023-11-07T05:31:56Z",
"external_status": "DRAFT"
},
"contract_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"contract_custom_fields": {},
"amendment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"custom_fields": {}
}
]
}
Bearer authentication header of the form Bearer <token>
, where <token>
is your auth token.
Create a historical usage invoice for a contract
The body is of type object
.
Success
The response is of type object
.