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

Create Historical Invoices

API Reference
V1
Contracts
Create historical invoices
v1.contracts.create_historical_invoices(ContractCreateHistoricalInvoicesParams**kwargs) -> datalistContractCreateHistoricalInvoicesResponse
post/v1/contracts/createHistoricalInvoices

Creates historical usage invoices for a contract

Parameters
invoicesiterable
contract_idstrcredit_type_idstrcustomer_idstrexclusive_end_dateunioninclusive_start_dateunionissue_dateunionusage_line_itemsiterablebillable_statusliteralbreakdown_granularityliteralcustom_fieldsDict[str, str]Iterable[Invoice]
Hide ParametersShow Parameters
contract_idstr
formatuuid
credit_type_idstr
formatuuid
customer_idstr
formatuuid
exclusive_end_dateunion
Union[str, datetime]
formatdate-time
inclusive_start_dateunion
Union[str, datetime]
formatdate-time
issue_dateunion
Union[str, datetime]
formatdate-time
usage_line_itemsiterable
exclusive_end_dateunioninclusive_start_dateunionproduct_idstrpresentation_group_valuesDict[str, str]pricing_group_valuesDict[str, str]quantityfloatsubtotals_with_quantityiterableIterable[InvoiceUsageLineItem]
Hide ParametersShow Parameters
exclusive_end_dateunion
Union[str, datetime]
formatdate-time
inclusive_start_dateunion
Union[str, datetime]
formatdate-time
product_idstr
formatuuid
presentation_group_valuesDict[str, str]
optional
Dict[str, str]
pricing_group_valuesDict[str, str]
optional
Dict[str, str]
quantityfloat
optional
subtotals_with_quantityiterable
optional
exclusive_end_dateunioninclusive_start_dateunionquantityfloatIterable[InvoiceUsageLineItemSubtotalsWithQuantity]
Hide ParametersShow Parameters
exclusive_end_dateunion
Union[str, datetime]
formatdate-time
inclusive_start_dateunion
Union[str, datetime]
formatdate-time
quantityfloat
billable_statusliteral
optional
Literal["billable", "unbillable"]

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

Hide ParametersShow Parameters
"billable"
"unbillable"
breakdown_granularityliteral
optional
Literal["HOUR", "DAY"]
Hide ParametersShow Parameters
"HOUR"
"DAY"
custom_fieldsDict[str, str]
optional
Dict[str, str]
previewbool
Returns
ContractCreateHistoricalInvoicesResponseclass
Hide ParametersShow Parameters
datalist
List[idstrcredit_typeCreditTypeDatacustomer_idstrline_itemsliststatusstrtotalfloattypestramendment_idstrbillable_statusliteralcontract_custom_fieldsDict[str, str]contract_idstrcorrection_recordCorrectionRecordcreated_atdatetimecustom_fieldsDict[str, object]customer_custom_fieldsDict[str, str]end_timestampdatetimeexternal_invoiceExternalInvoiceinvoice_adjustmentslistissued_atdatetimenet_payment_terms_daysfloatnetsuite_sales_order_idstrplan_custom_fieldsDict[str, str]plan_idstrplan_namestrreseller_royaltyResellerRoyaltysalesforce_opportunity_idstrstart_timestampdatetimesubtotalfloatInvoice]
Hide ParametersShow Parameters
idstr
formatuuid
credit_typeidstrnamestrCreditTypeData
customer_idstr
formatuuid
line_itemslist
List[LineItem]
Hide ParametersShow Parameters
credit_typeidstrnamestrCreditTypeData
namestr
totalfloat
applied_commit_or_creditidstrtypeliteralLineItemAppliedCommitOrCredit
optional

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.

Hide ParametersShow Parameters
idstr
formatuuid
typeliteral
Literal["PREPAID", "POSTPAID", "CREDIT"]
Hide ParametersShow Parameters
"PREPAID"
"POSTPAID"
"CREDIT"
commit_custom_fieldsDict[str, str]
optional
Optional[Dict[str, str]]
commit_idstr
optional

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.

