# Contracts ## Create `client.v1.contracts.create(ContractCreateParamsbody, RequestOptionsoptions?): ContractCreateResponse` **post** `/v1/contracts/create` Create a new contract ### Parameters - **body:** `ContractCreateParams` - **customer\_id:** `string` - **starting\_at:** `string` inclusive contract start time - **billing\_provider\_configuration:** `BillingProviderConfiguration` The billing provider configuration associated with a contract. Provide either an ID or the provider and delivery method. - **billing\_provider:** `"aws_marketplace" | "azure_marketplace" | "gcp_marketplace" | 2 more` Do not specify if using billing_provider_configuration_id. - `"aws_marketplace"` - `"azure_marketplace"` - `"gcp_marketplace"` - `"stripe"` - `"netsuite"` - **billing\_provider\_configuration\_id:** `string` 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. - **delivery\_method:** `"direct_to_billing_provider" | "aws_sqs" | "tackle" | "aws_sns"` Do not specify if using billing_provider_configuration_id. - `"direct_to_billing_provider"` - `"aws_sqs"` - `"tackle"` - `"aws_sns"` - **commits:** `Array` - **product\_id:** `string` - **type:** `"PREPAID" | "POSTPAID"` - `"PREPAID"` - `"POSTPAID"` - **access\_schedule:** `AccessSchedule` 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. - **schedule\_items:** `Array` - **amount:** `number` - **ending\_before:** `string` RFC 3339 timestamp (exclusive) - **starting\_at:** `string` RFC 3339 timestamp (inclusive) - **credit\_type\_id:** `string` Defaults to USD (cents) if not passed - **amount:** `number` (DEPRECATED) Use access_schedule and invoice_schedule instead. - **applicable\_product\_ids:** `Array` 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:** `Array` Which tags the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products. - **custom\_fields:** `Record` - **description:** `string` Used only in UI/API. It is not exposed to end customers. - **hierarchy\_configuration:** `HierarchyConfiguration` Optional configuration for commit hierarchy access control - **child\_access:** `CommitHierarchyChildAccessAll | CommitHierarchyChildAccessNone | CommitHierarchyChildAccessContractIDs` - `CommitHierarchyChildAccessAll` - **type:** `"ALL"` - `"ALL"` - `CommitHierarchyChildAccessNone` - **type:** `"NONE"` - `"NONE"` - `CommitHierarchyChildAccessContractIDs` - **contract\_ids:** `Array` - **type:** `"CONTRACT_IDS"` - `"CONTRACT_IDS"` - **invoice\_schedule:** `InvoiceSchedule` 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. - **credit\_type\_id:** `string` Defaults to USD (cents) if not passed. - **do\_not\_invoice:** `boolean` This field is only applicable to commit invoice schedules. If true, this schedule will not generate an invoice. - **recurring\_schedule:** `RecurringSchedule` 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. - **amount\_distribution:** `"DIVIDED" | "DIVIDED_ROUNDED" | "EACH"` - `"DIVIDED"` - `"DIVIDED_ROUNDED"` - `"EACH"` - **ending\_before:** `string` RFC 3339 timestamp (exclusive). - **frequency:** `"MONTHLY" | "QUARTERLY" | "SEMI_ANNUAL" | "ANNUAL"` - `"MONTHLY"` - `"QUARTERLY"` - `"SEMI_ANNUAL"` - `"ANNUAL"` - **starting\_at:** `string` RFC 3339 timestamp (inclusive). - **amount:** `number` 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. - **quantity:** `number` 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. - **unit\_price:** `number` 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. - **schedule\_items:** `Array` Either provide amount or provide both unit_price and quantity. - **timestamp:** `string` timestamp of the scheduled event - **amount:** `number` 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. - **quantity:** `number` 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. - **unit\_price:** `number` 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. - **name:** `string` displayed on invoices - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **payment\_gate\_config:** `PaymentGateConfig` optionally payment gate this commit - **payment\_gate\_type:** `"NONE" | "STRIPE" | "EXTERNAL"` 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"` - **precalculated\_tax\_config:** `PrecalculatedTaxConfig` Only applicable if using PRECALCULATED as your tax type. - **tax\_amount:** `number` Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule - **tax\_name:** `string` Name of the tax to be applied. This may be used in an invoice line item description. - **stripe\_config:** `StripeConfig` Only applicable if using STRIPE as your payment gate type. - **payment\_type:** `"INVOICE" | "PAYMENT_INTENT"` If left blank, will default to INVOICE - `"INVOICE"` - `"PAYMENT_INTENT"` - **invoice\_metadata:** `Record` Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type. - **tax\_type:** `"NONE" | "STRIPE" | "ANROK" | "PRECALCULATED"` 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"` - `"PRECALCULATED"` - **priority:** `number` If multiple commits are applicable, the one with the lower priority will apply first. - **rate\_type:** `"COMMIT_RATE" | "LIST_RATE"` - `"COMMIT_RATE"` - `"LIST_RATE"` - **rollover\_fraction:** `number` Fraction of unused segments that will be rolled over. Must be between 0 and 1. - **specifiers:** `Array` 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`. - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` If provided, the specifier will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the specifier will only apply to products with all the specified tags. - **temporary\_id:** `string` A temporary ID for the commit that can be used to reference the commit for commit specific overrides. - **credits:** `Array` - **access\_schedule:** `AccessSchedule` Schedule for distributing the credit to the customer. - **schedule\_items:** `Array` - **amount:** `number` - **ending\_before:** `string` RFC 3339 timestamp (exclusive) - **starting\_at:** `string` RFC 3339 timestamp (inclusive) - **credit\_type\_id:** `string` Defaults to USD (cents) if not passed - **product\_id:** `string` - **applicable\_product\_ids:** `Array` 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:** `Array` Which tags the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products. - **custom\_fields:** `Record` - **description:** `string` Used only in UI/API. It is not exposed to end customers. - **hierarchy\_configuration:** `HierarchyConfiguration` Optional configuration for credit hierarchy access control - **child\_access:** `CommitHierarchyChildAccessAll | CommitHierarchyChildAccessNone | CommitHierarchyChildAccessContractIDs` - `CommitHierarchyChildAccessAll` - **type:** `"ALL"` - `"ALL"` - `CommitHierarchyChildAccessNone` - **type:** `"NONE"` - `"NONE"` - `CommitHierarchyChildAccessContractIDs` - **contract\_ids:** `Array` - **type:** `"CONTRACT_IDS"` - `"CONTRACT_IDS"` - **name:** `string` displayed on invoices - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **priority:** `number` If multiple credits are applicable, the one with the lower priority will apply first. - **rate\_type:** `"COMMIT_RATE" | "LIST_RATE"` - `"COMMIT_RATE"` - `"LIST_RATE"` - **specifiers:** `Array` 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`. - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` If provided, the specifier will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the specifier will only apply to products with all the specified tags. - **custom\_fields:** `Record` - **discounts:** `Array` This field's availability is dependent on your client's configuration. - **product\_id:** `string` - **schedule:** `Schedule` Must provide either schedule_items or recurring_schedule. - **credit\_type\_id:** `string` Defaults to USD (cents) if not passed. - **do\_not\_invoice:** `boolean` This field is only applicable to commit invoice schedules. If true, this schedule will not generate an invoice. - **recurring\_schedule:** `RecurringSchedule` 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. - **amount\_distribution:** `"DIVIDED" | "DIVIDED_ROUNDED" | "EACH"` - `"DIVIDED"` - `"DIVIDED_ROUNDED"` - `"EACH"` - **ending\_before:** `string` RFC 3339 timestamp (exclusive). - **frequency:** `"MONTHLY" | "QUARTERLY" | "SEMI_ANNUAL" | "ANNUAL"` - `"MONTHLY"` - `"QUARTERLY"` - `"SEMI_ANNUAL"` - `"ANNUAL"` - **starting\_at:** `string` RFC 3339 timestamp (inclusive). - **amount:** `number` 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. - **quantity:** `number` 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. - **unit\_price:** `number` 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. - **schedule\_items:** `Array` Either provide amount or provide both unit_price and quantity. - **timestamp:** `string` timestamp of the scheduled event - **amount:** `number` 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. - **quantity:** `number` 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. - **unit\_price:** `number` 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. - **custom\_fields:** `Record` - **name:** `string` displayed on invoices - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **ending\_before:** `string` exclusive contract end time - **hierarchy\_configuration:** `HierarchyConfiguration` - **parent:** `Parent` - **contract\_id:** `string` - **customer\_id:** `string` - **multiplier\_override\_prioritization:** `"LOWEST_MULTIPLIER" | "EXPLICIT"` 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. - `"LOWEST_MULTIPLIER"` - `"EXPLICIT"` - **name:** `string` - **net\_payment\_terms\_days:** `number` - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **overrides:** `Array` - **starting\_at:** `string` RFC 3339 timestamp indicating when the override will start applying (inclusive) - **applicable\_product\_tags:** `Array` tags identifying products whose rates are being overridden. Cannot be used in conjunction with override_specifiers. - **ending\_before:** `string` RFC 3339 timestamp indicating when the override will stop applying (exclusive) - **entitled:** `boolean` - **is\_commit\_specific:** `boolean` 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`. if you do not specify `commit_ids`, then the override will apply when consuming any prepaid or postpaid commit. - **multiplier:** `number` Required for MULTIPLIER type. Must be >=0. - **override\_specifiers:** `Array` 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. - **billing\_frequency:** `"MONTHLY" | "QUARTERLY" | "ANNUAL" | "WEEKLY"` - `"MONTHLY"` - `"QUARTERLY"` - `"ANNUAL"` - `"WEEKLY"` - **commit\_ids:** `Array` 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. - **presentation\_group\_values:** `Record` A map of group names to values. The override will only apply to line items with the specified presentation group values. - **pricing\_group\_values:** `Record` A map of pricing group names to values. The override will only apply to products with the specified pricing group values. - **product\_id:** `string` If provided, the override will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the override will only apply to products with all the specified tags. - **recurring\_commit\_ids:** `Array` 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. - **recurring\_credit\_ids:** `Array` 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 credits created by the specified recurring credit ids. - **overwrite\_rate:** `OverwriteRate` Required for OVERWRITE type. - **rate\_type:** `"FLAT" | "PERCENTAGE" | "SUBSCRIPTION" | 2 more` - `"FLAT"` - `"PERCENTAGE"` - `"SUBSCRIPTION"` - `"TIERED"` - `"CUSTOM"` - **credit\_type\_id:** `string` - **custom\_rate:** `Record` Only set for CUSTOM rate_type. This field is interpreted by custom rate processors. - **is\_prorated:** `boolean` Default proration configuration. Only valid for SUBSCRIPTION rate_type. Must be set to true. - **price:** `number` 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:** `number` Default quantity. For SUBSCRIPTION rate_type, this must be >=0. - **tiers:** `Array` Only set for TIERED rate_type. - **price:** `number` - **size:** `number` - **priority:** `number` 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. - **product\_id:** `string` ID of the product whose rate is being overridden. Cannot be used in conjunction with override_specifiers. - **target:** `"COMMIT_RATE" | "LIST_RATE"` 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"`. - `"COMMIT_RATE"` - `"LIST_RATE"` - **tiers:** `Array` Required for TIERED type. Must have at least one tier. - **multiplier:** `number` - **size:** `number` - **type:** `"OVERWRITE" | "MULTIPLIER" | "TIERED"` Overwrites are prioritized over multipliers and tiered overrides. - `"OVERWRITE"` - `"MULTIPLIER"` - `"TIERED"` - **prepaid\_balance\_threshold\_configuration:** `PrepaidBalanceThresholdConfiguration` - **commit:** `Commit` - **product\_id:** `string` The commit product that will be used to generate the line item for commit payment. - **applicable\_product\_ids:** `Array` 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:** `Array` 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. - **description:** `string` - **name:** `string` Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name. - **specifiers:** `Array` 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`. - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` If provided, the specifier will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the specifier will only apply to products with all the specified tags. - **is\_enabled:** `boolean` 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. - **payment\_gate\_config:** `PaymentGateConfig` - **payment\_gate\_type:** `"NONE" | "STRIPE" | "EXTERNAL"` 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"` - **precalculated\_tax\_config:** `PrecalculatedTaxConfig` Only applicable if using PRECALCULATED as your tax type. - **tax\_amount:** `number` Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule - **tax\_name:** `string` Name of the tax to be applied. This may be used in an invoice line item description. - **stripe\_config:** `StripeConfig` Only applicable if using STRIPE as your payment gate type. - **payment\_type:** `"INVOICE" | "PAYMENT_INTENT"` If left blank, will default to INVOICE - `"INVOICE"` - `"PAYMENT_INTENT"` - **invoice\_metadata:** `Record` Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type. - **tax\_type:** `"NONE" | "STRIPE" | "ANROK" | "PRECALCULATED"` 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"` - `"PRECALCULATED"` - **recharge\_to\_amount:** `number` Specify the amount the balance should be recharged to. - **threshold\_amount:** `number` Specify the threshold amount for the contract. Each time the contract's prepaid balance lowers to this amount, a threshold charge will be initiated. - **custom\_credit\_type\_id:** `string` 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. - **priority:** `number` Priority of the contract. - **professional\_services:** `Array` This field's availability is dependent on your client's configuration. - **max\_amount:** `number` Maximum amount for the term. - **product\_id:** `string` - **quantity:** `number` Quantity for the charge. Will be multiplied by unit_price to determine the amount. - **unit\_price:** `number` Unit price for the charge. Will be multiplied by quantity to determine the amount and must be specified. - **custom\_fields:** `Record` - **description:** `string` - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **rate\_card\_alias:** `string` Selects the rate card linked to the specified alias as of the contract's start date. - **rate\_card\_id:** `string` - **recurring\_commits:** `Array` - **access\_amount:** `AccessAmount` The amount of commit to grant. - **credit\_type\_id:** `string` - **unit\_price:** `number` - **quantity:** `number` This field is required unless a subscription is attached via `subscription_config`. - **commit\_duration:** `CommitDuration` 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. - **value:** `number` - **unit:** `"PERIODS"` - `"PERIODS"` - **priority:** `number` Will be passed down to the individual commits - **product\_id:** `string` - **starting\_at:** `string` determines the start time for the first commit - **applicable\_product\_ids:** `Array` Will be passed down to the individual commits - **applicable\_product\_tags:** `Array` Will be passed down to the individual commits - **description:** `string` Will be passed down to the individual commits - **ending\_before:** `string` Determines when the contract will stop creating recurring commits. optional - **hierarchy\_configuration:** `HierarchyConfiguration` Optional configuration for recurring commit/credit hierarchy access control - **child\_access:** `CommitHierarchyChildAccessAll | CommitHierarchyChildAccessNone | CommitHierarchyChildAccessContractIDs` - `CommitHierarchyChildAccessAll` - **type:** `"ALL"` - `"ALL"` - `CommitHierarchyChildAccessNone` - **type:** `"NONE"` - `"NONE"` - `CommitHierarchyChildAccessContractIDs` - **contract\_ids:** `Array` - **type:** `"CONTRACT_IDS"` - `"CONTRACT_IDS"` - **invoice\_amount:** `InvoiceAmount` The amount the customer should be billed for the commit. Not required. - **credit\_type\_id:** `string` - **quantity:** `number` - **unit\_price:** `number` - **name:** `string` displayed on invoices. will be passed through to the individual commits - **netsuite\_sales\_order\_id:** `string` Will be passed down to the individual commits - **proration:** `"NONE" | "FIRST" | "LAST" | "FIRST_AND_LAST"` 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"` - `"FIRST"` - `"LAST"` - `"FIRST_AND_LAST"` - **rate\_type:** `"COMMIT_RATE" | "LIST_RATE"` Whether the created commits will use the commit rate or list rate - `"COMMIT_RATE"` - `"LIST_RATE"` - **recurrence\_frequency:** `"MONTHLY" | "QUARTERLY" | "ANNUAL" | "WEEKLY"` 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"` - `"QUARTERLY"` - `"ANNUAL"` - `"WEEKLY"` - **rollover\_fraction:** `number` 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. - **specifiers:** `Array` 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`. - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` If provided, the specifier will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the specifier will only apply to products with all the specified tags. - **subscription\_config:** `SubscriptionConfig` Attach a subscription to the recurring commit/credit. - **apply\_seat\_increase\_config:** `ApplySeatIncreaseConfig` - **is\_prorated:** `boolean` Indicates whether a mid-period seat increase should be prorated. - **subscription\_id:** `string` ID of the subscription to configure on the recurring commit/credit. - **allocation:** `"POOLED"` If set to POOLED, allocation added per seat is pooled across the account. - `"POOLED"` - **temporary\_id:** `string` A temporary ID that can be used to reference the recurring commit for commit specific overrides. - **recurring\_credits:** `Array` - **access\_amount:** `AccessAmount` The amount of commit to grant. - **credit\_type\_id:** `string` - **unit\_price:** `number` - **quantity:** `number` This field is required unless a subscription is attached via `subscription_config`. - **commit\_duration:** `CommitDuration` 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. - **value:** `number` - **unit:** `"PERIODS"` - `"PERIODS"` - **priority:** `number` Will be passed down to the individual commits - **product\_id:** `string` - **starting\_at:** `string` determines the start time for the first commit - **applicable\_product\_ids:** `Array` Will be passed down to the individual commits - **applicable\_product\_tags:** `Array` Will be passed down to the individual commits - **description:** `string` Will be passed down to the individual commits - **ending\_before:** `string` Determines when the contract will stop creating recurring commits. optional - **hierarchy\_configuration:** `HierarchyConfiguration` Optional configuration for recurring commit/credit hierarchy access control - **child\_access:** `CommitHierarchyChildAccessAll | CommitHierarchyChildAccessNone | CommitHierarchyChildAccessContractIDs` - `CommitHierarchyChildAccessAll` - **type:** `"ALL"` - `"ALL"` - `CommitHierarchyChildAccessNone` - **type:** `"NONE"` - `"NONE"` - `CommitHierarchyChildAccessContractIDs` - **contract\_ids:** `Array` - **type:** `"CONTRACT_IDS"` - `"CONTRACT_IDS"` - **name:** `string` displayed on invoices. will be passed through to the individual commits - **netsuite\_sales\_order\_id:** `string` Will be passed down to the individual commits - **proration:** `"NONE" | "FIRST" | "LAST" | "FIRST_AND_LAST"` 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"` - `"FIRST"` - `"LAST"` - `"FIRST_AND_LAST"` - **rate\_type:** `"COMMIT_RATE" | "LIST_RATE"` Whether the created commits will use the commit rate or list rate - `"COMMIT_RATE"` - `"LIST_RATE"` - **recurrence\_frequency:** `"MONTHLY" | "QUARTERLY" | "ANNUAL" | "WEEKLY"` 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"` - `"QUARTERLY"` - `"ANNUAL"` - `"WEEKLY"` - **rollover\_fraction:** `number` 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. - **specifiers:** `Array` 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`. - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` If provided, the specifier will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the specifier will only apply to products with all the specified tags. - **subscription\_config:** `SubscriptionConfig` Attach a subscription to the recurring commit/credit. - **apply\_seat\_increase\_config:** `ApplySeatIncreaseConfig` - **is\_prorated:** `boolean` Indicates whether a mid-period seat increase should be prorated. - **subscription\_id:** `string` ID of the subscription to configure on the recurring commit/credit. - **allocation:** `"POOLED"` If set to POOLED, allocation added per seat is pooled across the account. - `"POOLED"` - **temporary\_id:** `string` A temporary ID that can be used to reference the recurring commit for commit specific overrides. - **reseller\_royalties:** `Array` This field's availability is dependent on your client's configuration. - **fraction:** `number` - **netsuite\_reseller\_id:** `string` - **reseller\_type:** `"AWS" | "AWS_PRO_SERVICE" | "GCP" | "GCP_PRO_SERVICE"` - `"AWS"` - `"AWS_PRO_SERVICE"` - `"GCP"` - `"GCP_PRO_SERVICE"` - **starting\_at:** `string` - **applicable\_product\_ids:** `Array` Must provide at least one of applicable_product_ids or applicable_product_tags. - **applicable\_product\_tags:** `Array` Must provide at least one of applicable_product_ids or applicable_product_tags. - **aws\_options:** `AwsOptions` - **aws\_account\_number:** `string` - **aws\_offer\_id:** `string` - **aws\_payer\_reference\_id:** `string` - **ending\_before:** `string` - **gcp\_options:** `GcpOptions` - **gcp\_account\_id:** `string` - **gcp\_offer\_id:** `string` - **reseller\_contract\_value:** `number` - **salesforce\_opportunity\_id:** `string` This field's availability is dependent on your client's configuration. - **scheduled\_charges:** `Array` - **product\_id:** `string` - **schedule:** `Schedule` Must provide either schedule_items or recurring_schedule. - **credit\_type\_id:** `string` Defaults to USD (cents) if not passed. - **do\_not\_invoice:** `boolean` This field is only applicable to commit invoice schedules. If true, this schedule will not generate an invoice. - **recurring\_schedule:** `RecurringSchedule` 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. - **amount\_distribution:** `"DIVIDED" | "DIVIDED_ROUNDED" | "EACH"` - `"DIVIDED"` - `"DIVIDED_ROUNDED"` - `"EACH"` - **ending\_before:** `string` RFC 3339 timestamp (exclusive). - **frequency:** `"MONTHLY" | "QUARTERLY" | "SEMI_ANNUAL" | "ANNUAL"` - `"MONTHLY"` - `"QUARTERLY"` - `"SEMI_ANNUAL"` - `"ANNUAL"` - **starting\_at:** `string` RFC 3339 timestamp (inclusive). - **amount:** `number` 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. - **quantity:** `number` 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. - **unit\_price:** `number` 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. - **schedule\_items:** `Array` Either provide amount or provide both unit_price and quantity. - **timestamp:** `string` timestamp of the scheduled event - **amount:** `number` 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. - **quantity:** `number` 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. - **unit\_price:** `number` 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. - **name:** `string` displayed on invoices - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **scheduled\_charges\_on\_usage\_invoices:** `"ALL"` 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. - `"ALL"` - **spend\_threshold\_configuration:** `SpendThresholdConfiguration` - **commit:** `Commit` - **product\_id:** `string` The commit product that will be used to generate the line item for commit payment. - **description:** `string` - **name:** `string` Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name. - **is\_enabled:** `boolean` 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. - **payment\_gate\_config:** `PaymentGateConfig` - **payment\_gate\_type:** `"NONE" | "STRIPE" | "EXTERNAL"` 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"` - **precalculated\_tax\_config:** `PrecalculatedTaxConfig` Only applicable if using PRECALCULATED as your tax type. - **tax\_amount:** `number` Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule - **tax\_name:** `string` Name of the tax to be applied. This may be used in an invoice line item description. - **stripe\_config:** `StripeConfig` Only applicable if using STRIPE as your payment gate type. - **payment\_type:** `"INVOICE" | "PAYMENT_INTENT"` If left blank, will default to INVOICE - `"INVOICE"` - `"PAYMENT_INTENT"` - **invoice\_metadata:** `Record` Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type. - **tax\_type:** `"NONE" | "STRIPE" | "ANROK" | "PRECALCULATED"` 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"` - `"PRECALCULATED"` - **threshold\_amount:** `number` Specify the threshold amount for the contract. Each time the contract's usage hits this amount, a threshold charge will be initiated. - **subscriptions:** `Array` Optional list of [subscriptions](https://docs.metronome.com/manage-product-access/create-subscription/) to add to the contract. - **collection\_schedule:** `"ADVANCE" | "ARREARS"` - `"ADVANCE"` - `"ARREARS"` - **initial\_quantity:** `number` The initial quantity for the subscription. It must be non-negative value. - **proration:** `Proration` - **invoice\_behavior:** `"BILL_IMMEDIATELY" | "BILL_ON_NEXT_COLLECTION_DATE"` Indicates how mid-period quantity adjustments are invoiced. **BILL\_IMMEDIATELY**: Only available when collection schedule is `ADVANCE`. The quantity increase will be billed immediately on the scheduled date. **BILL\_ON\_NEXT\_COLLECTION\_DATE**: The quantity increase will be billed for in-arrears at the end of the period. - `"BILL_IMMEDIATELY"` - `"BILL_ON_NEXT_COLLECTION_DATE"` - **is\_prorated:** `boolean` Indicates if the partial period will be prorated or charged a full amount. - **subscription\_rate:** `SubscriptionRate` - **billing\_frequency:** `"MONTHLY" | "QUARTERLY" | "ANNUAL" | "WEEKLY"` Frequency to bill subscription with. Together with product_id, must match existing rate on the rate card. - `"MONTHLY"` - `"QUARTERLY"` - `"ANNUAL"` - `"WEEKLY"` - **product\_id:** `string` Must be subscription type product - **custom\_fields:** `Record` - **description:** `string` - **ending\_before:** `string` Exclusive end time for the subscription. If not provided, subscription inherits contract end date. - **name:** `string` - **starting\_at:** `string` Inclusive start time for the subscription. If not provided, defaults to contract start date - **temporary\_id:** `string` A temporary ID used to reference the subscription in recurring commit/credit subscription configs created within the same payload. - **total\_contract\_value:** `number` This field's availability is dependent on your client's configuration. - **transition:** `Transition` - **from\_contract\_id:** `string` - **type:** `"SUPERSEDE" | "RENEWAL"` This field's available values may vary based on your client's configuration. - `"SUPERSEDE"` - `"RENEWAL"` - **future\_invoice\_behavior:** `FutureInvoiceBehavior` - **trueup:** `"REMOVE" | "AS_IS" | null` Controls whether future trueup invoices are billed or removed. Default behavior is AS_IS if not specified. - `"REMOVE"` - `"AS_IS"` - **uniqueness\_key:** `string` 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. - **usage\_filter:** `BaseUsageFilter` - **usage\_statement\_schedule:** `UsageStatementSchedule` - **frequency:** `"MONTHLY" | "QUARTERLY" | "ANNUAL" | "WEEKLY"` - `"MONTHLY"` - `"QUARTERLY"` - `"ANNUAL"` - `"WEEKLY"` - **billing\_anchor\_date:** `string` 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. - **day:** `"FIRST_OF_MONTH" | "CONTRACT_START" | "CUSTOM_DATE"` If not provided, defaults to the first day of the month. - `"FIRST_OF_MONTH"` - `"CONTRACT_START"` - `"CUSTOM_DATE"` - **invoice\_generation\_starting\_at:** `string` 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. ### Returns - `ContractCreateResponse` - **data:** `ID` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const contract = await client.v1.contracts.create({ customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d', starting_at: '2020-01-01T00:00:00.000Z', billing_provider_configuration: { billing_provider: 'stripe', delivery_method: 'direct_to_billing_provider', }, rate_card_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc', }); console.log(contract.data); ``` ## Retrieve `client.v1.contracts.retrieve(ContractRetrieveParamsbody, RequestOptionsoptions?): ContractRetrieveResponse` **post** `/v1/contracts/get` This is the v1 endpoint to get a contract. New clients should implement using the v2 endpoint. ### Parameters - **body:** `ContractRetrieveParams` - **contract\_id:** `string` - **customer\_id:** `string` - **include\_balance:** `boolean` Include the balance of credits and commits in the response. Setting this flag may cause the query to be slower. - **include\_ledgers:** `boolean` Include commit ledgers in the response. Setting this flag may cause the query to be slower. ### Returns - `ContractRetrieveResponse` - **data:** `Data` - **id:** `string` - **amendments:** `Array` - **id:** `string` - **commits:** `Array` - **id:** `string` - **product:** `Product` - **id:** `string` - **name:** `string` - **type:** `"PREPAID" | "POSTPAID"` - `"PREPAID"` - `"POSTPAID"` - **access\_schedule:** `ScheduleDuration` The schedule that the customer will gain access to the credits purposed with this commit. - **amount:** `number` (DEPRECATED) Use access_schedule + invoice_schedule instead. - **applicable\_contract\_ids:** `Array` - **applicable\_product\_ids:** `Array` - **applicable\_product\_tags:** `Array` - **archived\_at:** `string` RFC 3339 timestamp indicating when the commit was archived. If not provided, the commit is not archived. - **balance:** `number` 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. - **contract:** `Contract` - **id:** `string` - **custom\_fields:** `Record` - **description:** `string` - **hierarchy\_configuration:** `HierarchyConfiguration` Optional configuration for commit hierarchy access control - **child\_access:** `CommitHierarchyChildAccessAll | CommitHierarchyChildAccessNone | CommitHierarchyChildAccessContractIDs` - `CommitHierarchyChildAccessAll` - **type:** `"ALL"` - `"ALL"` - `CommitHierarchyChildAccessNone` - **type:** `"NONE"` - `"NONE"` - `CommitHierarchyChildAccessContractIDs` - **contract\_ids:** `Array` - **type:** `"CONTRACT_IDS"` - `"CONTRACT_IDS"` - **invoice\_contract:** `InvoiceContract` The contract that this commit will be billed on. - **id:** `string` - **invoice\_schedule:** `SchedulePointInTime` The schedule that the customer will be invoiced for this commit. - **ledger:** `Array` A list of ordered events that impact the balance of a commit. For example, an invoice deduction or a rollover. - `PrepaidCommitSegmentStartLedgerEntry` - **amount:** `number` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_SEGMENT_START"` - `"PREPAID_COMMIT_SEGMENT_START"` - `PrepaidCommitAutomatedInvoiceDeductionLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION"` - `"PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION"` - **contract\_id:** `string` - `PrepaidCommitRolloverLedgerEntry` - **amount:** `number` - **new\_contract\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_ROLLOVER"` - `"PREPAID_COMMIT_ROLLOVER"` - `PrepaidCommitExpirationLedgerEntry` - **amount:** `number` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_EXPIRATION"` - `"PREPAID_COMMIT_EXPIRATION"` - `PrepaidCommitCanceledLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_CANCELED"` - `"PREPAID_COMMIT_CANCELED"` - **contract\_id:** `string` - `PrepaidCommitCreditedLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_CREDITED"` - `"PREPAID_COMMIT_CREDITED"` - **contract\_id:** `string` - `PrepaidCommitSeatBasedAdjustmentLedgerEntry` - **amount:** `number` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_SEAT_BASED_ADJUSTMENT"` - `"PREPAID_COMMIT_SEAT_BASED_ADJUSTMENT"` - `PostpaidCommitInitialBalanceLedgerEntry` - **amount:** `number` - **timestamp:** `string` - **type:** `"POSTPAID_COMMIT_INITIAL_BALANCE"` - `"POSTPAID_COMMIT_INITIAL_BALANCE"` - `PostpaidCommitAutomatedInvoiceDeductionLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"POSTPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION"` - `"POSTPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION"` - **contract\_id:** `string` - `PostpaidCommitRolloverLedgerEntry` - **amount:** `number` - **new\_contract\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"POSTPAID_COMMIT_ROLLOVER"` - `"POSTPAID_COMMIT_ROLLOVER"` - `PostpaidCommitTrueupLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **timestamp:** `string` - **type:** `"POSTPAID_COMMIT_TRUEUP"` - `"POSTPAID_COMMIT_TRUEUP"` - **contract\_id:** `string` - `PrepaidCommitManualLedgerEntry` - **amount:** `number` - **reason:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_MANUAL"` - `"PREPAID_COMMIT_MANUAL"` - `PostpaidCommitManualLedgerEntry` - **amount:** `number` - **reason:** `string` - **timestamp:** `string` - **type:** `"POSTPAID_COMMIT_MANUAL"` - `"POSTPAID_COMMIT_MANUAL"` - `PostpaidCommitExpirationLedgerEntry` - **amount:** `number` - **timestamp:** `string` - **type:** `"POSTPAID_COMMIT_EXPIRATION"` - `"POSTPAID_COMMIT_EXPIRATION"` - **name:** `string` - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **priority:** `number` If multiple credits or commits are applicable, the one with the lower priority will apply first. - **rate\_type:** `"COMMIT_RATE" | "LIST_RATE"` - `"COMMIT_RATE"` - `"LIST_RATE"` - **rolled\_over\_from:** `RolledOverFrom` - **commit\_id:** `string` - **contract\_id:** `string` - **rollover\_fraction:** `number` - **salesforce\_opportunity\_id:** `string` This field's availability is dependent on your client's configuration. - **specifiers:** `Array` 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. - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` If provided, the specifier will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the specifier will only apply to products with all the specified tags. - **uniqueness\_key:** `string` 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. - **created\_at:** `string` - **created\_by:** `string` - **overrides:** `Array` - **id:** `string` - **starting\_at:** `string` - **applicable\_product\_tags:** `Array` - **credit\_type:** `CreditTypeData` - **ending\_before:** `string` - **entitled:** `boolean` - **is\_commit\_specific:** `boolean` - **is\_prorated:** `boolean` Default proration configuration. Only valid for SUBSCRIPTION rate_type. Must be set to true. - **multiplier:** `number` - **override\_specifiers:** `Array` - **billing\_frequency:** `"MONTHLY" | "QUARTERLY" | "ANNUAL" | "WEEKLY"` - `"MONTHLY"` - `"QUARTERLY"` - `"ANNUAL"` - `"WEEKLY"` - **commit\_ids:** `Array` - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` - **product\_tags:** `Array` - **recurring\_commit\_ids:** `Array` - **recurring\_credit\_ids:** `Array` - **override\_tiers:** `Array` - **multiplier:** `number` - **size:** `number` - **overwrite\_rate:** `OverwriteRate` - **rate\_type:** `"FLAT" | "PERCENTAGE" | "SUBSCRIPTION" | 2 more` - `"FLAT"` - `"PERCENTAGE"` - `"SUBSCRIPTION"` - `"TIERED"` - `"CUSTOM"` - **credit\_type:** `CreditTypeData` - **custom\_rate:** `Record` Only set for CUSTOM rate_type. This field is interpreted by custom rate processors. - **is\_prorated:** `boolean` Default proration configuration. Only valid for SUBSCRIPTION rate_type. Must be set to true. - **price:** `number` 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:** `number` Default quantity. For SUBSCRIPTION rate_type, this must be >=0. - **tiers:** `Array` Only set for TIERED rate_type. - **price:** `number` - **size:** `number` - **price:** `number` 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. - **priority:** `number` - **product:** `Product` - **id:** `string` - **name:** `string` - **quantity:** `number` Default quantity. For SUBSCRIPTION rate_type, this must be >=0. - **rate\_type:** `"FLAT" | "PERCENTAGE" | "SUBSCRIPTION" | 2 more` - `"FLAT"` - `"PERCENTAGE"` - `"SUBSCRIPTION"` - `"TIERED"` - `"CUSTOM"` - **target:** `"COMMIT_RATE" | "LIST_RATE"` - `"COMMIT_RATE"` - `"LIST_RATE"` - **tiers:** `Array` Only set for TIERED rate_type. - **price:** `number` - **size:** `number` - **type:** `"OVERWRITE" | "MULTIPLIER" | "TIERED"` - `"OVERWRITE"` - `"MULTIPLIER"` - `"TIERED"` - **value:** `Record` Only set for CUSTOM rate_type. This field is interpreted by custom rate processors. - **scheduled\_charges:** `Array` - **id:** `string` - **product:** `Product` - **id:** `string` - **name:** `string` - **schedule:** `SchedulePointInTime` - **archived\_at:** `string` - **custom\_fields:** `Record` - **name:** `string` displayed on invoices - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **starting\_at:** `string` - **credits:** `Array` - **id:** `string` - **product:** `Product` - **id:** `string` - **name:** `string` - **type:** `"CREDIT"` - `"CREDIT"` - **access\_schedule:** `ScheduleDuration` The schedule that the customer will gain access to the credits. - **applicable\_contract\_ids:** `Array` - **applicable\_product\_ids:** `Array` - **applicable\_product\_tags:** `Array` - **balance:** `number` 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. - **contract:** `Contract` - **id:** `string` - **custom\_fields:** `Record` - **description:** `string` - **hierarchy\_configuration:** `HierarchyConfiguration` Optional configuration for credit hierarchy access control - **child\_access:** `CommitHierarchyChildAccessAll | CommitHierarchyChildAccessNone | CommitHierarchyChildAccessContractIDs` - `CommitHierarchyChildAccessAll` - **type:** `"ALL"` - `"ALL"` - `CommitHierarchyChildAccessNone` - **type:** `"NONE"` - `"NONE"` - `CommitHierarchyChildAccessContractIDs` - **contract\_ids:** `Array` - **type:** `"CONTRACT_IDS"` - `"CONTRACT_IDS"` - **ledger:** `Array` A list of ordered events that impact the balance of a credit. For example, an invoice deduction or an expiration. - `CreditSegmentStartLedgerEntry` - **amount:** `number` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"CREDIT_SEGMENT_START"` - `"CREDIT_SEGMENT_START"` - `CreditAutomatedInvoiceDeductionLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"CREDIT_AUTOMATED_INVOICE_DEDUCTION"` - `"CREDIT_AUTOMATED_INVOICE_DEDUCTION"` - **contract\_id:** `string` - `CreditExpirationLedgerEntry` - **amount:** `number` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"CREDIT_EXPIRATION"` - `"CREDIT_EXPIRATION"` - `CreditCanceledLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"CREDIT_CANCELED"` - `"CREDIT_CANCELED"` - **contract\_id:** `string` - `CreditCreditedLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"CREDIT_CREDITED"` - `"CREDIT_CREDITED"` - **contract\_id:** `string` - `CreditManualLedgerEntry` - **amount:** `number` - **reason:** `string` - **timestamp:** `string` - **type:** `"CREDIT_MANUAL"` - `"CREDIT_MANUAL"` - `CreditSeatBasedAdjustmentLedgerEntry` - **amount:** `number` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"CREDIT_SEAT_BASED_ADJUSTMENT"` - `"CREDIT_SEAT_BASED_ADJUSTMENT"` - **name:** `string` - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **priority:** `number` If multiple credits or commits are applicable, the one with the lower priority will apply first. - **rate\_type:** `"COMMIT_RATE" | "LIST_RATE"` - `"COMMIT_RATE"` - `"LIST_RATE"` - **salesforce\_opportunity\_id:** `string` This field's availability is dependent on your client's configuration. - **specifiers:** `Array` 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. - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` If provided, the specifier will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the specifier will only apply to products with all the specified tags. - **uniqueness\_key:** `string` 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. - **discounts:** `Array` This field's availability is dependent on your client's configuration. - **id:** `string` - **product:** `Product` - **id:** `string` - **name:** `string` - **schedule:** `SchedulePointInTime` - **custom\_fields:** `Record` - **name:** `string` - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **professional\_services:** `Array` This field's availability is dependent on your client's configuration. - **id:** `string` - **max\_amount:** `number` Maximum amount for the term. - **product\_id:** `string` - **quantity:** `number` Quantity for the charge. Will be multiplied by unit_price to determine the amount. - **unit\_price:** `number` Unit price for the charge. Will be multiplied by quantity to determine the amount and must be specified. - **custom\_fields:** `Record` - **description:** `string` - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **reseller\_royalties:** `Array` This field's availability is dependent on your client's configuration. - **reseller\_type:** `"AWS" | "AWS_PRO_SERVICE" | "GCP" | "GCP_PRO_SERVICE"` - `"AWS"` - `"AWS_PRO_SERVICE"` - `"GCP"` - `"GCP_PRO_SERVICE"` - **aws\_account\_number:** `string` - **aws\_offer\_id:** `string` - **aws\_payer\_reference\_id:** `string` - **ending\_before:** `string | null` - **fraction:** `number` - **gcp\_account\_id:** `string` - **gcp\_offer\_id:** `string` - **netsuite\_reseller\_id:** `string` - **reseller\_contract\_value:** `number` - **starting\_at:** `string` - **salesforce\_opportunity\_id:** `string` This field's availability is dependent on your client's configuration. - **current:** `ContractWithoutAmendments` - **customer\_id:** `string` - **initial:** `ContractWithoutAmendments` - **archived\_at:** `string` RFC 3339 timestamp indicating when the contract was archived. If not returned, the contract is not archived. - **custom\_fields:** `Record` - **customer\_billing\_provider\_configuration:** `CustomerBillingProviderConfiguration` The billing provider configuration associated with a contract. - **billing\_provider:** `"aws_marketplace" | "stripe" | "netsuite" | 5 more` - `"aws_marketplace"` - `"stripe"` - `"netsuite"` - `"custom"` - `"azure_marketplace"` - `"quickbooks_online"` - `"workday"` - `"gcp_marketplace"` - **delivery\_method:** `"direct_to_billing_provider" | "aws_sqs" | "tackle" | "aws_sns"` - `"direct_to_billing_provider"` - `"aws_sqs"` - `"tackle"` - `"aws_sns"` - **id:** `string` - **configuration:** `Record` Configuration for the billing provider. The structure of this object is specific to the billing provider. - **prepaid\_balance\_threshold\_configuration:** `PrepaidBalanceThresholdConfiguration` - **commit:** `Commit` - **product\_id:** `string` The commit product that will be used to generate the line item for commit payment. - **applicable\_product\_ids:** `Array` 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:** `Array` 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. - **description:** `string` - **name:** `string` Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name. - **specifiers:** `Array` 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`. - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` If provided, the specifier will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the specifier will only apply to products with all the specified tags. - **is\_enabled:** `boolean` 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. - **payment\_gate\_config:** `PaymentGateConfig` - **payment\_gate\_type:** `"NONE" | "STRIPE" | "EXTERNAL"` 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"` - **precalculated\_tax\_config:** `PrecalculatedTaxConfig` Only applicable if using PRECALCULATED as your tax type. - **tax\_amount:** `number` Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule - **tax\_name:** `string` Name of the tax to be applied. This may be used in an invoice line item description. - **stripe\_config:** `StripeConfig` Only applicable if using STRIPE as your payment gate type. - **payment\_type:** `"INVOICE" | "PAYMENT_INTENT"` If left blank, will default to INVOICE - `"INVOICE"` - `"PAYMENT_INTENT"` - **invoice\_metadata:** `Record` Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type. - **tax\_type:** `"NONE" | "STRIPE" | "ANROK" | "PRECALCULATED"` 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"` - `"PRECALCULATED"` - **recharge\_to\_amount:** `number` Specify the amount the balance should be recharged to. - **threshold\_amount:** `number` Specify the threshold amount for the contract. Each time the contract's prepaid balance lowers to this amount, a threshold charge will be initiated. - **custom\_credit\_type\_id:** `string` 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. - **priority:** `number` Priority of the contract. - **scheduled\_charges\_on\_usage\_invoices:** `"ALL"` 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. - `"ALL"` - **spend\_threshold\_configuration:** `SpendThresholdConfiguration` - **commit:** `Commit` - **product\_id:** `string` The commit product that will be used to generate the line item for commit payment. - **description:** `string` - **name:** `string` Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name. - **is\_enabled:** `boolean` 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. - **payment\_gate\_config:** `PaymentGateConfig` - **payment\_gate\_type:** `"NONE" | "STRIPE" | "EXTERNAL"` 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"` - **precalculated\_tax\_config:** `PrecalculatedTaxConfig` Only applicable if using PRECALCULATED as your tax type. - **tax\_amount:** `number` Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule - **tax\_name:** `string` Name of the tax to be applied. This may be used in an invoice line item description. - **stripe\_config:** `StripeConfig` Only applicable if using STRIPE as your payment gate type. - **payment\_type:** `"INVOICE" | "PAYMENT_INTENT"` If left blank, will default to INVOICE - `"INVOICE"` - `"PAYMENT_INTENT"` - **invoice\_metadata:** `Record` Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type. - **tax\_type:** `"NONE" | "STRIPE" | "ANROK" | "PRECALCULATED"` 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"` - `"PRECALCULATED"` - **threshold\_amount:** `number` Specify the threshold amount for the contract. Each time the contract's usage hits this amount, a threshold charge will be initiated. - **subscriptions:** `Array` List of subscriptions on the contract. - **collection\_schedule:** `"ADVANCE" | "ARREARS"` - `"ADVANCE"` - `"ARREARS"` - **proration:** `Proration` - **invoice\_behavior:** `"BILL_IMMEDIATELY" | "BILL_ON_NEXT_COLLECTION_DATE"` - `"BILL_IMMEDIATELY"` - `"BILL_ON_NEXT_COLLECTION_DATE"` - **is\_prorated:** `boolean` - **quantity\_schedule:** `Array` List of quantity schedule items for the subscription. Only includes the current quantity and future quantity changes. - **quantity:** `number` - **starting\_at:** `string` - **ending\_before:** `string` - **starting\_at:** `string` - **subscription\_rate:** `SubscriptionRate` - **billing\_frequency:** `"MONTHLY" | "QUARTERLY" | "ANNUAL" | "WEEKLY"` - `"MONTHLY"` - `"QUARTERLY"` - `"ANNUAL"` - `"WEEKLY"` - **product:** `Product` - **id:** `string` - **name:** `string` - **id:** `string` - **custom\_fields:** `Record` - **description:** `string` - **ending\_before:** `string` - **fiat\_credit\_type\_id:** `string` - **name:** `string` - **uniqueness\_key:** `string` 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. ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const contract = await client.v1.contracts.retrieve({ contract_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc', customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d', }); console.log(contract.data); ``` ## List `client.v1.contracts.list(ContractListParamsbody, RequestOptionsoptions?): ContractListResponse` **post** `/v1/contracts/list` This is the v1 endpoint to list all contracts for a customer. New clients should implement using the v2 endpoint. ### Parameters - **body:** `ContractListParams` - **customer\_id:** `string` - **covering\_date:** `string` 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. - **include\_archived:** `boolean` Include archived contracts in the response - **include\_balance:** `boolean` Include the balance of credits and commits in the response. Setting this flag may cause the query to be slower. - **include\_ledgers:** `boolean` Include commit ledgers in the response. Setting this flag may cause the query to be slower. - **starting\_at:** `string` 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. ### Returns - `ContractListResponse` - **data:** `Array` - **id:** `string` - **amendments:** `Array` - **id:** `string` - **commits:** `Array` - **id:** `string` - **product:** `Product` - **id:** `string` - **name:** `string` - **type:** `"PREPAID" | "POSTPAID"` - `"PREPAID"` - `"POSTPAID"` - **access\_schedule:** `ScheduleDuration` The schedule that the customer will gain access to the credits purposed with this commit. - **amount:** `number` (DEPRECATED) Use access_schedule + invoice_schedule instead. - **applicable\_contract\_ids:** `Array` - **applicable\_product\_ids:** `Array` - **applicable\_product\_tags:** `Array` - **archived\_at:** `string` RFC 3339 timestamp indicating when the commit was archived. If not provided, the commit is not archived. - **balance:** `number` 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. - **contract:** `Contract` - **id:** `string` - **custom\_fields:** `Record` - **description:** `string` - **hierarchy\_configuration:** `HierarchyConfiguration` Optional configuration for commit hierarchy access control - **child\_access:** `CommitHierarchyChildAccessAll | CommitHierarchyChildAccessNone | CommitHierarchyChildAccessContractIDs` - `CommitHierarchyChildAccessAll` - **type:** `"ALL"` - `"ALL"` - `CommitHierarchyChildAccessNone` - **type:** `"NONE"` - `"NONE"` - `CommitHierarchyChildAccessContractIDs` - **contract\_ids:** `Array` - **type:** `"CONTRACT_IDS"` - `"CONTRACT_IDS"` - **invoice\_contract:** `InvoiceContract` The contract that this commit will be billed on. - **id:** `string` - **invoice\_schedule:** `SchedulePointInTime` The schedule that the customer will be invoiced for this commit. - **ledger:** `Array` A list of ordered events that impact the balance of a commit. For example, an invoice deduction or a rollover. - `PrepaidCommitSegmentStartLedgerEntry` - **amount:** `number` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_SEGMENT_START"` - `"PREPAID_COMMIT_SEGMENT_START"` - `PrepaidCommitAutomatedInvoiceDeductionLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION"` - `"PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION"` - **contract\_id:** `string` - `PrepaidCommitRolloverLedgerEntry` - **amount:** `number` - **new\_contract\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_ROLLOVER"` - `"PREPAID_COMMIT_ROLLOVER"` - `PrepaidCommitExpirationLedgerEntry` - **amount:** `number` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_EXPIRATION"` - `"PREPAID_COMMIT_EXPIRATION"` - `PrepaidCommitCanceledLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_CANCELED"` - `"PREPAID_COMMIT_CANCELED"` - **contract\_id:** `string` - `PrepaidCommitCreditedLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_CREDITED"` - `"PREPAID_COMMIT_CREDITED"` - **contract\_id:** `string` - `PrepaidCommitSeatBasedAdjustmentLedgerEntry` - **amount:** `number` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_SEAT_BASED_ADJUSTMENT"` - `"PREPAID_COMMIT_SEAT_BASED_ADJUSTMENT"` - `PostpaidCommitInitialBalanceLedgerEntry` - **amount:** `number` - **timestamp:** `string` - **type:** `"POSTPAID_COMMIT_INITIAL_BALANCE"` - `"POSTPAID_COMMIT_INITIAL_BALANCE"` - `PostpaidCommitAutomatedInvoiceDeductionLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"POSTPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION"` - `"POSTPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION"` - **contract\_id:** `string` - `PostpaidCommitRolloverLedgerEntry` - **amount:** `number` - **new\_contract\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"POSTPAID_COMMIT_ROLLOVER"` - `"POSTPAID_COMMIT_ROLLOVER"` - `PostpaidCommitTrueupLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **timestamp:** `string` - **type:** `"POSTPAID_COMMIT_TRUEUP"` - `"POSTPAID_COMMIT_TRUEUP"` - **contract\_id:** `string` - `PrepaidCommitManualLedgerEntry` - **amount:** `number` - **reason:** `string` - **timestamp:** `string` - **type:** `"PREPAID_COMMIT_MANUAL"` - `"PREPAID_COMMIT_MANUAL"` - `PostpaidCommitManualLedgerEntry` - **amount:** `number` - **reason:** `string` - **timestamp:** `string` - **type:** `"POSTPAID_COMMIT_MANUAL"` - `"POSTPAID_COMMIT_MANUAL"` - `PostpaidCommitExpirationLedgerEntry` - **amount:** `number` - **timestamp:** `string` - **type:** `"POSTPAID_COMMIT_EXPIRATION"` - `"POSTPAID_COMMIT_EXPIRATION"` - **name:** `string` - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **priority:** `number` If multiple credits or commits are applicable, the one with the lower priority will apply first. - **rate\_type:** `"COMMIT_RATE" | "LIST_RATE"` - `"COMMIT_RATE"` - `"LIST_RATE"` - **rolled\_over\_from:** `RolledOverFrom` - **commit\_id:** `string` - **contract\_id:** `string` - **rollover\_fraction:** `number` - **salesforce\_opportunity\_id:** `string` This field's availability is dependent on your client's configuration. - **specifiers:** `Array` 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. - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` If provided, the specifier will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the specifier will only apply to products with all the specified tags. - **uniqueness\_key:** `string` 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. - **created\_at:** `string` - **created\_by:** `string` - **overrides:** `Array` - **id:** `string` - **starting\_at:** `string` - **applicable\_product\_tags:** `Array` - **credit\_type:** `CreditTypeData` - **ending\_before:** `string` - **entitled:** `boolean` - **is\_commit\_specific:** `boolean` - **is\_prorated:** `boolean` Default proration configuration. Only valid for SUBSCRIPTION rate_type. Must be set to true. - **multiplier:** `number` - **override\_specifiers:** `Array` - **billing\_frequency:** `"MONTHLY" | "QUARTERLY" | "ANNUAL" | "WEEKLY"` - `"MONTHLY"` - `"QUARTERLY"` - `"ANNUAL"` - `"WEEKLY"` - **commit\_ids:** `Array` - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` - **product\_tags:** `Array` - **recurring\_commit\_ids:** `Array` - **recurring\_credit\_ids:** `Array` - **override\_tiers:** `Array` - **multiplier:** `number` - **size:** `number` - **overwrite\_rate:** `OverwriteRate` - **rate\_type:** `"FLAT" | "PERCENTAGE" | "SUBSCRIPTION" | 2 more` - `"FLAT"` - `"PERCENTAGE"` - `"SUBSCRIPTION"` - `"TIERED"` - `"CUSTOM"` - **credit\_type:** `CreditTypeData` - **custom\_rate:** `Record` Only set for CUSTOM rate_type. This field is interpreted by custom rate processors. - **is\_prorated:** `boolean` Default proration configuration. Only valid for SUBSCRIPTION rate_type. Must be set to true. - **price:** `number` 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:** `number` Default quantity. For SUBSCRIPTION rate_type, this must be >=0. - **tiers:** `Array` Only set for TIERED rate_type. - **price:** `number` - **size:** `number` - **price:** `number` 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. - **priority:** `number` - **product:** `Product` - **id:** `string` - **name:** `string` - **quantity:** `number` Default quantity. For SUBSCRIPTION rate_type, this must be >=0. - **rate\_type:** `"FLAT" | "PERCENTAGE" | "SUBSCRIPTION" | 2 more` - `"FLAT"` - `"PERCENTAGE"` - `"SUBSCRIPTION"` - `"TIERED"` - `"CUSTOM"` - **target:** `"COMMIT_RATE" | "LIST_RATE"` - `"COMMIT_RATE"` - `"LIST_RATE"` - **tiers:** `Array` Only set for TIERED rate_type. - **price:** `number` - **size:** `number` - **type:** `"OVERWRITE" | "MULTIPLIER" | "TIERED"` - `"OVERWRITE"` - `"MULTIPLIER"` - `"TIERED"` - **value:** `Record` Only set for CUSTOM rate_type. This field is interpreted by custom rate processors. - **scheduled\_charges:** `Array` - **id:** `string` - **product:** `Product` - **id:** `string` - **name:** `string` - **schedule:** `SchedulePointInTime` - **archived\_at:** `string` - **custom\_fields:** `Record` - **name:** `string` displayed on invoices - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **starting\_at:** `string` - **credits:** `Array` - **id:** `string` - **product:** `Product` - **id:** `string` - **name:** `string` - **type:** `"CREDIT"` - `"CREDIT"` - **access\_schedule:** `ScheduleDuration` The schedule that the customer will gain access to the credits. - **applicable\_contract\_ids:** `Array` - **applicable\_product\_ids:** `Array` - **applicable\_product\_tags:** `Array` - **balance:** `number` 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. - **contract:** `Contract` - **id:** `string` - **custom\_fields:** `Record` - **description:** `string` - **hierarchy\_configuration:** `HierarchyConfiguration` Optional configuration for credit hierarchy access control - **child\_access:** `CommitHierarchyChildAccessAll | CommitHierarchyChildAccessNone | CommitHierarchyChildAccessContractIDs` - `CommitHierarchyChildAccessAll` - **type:** `"ALL"` - `"ALL"` - `CommitHierarchyChildAccessNone` - **type:** `"NONE"` - `"NONE"` - `CommitHierarchyChildAccessContractIDs` - **contract\_ids:** `Array` - **type:** `"CONTRACT_IDS"` - `"CONTRACT_IDS"` - **ledger:** `Array` A list of ordered events that impact the balance of a credit. For example, an invoice deduction or an expiration. - `CreditSegmentStartLedgerEntry` - **amount:** `number` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"CREDIT_SEGMENT_START"` - `"CREDIT_SEGMENT_START"` - `CreditAutomatedInvoiceDeductionLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"CREDIT_AUTOMATED_INVOICE_DEDUCTION"` - `"CREDIT_AUTOMATED_INVOICE_DEDUCTION"` - **contract\_id:** `string` - `CreditExpirationLedgerEntry` - **amount:** `number` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"CREDIT_EXPIRATION"` - `"CREDIT_EXPIRATION"` - `CreditCanceledLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"CREDIT_CANCELED"` - `"CREDIT_CANCELED"` - **contract\_id:** `string` - `CreditCreditedLedgerEntry` - **amount:** `number` - **invoice\_id:** `string` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"CREDIT_CREDITED"` - `"CREDIT_CREDITED"` - **contract\_id:** `string` - `CreditManualLedgerEntry` - **amount:** `number` - **reason:** `string` - **timestamp:** `string` - **type:** `"CREDIT_MANUAL"` - `"CREDIT_MANUAL"` - `CreditSeatBasedAdjustmentLedgerEntry` - **amount:** `number` - **segment\_id:** `string` - **timestamp:** `string` - **type:** `"CREDIT_SEAT_BASED_ADJUSTMENT"` - `"CREDIT_SEAT_BASED_ADJUSTMENT"` - **name:** `string` - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **priority:** `number` If multiple credits or commits are applicable, the one with the lower priority will apply first. - **rate\_type:** `"COMMIT_RATE" | "LIST_RATE"` - `"COMMIT_RATE"` - `"LIST_RATE"` - **salesforce\_opportunity\_id:** `string` This field's availability is dependent on your client's configuration. - **specifiers:** `Array` 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. - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` If provided, the specifier will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the specifier will only apply to products with all the specified tags. - **uniqueness\_key:** `string` 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. - **discounts:** `Array` This field's availability is dependent on your client's configuration. - **id:** `string` - **product:** `Product` - **id:** `string` - **name:** `string` - **schedule:** `SchedulePointInTime` - **custom\_fields:** `Record` - **name:** `string` - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **professional\_services:** `Array` This field's availability is dependent on your client's configuration. - **id:** `string` - **max\_amount:** `number` Maximum amount for the term. - **product\_id:** `string` - **quantity:** `number` Quantity for the charge. Will be multiplied by unit_price to determine the amount. - **unit\_price:** `number` Unit price for the charge. Will be multiplied by quantity to determine the amount and must be specified. - **custom\_fields:** `Record` - **description:** `string` - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **reseller\_royalties:** `Array` This field's availability is dependent on your client's configuration. - **reseller\_type:** `"AWS" | "AWS_PRO_SERVICE" | "GCP" | "GCP_PRO_SERVICE"` - `"AWS"` - `"AWS_PRO_SERVICE"` - `"GCP"` - `"GCP_PRO_SERVICE"` - **aws\_account\_number:** `string` - **aws\_offer\_id:** `string` - **aws\_payer\_reference\_id:** `string` - **ending\_before:** `string | null` - **fraction:** `number` - **gcp\_account\_id:** `string` - **gcp\_offer\_id:** `string` - **netsuite\_reseller\_id:** `string` - **reseller\_contract\_value:** `number` - **starting\_at:** `string` - **salesforce\_opportunity\_id:** `string` This field's availability is dependent on your client's configuration. - **current:** `ContractWithoutAmendments` - **customer\_id:** `string` - **initial:** `ContractWithoutAmendments` - **archived\_at:** `string` RFC 3339 timestamp indicating when the contract was archived. If not returned, the contract is not archived. - **custom\_fields:** `Record` - **customer\_billing\_provider\_configuration:** `CustomerBillingProviderConfiguration` The billing provider configuration associated with a contract. - **billing\_provider:** `"aws_marketplace" | "stripe" | "netsuite" | 5 more` - `"aws_marketplace"` - `"stripe"` - `"netsuite"` - `"custom"` - `"azure_marketplace"` - `"quickbooks_online"` - `"workday"` - `"gcp_marketplace"` - **delivery\_method:** `"direct_to_billing_provider" | "aws_sqs" | "tackle" | "aws_sns"` - `"direct_to_billing_provider"` - `"aws_sqs"` - `"tackle"` - `"aws_sns"` - **id:** `string` - **configuration:** `Record` Configuration for the billing provider. The structure of this object is specific to the billing provider. - **prepaid\_balance\_threshold\_configuration:** `PrepaidBalanceThresholdConfiguration` - **commit:** `Commit` - **product\_id:** `string` The commit product that will be used to generate the line item for commit payment. - **applicable\_product\_ids:** `Array` 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:** `Array` 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. - **description:** `string` - **name:** `string` Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name. - **specifiers:** `Array` 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`. - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` If provided, the specifier will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the specifier will only apply to products with all the specified tags. - **is\_enabled:** `boolean` 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. - **payment\_gate\_config:** `PaymentGateConfig` - **payment\_gate\_type:** `"NONE" | "STRIPE" | "EXTERNAL"` 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"` - **precalculated\_tax\_config:** `PrecalculatedTaxConfig` Only applicable if using PRECALCULATED as your tax type. - **tax\_amount:** `number` Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule - **tax\_name:** `string` Name of the tax to be applied. This may be used in an invoice line item description. - **stripe\_config:** `StripeConfig` Only applicable if using STRIPE as your payment gate type. - **payment\_type:** `"INVOICE" | "PAYMENT_INTENT"` If left blank, will default to INVOICE - `"INVOICE"` - `"PAYMENT_INTENT"` - **invoice\_metadata:** `Record` Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type. - **tax\_type:** `"NONE" | "STRIPE" | "ANROK" | "PRECALCULATED"` 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"` - `"PRECALCULATED"` - **recharge\_to\_amount:** `number` Specify the amount the balance should be recharged to. - **threshold\_amount:** `number` Specify the threshold amount for the contract. Each time the contract's prepaid balance lowers to this amount, a threshold charge will be initiated. - **custom\_credit\_type\_id:** `string` 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. - **priority:** `number` Priority of the contract. - **scheduled\_charges\_on\_usage\_invoices:** `"ALL"` 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. - `"ALL"` - **spend\_threshold\_configuration:** `SpendThresholdConfiguration` - **commit:** `Commit` - **product\_id:** `string` The commit product that will be used to generate the line item for commit payment. - **description:** `string` - **name:** `string` Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name. - **is\_enabled:** `boolean` 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. - **payment\_gate\_config:** `PaymentGateConfig` - **payment\_gate\_type:** `"NONE" | "STRIPE" | "EXTERNAL"` 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"` - **precalculated\_tax\_config:** `PrecalculatedTaxConfig` Only applicable if using PRECALCULATED as your tax type. - **tax\_amount:** `number` Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule - **tax\_name:** `string` Name of the tax to be applied. This may be used in an invoice line item description. - **stripe\_config:** `StripeConfig` Only applicable if using STRIPE as your payment gate type. - **payment\_type:** `"INVOICE" | "PAYMENT_INTENT"` If left blank, will default to INVOICE - `"INVOICE"` - `"PAYMENT_INTENT"` - **invoice\_metadata:** `Record` Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type. - **tax\_type:** `"NONE" | "STRIPE" | "ANROK" | "PRECALCULATED"` 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"` - `"PRECALCULATED"` - **threshold\_amount:** `number` Specify the threshold amount for the contract. Each time the contract's usage hits this amount, a threshold charge will be initiated. - **subscriptions:** `Array` List of subscriptions on the contract. - **collection\_schedule:** `"ADVANCE" | "ARREARS"` - `"ADVANCE"` - `"ARREARS"` - **proration:** `Proration` - **invoice\_behavior:** `"BILL_IMMEDIATELY" | "BILL_ON_NEXT_COLLECTION_DATE"` - `"BILL_IMMEDIATELY"` - `"BILL_ON_NEXT_COLLECTION_DATE"` - **is\_prorated:** `boolean` - **quantity\_schedule:** `Array` List of quantity schedule items for the subscription. Only includes the current quantity and future quantity changes. - **quantity:** `number` - **starting\_at:** `string` - **ending\_before:** `string` - **starting\_at:** `string` - **subscription\_rate:** `SubscriptionRate` - **billing\_frequency:** `"MONTHLY" | "QUARTERLY" | "ANNUAL" | "WEEKLY"` - `"MONTHLY"` - `"QUARTERLY"` - `"ANNUAL"` - `"WEEKLY"` - **product:** `Product` - **id:** `string` - **name:** `string` - **id:** `string` - **custom\_fields:** `Record` - **description:** `string` - **ending\_before:** `string` - **fiat\_credit\_type\_id:** `string` - **name:** `string` - **uniqueness\_key:** `string` 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. ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const contracts = await client.v1.contracts.list({ customer_id: '9b85c1c1-5238-4f2a-a409-61412905e1e1' }); console.log(contracts.data); ``` ## Add Manual Balance Entry `client.v1.contracts.addManualBalanceEntry(ContractAddManualBalanceEntryParamsbody, RequestOptionsoptions?): void` **post** `/v1/contracts/addManualBalanceLedgerEntry` Add a manual balance entry ### Parameters - **body:** `ContractAddManualBalanceEntryParams` - **id:** `string` ID of the balance (commit or credit) to update. - **amount:** `number` Amount to add to the segment. A negative number will draw down from the balance. - **customer\_id:** `string` ID of the customer whose balance is to be updated. - **reason:** `string` Reason for the manual adjustment. This will be displayed in the ledger. - **segment\_id:** `string` ID of the segment to update. - **contract\_id:** `string` ID of the contract to update. Leave blank to update a customer level balance. - **timestamp:** `string` RFC 3339 timestamp indicating when the manual adjustment takes place. If not provided, it will default to the start of the segment. ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); await client.v1.contracts.addManualBalanceEntry({ id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85', amount: -1000, customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d', reason: 'Reason for entry', segment_id: '66368e29-3f97-4d15-a6e9-120897f0070a', contract_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc', }); ``` ## Amend `client.v1.contracts.amend(ContractAmendParamsbody, RequestOptionsoptions?): ContractAmendResponse` **post** `/v1/contracts/amend` Amendments will be replaced by Contract editing. New clients should implement using the editContract endpoint. Read more about the migration to contract editing [here](https://docs.metronome.com/migrate-amendments-to-edits/) and reach out to your Metronome representative for more details. Once contract editing is enabled, access to this endpoint will be removed. ### Parameters - **body:** `ContractAmendParams` - **contract\_id:** `string` ID of the contract to amend - **customer\_id:** `string` ID of the customer whose contract is to be amended - **starting\_at:** `string` inclusive start time for the amendment - **commits:** `Array` - **product\_id:** `string` - **type:** `"PREPAID" | "POSTPAID"` - `"PREPAID"` - `"POSTPAID"` - **access\_schedule:** `AccessSchedule` 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. - **schedule\_items:** `Array` - **amount:** `number` - **ending\_before:** `string` RFC 3339 timestamp (exclusive) - **starting\_at:** `string` RFC 3339 timestamp (inclusive) - **credit\_type\_id:** `string` Defaults to USD (cents) if not passed - **amount:** `number` (DEPRECATED) Use access_schedule and invoice_schedule instead. - **applicable\_product\_ids:** `Array` 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:** `Array` Which tags the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products. - **custom\_fields:** `Record` - **description:** `string` Used only in UI/API. It is not exposed to end customers. - **hierarchy\_configuration:** `HierarchyConfiguration` Optional configuration for commit hierarchy access control - **child\_access:** `CommitHierarchyChildAccessAll | CommitHierarchyChildAccessNone | CommitHierarchyChildAccessContractIDs` - `CommitHierarchyChildAccessAll` - **type:** `"ALL"` - `"ALL"` - `CommitHierarchyChildAccessNone` - **type:** `"NONE"` - `"NONE"` - `CommitHierarchyChildAccessContractIDs` - **contract\_ids:** `Array` - **type:** `"CONTRACT_IDS"` - `"CONTRACT_IDS"` - **invoice\_schedule:** `InvoiceSchedule` 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. - **credit\_type\_id:** `string` Defaults to USD (cents) if not passed. - **do\_not\_invoice:** `boolean` This field is only applicable to commit invoice schedules. If true, this schedule will not generate an invoice. - **recurring\_schedule:** `RecurringSchedule` 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. - **amount\_distribution:** `"DIVIDED" | "DIVIDED_ROUNDED" | "EACH"` - `"DIVIDED"` - `"DIVIDED_ROUNDED"` - `"EACH"` - **ending\_before:** `string` RFC 3339 timestamp (exclusive). - **frequency:** `"MONTHLY" | "QUARTERLY" | "SEMI_ANNUAL" | "ANNUAL"` - `"MONTHLY"` - `"QUARTERLY"` - `"SEMI_ANNUAL"` - `"ANNUAL"` - **starting\_at:** `string` RFC 3339 timestamp (inclusive). - **amount:** `number` 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. - **quantity:** `number` 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. - **unit\_price:** `number` 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. - **schedule\_items:** `Array` Either provide amount or provide both unit_price and quantity. - **timestamp:** `string` timestamp of the scheduled event - **amount:** `number` 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. - **quantity:** `number` 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. - **unit\_price:** `number` 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. - **name:** `string` displayed on invoices - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **payment\_gate\_config:** `PaymentGateConfig` optionally payment gate this commit - **payment\_gate\_type:** `"NONE" | "STRIPE" | "EXTERNAL"` 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"` - **precalculated\_tax\_config:** `PrecalculatedTaxConfig` Only applicable if using PRECALCULATED as your tax type. - **tax\_amount:** `number` Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule - **tax\_name:** `string` Name of the tax to be applied. This may be used in an invoice line item description. - **stripe\_config:** `StripeConfig` Only applicable if using STRIPE as your payment gate type. - **payment\_type:** `"INVOICE" | "PAYMENT_INTENT"` If left blank, will default to INVOICE - `"INVOICE"` - `"PAYMENT_INTENT"` - **invoice\_metadata:** `Record` Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type. - **tax\_type:** `"NONE" | "STRIPE" | "ANROK" | "PRECALCULATED"` 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"` - `"PRECALCULATED"` - **priority:** `number` If multiple commits are applicable, the one with the lower priority will apply first. - **rate\_type:** `"COMMIT_RATE" | "LIST_RATE"` - `"COMMIT_RATE"` - `"LIST_RATE"` - **rollover\_fraction:** `number` Fraction of unused segments that will be rolled over. Must be between 0 and 1. - **specifiers:** `Array` 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`. - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` If provided, the specifier will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the specifier will only apply to products with all the specified tags. - **temporary\_id:** `string` A temporary ID for the commit that can be used to reference the commit for commit specific overrides. - **credits:** `Array` - **access\_schedule:** `AccessSchedule` Schedule for distributing the credit to the customer. - **schedule\_items:** `Array` - **amount:** `number` - **ending\_before:** `string` RFC 3339 timestamp (exclusive) - **starting\_at:** `string` RFC 3339 timestamp (inclusive) - **credit\_type\_id:** `string` Defaults to USD (cents) if not passed - **product\_id:** `string` - **applicable\_product\_ids:** `Array` 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:** `Array` Which tags the credit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the credit applies to all products. - **custom\_fields:** `Record` - **description:** `string` Used only in UI/API. It is not exposed to end customers. - **hierarchy\_configuration:** `HierarchyConfiguration` Optional configuration for credit hierarchy access control - **child\_access:** `CommitHierarchyChildAccessAll | CommitHierarchyChildAccessNone | CommitHierarchyChildAccessContractIDs` - `CommitHierarchyChildAccessAll` - **type:** `"ALL"` - `"ALL"` - `CommitHierarchyChildAccessNone` - **type:** `"NONE"` - `"NONE"` - `CommitHierarchyChildAccessContractIDs` - **contract\_ids:** `Array` - **type:** `"CONTRACT_IDS"` - `"CONTRACT_IDS"` - **name:** `string` displayed on invoices - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **priority:** `number` If multiple credits are applicable, the one with the lower priority will apply first. - **rate\_type:** `"COMMIT_RATE" | "LIST_RATE"` - `"COMMIT_RATE"` - `"LIST_RATE"` - **specifiers:** `Array` 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`. - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **product\_id:** `string` If provided, the specifier will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the specifier will only apply to products with all the specified tags. - **custom\_fields:** `Record` - **discounts:** `Array` This field's availability is dependent on your client's configuration. - **product\_id:** `string` - **schedule:** `Schedule` Must provide either schedule_items or recurring_schedule. - **credit\_type\_id:** `string` Defaults to USD (cents) if not passed. - **do\_not\_invoice:** `boolean` This field is only applicable to commit invoice schedules. If true, this schedule will not generate an invoice. - **recurring\_schedule:** `RecurringSchedule` 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. - **amount\_distribution:** `"DIVIDED" | "DIVIDED_ROUNDED" | "EACH"` - `"DIVIDED"` - `"DIVIDED_ROUNDED"` - `"EACH"` - **ending\_before:** `string` RFC 3339 timestamp (exclusive). - **frequency:** `"MONTHLY" | "QUARTERLY" | "SEMI_ANNUAL" | "ANNUAL"` - `"MONTHLY"` - `"QUARTERLY"` - `"SEMI_ANNUAL"` - `"ANNUAL"` - **starting\_at:** `string` RFC 3339 timestamp (inclusive). - **amount:** `number` 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. - **quantity:** `number` 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. - **unit\_price:** `number` 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. - **schedule\_items:** `Array` Either provide amount or provide both unit_price and quantity. - **timestamp:** `string` timestamp of the scheduled event - **amount:** `number` 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. - **quantity:** `number` 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. - **unit\_price:** `number` 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. - **custom\_fields:** `Record` - **name:** `string` displayed on invoices - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **overrides:** `Array` - **starting\_at:** `string` RFC 3339 timestamp indicating when the override will start applying (inclusive) - **applicable\_product\_tags:** `Array` tags identifying products whose rates are being overridden. Cannot be used in conjunction with override_specifiers. - **ending\_before:** `string` RFC 3339 timestamp indicating when the override will stop applying (exclusive) - **entitled:** `boolean` - **is\_commit\_specific:** `boolean` 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`. if you do not specify `commit_ids`, then the override will apply when consuming any prepaid or postpaid commit. - **multiplier:** `number` Required for MULTIPLIER type. Must be >=0. - **override\_specifiers:** `Array` 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. - **billing\_frequency:** `"MONTHLY" | "QUARTERLY" | "ANNUAL" | "WEEKLY"` - `"MONTHLY"` - `"QUARTERLY"` - `"ANNUAL"` - `"WEEKLY"` - **commit\_ids:** `Array` 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. - **presentation\_group\_values:** `Record` A map of group names to values. The override will only apply to line items with the specified presentation group values. - **pricing\_group\_values:** `Record` A map of pricing group names to values. The override will only apply to products with the specified pricing group values. - **product\_id:** `string` If provided, the override will only apply to the product with the specified ID. - **product\_tags:** `Array` If provided, the override will only apply to products with all the specified tags. - **recurring\_commit\_ids:** `Array` 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. - **recurring\_credit\_ids:** `Array` 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 credits created by the specified recurring credit ids. - **overwrite\_rate:** `OverwriteRate` Required for OVERWRITE type. - **rate\_type:** `"FLAT" | "PERCENTAGE" | "SUBSCRIPTION" | 2 more` - `"FLAT"` - `"PERCENTAGE"` - `"SUBSCRIPTION"` - `"TIERED"` - `"CUSTOM"` - **credit\_type\_id:** `string` - **custom\_rate:** `Record` Only set for CUSTOM rate_type. This field is interpreted by custom rate processors. - **is\_prorated:** `boolean` Default proration configuration. Only valid for SUBSCRIPTION rate_type. Must be set to true. - **price:** `number` 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:** `number` Default quantity. For SUBSCRIPTION rate_type, this must be >=0. - **tiers:** `Array` Only set for TIERED rate_type. - **price:** `number` - **size:** `number` - **priority:** `number` 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. - **product\_id:** `string` ID of the product whose rate is being overridden. Cannot be used in conjunction with override_specifiers. - **target:** `"COMMIT_RATE" | "LIST_RATE"` 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"`. - `"COMMIT_RATE"` - `"LIST_RATE"` - **tiers:** `Array` Required for TIERED type. Must have at least one tier. - **multiplier:** `number` - **size:** `number` - **type:** `"OVERWRITE" | "MULTIPLIER" | "TIERED"` Overwrites are prioritized over multipliers and tiered overrides. - `"OVERWRITE"` - `"MULTIPLIER"` - `"TIERED"` - **professional\_services:** `Array` This field's availability is dependent on your client's configuration. - **max\_amount:** `number` Maximum amount for the term. - **product\_id:** `string` - **quantity:** `number` Quantity for the charge. Will be multiplied by unit_price to determine the amount. - **unit\_price:** `number` Unit price for the charge. Will be multiplied by quantity to determine the amount and must be specified. - **custom\_fields:** `Record` - **description:** `string` - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **reseller\_royalties:** `Array` This field's availability is dependent on your client's configuration. - **reseller\_type:** `"AWS" | "AWS_PRO_SERVICE" | "GCP" | "GCP_PRO_SERVICE"` - `"AWS"` - `"AWS_PRO_SERVICE"` - `"GCP"` - `"GCP_PRO_SERVICE"` - **applicable\_product\_ids:** `Array` Must provide at least one of applicable_product_ids or applicable_product_tags. - **applicable\_product\_tags:** `Array` Must provide at least one of applicable_product_ids or applicable_product_tags. - **aws\_options:** `AwsOptions` - **aws\_account\_number:** `string` - **aws\_offer\_id:** `string` - **aws\_payer\_reference\_id:** `string` - **ending\_before:** `string | null` Use null to indicate that the existing end timestamp should be removed. - **fraction:** `number` - **gcp\_options:** `GcpOptions` - **gcp\_account\_id:** `string` - **gcp\_offer\_id:** `string` - **netsuite\_reseller\_id:** `string` - **reseller\_contract\_value:** `number` - **starting\_at:** `string` - **salesforce\_opportunity\_id:** `string` This field's availability is dependent on your client's configuration. - **scheduled\_charges:** `Array` - **product\_id:** `string` - **schedule:** `Schedule` Must provide either schedule_items or recurring_schedule. - **credit\_type\_id:** `string` Defaults to USD (cents) if not passed. - **do\_not\_invoice:** `boolean` This field is only applicable to commit invoice schedules. If true, this schedule will not generate an invoice. - **recurring\_schedule:** `RecurringSchedule` 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. - **amount\_distribution:** `"DIVIDED" | "DIVIDED_ROUNDED" | "EACH"` - `"DIVIDED"` - `"DIVIDED_ROUNDED"` - `"EACH"` - **ending\_before:** `string` RFC 3339 timestamp (exclusive). - **frequency:** `"MONTHLY" | "QUARTERLY" | "SEMI_ANNUAL" | "ANNUAL"` - `"MONTHLY"` - `"QUARTERLY"` - `"SEMI_ANNUAL"` - `"ANNUAL"` - **starting\_at:** `string` RFC 3339 timestamp (inclusive). - **amount:** `number` 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. - **quantity:** `number` 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. - **unit\_price:** `number` 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. - **schedule\_items:** `Array` Either provide amount or provide both unit_price and quantity. - **timestamp:** `string` timestamp of the scheduled event - **amount:** `number` 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. - **quantity:** `number` 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. - **unit\_price:** `number` 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. - **name:** `string` displayed on invoices - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **total\_contract\_value:** `number` This field's availability is dependent on your client's configuration. ### Returns - `ContractAmendResponse` - **data:** `ID` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const response = await client.v1.contracts.amend({ contract_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc', customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d', starting_at: '2020-01-01T00:00:00.000Z', }); console.log(response.data); ``` ## Archive `client.v1.contracts.archive(ContractArchiveParamsbody, RequestOptionsoptions?): ContractArchiveResponse` **post** `/v1/contracts/archive` Archive a contract ### Parameters - **body:** `ContractArchiveParams` - **contract\_id:** `string` ID of the contract to archive - **customer\_id:** `string` ID of the customer whose contract is to be archived - **void\_invoices:** `boolean` If false, the existing finalized invoices will remain after the contract is archived. ### Returns - `ContractArchiveResponse` - **data:** `ID` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const response = await client.v1.contracts.archive({ contract_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc', customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d', void_invoices: true, }); console.log(response.data); ``` ## Create Historical Invoices `client.v1.contracts.createHistoricalInvoices(ContractCreateHistoricalInvoicesParamsbody, RequestOptionsoptions?): ContractCreateHistoricalInvoicesResponse` **post** `/v1/contracts/createHistoricalInvoices` Creates historical usage invoices for a contract ### Parameters - **body:** `ContractCreateHistoricalInvoicesParams` - **invoices:** `Array` - **contract\_id:** `string` - **credit\_type\_id:** `string` - **customer\_id:** `string` - **exclusive\_end\_date:** `string` - **inclusive\_start\_date:** `string` - **issue\_date:** `string` - **usage\_line\_items:** `Array` - **exclusive\_end\_date:** `string` - **inclusive\_start\_date:** `string` - **product\_id:** `string` - **presentation\_group\_values:** `Record` - **pricing\_group\_values:** `Record` - **quantity:** `number` - **subtotals\_with\_quantity:** `Array` - **exclusive\_end\_date:** `string` - **inclusive\_start\_date:** `string` - **quantity:** `number` - **billable\_status:** `"billable" | "unbillable"` This field's availability is dependent on your client's configuration. - `"billable"` - `"unbillable"` - **breakdown\_granularity:** `"HOUR" | "DAY"` - `"HOUR"` - `"DAY"` - **custom\_fields:** `Record` - **preview:** `boolean` ### Returns - `ContractCreateHistoricalInvoicesResponse` - **data:** `Array` - **id:** `string` - **credit\_type:** `CreditTypeData` - **customer\_id:** `string` - **line\_items:** `Array` - **credit\_type:** `CreditTypeData` - **name:** `string` - **total:** `number` - **applied\_commit\_or\_credit:** `AppliedCommitOrCredit` Details about the credit or commit that was applied to this line item. Only present on line items with product of `USAGE`, `SUBSCRIPTION` or `COMPOSITE` types. - **id:** `string` - **type:** `"PREPAID" | "POSTPAID" | "CREDIT"` - `"PREPAID"` - `"POSTPAID"` - `"CREDIT"` - **commit\_custom\_fields:** `Record` - **commit\_id:** `string` For line items with product of `USAGE`, `SUBSCRIPTION`, or `COMPOSITE` types, the ID of the credit or commit that was applied to this line item. For line items with product type of `FIXED`, the ID of the prepaid or postpaid commit that is being paid for. - **commit\_netsuite\_item\_id:** `string` - **commit\_netsuite\_sales\_order\_id:** `string` - **commit\_segment\_id:** `string` - **commit\_type:** `string` `PrepaidCommit` (for commit types `PREPAID` and `CREDIT`) or `PostpaidCommit` (for commit type `POSTPAID`). - **custom\_fields:** `Record` - **discount\_custom\_fields:** `Record` - **discount\_id:** `string` ID of the discount applied to this line item. - **ending\_before:** `string` The line item's end date (exclusive). - **group\_key:** `string` - **group\_value:** `string | null` - **is\_prorated:** `boolean` Indicates whether the line item is prorated for `SUBSCRIPTION` type product. - **list\_price:** `Rate` 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. - **metadata:** `string` - **netsuite\_invoice\_billing\_end:** `string` The end date for the billing period on the invoice. - **netsuite\_invoice\_billing\_start:** `string` The start date for the billing period on the invoice. - **netsuite\_item\_id:** `string` - **postpaid\_commit:** `PostpaidCommit` Only present for line items paying for a postpaid commit true-up. - **id:** `string` - **presentation\_group\_values:** `Record` Includes the presentation group values associated with this line item if presentation group keys are used. - **pricing\_group\_values:** `Record` Includes the pricing group values associated with this line item if dimensional pricing is used. - **product\_custom\_fields:** `Record` - **product\_id:** `string` ID of the product associated with the line item. - **product\_tags:** `Array` The current product tags associated with the line item's `product_id`. - **product\_type:** `string` 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`. - **professional\_service\_custom\_fields:** `Record` - **professional\_service\_id:** `string` - **quantity:** `number` The quantity associated with the line item. - **reseller\_type:** `"AWS" | "AWS_PRO_SERVICE" | "GCP" | "GCP_PRO_SERVICE"` - `"AWS"` - `"AWS_PRO_SERVICE"` - `"GCP"` - `"GCP_PRO_SERVICE"` - **scheduled\_charge\_custom\_fields:** `Record` - **scheduled\_charge\_id:** `string` ID of scheduled charge. - **starting\_at:** `string` The line item's start date (inclusive). - **sub\_line\_items:** `Array` - **custom\_fields:** `Record` - **name:** `string` - **quantity:** `number` - **subtotal:** `number` - **charge\_id:** `string` - **credit\_grant\_id:** `string` - **end\_date:** `string` The end date for the charge (for seats charges only). - **price:** `number` the unit price for this charge, present only if the charge is not tiered and the quantity is nonzero - **start\_date:** `string` The start date for the charge (for seats charges only). - **tier\_period:** `TierPeriod` when the current tier started and ends (for tiered charges only) - **starting\_at:** `string` - **ending\_before:** `string` - **tiers:** `Array` - **price:** `number` - **quantity:** `number` - **starting\_at:** `number` at what metric amount this tier begins - **subtotal:** `number` - **subscription\_custom\_fields:** `Record` - **tier:** `Tier` Populated if the line item has a tiered price. - **level:** `number` - **starting\_at:** `string` - **size:** `string | null` - **unit\_price:** `number` The unit price associated with the line item. - **status:** `string` - **total:** `number` - **type:** `string` - **amendment\_id:** `string` - **billable\_status:** `"billable" | "unbillable"` This field's availability is dependent on your client's configuration. - `"billable"` - `"unbillable"` - **contract\_custom\_fields:** `Record` - **contract\_id:** `string` - **correction\_record:** `CorrectionRecord` - **corrected\_invoice\_id:** `string` - **memo:** `string` - **reason:** `string` - **corrected\_external\_invoice:** `CorrectedExternalInvoice` - **billing\_provider\_type:** `"aws_marketplace" | "stripe" | "netsuite" | 5 more` - `"aws_marketplace"` - `"stripe"` - `"netsuite"` - `"custom"` - `"azure_marketplace"` - `"quickbooks_online"` - `"workday"` - `"gcp_marketplace"` - **external\_status:** `"DRAFT" | "FINALIZED" | "PAID" | 8 more` - `"DRAFT"` - `"FINALIZED"` - `"PAID"` - `"UNCOLLECTIBLE"` - `"VOID"` - `"DELETED"` - `"PAYMENT_FAILED"` - `"INVALID_REQUEST_ERROR"` - `"SKIPPED"` - `"SENT"` - `"QUEUED"` - **invoice\_id:** `string` - **issued\_at\_timestamp:** `string` - **created\_at:** `string` When the invoice was created (UTC). This field is present for correction invoices only. - **custom\_fields:** `Record` - **customer\_custom\_fields:** `Record` - **end\_timestamp:** `string` End of the usage period this invoice covers (UTC) - **external\_invoice:** `ExternalInvoice | null` - **billing\_provider\_type:** `"aws_marketplace" | "stripe" | "netsuite" | 5 more` - `"aws_marketplace"` - `"stripe"` - `"netsuite"` - `"custom"` - `"azure_marketplace"` - `"quickbooks_online"` - `"workday"` - `"gcp_marketplace"` - **external\_status:** `"DRAFT" | "FINALIZED" | "PAID" | 8 more` - `"DRAFT"` - `"FINALIZED"` - `"PAID"` - `"UNCOLLECTIBLE"` - `"VOID"` - `"DELETED"` - `"PAYMENT_FAILED"` - `"INVALID_REQUEST_ERROR"` - `"SKIPPED"` - `"SENT"` - `"QUEUED"` - **invoice\_id:** `string` - **issued\_at\_timestamp:** `string` - **invoice\_adjustments:** `Array` - **credit\_type:** `CreditTypeData` - **name:** `string` - **total:** `number` - **credit\_grant\_custom\_fields:** `Record` - **credit\_grant\_id:** `string` - **issued\_at:** `string` When the invoice was issued (UTC) - **net\_payment\_terms\_days:** `number` - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **plan\_custom\_fields:** `Record` - **plan\_id:** `string` - **plan\_name:** `string` - **reseller\_royalty:** `ResellerRoyalty` Only present for contract invoices with reseller royalties. - **fraction:** `string` - **netsuite\_reseller\_id:** `string` - **reseller\_type:** `"AWS" | "AWS_PRO_SERVICE" | "GCP" | "GCP_PRO_SERVICE"` - `"AWS"` - `"AWS_PRO_SERVICE"` - `"GCP"` - `"GCP_PRO_SERVICE"` - **aws\_options:** `AwsOptions` - **aws\_account\_number:** `string` - **aws\_offer\_id:** `string` - **aws\_payer\_reference\_id:** `string` - **gcp\_options:** `GcpOptions` - **gcp\_account\_id:** `string` - **gcp\_offer\_id:** `string` - **salesforce\_opportunity\_id:** `string` This field's availability is dependent on your client's configuration. - **start\_timestamp:** `string` Beginning of the usage period this invoice covers (UTC) - **subtotal:** `number` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const response = await client.v1.contracts.createHistoricalInvoices({ 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, }); console.log(response.data); ``` ## List Balances `client.v1.contracts.listBalances(ContractListBalancesParamsbody, RequestOptionsoptions?): ContractListBalancesResponse` **post** `/v1/contracts/customerBalances/list` List balances (commits and credits). ### Parameters - **body:** `ContractListBalancesParams` - **customer\_id:** `string` - **id:** `string` - **covering\_date:** `string` Return only balances that have access schedules that "cover" the provided date - **effective\_before:** `string` Include only balances that have any access before the provided date (exclusive) - **include\_archived:** `boolean` Include archived credits and credits from archived contracts. - **include\_balance:** `boolean` Include the balance of credits and commits in the response. Setting this flag may cause the query to be slower. - **include\_contract\_balances:** `boolean` Include balances on the contract level. - **include\_ledgers:** `boolean` Include ledgers in the response. Setting this flag may cause the query to be slower. - **limit:** `number` The maximum number of commits to return. Defaults to 25. - **next\_page:** `string` The next page token from a previous response. - **starting\_at:** `string` Include only balances that have any access on or after the provided date ### Returns - `ContractListBalancesResponse` - **data:** `Array` - `Commit` - `Credit` - **next\_page:** `string | null` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const response = await client.v1.contracts.listBalances({ customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d', id: '6162d87b-e5db-4a33-b7f2-76ce6ead4e85', include_ledgers: true, }); console.log(response.data); ``` ## Retrieve Rate Schedule `client.v1.contracts.retrieveRateSchedule(ContractRetrieveRateScheduleParamsparams, RequestOptionsoptions?): ContractRetrieveRateScheduleResponse` **post** `/v1/contracts/getContractRateSchedule` Get the rate schedule for the rate card on a given contract. ### Parameters - **params:** `ContractRetrieveRateScheduleParams` - **contract\_id:** `string` Body param: ID of the contract to get the rate schedule for. - **customer\_id:** `string` Body param: ID of the customer for whose contract to get the rate schedule for. - **limit:** `number` Query param: Max number of results that should be returned - **next\_page:** `string` Query param: Cursor that indicates where the next page of results should start. - **at:** `string` Body param: optional timestamp which overlaps with the returned rate schedule segments. When not specified, the current timestamp will be used. - **selectors:** `Array` Body param: 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. - **billing\_frequency:** `"MONTHLY" | "QUARTERLY" | "ANNUAL" | "WEEKLY"` Subscription rates matching the billing frequency will be included in the response. - `"MONTHLY"` - `"QUARTERLY"` - `"ANNUAL"` - `"WEEKLY"` - **partial\_pricing\_group\_values:** `Record` List of pricing group key value pairs, rates containing the matching key / value pairs will be included in the response. - **pricing\_group\_values:** `Record` List of pricing group key value pairs, rates matching all of the key / value pairs will be included in the response. - **product\_id:** `string` Rates matching the product id will be included in the response. - **product\_tags:** `Array` List of product tags, rates matching any of the tags will be included in the response. ### Returns - `ContractRetrieveRateScheduleResponse` - **data:** `Array` - **entitled:** `boolean` - **list\_rate:** `Rate` - **product\_custom\_fields:** `Record` - **product\_id:** `string` - **product\_name:** `string` - **product\_tags:** `Array` - **rate\_card\_id:** `string` - **starting\_at:** `string` - **billing\_frequency:** `"MONTHLY" | "QUARTERLY" | "ANNUAL" | "WEEKLY"` - `"MONTHLY"` - `"QUARTERLY"` - `"ANNUAL"` - `"WEEKLY"` - **commit\_rate:** `CommitRate` A distinct rate on the rate card. You can choose to use this rate rather than list rate when consuming a credit or commit. - **rate\_type:** `"FLAT" | "PERCENTAGE" | "SUBSCRIPTION" | 2 more` - `"FLAT"` - `"PERCENTAGE"` - `"SUBSCRIPTION"` - `"TIERED"` - `"CUSTOM"` - **price:** `number` Commit rate price. For FLAT rate_type, this must be >=0. - **tiers:** `Array` Only set for TIERED rate_type. - **price:** `number` - **size:** `number` - **ending\_before:** `string` - **override\_rate:** `Rate` - **pricing\_group\_values:** `Record` - **next\_page:** `string | null` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const response = await client.v1.contracts.retrieveRateSchedule({ contract_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc', customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d', at: '2020-01-01T00:00:00.000Z', selectors: [ { product_id: 'd6300dbb-882e-4d2d-8dec-5125d16b65d0', partial_pricing_group_values: { region: 'us-west-2', cloud: 'aws' }, }, ], }); console.log(response.data); ``` ## Retrieve Subscription Quantity History `client.v1.contracts.retrieveSubscriptionQuantityHistory(ContractRetrieveSubscriptionQuantityHistoryParamsbody, RequestOptionsoptions?): ContractRetrieveSubscriptionQuantityHistoryResponse` **post** `/v1/contracts/getSubscriptionQuantityHistory` Fetch the quantity and price for a subscription over time. End-point does not return future scheduled changes. ### Parameters - **body:** `ContractRetrieveSubscriptionQuantityHistoryParams` - **contract\_id:** `string` - **customer\_id:** `string` - **subscription\_id:** `string` ### Returns - `ContractRetrieveSubscriptionQuantityHistoryResponse` - **data:** `Data` - **fiat\_credit\_type\_id:** `string` - **history:** `Array` - **data:** `Array` - **quantity:** `number` - **total:** `number` - **unit\_price:** `number` - **starting\_at:** `string` - **subscription\_id:** `string` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const response = await client.v1.contracts.retrieveSubscriptionQuantityHistory({ contract_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc', customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d', subscription_id: '1a824d53-bde6-4d82-96d7-6347ff227d5c', }); console.log(response.data); ``` ## Schedule Pro Services Invoice `client.v1.contracts.scheduleProServicesInvoice(ContractScheduleProServicesInvoiceParamsbody, RequestOptionsoptions?): ContractScheduleProServicesInvoiceResponse` **post** `/v1/contracts/scheduleProServicesInvoice` Create a new scheduled invoice for Professional Services terms on a contract. This endpoint's availability is dependent on your client's configuration. ### Parameters - **body:** `ContractScheduleProServicesInvoiceParams` - **contract\_id:** `string` - **customer\_id:** `string` - **issued\_at:** `string` The date the invoice is issued - **line\_items:** `Array` Each line requires an amount or both unit_price and quantity. - **professional\_service\_id:** `string` - **amendment\_id:** `string` If the professional_service_id was added on an amendment, this is required. - **amount:** `number` Amount for the term on the new invoice. - **metadata:** `string` For client use. - **netsuite\_invoice\_billing\_end:** `string` The end date for the billing period on the invoice. - **netsuite\_invoice\_billing\_start:** `string` The start date for the billing period on the invoice. - **quantity:** `number` Quantity for the charge. Will be multiplied by unit_price to determine the amount. - **unit\_price:** `number` If specified, this overrides the unit price on the pro service term. Must also provide quantity (but not amount) if providing unit_price. - **netsuite\_invoice\_header\_end:** `string` The end date of the invoice header in Netsuite - **netsuite\_invoice\_header\_start:** `string` The start date of the invoice header in Netsuite ### Returns - `ContractScheduleProServicesInvoiceResponse` - **data:** `Array` - **id:** `string` - **credit\_type:** `CreditTypeData` - **customer\_id:** `string` - **line\_items:** `Array` - **credit\_type:** `CreditTypeData` - **name:** `string` - **total:** `number` - **applied\_commit\_or\_credit:** `AppliedCommitOrCredit` Details about the credit or commit that was applied to this line item. Only present on line items with product of `USAGE`, `SUBSCRIPTION` or `COMPOSITE` types. - **id:** `string` - **type:** `"PREPAID" | "POSTPAID" | "CREDIT"` - `"PREPAID"` - `"POSTPAID"` - `"CREDIT"` - **commit\_custom\_fields:** `Record` - **commit\_id:** `string` For line items with product of `USAGE`, `SUBSCRIPTION`, or `COMPOSITE` types, the ID of the credit or commit that was applied to this line item. For line items with product type of `FIXED`, the ID of the prepaid or postpaid commit that is being paid for. - **commit\_netsuite\_item\_id:** `string` - **commit\_netsuite\_sales\_order\_id:** `string` - **commit\_segment\_id:** `string` - **commit\_type:** `string` `PrepaidCommit` (for commit types `PREPAID` and `CREDIT`) or `PostpaidCommit` (for commit type `POSTPAID`). - **custom\_fields:** `Record` - **discount\_custom\_fields:** `Record` - **discount\_id:** `string` ID of the discount applied to this line item. - **ending\_before:** `string` The line item's end date (exclusive). - **group\_key:** `string` - **group\_value:** `string | null` - **is\_prorated:** `boolean` Indicates whether the line item is prorated for `SUBSCRIPTION` type product. - **list\_price:** `Rate` 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. - **metadata:** `string` - **netsuite\_invoice\_billing\_end:** `string` The end date for the billing period on the invoice. - **netsuite\_invoice\_billing\_start:** `string` The start date for the billing period on the invoice. - **netsuite\_item\_id:** `string` - **postpaid\_commit:** `PostpaidCommit` Only present for line items paying for a postpaid commit true-up. - **id:** `string` - **presentation\_group\_values:** `Record` Includes the presentation group values associated with this line item if presentation group keys are used. - **pricing\_group\_values:** `Record` Includes the pricing group values associated with this line item if dimensional pricing is used. - **product\_custom\_fields:** `Record` - **product\_id:** `string` ID of the product associated with the line item. - **product\_tags:** `Array` The current product tags associated with the line item's `product_id`. - **product\_type:** `string` 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`. - **professional\_service\_custom\_fields:** `Record` - **professional\_service\_id:** `string` - **quantity:** `number` The quantity associated with the line item. - **reseller\_type:** `"AWS" | "AWS_PRO_SERVICE" | "GCP" | "GCP_PRO_SERVICE"` - `"AWS"` - `"AWS_PRO_SERVICE"` - `"GCP"` - `"GCP_PRO_SERVICE"` - **scheduled\_charge\_custom\_fields:** `Record` - **scheduled\_charge\_id:** `string` ID of scheduled charge. - **starting\_at:** `string` The line item's start date (inclusive). - **sub\_line\_items:** `Array` - **custom\_fields:** `Record` - **name:** `string` - **quantity:** `number` - **subtotal:** `number` - **charge\_id:** `string` - **credit\_grant\_id:** `string` - **end\_date:** `string` The end date for the charge (for seats charges only). - **price:** `number` the unit price for this charge, present only if the charge is not tiered and the quantity is nonzero - **start\_date:** `string` The start date for the charge (for seats charges only). - **tier\_period:** `TierPeriod` when the current tier started and ends (for tiered charges only) - **starting\_at:** `string` - **ending\_before:** `string` - **tiers:** `Array` - **price:** `number` - **quantity:** `number` - **starting\_at:** `number` at what metric amount this tier begins - **subtotal:** `number` - **subscription\_custom\_fields:** `Record` - **tier:** `Tier` Populated if the line item has a tiered price. - **level:** `number` - **starting\_at:** `string` - **size:** `string | null` - **unit\_price:** `number` The unit price associated with the line item. - **status:** `string` - **total:** `number` - **type:** `string` - **amendment\_id:** `string` - **billable\_status:** `"billable" | "unbillable"` This field's availability is dependent on your client's configuration. - `"billable"` - `"unbillable"` - **contract\_custom\_fields:** `Record` - **contract\_id:** `string` - **correction\_record:** `CorrectionRecord` - **corrected\_invoice\_id:** `string` - **memo:** `string` - **reason:** `string` - **corrected\_external\_invoice:** `CorrectedExternalInvoice` - **billing\_provider\_type:** `"aws_marketplace" | "stripe" | "netsuite" | 5 more` - `"aws_marketplace"` - `"stripe"` - `"netsuite"` - `"custom"` - `"azure_marketplace"` - `"quickbooks_online"` - `"workday"` - `"gcp_marketplace"` - **external\_status:** `"DRAFT" | "FINALIZED" | "PAID" | 8 more` - `"DRAFT"` - `"FINALIZED"` - `"PAID"` - `"UNCOLLECTIBLE"` - `"VOID"` - `"DELETED"` - `"PAYMENT_FAILED"` - `"INVALID_REQUEST_ERROR"` - `"SKIPPED"` - `"SENT"` - `"QUEUED"` - **invoice\_id:** `string` - **issued\_at\_timestamp:** `string` - **created\_at:** `string` When the invoice was created (UTC). This field is present for correction invoices only. - **custom\_fields:** `Record` - **customer\_custom\_fields:** `Record` - **end\_timestamp:** `string` End of the usage period this invoice covers (UTC) - **external\_invoice:** `ExternalInvoice | null` - **billing\_provider\_type:** `"aws_marketplace" | "stripe" | "netsuite" | 5 more` - `"aws_marketplace"` - `"stripe"` - `"netsuite"` - `"custom"` - `"azure_marketplace"` - `"quickbooks_online"` - `"workday"` - `"gcp_marketplace"` - **external\_status:** `"DRAFT" | "FINALIZED" | "PAID" | 8 more` - `"DRAFT"` - `"FINALIZED"` - `"PAID"` - `"UNCOLLECTIBLE"` - `"VOID"` - `"DELETED"` - `"PAYMENT_FAILED"` - `"INVALID_REQUEST_ERROR"` - `"SKIPPED"` - `"SENT"` - `"QUEUED"` - **invoice\_id:** `string` - **issued\_at\_timestamp:** `string` - **invoice\_adjustments:** `Array` - **credit\_type:** `CreditTypeData` - **name:** `string` - **total:** `number` - **credit\_grant\_custom\_fields:** `Record` - **credit\_grant\_id:** `string` - **issued\_at:** `string` When the invoice was issued (UTC) - **net\_payment\_terms\_days:** `number` - **netsuite\_sales\_order\_id:** `string` This field's availability is dependent on your client's configuration. - **plan\_custom\_fields:** `Record` - **plan\_id:** `string` - **plan\_name:** `string` - **reseller\_royalty:** `ResellerRoyalty` Only present for contract invoices with reseller royalties. - **fraction:** `string` - **netsuite\_reseller\_id:** `string` - **reseller\_type:** `"AWS" | "AWS_PRO_SERVICE" | "GCP" | "GCP_PRO_SERVICE"` - `"AWS"` - `"AWS_PRO_SERVICE"` - `"GCP"` - `"GCP_PRO_SERVICE"` - **aws\_options:** `AwsOptions` - **aws\_account\_number:** `string` - **aws\_offer\_id:** `string` - **aws\_payer\_reference\_id:** `string` - **gcp\_options:** `GcpOptions` - **gcp\_account\_id:** `string` - **gcp\_offer\_id:** `string` - **salesforce\_opportunity\_id:** `string` This field's availability is dependent on your client's configuration. - **start\_timestamp:** `string` Beginning of the usage period this invoice covers (UTC) - **subtotal:** `number` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const response = await client.v1.contracts.scheduleProServicesInvoice({ contract_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', customer_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', issued_at: '2019-12-27T18:11:19.117Z', line_items: [{ professional_service_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' }], }); console.log(response.data); ``` ## Set Usage Filter `client.v1.contracts.setUsageFilter(ContractSetUsageFilterParamsbody, RequestOptionsoptions?): void` **post** `/v1/contracts/setUsageFilter` Set usage filter for a contract ### Parameters - **body:** `ContractSetUsageFilterParams` - **contract\_id:** `string` - **customer\_id:** `string` - **group\_key:** `string` - **group\_values:** `Array` - **starting\_at:** `string` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); await client.v1.contracts.setUsageFilter({ contract_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc', customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d', group_key: 'business_subscription_id', group_values: ['ID-1', 'ID-2'], starting_at: '2020-01-01T00:00:00.000Z', }); ``` ## Update End Date `client.v1.contracts.updateEndDate(ContractUpdateEndDateParamsbody, RequestOptionsoptions?): ContractUpdateEndDateResponse` **post** `/v1/contracts/updateEndDate` Update the end date of a contract ### Parameters - **body:** `ContractUpdateEndDateParams` - **contract\_id:** `string` ID of the contract to update - **customer\_id:** `string` ID of the customer whose contract is to be updated - **allow\_ending\_before\_finalized\_invoice:** `boolean` 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. - **ending\_before:** `string` RFC 3339 timestamp indicating when the contract will end (exclusive). If not provided, the contract will be updated to be open-ended. ### Returns - `ContractUpdateEndDateResponse` - **data:** `ID` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const response = await client.v1.contracts.updateEndDate({ contract_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc', customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d', ending_before: '2020-01-01T00:00:00.000Z', }); console.log(response.data); ```