List customer contracts (v1)
curl --request POST \
--url https://api.metronome.com/v1/contracts/list \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customer_id": "9b85c1c1-5238-4f2a-a409-61412905e1e1"
}
'{
"data": [
{
"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
"customer_id": "e3fd63fd-fc9f-4153-a543-1fc2261a0e1c",
"initial": {
"name": "My contract",
"rate_card_id": "92f3080d-27ca-4306-a23f-2430de61851e",
"starting_at": "2020-01-01T00:00:00.000Z",
"net_payment_terms_days": 7,
"ending_before": "2022-01-01T00:00:00.000Z",
"commits": [
{
"id": "62c0cb84-bf3f-48b9-9bcf-a8ddf8c1cf35",
"type": "PREPAID",
"name": "My test commit",
"description": "My test commit description",
"product": {
"id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
"name": "My product A"
},
"rollover_fraction": 0.1,
"applicable_product_ids": [
"13a2179b-f0cb-460b-85a1-cd42964ca533"
],
"access_schedule": {
"credit_type": {
"id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"name": "USD (cents)"
},
"schedule_items": [
{
"id": "2d45952c-5a6e-43a9-8aab-f61ee21be81a",
"amount": 10000000,
"starting_at": "2020-02-01T00:00:00.000Z",
"ending_before": "2021-02-01T00:00:00.000Z"
}
]
},
"invoice_schedule": {
"credit_type": {
"id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"name": "USD (cents)"
},
"schedule_items": [
{
"id": "f15e4e23-f74e-4de4-9b3a-8b07434116c4",
"invoice_id": "525b9759-7bbd-4a05-aab1-d7c43c976b57",
"amount": 10000000,
"unit_price": 10000000,
"quantity": 1,
"timestamp": "2020-03-01T00:00:00.000Z"
}
],
"do_not_invoice": false
},
"ledger": [
{
"invoice_id": "525b9759-7bbd-4a05-aab1-d7c43c976b57",
"amount": 10000000,
"timestamp": "2020-03-01T00:00:00.000Z",
"type": "PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION",
"segment_id": "2d45952c-5a6e-43a9-8aab-f61ee21be81a"
}
],
"created_at": "2020-01-01T00:00:00.000Z"
}
],
"overrides": [
{
"id": "6cf3292a-e85c-4be6-822c-e25ba9d19757",
"created_at": "2020-01-01T00:00:00.000Z",
"product": {
"id": "eae8903b-693b-41a7-8c0b-f23748c9a9c8",
"name": "My product B"
},
"starting_at": "2020-01-01T00:00:00.000Z",
"type": "MULTIPLIER",
"multiplier": 0.1
}
],
"scheduled_charges": [],
"scheduled_charges_on_usage_invoices": "ALL",
"transitions": [
{
"type": "RENEWAL",
"from_contract_id": "9bf48856-b430-42f4-844f-4d2ea85bcff8",
"to_contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
}
],
"reseller_royalties": [],
"usage_statement_schedule": {
"frequency": "MONTHLY",
"billing_anchor_date": "2020-01-01T00:00:00.000Z"
},
"created_at": "2019-12-31T14:23:55.234Z",
"created_by": "Alice"
},
"current": {
"rate_card_id": "92f3080d-27ca-4306-a23f-2430de61851e",
"starting_at": "2020-01-01T00:00:00.000Z",
"net_payment_terms_days": 7,
"ending_before": "2022-01-01T00:00:00.000Z",
"commits": [
{
"id": "62c0cb84-bf3f-48b9-9bcf-a8ddf8c1cf35",
"type": "PREPAID",
"name": "My test commit",
"description": "My test commit description",
"product": {
"id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
"name": "My product A"
},
"rollover_fraction": 0.1,
"applicable_product_ids": [
"13a2179b-f0cb-460b-85a1-cd42964ca533"
],
"access_schedule": {
"credit_type": {
"id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"name": "USD (cents)"
},
"schedule_items": [
{
"id": "2d45952c-5a6e-43a9-8aab-f61ee21be81a",
"amount": 10000000,
"starting_at": "2020-02-01T00:00:00.000Z",
"ending_before": "2021-02-01T00:00:00.000Z"
}
]
},
"invoice_schedule": {
"credit_type": {
"id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"name": "USD (cents)"
},
"schedule_items": [
{
"id": "f15e4e23-f74e-4de4-9b3a-8b07434116c4",
"invoice_id": "525b9759-7bbd-4a05-aab1-d7c43c976b57",
"amount": 10000000,
"unit_price": 10000000,
"quantity": 1,
"timestamp": "2020-03-01T00:00:00.000Z"
}
],
"do_not_invoice": false
},
"created_at": "2020-01-01T00:00:00.000Z"
}
],
"overrides": [
{
"id": "6cf3292a-e85c-4be6-822c-e25ba9d19757",
"created_at": "2020-01-01T00:00:00.000Z",
"product": {
"id": "eae8903b-693b-41a7-8c0b-f23748c9a9c8",
"name": "My product B"
},
"starting_at": "2020-01-01T00:00:00.000Z",
"type": "MULTIPLIER",
"multiplier": 0.1
}
],
"scheduled_charges": [
{
"id": "8e511ff1-3fd5-4d86-bc89-1e80239874bf",
"name": "My test scheduled charge",
"product": {
"id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
"name": "My product A"
},
"schedule": {
"schedule_items": [
{
"id": "6ca40ebc-9c01-484e-a64e-4e47fbbd0ebe",
"invoice_id": "5cced82b-5464-41b4-9ea7-3e080e0a4dba",
"amount": 1000000,
"unit_price": 1000000,
"quantity": 1,
"timestamp": "2020-02-15T00:00:00.000Z"
}
]
}
}
],
"scheduled_charges_on_usage_invoices": "ALL",
"transitions": [
{
"type": "RENEWAL",
"from_contract_id": "9bf48856-b430-42f4-844f-4d2ea85bcff8",
"to_contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
}
],
"reseller_royalties": [],
"usage_statement_schedule": {
"frequency": "MONTHLY",
"billing_anchor_date": "2020-01-01T00:00:00.000Z"
},
"created_at": "2019-12-31T14:23:55.234Z",
"created_by": "Alice"
},
"amendments": [
{
"id": "4e2fab26-31ea-473c-b07d-1ce10e7c0146",
"starting_at": "2020-04-01T00:00:00.000Z",
"scheduled_charges": [
{
"id": "8e511ff1-3fd5-4d86-bc89-1e80239874bf",
"name": "My test scheduled charge",
"product": {
"id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
"name": "My product A"
},
"schedule": {
"schedule_items": [
{
"id": "6ca40ebc-9c01-484e-a64e-4e47fbbd0ebe",
"invoice_id": "5cced82b-5464-41b4-9ea7-3e080e0a4dba",
"amount": 1000000,
"unit_price": 1000000,
"quantity": 1,
"timestamp": "2020-02-15T00:00:00.000Z"
}
]
}
}
],
"commits": [],
"overrides": [],
"created_at": "2019-12-31T16:12:45.123Z",
"created_by": "Bob"
}
],
"custom_fields": {
"x_account_id": "KyVnHhSBWl7eY2bl"
}
}
]
}Contracts
List customer contracts (v1)
Retrieves all contracts for a specific customer, including pricing, terms, credits, and commitments. Use this to view a customer’s contract history and current agreements for billing management. Returns contract details with optional ledgers and balance information.
⚠️ Note: This is the legacy v1 endpoint - new integrations should use the v2 endpoint for enhanced features.
POST
/
v1
/
contracts
/
list
List customer contracts (v1)
curl --request POST \
--url https://api.metronome.com/v1/contracts/list \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customer_id": "9b85c1c1-5238-4f2a-a409-61412905e1e1"
}
'{
"data": [
{
"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
"customer_id": "e3fd63fd-fc9f-4153-a543-1fc2261a0e1c",
"initial": {
"name": "My contract",
"rate_card_id": "92f3080d-27ca-4306-a23f-2430de61851e",
"starting_at": "2020-01-01T00:00:00.000Z",
"net_payment_terms_days": 7,
"ending_before": "2022-01-01T00:00:00.000Z",
"commits": [
{
"id": "62c0cb84-bf3f-48b9-9bcf-a8ddf8c1cf35",
"type": "PREPAID",
"name": "My test commit",
"description": "My test commit description",
"product": {
"id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
"name": "My product A"
},
"rollover_fraction": 0.1,
"applicable_product_ids": [
"13a2179b-f0cb-460b-85a1-cd42964ca533"
],
"access_schedule": {
"credit_type": {
"id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"name": "USD (cents)"
},
"schedule_items": [
{
"id": "2d45952c-5a6e-43a9-8aab-f61ee21be81a",
"amount": 10000000,
"starting_at": "2020-02-01T00:00:00.000Z",
"ending_before": "2021-02-01T00:00:00.000Z"
}
]
},
"invoice_schedule": {
"credit_type": {
"id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"name": "USD (cents)"
},
"schedule_items": [
{
"id": "f15e4e23-f74e-4de4-9b3a-8b07434116c4",
"invoice_id": "525b9759-7bbd-4a05-aab1-d7c43c976b57",
"amount": 10000000,
"unit_price": 10000000,
"quantity": 1,
"timestamp": "2020-03-01T00:00:00.000Z"
}
],
"do_not_invoice": false
},
"ledger": [
{
"invoice_id": "525b9759-7bbd-4a05-aab1-d7c43c976b57",
"amount": 10000000,
"timestamp": "2020-03-01T00:00:00.000Z",
"type": "PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION",
"segment_id": "2d45952c-5a6e-43a9-8aab-f61ee21be81a"
}
],
"created_at": "2020-01-01T00:00:00.000Z"
}
],
"overrides": [
{
"id": "6cf3292a-e85c-4be6-822c-e25ba9d19757",
"created_at": "2020-01-01T00:00:00.000Z",
"product": {
"id": "eae8903b-693b-41a7-8c0b-f23748c9a9c8",
"name": "My product B"
},
"starting_at": "2020-01-01T00:00:00.000Z",
"type": "MULTIPLIER",
"multiplier": 0.1
}
],
"scheduled_charges": [],
"scheduled_charges_on_usage_invoices": "ALL",
"transitions": [
{
"type": "RENEWAL",
"from_contract_id": "9bf48856-b430-42f4-844f-4d2ea85bcff8",
"to_contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
}
],
"reseller_royalties": [],
"usage_statement_schedule": {
"frequency": "MONTHLY",
"billing_anchor_date": "2020-01-01T00:00:00.000Z"
},
"created_at": "2019-12-31T14:23:55.234Z",
"created_by": "Alice"
},
"current": {
"rate_card_id": "92f3080d-27ca-4306-a23f-2430de61851e",
"starting_at": "2020-01-01T00:00:00.000Z",
"net_payment_terms_days": 7,
"ending_before": "2022-01-01T00:00:00.000Z",
"commits": [
{
"id": "62c0cb84-bf3f-48b9-9bcf-a8ddf8c1cf35",
"type": "PREPAID",
"name": "My test commit",
"description": "My test commit description",
"product": {
"id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
"name": "My product A"
},
"rollover_fraction": 0.1,
"applicable_product_ids": [
"13a2179b-f0cb-460b-85a1-cd42964ca533"
],
"access_schedule": {
"credit_type": {
"id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"name": "USD (cents)"
},
"schedule_items": [
{
"id": "2d45952c-5a6e-43a9-8aab-f61ee21be81a",
"amount": 10000000,
"starting_at": "2020-02-01T00:00:00.000Z",
"ending_before": "2021-02-01T00:00:00.000Z"
}
]
},
"invoice_schedule": {
"credit_type": {
"id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
"name": "USD (cents)"
},
"schedule_items": [
{
"id": "f15e4e23-f74e-4de4-9b3a-8b07434116c4",
"invoice_id": "525b9759-7bbd-4a05-aab1-d7c43c976b57",
"amount": 10000000,
"unit_price": 10000000,
"quantity": 1,
"timestamp": "2020-03-01T00:00:00.000Z"
}
],
"do_not_invoice": false
},
"created_at": "2020-01-01T00:00:00.000Z"
}
],
"overrides": [
{
"id": "6cf3292a-e85c-4be6-822c-e25ba9d19757",
"created_at": "2020-01-01T00:00:00.000Z",
"product": {
"id": "eae8903b-693b-41a7-8c0b-f23748c9a9c8",
"name": "My product B"
},
"starting_at": "2020-01-01T00:00:00.000Z",
"type": "MULTIPLIER",
"multiplier": 0.1
}
],
"scheduled_charges": [
{
"id": "8e511ff1-3fd5-4d86-bc89-1e80239874bf",
"name": "My test scheduled charge",
"product": {
"id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
"name": "My product A"
},
"schedule": {
"schedule_items": [
{
"id": "6ca40ebc-9c01-484e-a64e-4e47fbbd0ebe",
"invoice_id": "5cced82b-5464-41b4-9ea7-3e080e0a4dba",
"amount": 1000000,
"unit_price": 1000000,
"quantity": 1,
"timestamp": "2020-02-15T00:00:00.000Z"
}
]
}
}
],
"scheduled_charges_on_usage_invoices": "ALL",
"transitions": [
{
"type": "RENEWAL",
"from_contract_id": "9bf48856-b430-42f4-844f-4d2ea85bcff8",
"to_contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
}
],
"reseller_royalties": [],
"usage_statement_schedule": {
"frequency": "MONTHLY",
"billing_anchor_date": "2020-01-01T00:00:00.000Z"
},
"created_at": "2019-12-31T14:23:55.234Z",
"created_by": "Alice"
},
"amendments": [
{
"id": "4e2fab26-31ea-473c-b07d-1ce10e7c0146",
"starting_at": "2020-04-01T00:00:00.000Z",
"scheduled_charges": [
{
"id": "8e511ff1-3fd5-4d86-bc89-1e80239874bf",
"name": "My test scheduled charge",
"product": {
"id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
"name": "My product A"
},
"schedule": {
"schedule_items": [
{
"id": "6ca40ebc-9c01-484e-a64e-4e47fbbd0ebe",
"invoice_id": "5cced82b-5464-41b4-9ea7-3e080e0a4dba",
"amount": 1000000,
"unit_price": 1000000,
"quantity": 1,
"timestamp": "2020-02-15T00:00:00.000Z"
}
]
}
}
],
"commits": [],
"overrides": [],
"created_at": "2019-12-31T16:12:45.123Z",
"created_by": "Bob"
}
],
"custom_fields": {
"x_account_id": "KyVnHhSBWl7eY2bl"
}
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
List all contracts for a customer
Include commit ledgers in the response. Setting this flag may cause the query to be slower.
Include the balance of credits and commits in the response. Setting this flag may cause the query to be slower.
Include archived contracts in the response
Optional RFC 3339 timestamp. If provided, the response will include only contracts where effective_at is on or after the provided date. This cannot be provided if the covering_date filter is provided.
Optional RFC 3339 timestamp. If provided, the response will include only contracts effective on the provided date. This cannot be provided if the starting_at filter is provided.
Response
Success
Show child attributes
Show child attributes
⌘I