formatuuid
commit_netsuite_item_idstr
optional
commit_netsuite_sales_order_idstr
optional
commit_segment_idstr
optional
formatuuid
commit_typestr
optional

PrepaidCommit (for commit types PREPAID and CREDIT) or PostpaidCommit (for commit type POSTPAID).

custom_fieldsDict[str, str]
optional
Optional[Dict[str, str]]
discount_custom_fieldsDict[str, str]
optional
Optional[Dict[str, str]]
discount_idstr
optional

ID of the discount applied to this line item.

formatuuid
ending_beforedatetime
optional

The line item's end date (exclusive).

formatdate-time
group_keystr
optional
group_valuestr
optional
is_proratedbool
optional

Indicates whether the line item is prorated for SUBSCRIPTION type product.

list_priceRate
optional

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.

metadatastr
optional
netsuite_invoice_billing_enddatetime
optional

The end date for the billing period on the invoice.

formatdate-time
netsuite_invoice_billing_startdatetime
optional

The start date for the billing period on the invoice.

formatdate-time
netsuite_item_idstr
optional
postpaid_commitidstrLineItemPostpaidCommit
optional

Only present for line items paying for a postpaid commit true-up.

Hide ParametersShow Parameters
idstr
formatuuid
presentation_group_valuesDict[str, Optional[str]]
optional
Optional[Dict[str, Optional[str]]]

Includes the presentation group values associated with this line item if presentation group keys are used.

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

Includes the pricing group values associated with this line item if dimensional pricing is used.

product_custom_fieldsDict[str, str]
optional
Optional[Dict[str, str]]
product_idstr
optional

ID of the product associated with the line item.

formatuuid
product_tagslist
optional
Optional[List[str]]

The current product tags associated with the line item's product_id.

product_typestr
optional

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_fieldsDict[str, str]
optional
Optional[Dict[str, str]]
professional_service_idstr
optional
formatuuid
quantityfloat
optional

The quantity associated with the line item.

reseller_typeliteral
optional
Optional[Literal["AWS", "AWS_PRO_SERVICE", "GCP", "GCP_PRO_SERVICE"]]
Hide ParametersShow Parameters
"AWS"
"AWS_PRO_SERVICE"
"GCP"
"GCP_PRO_SERVICE"
scheduled_charge_custom_fieldsDict[str, str]
optional
Optional[Dict[str, str]]
scheduled_charge_idstr
optional

ID of scheduled charge.

formatuuid
starting_atdatetime
optional

The line item's start date (inclusive).

formatdate-time
sub_line_itemslist
optional
Optional[List[LineItemSubLineItem]]
Hide ParametersShow Parameters
custom_fieldsDict[str, str]
Dict[str, str]
namestr
quantityfloat
subtotalfloat
charge_idstr
optional
formatuuid
credit_grant_idstr
optional
formatuuid
end_datedatetime
optional

The end date for the charge (for seats charges only).

formatdate-time
pricefloat
optional

the unit price for this charge, present only if the charge is not tiered and the quantity is nonzero

start_datedatetime
optional

The start date for the charge (for seats charges only).

formatdate-time
tier_periodstarting_atdatetimeending_beforedatetimeLineItemSubLineItemTierPeriod
optional

when the current tier started and ends (for tiered charges only)

Hide ParametersShow Parameters
starting_atdatetime
formatdate-time
ending_beforedatetime
optional
formatdate-time
tierslist
optional
Optional[List[LineItemSubLineItemTier]]
Hide ParametersShow Parameters
pricefloat
quantityfloat
starting_atfloat

at what metric amount this tier begins

subtotalfloat
subscription_custom_fieldsDict[str, str]
optional
Optional[Dict[str, str]]
tierlevelfloatstarting_atstrsizestrLineItemTier
optional

