Skip to content
Metronome Docs
  • Auto
  • Light
  • Dark
Talk to an expert

Edit

API Reference
V2
Contracts
Edit a contract
v2.contracts.edit(ContractEditParams**kwargs) -> dataIDContractEditResponse
post/v2/contracts/edit

Edit a contract. Contract editing must be enabled to use this endpoint.

Parameters
contract_idstr

ID of the contract being edited

formatuuid
customer_idstr

ID of the customer whose contract is being edited

formatuuid
add_commitsiterable
optional
product_idstrtypeliteralaccess_scheduleAddCommitAccessScheduleamountfloatapplicable_product_idslistapplicable_product_tagslistcustom_fieldsDict[str, str]descriptionstrhierarchy_configurationAddCommitHierarchyConfigurationinvoice_scheduleAddCommitInvoiceSchedulenamestrnetsuite_sales_order_idstrpayment_gate_configAddCommitPaymentGateConfigpriorityfloatrate_typeliteralrollover_fractionfloatspecifiersiterabletemporary_idstrIterable[AddCommit]
Hide ParametersShow Parameters
product_idstr
formatuuid
typeliteral
Literal["PREPAID", "POSTPAID"]
Hide ParametersShow Parameters
"PREPAID"
"POSTPAID"
access_scheduleschedule_itemsiterablecredit_type_idstrAddCommitAccessSchedule
optional

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.

Hide ParametersShow Parameters
schedule_itemsiterable
amountfloatending_beforeunionstarting_atunionIterable[AddCommitAccessScheduleScheduleItem]
Hide ParametersShow Parameters
amountfloat
ending_beforeunion
Union[str, datetime]

RFC 3339 timestamp (exclusive)

formatdate-time
starting_atunion
Union[str, datetime]

RFC 3339 timestamp (inclusive)

formatdate-time
credit_type_idstr
optional
formatuuid
amountfloat
optional

(DEPRECATED) Use access_schedule and invoice_schedule instead.

applicable_product_idslist
optional
List[str]

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_tagslist
optional
List[str]

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_fieldsDict[str, str]
optional
Dict[str, str]
descriptionstr
optional

Used only in UI/API. It is not exposed to end customers.

hierarchy_configurationchild_accessAddCommitHierarchyConfigurationChildAccessAddCommitHierarchyConfiguration
optional

Optional configuration for commit hierarchy access control

Hide ParametersShow Parameters
child_accessAddCommitHierarchyConfigurationChildAccess
Hide ParametersShow Parameters
AddCommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessAllclass
Hide ParametersShow Parameters
typeliteral
Literal["ALL"]
Hide ParametersShow Parameters
"ALL"
AddCommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessNoneclass
Hide ParametersShow Parameters
typeliteral
Literal["NONE"]
Hide ParametersShow Parameters
"NONE"
AddCommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessContractIDsclass
Hide ParametersShow Parameters
contract_idslist
List[str]
typeliteral
Literal["CONTRACT_IDS"]
Hide ParametersShow Parameters
"CONTRACT_IDS"
invoice_schedulecredit_type_idstrdo_not_invoiceboolrecurring_scheduleAddCommitInvoiceScheduleRecurringScheduleschedule_itemsiterableAddCommitInvoiceSchedule
optional

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.

Hide ParametersShow Parameters
credit_type_idstr
optional

Defaults to USD (cents) if not passed.

formatuuid
do_not_invoicebool
optional

This field is only applicable to commit invoice schedules. If true, this schedule will not generate an invoice.

recurring_scheduleamount_distributionliteralending_beforeunionfrequencyliteralstarting_atunionamountfloatquantityfloatunit_pricefloatAddCommitInvoiceScheduleRecurringSchedule
optional

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.

Hide ParametersShow Parameters
amount_distributionliteral
Literal["DIVIDED", "DIVIDED_ROUNDED", "EACH"]
Hide ParametersShow Parameters
"DIVIDED"
"DIVIDED_ROUNDED"
"EACH"
ending_beforeunion
Union[str, datetime]

RFC 3339 timestamp (exclusive).

formatdate-time
frequencyliteral
Literal["MONTHLY", "QUARTERLY", "SEMI_ANNUAL", 2 more]
Hide ParametersShow Parameters
"MONTHLY"
"QUARTERLY"
"SEMI_ANNUAL"
"ANNUAL"
"WEEKLY"
starting_atunion
Union[str, datetime]

RFC 3339 timestamp (inclusive).

formatdate-time
amountfloat
optional

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.

quantityfloat
optional

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_pricefloat
optional

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_itemsiterable
optional
timestampunionamountfloatquantityfloatunit_pricefloatIterable[AddCommitInvoiceScheduleScheduleItem]

Either provide amount or provide both unit_price and quantity.

Hide ParametersShow Parameters
timestampunion
Union[str, datetime]

timestamp of the scheduled event

formatdate-time
amountfloat
optional

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.

quantityfloat
optional

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_pricefloat
optional

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.

namestr
optional

displayed on invoices

minLength1
netsuite_sales_order_idstr
optional

This field's availability is dependent on your client's configuration.

payment_gate_configpayment_gate_typeliteralprecalculated_tax_configAddCommitPaymentGateConfigPrecalculatedTaxConfigstripe_configAddCommitPaymentGateConfigStripeConfigtax_typeliteralAddCommitPaymentGateConfig
optional

optionally payment gate this commit

