GET STARTED
ENDPOINTS
- POSTCreate a contract
- POSTGet a contract (v2)
- POSTGet a contract (v1)
- POSTList customer contracts (v2)
- POSTList customer contracts (v1)
- POSTGet the rate schedule for a contract
- POSTList seat balances
- POSTGet subscription quantity history
- POSTGet subscription seats history
- POSTGet contract edit history
- POSTEdit a contract
- POSTAmend a contract
- POSTSet a contract usage filter
- POSTUpdate invoice issue date
- POSTUpdate the contract end date
- POSTCreate historical invoices
- POSTArchive a contract
- POST
curl --request POST \
--url https://api.metronome.com/v2/contracts/getEditHistory \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
"contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
}
'{
"data": [
{
"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
"add_commits": [
{
"id": "addda517-6d7a-42ea-834c-f5e6cf8c670e",
"type": "PREPAID",
"product": {
"id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
"name": "My product A"
},
"description": "A new commit",
"applicable_product_tags": [
"tag1",
"tag2"
],
"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
}
}
]
},
{
"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
"add_overrides": [
{
"id": "6cf3292a-e85c-4be6-822c-e25ba9d19757",
"starting_at": "2020-01-01T00:00:00.000Z",
"type": "MULTIPLIER",
"multiplier": 1.5,
"priority": 1,
"override_specifiers": [
{
"product_tags": [
"tag1"
],
"pricing_group_values": {
"region": "us-west-1",
"hardware_type": "gpu"
}
}
],
"entitled": true
}
]
}
]
}Get contract edit history
List all the edits made to a contract over time. In Metronome, you can edit a contract at any point after it’s created to fix mistakes or reflect changes in terms. Metronome stores a full history of all edits that were ever made to a contract, whether through the UI, editContract endpoint, or other endpoints like updateContractEndDate.
Use this endpoint to:
- Understand what changes were made to a contract, when, and by who
Key response fields:
- An array of every edit ever made to the contract
- Details on each individual edit - for example showing that in one edit, a user added two discounts and incremented a subscription quantity.
curl --request POST \
--url https://api.metronome.com/v2/contracts/getEditHistory \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
"contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
}
'{
"data": [
{
"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
"add_commits": [
{
"id": "addda517-6d7a-42ea-834c-f5e6cf8c670e",
"type": "PREPAID",
"product": {
"id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
"name": "My product A"
},
"description": "A new commit",
"applicable_product_tags": [
"tag1",
"tag2"
],
"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
}
}
]
},
{
"id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
"add_overrides": [
{
"id": "6cf3292a-e85c-4be6-822c-e25ba9d19757",
"starting_at": "2020-01-01T00:00:00.000Z",
"type": "MULTIPLIER",
"multiplier": 1.5,
"priority": 1,
"override_specifiers": [
{
"product_tags": [
"tag1"
],
"pricing_group_values": {
"region": "us-west-1",
"hardware_type": "gpu"
}
}
],
"entitled": true
}
]
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Response
Success
Show child attributes
Show child attributes
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.
1 - 128Show child attributes
Show child attributes
Show child attributes
Show child attributes
MONTHLY, QUARTERLY, ANNUAL, WEEKLY OVERWRITE, MULTIPLIER, TIERED Show child attributes
Show child attributes
FLAT, flat, PERCENTAGE, percentage, SUBSCRIPTION, subscription, TIERED, tiered 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.
Default quantity. For SUBSCRIPTION rate_type, this must be >=0.
Default proration configuration. Only valid for SUBSCRIPTION rate_type. Must be set to true.
COMMIT_RATE, LIST_RATE Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
This field is only applicable to commit invoice schedules. If true, this schedule will not generate an invoice.
displayed on invoices
1Show child attributes
Show child attributes
PREPAID, POSTPAID COMMIT_RATE, LIST_RATE If multiple credits or commits are applicable, the one with the lower priority will apply first.
The schedule that the customer will gain access to the credits purposed with this commit.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The schedule that the customer will be invoiced for this commit.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
If true, this schedule will not generate an invoice.
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. Instead, to target usage by product or product tag, pass those values in the body of specifiers.
Show child attributes
Show child attributes
If provided, the specifier will only apply to the product with the specified ID.
If provided, the specifier will only apply to products with all the specified tags.
Show child attributes
Show child attributes
CREDIT If multiple credits or commits are applicable, the one with the lower priority will apply first.
The schedule that the customer will gain access to the credits.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
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. Instead, to target usage by product or product tag, pass those values in the body of specifiers.
Show child attributes
Show child attributes
If provided, the specifier will only apply to the product with the specified ID.
If provided, the specifier will only apply to products with all the specified tags.
Show child attributes
Show child attributes
Will be passed down to the individual commits
Whether the created commits will use the commit rate or list rate
COMMIT_RATE, commit_rate, LIST_RATE, list_rate Determines the start time for the first commit
Displayed on invoices. Will be passed through to the individual commits
Will be passed down to the individual commits
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.
Will be passed down to the individual commits
Will be passed down to the individual commits
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.
Show child attributes
Show child attributes
If provided, the specifier will only apply to the product with the specified ID.
If provided, the specifier will only apply to products with all the specified tags.
Determines when the contract will stop creating recurring commits. Optional
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.
MONTHLY, monthly, QUARTERLY, quarterly, ANNUAL, annual, WEEKLY, weekly 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).
NONE, none, FIRST, first, LAST, last, FIRST_AND_LAST, first_and_last Attach a subscription to the recurring commit/credit.
Show child attributes
Show child attributes
INDIVIDUAL, POOLED The amount the customer should be billed for the commit. Not required.
Show child attributes
Show child attributes
Will be passed down to the individual commits
Whether the created commits will use the commit rate or list rate
COMMIT_RATE, commit_rate, LIST_RATE, list_rate Determines the start time for the first commit
Displayed on invoices. Will be passed through to the individual commits
Will be passed down to the individual commits
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.
Will be passed down to the individual commits
Will be passed down to the individual commits
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.
Show child attributes
Show child attributes
If provided, the specifier will only apply to the product with the specified ID.
If provided, the specifier will only apply to products with all the specified tags.
Determines when the contract will stop creating recurring commits. Optional
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.
MONTHLY, monthly, QUARTERLY, quarterly, ANNUAL, annual, WEEKLY, weekly 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).
NONE, none, FIRST, first, LAST, last, FIRST_AND_LAST, first_and_last Attach a subscription to the recurring commit/credit.
Show child attributes
Show child attributes
INDIVIDUAL, POOLED Show child attributes
Show child attributes
This will match contract starting_at value if usage filter is active from the beginning of the contract.
This will match contract ending_before value if usage filter is active until the end of the contract. It will be undefined if the contract is open-ended.
List of subscriptions on the contract.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
MONTHLY, QUARTERLY, ANNUAL, WEEKLY, monthly, quarterly, annual, weekly ADVANCE, ARREARS, advance, arrears List of quantity schedule items for the subscription. Only includes the current quantity and future quantity changes.
Previous, current, and next billing periods for the subscription.
Show child attributes
Show child attributes
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_BASED, seat_based, QUANTITY_ONLY, quantity_only Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
Specify the threshold amount for the contract. Each time the contract's balance lowers to this amount, a threshold charge will be initiated.
Specify the amount the balance should be recharged to.
Show child attributes
Show child attributes
The commit product that will be used to generate the line item for commit payment.
Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name.
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.
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.
Show child attributes
Show child attributes
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.
NONE, STRIPE, EXTERNAL 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.
NONE, STRIPE, ANROK, AVALARA, PRECALCULATED Only applicable if using STRIPE as your payment gateway type.
Show child attributes
Show child attributes
If left blank, will default to INVOICE
INVOICE, PAYMENT_INTENT Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type.
Show child attributes
Show child attributes
Only applicable if using PRECALCULATED as your tax type.
Show child attributes
Show child attributes
Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule
Name of the tax to be applied. This may be used in an invoice line item 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.
Show child attributes
Show child attributes
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.
Specify the threshold amount for the contract. Each time the contract's usage hits this amount, a threshold charge will be initiated.
Show child attributes
Show child attributes
The commit product that will be used to generate the line item for commit payment.
Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name.
Show child attributes
Show child attributes
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.
NONE, STRIPE, EXTERNAL 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.
NONE, STRIPE, ANROK, AVALARA, PRECALCULATED Only applicable if using STRIPE as your payment gateway type.
Show child attributes
Show child attributes
If left blank, will default to INVOICE
INVOICE, PAYMENT_INTENT Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type.
Show child attributes
Show child attributes
Only applicable if using PRECALCULATED as your tax type.
Show child attributes
Show child attributes
Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule
Name of the tax to be applied. This may be used in an invoice line item description.
Value to update the contract name to. If not provided, the contract name will remain unchanged.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
RFC 3339 timestamp (inclusive)
RFC 3339 timestamp (exclusive)
Show child attributes
Show child attributes
RFC 3339 timestamp (inclusive)
RFC 3339 timestamp (exclusive)
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Which products the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products.
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. Instead, to target usage by product or product tag, pass those values in the body of specifiers.
Show child attributes
Show child attributes
If provided, the specifier will only apply to the product with the specified ID.
If provided, the specifier will only apply to products with all the specified tags.
Which tags the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products.
If multiple commits are applicable, the one with the lower priority will apply first.
If set, the commit's rate type was updated to the specified value.
COMMIT_RATE, LIST_RATE Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
RFC 3339 timestamp (inclusive)
RFC 3339 timestamp (exclusive)
Show child attributes
Show child attributes
RFC 3339 timestamp (inclusive)
RFC 3339 timestamp (exclusive)
If multiple credits are applicable, the one with the lower priority will apply first.
If set, the credit's rate type was updated to the specified value.
LIST_RATE, COMMIT_RATE Show child attributes
Show child attributes
LIST_RATE, list_rate, COMMIT_RATE, commit_rate Show child attributes
Show child attributes
LIST_RATE, list_rate, COMMIT_RATE, commit_rate Optional list of subscriptions to update.
Show child attributes
Show child attributes
Manage subscription seats for subscriptions in SEAT_BASED mode.
Show child attributes
Show child attributes
Adds seat IDs to the subscription. If there are unassigned seats, the new seat IDs will fill these unassigned seats and not increase the total subscription quantity. Otherwise, if there are more new seat IDs than unassigned seats, the total subscription quantity will increase.
Removes seat IDs from the subscription, if possible. If a seat ID is removed, the total subscription quantity will decrease. Otherwise, if the seat ID is not found on the subscription, this is a no-op.
Adds unassigned seats to the subscription. This will increase the total subscription quantity.
Show child attributes
Show child attributes
The number of unassigned seats on the subscription will increase/decrease by this delta. Must be greater than 0.
x >= 1Unassigned seats will be updated starting at this date.
Removes unassigned seats from the subscription. This will decrease the total subscription quantity if there are are unassigned seats.
Show child attributes
Show child attributes
The number of unassigned seats on the subscription will increase/decrease by this delta. Must be greater than 0.
x >= 1Unassigned seats will be updated starting at this date.
Show child attributes
Show child attributes
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.
Specify the threshold amount for the contract. Each time the contract's balance lowers to this amount, a threshold charge will be initiated.
Specify the amount the balance should be recharged to.
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.
Show child attributes
Show child attributes
The commit product that will be used to generate the line item for commit payment.
Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name.
Which products the threshold commit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the commit applies to all products.
Which tags the threshold commit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the commit applies to all products.
Show child attributes
Show child attributes
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.
NONE, STRIPE, EXTERNAL 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.
NONE, STRIPE, ANROK, AVALARA, PRECALCULATED Only applicable if using STRIPE as your payment gateway type.
Show child attributes
Show child attributes
If left blank, will default to INVOICE
INVOICE, PAYMENT_INTENT Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type.
Show child attributes
Show child attributes
Only applicable if using PRECALCULATED as your tax type.
Show child attributes
Show child attributes
Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule
Name of the tax to be applied. This may be used in an invoice line item description.
Show child attributes
Show child attributes
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.
Specify the threshold amount for the contract. Each time the contract's usage hits this amount, a threshold charge will be initiated.
Show child attributes
Show child attributes
The commit product that will be used to generate the line item for commit payment.
Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name.
Show child attributes
Show child attributes
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.
NONE, STRIPE, EXTERNAL 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.
NONE, STRIPE, ANROK, AVALARA, PRECALCULATED Only applicable if using STRIPE as your payment gateway type.
Show child attributes
Show child attributes
If left blank, will default to INVOICE
INVOICE, PAYMENT_INTENT Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type.
Show child attributes
Show child attributes
Only applicable if using PRECALCULATED as your tax type.
Show child attributes
Show child attributes
Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule
Name of the tax to be applied. This may be used in an invoice line item description.