Populated if the line item has a tiered price.

Hide ParametersShow Parameters
levelfloat
starting_atstr
sizestr
optional
unit_pricefloat
optional

The unit price associated with the line item.

statusstr
totalfloat
typestr
amendment_idstr
optional
formatuuid
billable_statusliteral
optional
Optional[Literal["billable", "unbillable"]]

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

Hide ParametersShow Parameters
"billable"
"unbillable"
contract_custom_fieldsDict[str, str]
optional
Optional[Dict[str, str]]
contract_idstr
optional
formatuuid
correction_recordcorrected_invoice_idstrmemostrreasonstrcorrected_external_invoiceCorrectionRecordCorrectedExternalInvoiceCorrectionRecord
optional
Hide ParametersShow Parameters
corrected_invoice_idstr
formatuuid
memostr
reasonstr
corrected_external_invoicebilling_provider_typeliteralexternal_statusliteralinvoice_idstrissued_at_timestampdatetimeCorrectionRecordCorrectedExternalInvoice
optional
Hide ParametersShow Parameters
billing_provider_typeliteral
Literal["aws_marketplace", "stripe", "netsuite", 5 more]
Hide ParametersShow Parameters
"aws_marketplace"
"stripe"
"netsuite"
"custom"
"azure_marketplace"
"quickbooks_online"
"workday"
"gcp_marketplace"
external_statusliteral
optional
Optional[Literal["DRAFT", "FINALIZED", "PAID", 8 more]]
Hide ParametersShow Parameters
"DRAFT"
"FINALIZED"
"PAID"
"UNCOLLECTIBLE"
"VOID"
"DELETED"
"PAYMENT_FAILED"
"INVALID_REQUEST_ERROR"
"SKIPPED"
"SENT"
"QUEUED"
invoice_idstr
optional
issued_at_timestampdatetime
optional
formatdate-time
created_atdatetime
optional

When the invoice was created (UTC). This field is present for correction invoices only.

formatdate-time
custom_fieldsDict[str, object]
optional
Optional[Dict[str, object]]
customer_custom_fieldsDict[str, str]
optional
Optional[Dict[str, str]]
end_timestampdatetime
optional

End of the usage period this invoice covers (UTC)

formatdate-time
external_invoicebilling_provider_typeliteralexternal_statusliteralinvoice_idstrissued_at_timestampdatetimeExternalInvoice
optional
Hide ParametersShow Parameters
billing_provider_typeliteral
Literal["aws_marketplace", "stripe", "netsuite", 5 more]
Hide ParametersShow Parameters
"aws_marketplace"
"stripe"
"netsuite"
"custom"
"azure_marketplace"
"quickbooks_online"
"workday"
"gcp_marketplace"
external_statusliteral
optional
Optional[Literal["DRAFT", "FINALIZED", "PAID", 8 more]]
Hide ParametersShow Parameters
"DRAFT"
"FINALIZED"
"PAID"
"UNCOLLECTIBLE"
"VOID"
"DELETED"
"PAYMENT_FAILED"
"INVALID_REQUEST_ERROR"
"SKIPPED"
"SENT"
"QUEUED"
invoice_idstr
optional
issued_at_timestampdatetime
optional
formatdate-time
invoice_adjustmentslist
optional
Optional[List[InvoiceAdjustment]]
Hide ParametersShow Parameters
credit_typeidstrnamestrCreditTypeData
namestr
totalfloat
credit_grant_custom_fieldsDict[str, str]
optional
Optional[Dict[str, str]]
credit_grant_idstr
optional
issued_atdatetime
optional

When the invoice was issued (UTC)

formatdate-time
net_payment_terms_daysfloat
optional
netsuite_sales_order_idstr
optional

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