Hide ParametersShow Parameters
payment_gate_typeliteral
Literal["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.

Hide ParametersShow Parameters
"NONE"
"STRIPE"
"EXTERNAL"
precalculated_tax_configtax_amountfloattax_namestrAddCommitPaymentGateConfigPrecalculatedTaxConfig
optional

Only applicable if using PRECALCULATED as your tax type.

Hide ParametersShow Parameters
tax_amountfloat

Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule

tax_namestr
optional

Name of the tax to be applied. This may be used in an invoice line item description.

stripe_configpayment_typeliteralinvoice_metadataDict[str, str]AddCommitPaymentGateConfigStripeConfig
optional

Only applicable if using STRIPE as your payment gateway type.

Hide ParametersShow Parameters
payment_typeliteral
Literal["INVOICE", "PAYMENT_INTENT"]

If left blank, will default to INVOICE

Hide ParametersShow Parameters
"INVOICE"
"PAYMENT_INTENT"
invoice_metadataDict[str, str]
optional
Dict[str, str]

Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type.

tax_typeliteral
optional
Literal["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.

Hide ParametersShow Parameters
"NONE"
"STRIPE"
"ANROK"
"PRECALCULATED"
priorityfloat
optional

If multiple commits are applicable, the one with the lower priority will apply first.

rate_typeliteral
optional
Literal["COMMIT_RATE", "LIST_RATE"]
Hide ParametersShow Parameters
"COMMIT_RATE"
"LIST_RATE"
rollover_fractionfloat
optional

Fraction of unused segments that will be rolled over. Must be between 0 and 1.

specifiersiterable
optional
presentation_group_valuesDict[str, str]pricing_group_valuesDict[str, str]product_idstrproduct_tagslistIterable[AddCommitSpecifier]

List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with applicable_product_ids or applicable_product_tags. Instead, to target usage by product or product tag, pass those values in the body of specifiers.

Hide ParametersShow Parameters
presentation_group_valuesDict[str, str]
optional
Dict[str, str]
pricing_group_valuesDict[str, str]
optional
Dict[str, str]
product_idstr
optional

If provided, the specifier will only apply to the product with the specified ID.

formatuuid
product_tagslist
optional
List[str]

If provided, the specifier will only apply to products with all the specified tags.

temporary_idstr
optional

A temporary ID for the commit that can be used to reference the commit for commit specific overrides.

add_creditsiterable
optional
access_scheduleAddCreditAccessScheduleproduct_idstrapplicable_product_idslistapplicable_product_tagslistcustom_fieldsDict[str, str]descriptionstrhierarchy_configurationAddCreditHierarchyConfigurationnamestrnetsuite_sales_order_idstrpriorityfloatrate_typeliteralspecifiersiterableIterable[AddCredit]
Hide ParametersShow Parameters
access_scheduleschedule_itemsiterablecredit_type_idstrAddCreditAccessSchedule

Schedule for distributing the credit to the customer.

Hide ParametersShow Parameters
schedule_itemsiterable
amountfloatending_beforeunionstarting_atunionIterable[AddCreditAccessScheduleScheduleItem]
Hide ParametersShow Parameters
amountfloat
ending_beforeunion
Union[str, datetime]

RFC 3339 timestamp (exclusive)

formatdate-time
starting_atunion
Union[str, datetime]

RFC 3339 timestamp (inclusive)

formatdate-time
credit_type_idstr
optional
formatuuid
product_idstr
formatuuid
applicable_product_idslist
optional
List[str]

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_tagslist
optional
List[str]

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_fieldsDict[str, str]
optional
Dict[str, str]
descriptionstr
optional

Used only in UI/API. It is not exposed to end customers.

hierarchy_configurationchild_accessAddCreditHierarchyConfigurationChildAccessAddCreditHierarchyConfiguration
optional

Optional configuration for credit hierarchy access control

Hide ParametersShow Parameters
child_accessAddCreditHierarchyConfigurationChildAccess
Hide ParametersShow Parameters
AddCreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessAllclass
Hide ParametersShow Parameters
typeliteral
Literal["ALL"]
Hide ParametersShow Parameters
"ALL"
AddCreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessNoneclass
Hide ParametersShow Parameters
typeliteral
Literal["NONE"]
Hide ParametersShow Parameters
"NONE"
AddCreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessContractIDsclass
Hide ParametersShow Parameters
contract_idslist
List[str]
typeliteral
Literal["CONTRACT_IDS"]
Hide ParametersShow Parameters
"CONTRACT_IDS"
namestr
optional

displayed on invoices

minLength1
netsuite_sales_order_idstr
optional

This field's availability is dependent on your client's configuration.

priorityfloat
optional

If multiple credits are applicable, the one with the lower priority will apply first.

rate_typeliteral
optional
Literal["COMMIT_RATE", "LIST_RATE"]
Hide ParametersShow Parameters
"COMMIT_RATE"
"LIST_RATE"
specifiersiterable
optional
presentation_group_valuesDict[str, str]pricing_group_valuesDict[str, str]product_idstrproduct_tagslistIterable[AddCreditSpecifier]

List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with applicable_product_ids or applicable_product_tags. Instead, to target usage by product or product tag, pass those values in the body of specifiers.

Hide ParametersShow Parameters
presentation_group_valuesDict[str, str]
optional
Dict[str, str]
pricing_group_valuesDict[str, str]
optional
Dict[str, str]
product_idstr
optional

If provided, the specifier will only apply to the product with the specified ID.

formatuuid
product_tagslist
optional
List[str]

If provided, the specifier will only apply to products with all the specified tags.

add_discountsiterable
optional
product_idstrscheduleAddDiscountSchedulecustom_fieldsDict[str, str]namestrnetsuite_sales_order_idstrIterable[AddDiscount]
Hide ParametersShow Parameters
product_idstr
formatuuid
schedulecredit_type_idstrdo_not_invoiceboolrecurring_scheduleAddDiscountScheduleRecurringScheduleschedule_itemsiterableAddDiscountSchedule

Must provide either schedule_items or recurring_schedule.

Hide ParametersShow Parameters
credit_type_idstr
optional

Defaults to USD (cents) if not passed.

formatuuid
do_not_invoicebool
optional

This field is only applicable to commit invoice schedules. If true, this schedule will not generate an invoice.

recurring_scheduleamount_distributionliteralending_beforeunionfrequencyliteralstarting_atunionamountfloatquantityfloatunit_pricefloatAddDiscountScheduleRecurringSchedule
optional

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.

Hide ParametersShow Parameters
amount_distributionliteral
Literal["DIVIDED", "DIVIDED_ROUNDED", "EACH"]
Hide ParametersShow Parameters
"DIVIDED"
"DIVIDED_ROUNDED"
"EACH"
ending_beforeunion
Union[str, datetime]

RFC 3339 timestamp (exclusive).

formatdate-time
frequencyliteral
Literal["MONTHLY", "QUARTERLY", "SEMI_ANNUAL", 2 more]
Hide ParametersShow Parameters
"MONTHLY"
"QUARTERLY"
"SEMI_ANNUAL"
"ANNUAL"
"WEEKLY"
starting_atunion
Union[str, datetime]

RFC 3339 timestamp (inclusive).

formatdate-time
amountfloat
optional

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.

quantityfloat
optional

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_pricefloat
optional

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_itemsiterable
optional
timestampunionamountfloatquantityfloatunit_pricefloatIterable[AddDiscountScheduleScheduleItem]

Either provide amount or provide both unit_price and quantity.

Hide ParametersShow Parameters
timestampunion
Union[str, datetime]

timestamp of the scheduled event

formatdate-time
amountfloat
optional

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.

quantityfloat
optional

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_pricefloat
optional

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_fieldsDict[str, str]
optional
Dict[str, str]
namestr
optional

displayed on invoices

minLength1
netsuite_sales_order_idstr
optional

This field's availability is dependent on your client's configuration.

add_overridesiterable
optional
starting_atunionapplicable_product_tagslistending_beforeunionentitledboolis_commit_specificboolmultiplierfloatoverride_specifiersiterableoverwrite_rateAddOverrideOverwriteRatepriorityfloatproduct_idstrtargetliteraltiersiterabletypeliteralIterable[AddOverride]
Hide ParametersShow Parameters
starting_atunion
Union[str, datetime]

RFC 3339 timestamp indicating when the override will start applying (inclusive)

formatdate-time
applicable_product_tagslist
optional
List[str]

tags identifying products whose rates are being overridden

ending_beforeunion
optional
Union[str, datetime]

RFC 3339 timestamp indicating when the override will stop applying (exclusive)

formatdate-time
entitledbool
optional
is_commit_specificbool
optional

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.

multiplierfloat
optional

Required for MULTIPLIER type. Must be >=0.

override_specifiersiterable
optional
billing_frequencyliteralcommit_idslistpresentation_group_valuesDict[str, str]pricing_group_valuesDict[str, str]product_idstrproduct_tagslistrecurring_commit_idslistrecurring_credit_idslistIterable[AddOverrideOverrideSpecifier]

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.

Hide ParametersShow Parameters
billing_frequencyliteral
optional
Literal["MONTHLY", "QUARTERLY", "ANNUAL", "WEEKLY"]
Hide ParametersShow Parameters
"MONTHLY"
"QUARTERLY"
"ANNUAL"
"WEEKLY"
commit_idslist
optional
List[str]

If provided, the override will only apply to the specified commits. Can only be used for commit specific overrides. If not provided, the override will apply to all commits.

presentation_group_valuesDict[str, str]
optional
Dict[str, str]

A map of group names to values. The override will only apply to line items with the specified presentation group values. Can only be used for multiplier overrides.

pricing_group_valuesDict[str, str]
optional
Dict[str, str]

A map of pricing group names to values. The override will only apply to products with the specified pricing group values.

product_idstr
optional

If provided, the override will only apply to the product with the specified ID.

formatuuid
product_tagslist
optional
List[str]

If provided, the override will only apply to products with all the specified tags.

recurring_commit_idslist
optional
List[str]

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_idslist
optional
List[str]

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 credit ids.

overwrite_raterate_typeliteralcredit_type_idstrcustom_rateDict[str, object]is_proratedboolpricefloatquantityfloattiersiterableAddOverrideOverwriteRate
optional

Required for OVERWRITE type.

Hide ParametersShow Parameters
rate_typeliteral
Literal["FLAT", "PERCENTAGE", "SUBSCRIPTION", 2 more]
Hide ParametersShow Parameters
"FLAT"
"PERCENTAGE"
"SUBSCRIPTION"
"TIERED"
"CUSTOM"
credit_type_idstr
optional
formatuuid
custom_rateDict[str, object]
optional
Dict[str, object]

Only set for CUSTOM rate_type. This field is interpreted by custom rate processors.

is_proratedbool
optional

Default proration configuration. Only valid for SUBSCRIPTION rate_type. Must be set to true.

pricefloat
optional

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.

quantityfloat
optional

Default quantity. For SUBSCRIPTION rate_type, this must be >=0.

tiersiterable
optional
pricefloatsizefloatIterable[pricefloatsizefloatTier]

Only set for TIERED rate_type.

Hide ParametersShow Parameters
pricefloat
sizefloat
optional
priorityfloat
optional

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_idstr
optional

ID of the product whose rate is being overridden

formatuuid
targetliteral
optional
Literal["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".

Hide ParametersShow Parameters
"COMMIT_RATE"
"LIST_RATE"
tiersiterable
optional
multiplierfloatsizefloatIterable[AddOverrideTier]

Required for TIERED type. Must have at least one tier.

Hide ParametersShow Parameters
multiplierfloat
sizefloat
optional
typeliteral
optional
Literal["OVERWRITE", "MULTIPLIER", "TIERED"]

Overwrites are prioritized over multipliers and tiered overrides.

Hide ParametersShow Parameters
"OVERWRITE"
"MULTIPLIER"
"TIERED"
add_prepaid_balance_threshold_configurationcommitAddPrepaidBalanceThresholdConfigurationCommitis_enabledboolpayment_gate_configAddPrepaidBalanceThresholdConfigurationPaymentGateConfigrecharge_to_amountfloatthreshold_amountfloatcustom_credit_type_idstrAddPrepaidBalanceThresholdConfiguration
optional
Hide ParametersShow Parameters
commitproduct_idstrapplicable_product_idslistapplicable_product_tagslistdescriptionstrnamestrspecifiersiterableAddPrepaidBalanceThresholdConfigurationCommit
Hide ParametersShow Parameters
product_idstr

The commit product that will be used to generate the line item for commit payment.

applicable_product_idslist
optional
List[str]

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_tagslist
optional
List[str]

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.

descriptionstr
optional
namestr
optional

Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name.

specifiersiterable
optional
presentation_group_valuesDict[str, str]pricing_group_valuesDict[str, str]product_idstrproduct_tagslistIterable[AddPrepaidBalanceThresholdConfigurationCommitSpecifier]

List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with applicable_product_ids or applicable_product_tags. Instead, to target usage by product or product tag, pass those values in the body of specifiers.

Hide ParametersShow Parameters
presentation_group_valuesDict[str, str]
optional
Dict[str, str]
pricing_group_valuesDict[str, str]
optional
Dict[str, str]
product_idstr
optional

If provided, the specifier will only apply to the product with the specified ID.

formatuuid
product_tagslist
optional
List[str]

If provided, the specifier will only apply to products with all the specified tags.

is_enabledbool

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_configpayment_gate_typeliteralprecalculated_tax_configAddPrepaidBalanceThresholdConfigurationPaymentGateConfigPrecalculatedTaxConfigstripe_configAddPrepaidBalanceThresholdConfigurationPaymentGateConfigStripeConfigtax_typeliteralAddPrepaidBalanceThresholdConfigurationPaymentGateConfig
Hide ParametersShow Parameters
payment_gate_typeliteral
Literal["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.

Hide ParametersShow Parameters
"NONE"
"STRIPE"
"EXTERNAL"
precalculated_tax_configtax_amountfloattax_namestrAddPrepaidBalanceThresholdConfigurationPaymentGateConfigPrecalculatedTaxConfig
optional

Only applicable if using PRECALCULATED as your tax type.

Hide ParametersShow Parameters
tax_amountfloat

Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule

tax_namestr
optional

Name of the tax to be applied. This may be used in an invoice line item description.

stripe_configpayment_typeliteralinvoice_metadataDict[str, str]AddPrepaidBalanceThresholdConfigurationPaymentGateConfigStripeConfig
optional

Only applicable if using STRIPE as your payment gateway type.

Hide ParametersShow Parameters
payment_typeliteral
Literal["INVOICE", "PAYMENT_INTENT"]

If left blank, will default to INVOICE

Hide ParametersShow Parameters
"INVOICE"
"PAYMENT_INTENT"
invoice_metadataDict[str, str]
optional
Dict[str, str]

Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type.

tax_typeliteral
optional
Literal["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.

Hide ParametersShow Parameters
"NONE"
"STRIPE"
"ANROK"
"PRECALCULATED"
recharge_to_amountfloat

Specify the amount the balance should be recharged to.

threshold_amountfloat

Specify the threshold amount for the contract. Each time the contract's balance lowers to this amount, a threshold charge will be initiated.

custom_credit_type_idstr
optional

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.

formatuuid
add_professional_servicesiterable
optional
max_amountfloatproduct_idstrquantityfloatunit_pricefloatcustom_fieldsDict[str, str]descriptionstrnetsuite_sales_order_idstrIterable[AddProfessionalService]

This field's availability is dependent on your client's configuration.

Hide ParametersShow Parameters
max_amountfloat

Maximum amount for the term.

product_idstr
formatuuid
quantityfloat

Quantity for the charge. Will be multiplied by unit_price to determine the amount.

unit_pricefloat

Unit price for the charge. Will be multiplied by quantity to determine the amount and must be specified.

custom_fieldsDict[str, str]
optional
Dict[str, str]
descriptionstr
optional
netsuite_sales_order_idstr
optional

This field's availability is dependent on your client's configuration.

add_recurring_commitsiterable
optional
access_amountAddRecurringCommitAccessAmountcommit_durationAddRecurringCommitCommitDurationpriorityfloatproduct_idstrstarting_atunionapplicable_product_idslistapplicable_product_tagslistdescriptionstrending_beforeunionhierarchy_configurationAddRecurringCommitHierarchyConfigurationinvoice_amountAddRecurringCommitInvoiceAmountnamestrnetsuite_sales_order_idstrprorationliteralrate_typeliteralrecurrence_frequencyliteralrollover_fractionfloatspecifiersiterablesubscription_configAddRecurringCommitSubscriptionConfigtemporary_idstrIterable[AddRecurringCommit]
Hide ParametersShow Parameters
access_amountcredit_type_idstrunit_pricefloatquantityfloatAddRecurringCommitAccessAmount

The amount of commit to grant.

Hide ParametersShow Parameters
credit_type_idstr
formatuuid
unit_pricefloat
quantityfloat
optional

This field is required unless a subscription is attached via subscription_config.

commit_durationvaluefloatunitliteralAddRecurringCommitCommitDuration

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.

Hide ParametersShow Parameters
valuefloat
unitliteral
optional
Literal["PERIODS"]
Hide ParametersShow Parameters
"PERIODS"
priorityfloat

Will be passed down to the individual commits

product_idstr
formatuuid
starting_atunion
Union[str, datetime]

determines the start time for the first commit

formatdate-time
applicable_product_idslist
optional
List[str]

Will be passed down to the individual commits

applicable_product_tagslist
optional
List[str]

Will be passed down to the individual commits

descriptionstr
optional

Will be passed down to the individual commits

ending_beforeunion
optional
Union[str, datetime]

Determines when the contract will stop creating recurring commits. optional

formatdate-time
hierarchy_configurationchild_accessAddRecurringCommitHierarchyConfigurationChildAccessAddRecurringCommitHierarchyConfiguration
optional

Optional configuration for recurring credit hierarchy access control

Hide ParametersShow Parameters
child_accessAddRecurringCommitHierarchyConfigurationChildAccess
Hide ParametersShow Parameters
AddRecurringCommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessAllclass
Hide ParametersShow Parameters
typeliteral
Literal["ALL"]
Hide ParametersShow Parameters
"ALL"
AddRecurringCommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessNoneclass
Hide ParametersShow Parameters
typeliteral
Literal["NONE"]
Hide ParametersShow Parameters
"NONE"
AddRecurringCommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessContractIDsclass
Hide ParametersShow Parameters
contract_idslist
List[str]
typeliteral
Literal["CONTRACT_IDS"]
Hide ParametersShow Parameters
"CONTRACT_IDS"
invoice_amountcredit_type_idstrquantityfloatunit_pricefloatAddRecurringCommitInvoiceAmount
optional

The amount the customer should be billed for the commit. Not required.

Hide ParametersShow Parameters
credit_type_idstr
formatuuid
quantityfloat
unit_pricefloat
namestr
optional

displayed on invoices. will be passed through to the individual commits

minLength1
netsuite_sales_order_idstr
optional

Will be passed down to the individual commits

prorationliteral
optional
Literal["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).

Hide ParametersShow Parameters
"NONE"
"FIRST"
"LAST"
"FIRST_AND_LAST"
rate_typeliteral
optional
Literal["COMMIT_RATE", "LIST_RATE"]

Whether the created commits will use the commit rate or list rate

Hide ParametersShow Parameters
"COMMIT_RATE"
"LIST_RATE"
recurrence_frequencyliteral
optional
Literal["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.

Hide ParametersShow Parameters
"MONTHLY"
"QUARTERLY"
"ANNUAL"
"WEEKLY"
rollover_fractionfloat
optional

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.

specifiersiterable
optional
presentation_group_valuesDict[str, str]pricing_group_valuesDict[str, str]product_idstrproduct_tagslistIterable[AddRecurringCommitSpecifier]

List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with applicable_product_ids or applicable_product_tags. Instead, to target usage by product or product tag, pass those values in the body of specifiers.

Hide ParametersShow Parameters
presentation_group_valuesDict[str, str]
optional
Dict[str, str]
pricing_group_valuesDict[str, str]
optional
Dict[str, str]
product_idstr
optional

If provided, the specifier will only apply to the product with the specified ID.

formatuuid
product_tagslist
optional
List[str]

If provided, the specifier will only apply to products with all the specified tags.

subscription_configapply_seat_increase_configAddRecurringCommitSubscriptionConfigApplySeatIncreaseConfigsubscription_idstrallocationliteralAddRecurringCommitSubscriptionConfig
optional

Attach a subscription to the recurring commit/credit.

Hide ParametersShow Parameters
apply_seat_increase_configis_proratedboolAddRecurringCommitSubscriptionConfigApplySeatIncreaseConfig
Hide ParametersShow Parameters
is_proratedbool

Indicates whether a mid-period seat increase should be prorated.

subscription_idstr

ID of the subscription to configure on the recurring commit/credit.

allocationliteral
optional
Literal["POOLED"]

If set to POOLED, allocation added per seat is pooled across the account.

Hide ParametersShow Parameters
"POOLED"
temporary_idstr
optional

A temporary ID that can be used to reference the recurring commit for commit specific overrides.

add_recurring_creditsiterable
optional
access_amountAddRecurringCreditAccessAmountcommit_durationAddRecurringCreditCommitDurationpriorityfloatproduct_idstrstarting_atunionapplicable_product_idslistapplicable_product_tagslistdescriptionstrending_beforeunionhierarchy_configurationAddRecurringCreditHierarchyConfigurationnamestrnetsuite_sales_order_idstrprorationliteralrate_typeliteralrecurrence_frequencyliteralrollover_fractionfloatspecifiersiterablesubscription_configAddRecurringCreditSubscriptionConfigtemporary_idstrIterable[AddRecurringCredit]
Hide ParametersShow Parameters
access_amountcredit_type_idstrunit_pricefloatquantityfloatAddRecurringCreditAccessAmount

The amount of commit to grant.

Hide ParametersShow Parameters
credit_type_idstr
formatuuid
unit_pricefloat
quantityfloat
optional

This field is required unless a subscription is attached via subscription_config.

commit_durationvaluefloatunitliteralAddRecurringCreditCommitDuration

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.

Hide ParametersShow Parameters
valuefloat
unitliteral
optional
Literal["PERIODS"]
Hide ParametersShow Parameters
"PERIODS"
priorityfloat

Will be passed down to the individual commits

product_idstr
formatuuid
starting_atunion
Union[str, datetime]

determines the start time for the first commit

formatdate-time
applicable_product_idslist
optional
List[str]

Will be passed down to the individual commits

applicable_product_tagslist
optional
List[str]

Will be passed down to the individual commits

descriptionstr
optional

Will be passed down to the individual commits

ending_beforeunion
optional
Union[str, datetime]

Determines when the contract will stop creating recurring commits. optional

formatdate-time
hierarchy_configurationchild_accessAddRecurringCreditHierarchyConfigurationChildAccessAddRecurringCreditHierarchyConfiguration
optional

Optional configuration for recurring credit hierarchy access control

Hide ParametersShow Parameters
child_accessAddRecurringCreditHierarchyConfigurationChildAccess
Hide ParametersShow Parameters
AddRecurringCreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessAllclass
Hide ParametersShow Parameters
typeliteral
Literal["ALL"]
Hide ParametersShow Parameters
"ALL"
AddRecurringCreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessNoneclass
Hide ParametersShow Parameters
typeliteral
Literal["NONE"]
Hide ParametersShow Parameters
"NONE"
AddRecurringCreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessContractIDsclass
Hide ParametersShow Parameters
contract_idslist
List[str]
typeliteral
Literal["CONTRACT_IDS"]
Hide ParametersShow Parameters
"CONTRACT_IDS"
namestr
optional

displayed on invoices. will be passed through to the individual commits

minLength1
netsuite_sales_order_idstr
optional

Will be passed down to the individual commits

prorationliteral
optional
Literal["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).

Hide ParametersShow Parameters
"NONE"
"FIRST"
"LAST"
"FIRST_AND_LAST"
rate_typeliteral
optional
Literal["COMMIT_RATE", "LIST_RATE"]

Whether the created commits will use the commit rate or list rate

Hide ParametersShow Parameters
"COMMIT_RATE"
"LIST_RATE"
recurrence_frequencyliteral
optional
Literal["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.

Hide ParametersShow Parameters
"MONTHLY"
"QUARTERLY"
"ANNUAL"
"WEEKLY"
rollover_fractionfloat
optional

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.

specifiersiterable
optional
presentation_group_valuesDict[str, str]pricing_group_valuesDict[str, str]product_idstrproduct_tagslistIterable[AddRecurringCreditSpecifier]

List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with applicable_product_ids or applicable_product_tags. Instead, to target usage by product or product tag, pass those values in the body of specifiers.

Hide ParametersShow Parameters
presentation_group_valuesDict[str, str]
optional
Dict[str, str]
pricing_group_valuesDict[str, str]
optional
Dict[str, str]
product_idstr
optional

If provided, the specifier will only apply to the product with the specified ID.

formatuuid
product_tagslist
optional
List[str]

If provided, the specifier will only apply to products with all the specified tags.

subscription_configapply_seat_increase_configAddRecurringCreditSubscriptionConfigApplySeatIncreaseConfigsubscription_idstrallocationliteralAddRecurringCreditSubscriptionConfig
optional

Attach a subscription to the recurring commit/credit.

Hide ParametersShow Parameters
apply_seat_increase_configis_proratedboolAddRecurringCreditSubscriptionConfigApplySeatIncreaseConfig
Hide ParametersShow Parameters
is_proratedbool

Indicates whether a mid-period seat increase should be prorated.

subscription_idstr

ID of the subscription to configure on the recurring commit/credit.

allocationliteral
optional
Literal["POOLED"]

If set to POOLED, allocation added per seat is pooled across the account.

Hide ParametersShow Parameters
"POOLED"
temporary_idstr
optional

A temporary ID that can be used to reference the recurring commit for commit specific overrides.

add_reseller_royaltiesiterable
optional
reseller_typeliteralapplicable_product_idslistapplicable_product_tagslistaws_optionsAddResellerRoyaltyAwsOptionsending_beforeunionfractionfloatgcp_optionsAddResellerRoyaltyGcpOptionsnetsuite_reseller_idstrreseller_contract_valuefloatstarting_atunionIterable[AddResellerRoyalty]
Hide ParametersShow Parameters
reseller_typeliteral
Literal["AWS", "AWS_PRO_SERVICE", "GCP", "GCP_PRO_SERVICE"]
Hide ParametersShow Parameters
"AWS"
"AWS_PRO_SERVICE"
"GCP"
"GCP_PRO_SERVICE"
applicable_product_idslist
optional
List[str]

Must provide at least one of applicable_product_ids or applicable_product_tags.

applicable_product_tagslist
optional
List[str]

Must provide at least one of applicable_product_ids or applicable_product_tags.

aws_optionsaws_account_numberstraws_offer_idstraws_payer_reference_idstrAddResellerRoyaltyAwsOptions
optional
Hide ParametersShow Parameters
aws_account_numberstr
optional
aws_offer_idstr
optional
aws_payer_reference_idstr
optional
ending_beforeunion
optional
Union[str, datetime, null]

Use null to indicate that the existing end timestamp should be removed.

formatdate-time
fractionfloat
optional
gcp_optionsgcp_account_idstrgcp_offer_idstrAddResellerRoyaltyGcpOptions
optional
Hide ParametersShow Parameters
gcp_account_idstr
optional
gcp_offer_idstr
optional
netsuite_reseller_idstr
optional
reseller_contract_valuefloat
optional
starting_atunion
optional
Union[str, datetime]
formatdate-time
add_scheduled_chargesiterable
optional
product_idstrscheduleAddScheduledChargeSchedulenamestrnetsuite_sales_order_idstrIterable[AddScheduledCharge]
Hide ParametersShow Parameters
product_idstr
formatuuid
schedulecredit_type_idstrdo_not_invoiceboolrecurring_scheduleAddScheduledChargeScheduleRecurringScheduleschedule_itemsiterableAddScheduledChargeSchedule

Must provide either schedule_items or recurring_schedule.

Hide ParametersShow Parameters
credit_type_idstr
optional

Defaults to USD (cents) if not passed.

formatuuid
do_not_invoicebool
optional

This field is only applicable to commit invoice schedules. If true, this schedule will not generate an invoice.

recurring_scheduleamount_distributionliteralending_beforeunionfrequencyliteralstarting_atunionamountfloatquantityfloatunit_pricefloatAddScheduledChargeScheduleRecurringSchedule
optional

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.

Hide ParametersShow Parameters
amount_distributionliteral
Literal["DIVIDED", "DIVIDED_ROUNDED", "EACH"]
Hide ParametersShow Parameters
"DIVIDED"
"DIVIDED_ROUNDED"
"EACH"
ending_beforeunion
Union[str, datetime]

RFC 3339 timestamp (exclusive).

formatdate-time
frequencyliteral
Literal["MONTHLY", "QUARTERLY", "SEMI_ANNUAL", 2 more]
Hide ParametersShow Parameters
"MONTHLY"
"QUARTERLY"
"SEMI_ANNUAL"
"ANNUAL"
"WEEKLY"
starting_atunion
Union[str, datetime]

RFC 3339 timestamp (inclusive).

formatdate-time
amountfloat
optional

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.

quantityfloat
optional

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_pricefloat
optional

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_itemsiterable
optional
timestampunionamountfloatquantityfloatunit_pricefloatIterable[AddScheduledChargeScheduleScheduleItem]

Either provide amount or provide both unit_price and quantity.

Hide ParametersShow Parameters
timestampunion
Union[str, datetime]

timestamp of the scheduled event

formatdate-time
amountfloat
optional

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.

quantityfloat
optional

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_pricefloat
optional

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.

namestr
optional

displayed on invoices

minLength1
netsuite_sales_order_idstr
optional

This field's availability is dependent on your client's configuration.

add_spend_threshold_configurationcommitAddSpendThresholdConfigurationCommitis_enabledboolpayment_gate_configAddSpendThresholdConfigurationPaymentGateConfigthreshold_amountfloatAddSpendThresholdConfiguration
optional
Hide ParametersShow Parameters
commitproduct_idstrdescriptionstrnamestrAddSpendThresholdConfigurationCommit
Hide ParametersShow Parameters
product_idstr

The commit product that will be used to generate the line item for commit payment.

descriptionstr
optional
namestr
optional

Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name.

is_enabledbool

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_configpayment_gate_typeliteralprecalculated_tax_configAddSpendThresholdConfigurationPaymentGateConfigPrecalculatedTaxConfigstripe_configAddSpendThresholdConfigurationPaymentGateConfigStripeConfigtax_typeliteralAddSpendThresholdConfigurationPaymentGateConfig
Hide ParametersShow Parameters
payment_gate_typeliteral
Literal["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.

Hide ParametersShow Parameters
"NONE"
"STRIPE"
"EXTERNAL"
precalculated_tax_configtax_amountfloattax_namestrAddSpendThresholdConfigurationPaymentGateConfigPrecalculatedTaxConfig
optional

Only applicable if using PRECALCULATED as your tax type.

Hide ParametersShow Parameters
tax_amountfloat

Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule

tax_namestr
optional

Name of the tax to be applied. This may be used in an invoice line item description.

stripe_configpayment_typeliteralinvoice_metadataDict[str, str]AddSpendThresholdConfigurationPaymentGateConfigStripeConfig
optional

Only applicable if using STRIPE as your payment gateway type.

Hide ParametersShow Parameters
payment_typeliteral
Literal["INVOICE", "PAYMENT_INTENT"]

If left blank, will default to INVOICE

Hide ParametersShow Parameters
"INVOICE"
"PAYMENT_INTENT"
invoice_metadataDict[str, str]
optional
Dict[str, str]

Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type.

tax_typeliteral
optional
Literal["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.

Hide ParametersShow Parameters
"NONE"
"STRIPE"
"ANROK"
"PRECALCULATED"
threshold_amountfloat

Specify the threshold amount for the contract. Each time the contract's usage hits this amount, a threshold charge will be initiated.

add_subscriptionsiterable
optional
collection_scheduleliteralinitial_quantityfloatprorationAddSubscriptionProrationsubscription_rateAddSubscriptionSubscriptionRatecustom_fieldsDict[str, str]descriptionstrending_beforeunionnamestrstarting_atuniontemporary_idstrIterable[AddSubscription]

Optional list of subscriptions to add to the contract.

Hide ParametersShow Parameters
collection_scheduleliteral
Literal["ADVANCE", "ARREARS"]
Hide ParametersShow Parameters
"ADVANCE"
"ARREARS"
initial_quantityfloat
prorationinvoice_behaviorliteralis_proratedboolAddSubscriptionProration
Hide ParametersShow Parameters
invoice_behaviorliteral
optional
Literal["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.

Hide ParametersShow Parameters
"BILL_IMMEDIATELY"
"BILL_ON_NEXT_COLLECTION_DATE"
is_proratedbool
optional

Indicates if the partial period will be prorated or charged a full amount.

subscription_ratebilling_frequencyliteralproduct_idstrAddSubscriptionSubscriptionRate
Hide ParametersShow Parameters
billing_frequencyliteral
Literal["MONTHLY", "QUARTERLY", "ANNUAL", "WEEKLY"]

Frequency to bill subscription with. Together with product_id, must match existing rate on the rate card.

Hide ParametersShow Parameters
"MONTHLY"
"QUARTERLY"
"ANNUAL"
"WEEKLY"
product_idstr

Must be subscription type product

formatuuid
custom_fieldsDict[str, str]
optional
Dict[str, str]
descriptionstr
optional
ending_beforeunion
optional
Union[str, datetime]

Exclusive end time for the subscription. If not provided, subscription inherits contract end date.

formatdate-time
namestr
optional
starting_atunion
optional
Union[str, datetime]

Inclusive start time for the subscription. If not provided, defaults to contract start date

formatdate-time
temporary_idstr
optional

A temporary ID used to reference the subscription in recurring commit/credit subscription configs created within the same payload.

allow_contract_ending_before_finalized_invoicebool
optional

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.

archive_commitsiterable
optional
idstrIterable[ArchiveCommit]

IDs of commits to archive

Hide ParametersShow Parameters
idstr
formatuuid
archive_creditsiterable
optional
idstrIterable[ArchiveCredit]

IDs of credits to archive

Hide ParametersShow Parameters
idstr
formatuuid
archive_scheduled_chargesiterable
optional
idstrIterable[ArchiveScheduledCharge]

IDs of scheduled charges to archive

Hide ParametersShow Parameters
idstr
formatuuid
remove_overridesiterable
optional
idstrIterable[RemoveOverride]

IDs of overrides to remove

Hide ParametersShow Parameters
idstr
formatuuid
update_commitsiterable
optional
commit_idstraccess_scheduleUpdateCommitAccessScheduleapplicable_product_idslistapplicable_product_tagslisthierarchy_configurationUpdateCommitHierarchyConfigurationinvoice_scheduleUpdateCommitInvoiceSchedulenetsuite_sales_order_idstrpriorityfloatproduct_idstrrollover_fractionfloatIterable[UpdateCommit]
Hide ParametersShow Parameters
commit_idstr
formatuuid
access_scheduleadd_schedule_itemsiterableremove_schedule_itemsiterableupdate_schedule_itemsiterableUpdateCommitAccessSchedule
optional
Hide ParametersShow Parameters
add_schedule_itemsiterable
optional
amountfloatending_beforeunionstarting_atunionIterable[UpdateCommitAccessScheduleAddScheduleItem]
Hide ParametersShow Parameters
amountfloat
ending_beforeunion
Union[str, datetime]
formatdate-time
starting_atunion
Union[str, datetime]
formatdate-time
remove_schedule_itemsiterable
optional
idstrIterable[UpdateCommitAccessScheduleRemoveScheduleItem]
Hide ParametersShow Parameters
idstr
formatuuid
update_schedule_itemsiterable
optional
idstramountfloatending_beforeunionstarting_atunionIterable[UpdateCommitAccessScheduleUpdateScheduleItem]
Hide ParametersShow Parameters
idstr
formatuuid
amountfloat
optional
ending_beforeunion
optional
Union[str, datetime]
formatdate-time
starting_atunion
optional
Union[str, datetime]
formatdate-time
applicable_product_idslist
optional
Optional[List[str]]

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_tagslist
optional
Optional[List[str]]

Which tags the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products.

hierarchy_configurationchild_accessUpdateCommitHierarchyConfigurationChildAccessUpdateCommitHierarchyConfiguration
optional

Optional configuration for commit hierarchy access control

Hide ParametersShow Parameters
child_accessUpdateCommitHierarchyConfigurationChildAccess
Hide ParametersShow Parameters
UpdateCommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessAllclass
Hide ParametersShow Parameters
typeliteral
Literal["ALL"]
Hide ParametersShow Parameters
"ALL"
UpdateCommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessNoneclass
Hide ParametersShow Parameters
typeliteral
Literal["NONE"]
Hide ParametersShow Parameters
"NONE"
UpdateCommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessContractIDsclass
Hide ParametersShow Parameters
contract_idslist
List[str]
typeliteral
Literal["CONTRACT_IDS"]
Hide ParametersShow Parameters
"CONTRACT_IDS"
invoice_scheduleadd_schedule_itemsiterableremove_schedule_itemsiterableupdate_schedule_itemsiterableUpdateCommitInvoiceSchedule
optional
Hide ParametersShow Parameters
add_schedule_itemsiterable
optional
timestampunionamountfloatquantityfloatunit_pricefloatIterable[UpdateCommitInvoiceScheduleAddScheduleItem]
Hide ParametersShow Parameters
timestampunion
Union[str, datetime]
formatdate-time
amountfloat
optional
quantityfloat
optional
unit_pricefloat
optional
remove_schedule_itemsiterable
optional
idstrIterable[UpdateCommitInvoiceScheduleRemoveScheduleItem]
Hide ParametersShow Parameters
idstr
formatuuid
update_schedule_itemsiterable
optional
idstramountfloatquantityfloattimestampunionunit_pricefloatIterable[UpdateCommitInvoiceScheduleUpdateScheduleItem]
Hide ParametersShow Parameters
idstr
formatuuid
amountfloat
optional
quantityfloat
optional
timestampunion
optional
Union[str, datetime]
formatdate-time
unit_pricefloat
optional
netsuite_sales_order_idstr
optional
priorityfloat
optional
product_idstr
optional
formatuuid
rollover_fractionfloat
optional
update_contract_end_dateunion
optional
Union[str, datetime, null]

RFC 3339 timestamp indicating when the contract will end (exclusive).

formatdate-time
update_contract_namestr
optional

Value to update the contract name to. If not provided, the contract name will remain unchanged.

update_creditsiterable
optional
credit_idstraccess_scheduleUpdateCreditAccessScheduleapplicable_product_idslistapplicable_product_tagslisthierarchy_configurationUpdateCreditHierarchyConfigurationnetsuite_sales_order_idstrpriorityfloatproduct_idstrIterable[UpdateCredit]
Hide ParametersShow Parameters
credit_idstr
formatuuid
access_scheduleadd_schedule_itemsiterableremove_schedule_itemsiterableupdate_schedule_itemsiterableUpdateCreditAccessSchedule
optional
Hide ParametersShow Parameters
add_schedule_itemsiterable
optional
amountfloatending_beforeunionstarting_atunionIterable[UpdateCreditAccessScheduleAddScheduleItem]
Hide ParametersShow Parameters
amountfloat
ending_beforeunion
Union[str, datetime]
formatdate-time
starting_atunion
Union[str, datetime]
formatdate-time
remove_schedule_itemsiterable
optional
idstrIterable[UpdateCreditAccessScheduleRemoveScheduleItem]
Hide ParametersShow Parameters
idstr
formatuuid
update_schedule_itemsiterable
optional
idstramountfloatending_beforeunionstarting_atunionIterable[UpdateCreditAccessScheduleUpdateScheduleItem]
Hide ParametersShow Parameters
idstr
formatuuid
amountfloat
optional
ending_beforeunion
optional
Union[str, datetime]
formatdate-time
starting_atunion
optional
Union[str, datetime]
formatdate-time
applicable_product_idslist
optional
Optional[List[str]]

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_tagslist
optional
Optional[List[str]]

Which tags the commit applies to. If applicable_product_ids, applicable_product_tags or specifiers are not provided, the commit applies to all products.

hierarchy_configurationchild_accessUpdateCreditHierarchyConfigurationChildAccessUpdateCreditHierarchyConfiguration
optional

Optional configuration for commit hierarchy access control

Hide ParametersShow Parameters
child_accessUpdateCreditHierarchyConfigurationChildAccess
Hide ParametersShow Parameters
UpdateCreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessAllclass
Hide ParametersShow Parameters
typeliteral
Literal["ALL"]
Hide ParametersShow Parameters
"ALL"
UpdateCreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessNoneclass
Hide ParametersShow Parameters
typeliteral
Literal["NONE"]
Hide ParametersShow Parameters
"NONE"
UpdateCreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessContractIDsclass
Hide ParametersShow Parameters
contract_idslist
List[str]
typeliteral
Literal["CONTRACT_IDS"]
Hide ParametersShow Parameters
"CONTRACT_IDS"
netsuite_sales_order_idstr
optional
priorityfloat
optional
product_idstr
optional
formatuuid
update_prepaid_balance_threshold_configurationcommitUpdatePrepaidBalanceThresholdConfigurationCommitcustom_credit_type_idstris_enabledboolpayment_gate_configUpdatePrepaidBalanceThresholdConfigurationPaymentGateConfigrecharge_to_amountfloatthreshold_amountfloatUpdatePrepaidBalanceThresholdConfiguration
optional
Hide ParametersShow Parameters
commitapplicable_product_idslistapplicable_product_tagslistdescriptionstrnamestrproduct_idstrspecifiersiterableUpdatePrepaidBalanceThresholdConfigurationCommit
optional
Hide ParametersShow Parameters
applicable_product_idslist
optional
Optional[List[str]]

Which products the threshold commit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the commit applies to all products.

applicable_product_tagslist
optional
Optional[List[str]]

Which tags the threshold commit applies to. If both applicable_product_ids and applicable_product_tags are not provided, the commit applies to all products.

descriptionstr
optional
namestr
optional

Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name.

product_idstr
optional

The commit product that will be used to generate the line item for commit payment.

specifiersiterable
optional
Optional[Iterable[UpdatePrepaidBalanceThresholdConfigurationCommitSpecifier]]

List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown. This field cannot be used together with applicable_product_ids or applicable_product_tags. Instead, to target usage by product or product tag, pass those values in the body of specifiers.

Hide ParametersShow Parameters
presentation_group_valuesDict[str, str]
optional
Dict[str, str]
pricing_group_valuesDict[str, str]
optional
Dict[str, str]
product_idstr
optional

If provided, the specifier will only apply to the product with the specified ID.

formatuuid
product_tagslist
optional
List[str]

If provided, the specifier will only apply to products with all the specified tags.

custom_credit_type_idstr
optional

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.

formatuuid
is_enabledbool
optional

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_configpayment_gate_typeliteralprecalculated_tax_configUpdatePrepaidBalanceThresholdConfigurationPaymentGateConfigPrecalculatedTaxConfigstripe_configUpdatePrepaidBalanceThresholdConfigurationPaymentGateConfigStripeConfigtax_typeliteralUpdatePrepaidBalanceThresholdConfigurationPaymentGateConfig
optional
Hide ParametersShow Parameters
payment_gate_typeliteral
Literal["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.

Hide ParametersShow Parameters
"NONE"
"STRIPE"
"EXTERNAL"
precalculated_tax_configtax_amountfloattax_namestrUpdatePrepaidBalanceThresholdConfigurationPaymentGateConfigPrecalculatedTaxConfig
optional

Only applicable if using PRECALCULATED as your tax type.

Hide ParametersShow Parameters
tax_amountfloat

Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule

tax_namestr
optional

Name of the tax to be applied. This may be used in an invoice line item description.

stripe_configpayment_typeliteralinvoice_metadataDict[str, str]UpdatePrepaidBalanceThresholdConfigurationPaymentGateConfigStripeConfig
optional

Only applicable if using STRIPE as your payment gateway type.

Hide ParametersShow Parameters
payment_typeliteral
Literal["INVOICE", "PAYMENT_INTENT"]

If left blank, will default to INVOICE

Hide ParametersShow Parameters
"INVOICE"
"PAYMENT_INTENT"
invoice_metadataDict[str, str]
optional
Dict[str, str]

Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type.

tax_typeliteral
optional
Literal["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.

Hide ParametersShow Parameters
"NONE"
"STRIPE"
"ANROK"
"PRECALCULATED"
recharge_to_amountfloat
optional

Specify the amount the balance should be recharged to.

threshold_amountfloat
optional

Specify the threshold amount for the contract. Each time the contract's balance lowers to this amount, a threshold charge will be initiated.

update_recurring_commitsiterable
optional
recurring_commit_idstraccess_amountUpdateRecurringCommitAccessAmountending_beforeunioninvoice_amountUpdateRecurringCommitInvoiceAmountIterable[UpdateRecurringCommit]

Edits to these recurring commits will only affect commits whose access schedules has not started. Expired commits, and commits with an active access schedule will remain unchanged.

Hide ParametersShow Parameters
recurring_commit_idstr
formatuuid
access_amountquantityfloatunit_pricefloatUpdateRecurringCommitAccessAmount
optional
Hide ParametersShow Parameters
quantityfloat
optional
unit_pricefloat
optional
ending_beforeunion
optional
Union[str, datetime, null]
formatdate-time
invoice_amountquantityfloatunit_pricefloatUpdateRecurringCommitInvoiceAmount
optional
Hide ParametersShow Parameters
quantityfloat
optional
unit_pricefloat
optional
update_recurring_creditsiterable
optional
recurring_credit_idstraccess_amountUpdateRecurringCreditAccessAmountending_beforeunionIterable[UpdateRecurringCredit]

Edits to these recurring credits will only affect credits whose access schedules has not started. Expired credits, and credits with an active access schedule will remain unchanged.

Hide ParametersShow Parameters
recurring_credit_idstr
formatuuid
access_amountquantityfloatunit_pricefloatUpdateRecurringCreditAccessAmount
optional
Hide ParametersShow Parameters
quantityfloat
optional
unit_pricefloat
optional
ending_beforeunion
optional
Union[str, datetime, null]
formatdate-time
update_scheduled_chargesiterable
optional
scheduled_charge_idstrinvoice_scheduleUpdateScheduledChargeInvoiceSchedulenetsuite_sales_order_idstrIterable[UpdateScheduledCharge]
Hide ParametersShow Parameters
scheduled_charge_idstr
formatuuid
invoice_scheduleadd_schedule_itemsiterableremove_schedule_itemsiterableupdate_schedule_itemsiterableUpdateScheduledChargeInvoiceSchedule
optional
Hide ParametersShow Parameters
add_schedule_itemsiterable
optional
timestampunionamountfloatquantityfloatunit_pricefloatIterable[UpdateScheduledChargeInvoiceScheduleAddScheduleItem]
Hide ParametersShow Parameters
timestampunion
Union[str, datetime]
formatdate-time
amountfloat
optional
quantityfloat
optional
unit_pricefloat
optional
remove_schedule_itemsiterable
optional
idstrIterable[UpdateScheduledChargeInvoiceScheduleRemoveScheduleItem]
Hide ParametersShow Parameters
idstr
formatuuid
update_schedule_itemsiterable
optional
idstramountfloatquantityfloattimestampunionunit_pricefloatIterable[UpdateScheduledChargeInvoiceScheduleUpdateScheduleItem]
Hide ParametersShow Parameters
idstr
formatuuid
amountfloat
optional
quantityfloat
optional
timestampunion
optional
Union[str, datetime]
formatdate-time
unit_pricefloat
optional
netsuite_sales_order_idstr
optional
update_spend_threshold_configurationcommitUpdateSpendThresholdConfigurationCommitis_enabledboolpayment_gate_configUpdateSpendThresholdConfigurationPaymentGateConfigthreshold_amountfloatUpdateSpendThresholdConfiguration
optional
Hide ParametersShow Parameters
commitdescriptionstrnamestrproduct_idstrUpdateSpendThresholdConfigurationCommit
optional
Hide ParametersShow Parameters
descriptionstr
optional
namestr
optional

Specify the name of the line item for the threshold charge. If left blank, it will default to the commit product name.

product_idstr
optional

The commit product that will be used to generate the line item for commit payment.

is_enabledbool
optional

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_configpayment_gate_typeliteralprecalculated_tax_configUpdateSpendThresholdConfigurationPaymentGateConfigPrecalculatedTaxConfigstripe_configUpdateSpendThresholdConfigurationPaymentGateConfigStripeConfigtax_typeliteralUpdateSpendThresholdConfigurationPaymentGateConfig
optional
Hide ParametersShow Parameters
payment_gate_typeliteral
Literal["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.

Hide ParametersShow Parameters
"NONE"
"STRIPE"
"EXTERNAL"
precalculated_tax_configtax_amountfloattax_namestrUpdateSpendThresholdConfigurationPaymentGateConfigPrecalculatedTaxConfig
optional

Only applicable if using PRECALCULATED as your tax type.

Hide ParametersShow Parameters
tax_amountfloat

Amount of tax to be applied. This should be in the same currency and denomination as the commit's invoice schedule

tax_namestr
optional

Name of the tax to be applied. This may be used in an invoice line item description.

stripe_configpayment_typeliteralinvoice_metadataDict[str, str]UpdateSpendThresholdConfigurationPaymentGateConfigStripeConfig
optional

Only applicable if using STRIPE as your payment gateway type.

Hide ParametersShow Parameters
payment_typeliteral
Literal["INVOICE", "PAYMENT_INTENT"]

If left blank, will default to INVOICE

Hide ParametersShow Parameters
"INVOICE"
"PAYMENT_INTENT"
invoice_metadataDict[str, str]
optional
Dict[str, str]

Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as your payment type.

tax_typeliteral
optional
Literal["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.

Hide ParametersShow Parameters
"NONE"
"STRIPE"
"ANROK"
"PRECALCULATED"
threshold_amountfloat
optional

Specify the threshold amount for the contract. Each time the contract's usage hits this amount, a threshold charge will be initiated.

update_subscriptionsiterable
optional
subscription_idstrending_beforeunionquantity_updatesiterableIterable[UpdateSubscription]

Optional list of subscriptions to update.

Hide ParametersShow Parameters
subscription_idstr
formatuuid
ending_beforeunion
optional
Union[str, datetime, null]
formatdate-time
quantity_updatesiterable
optional
starting_atunionquantityfloatquantity_deltafloatIterable[UpdateSubscriptionQuantityUpdate]

Quantity changes are applied on the effective date based on the order which they are sent. For example, if I scheduled the quantity to be 12 on May 21 and then scheduled a quantity delta change of -1, the result from that day would be 11.

Hide ParametersShow Parameters
starting_atunion
Union[str, datetime]
formatdate-time
quantityfloat
optional

The new quantity for the subscription. Must be provided if quantity_delta is not provided. Must be non-negative.

quantity_deltafloat
optional

The delta to add to the subscription's quantity. Must be provided if quantity is not provided. Can't be zero. It also can't result in a negative quantity on the subscription.

Returns
ContractEditResponseclass
Hide ParametersShow Parameters
dataidstrID
from datetime import datetime
from metronome import Metronome

client = Metronome(
    bearer_token="My Bearer Token",
)
response = client.v2.contracts.edit(
    contract_id="d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
    customer_id="13117714-3f05-48e5-a6e9-a66093f13b4d",
    add_overrides=[{
        "type": "MULTIPLIER",
        "starting_at": datetime.fromisoformat("2024-11-02T00:00:00"),
        "product_id": "d4fc086c-d8e5-4091-a235-fbba5da4ec14",
        "multiplier": 2,
        "priority": 100,
    }],
    add_scheduled_charges=[{
        "product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
        "schedule": {
            "schedule_items": [{
                "timestamp": datetime.fromisoformat("2020-02-15T00:00:00.000"),
                "unit_price": 1000000,
                "quantity": 1,
            }]
        },
    }],
)
print(response.data)
200 Example
{
  "data": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
  }
}