plan_custom_fieldsDict[str, str]
optional
Optional[Dict[str, str]]
plan_idstr
optional
formatuuid
plan_namestr
optional
reseller_royaltyfractionstrnetsuite_reseller_idstrreseller_typeliteralaws_optionsResellerRoyaltyAwsOptionsgcp_optionsResellerRoyaltyGcpOptionsResellerRoyalty
optional

Only present for contract invoices with reseller royalties.

Hide ParametersShow Parameters
fractionstr
netsuite_reseller_idstr
reseller_typeliteral
Literal["AWS", "AWS_PRO_SERVICE", "GCP", "GCP_PRO_SERVICE"]
Hide ParametersShow Parameters
"AWS"
"AWS_PRO_SERVICE"
"GCP"
"GCP_PRO_SERVICE"
aws_optionsaws_account_numberstraws_offer_idstraws_payer_reference_idstrResellerRoyaltyAwsOptions
optional
Hide ParametersShow Parameters
aws_account_numberstr
optional
aws_offer_idstr
optional
aws_payer_reference_idstr
optional
gcp_optionsgcp_account_idstrgcp_offer_idstrResellerRoyaltyGcpOptions
optional
Hide ParametersShow Parameters
gcp_account_idstr
optional
gcp_offer_idstr
optional
salesforce_opportunity_idstr
optional

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

start_timestampdatetime
optional

Beginning of the usage period this invoice covers (UTC)

formatdate-time
subtotalfloat
optional
from datetime import datetime
from metronome import Metronome

client = Metronome(
    bearer_token="My Bearer Token",
)
response = client.v1.contracts.create_historical_invoices(
    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": datetime.fromisoformat("2020-01-01T00:00:00.000"),
        "exclusive_end_date": datetime.fromisoformat("2020-02-01T00:00:00.000"),
        "issue_date": datetime.fromisoformat("2020-02-01T00:00:00.000"),
        "usage_line_items": [{
            "product_id": "f14d6729-6a44-4b13-9908-9387f1918790",
            "inclusive_start_date": datetime.fromisoformat("2020-01-01T00:00:00.000"),
            "exclusive_end_date": datetime.fromisoformat("2020-02-01T00:00:00.000"),
            "quantity": 100,
        }],
    }],
    preview=False,
)
print(response.data)
200 Example
{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "credit_type": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "name": "name"
      },
      "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "line_items": [
        {
          "credit_type": {
            "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
            "name": "name"
          },
          "name": "name",
          "total": 0,
          "applied_commit_or_credit": {
            "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
            "type": "PREPAID"
          },
          "commit_custom_fields": {
            "foo": "string"
          },
          "commit_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "commit_netsuite_item_id": "commit_netsuite_item_id",
          "commit_netsuite_sales_order_id": "commit_netsuite_sales_order_id",
          "commit_segment_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "commit_type": "commit_type",
          "custom_fields": {
            "foo": "string"
          },
          "discount_custom_fields": {
            "foo": "string"
          },
          "discount_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "ending_before": "2019-12-27T18:11:19.117Z",
          "group_key": "group_key",
          "group_value": "group_value",
          "is_prorated": true,
          "list_price": {
            "rate_type": "FLAT",
            "credit_type": {
              "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
              "name": "name"
            },
            "custom_rate": {
              "foo": "bar"
            },
            "is_prorated": true,
            "price": 0,
            "pricing_group_values": {
              "foo": "string"
            },
            "quantity": 0,
            "tiers": [
              {
                "price": 0,
                "size": 0
              }
            ],
            "use_list_prices": true
          },
          "metadata": "metadata",
          "netsuite_invoice_billing_end": "2019-12-27T18:11:19.117Z",
          "netsuite_invoice_billing_start": "2019-12-27T18:11:19.117Z",
          "netsuite_item_id": "netsuite_item_id",
          "postpaid_commit": {
            "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
          },
          "presentation_group_values": {
            "foo": "string"
          },
          "pricing_group_values": {
            "foo": "string"
          },
          "product_custom_fields": {
            "foo": "string"
          },
          "product_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "product_tags": [
            "string"
          ],
          "product_type": "product_type",
          "professional_service_custom_fields": {
            "foo": "string"
          },
          "professional_service_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "quantity": 0,
          "reseller_type": "AWS",
          "scheduled_charge_custom_fields": {
            "foo": "string"
          },
          "scheduled_charge_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "starting_at": "2019-12-27T18:11:19.117Z",
          "sub_line_items": [
            {
              "custom_fields": {
                "foo": "string"
              },
              "name": "name",
              "quantity": 0,
              "subtotal": 0,
              "charge_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
              "credit_grant_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
              "end_date": "2019-12-27T18:11:19.117Z",
              "price": 0,
              "start_date": "2019-12-27T18:11:19.117Z",
              "tier_period": {
                "starting_at": "2019-12-27T18:11:19.117Z",
                "ending_before": "2019-12-27T18:11:19.117Z"
              },
              "tiers": [
                {
                  "price": 0,
                  "quantity": 0,
                  "starting_at": 0,
                  "subtotal": 0
                }
              ]
            }
          ],
          "subscription_custom_fields": {
            "foo": "string"
          },
          "tier": {
            "level": 0,
            "starting_at": "starting_at",
            "size": "size"
          },
          "unit_price": 0
        }
      ],
      "status": "DRAFT, VOID, or FINALIZED",
      "total": 0,
      "type": "PLAN_ARREARS, SCHEDULED, USAGE, CORRECTION, CREDIT_PURCHASE, or SEAT_PURCHASE",
      "amendment_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "billable_status": "billable",
      "contract_custom_fields": {
        "foo": "string"
      },
      "contract_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "correction_record": {
        "corrected_invoice_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "memo": "memo",
        "reason": "reason",
        "corrected_external_invoice": {
          "billing_provider_type": "aws_marketplace",
          "external_status": "DRAFT",
          "invoice_id": "invoice_id",
          "issued_at_timestamp": "2019-12-27T18:11:19.117Z"
        }
      },
      "created_at": "2019-12-27T18:11:19.117Z",
      "custom_fields": {
        "foo": "bar"
      },
      "customer_custom_fields": {
        "foo": "string"
      },
      "end_timestamp": "2019-12-27T18:11:19.117Z",
      "external_invoice": {
        "billing_provider_type": "aws_marketplace",
        "external_status": "DRAFT",
        "invoice_id": "invoice_id",
        "issued_at_timestamp": "2019-12-27T18:11:19.117Z"
      },
      "invoice_adjustments": [
        {
          "credit_type": {
            "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
            "name": "name"
          },
          "name": "Monthly minimum ($1,000)",
          "total": 0,
          "credit_grant_custom_fields": {
            "foo": "string"
          },
          "credit_grant_id": "credit_grant_id"
        }
      ],
      "issued_at": "2019-12-27T18:11:19.117Z",
      "net_payment_terms_days": 0,
      "netsuite_sales_order_id": "netsuite_sales_order_id",
      "plan_custom_fields": {
        "foo": "string"
      },
      "plan_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "plan_name": "plan_name",
      "reseller_royalty": {
        "fraction": "fraction",
        "netsuite_reseller_id": "netsuite_reseller_id",
        "reseller_type": "AWS",
        "aws_options": {
          "aws_account_number": "aws_account_number",
          "aws_offer_id": "aws_offer_id",
          "aws_payer_reference_id": "aws_payer_reference_id"
        },
        "gcp_options": {
          "gcp_account_id": "gcp_account_id",
          "gcp_offer_id": "gcp_offer_id"
        }
      },
      "salesforce_opportunity_id": "salesforce_opportunity_id",
      "start_timestamp": "2019-12-27T18:11:19.117Z",
      "subtotal": 0
    }
  ]
}