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(**kwargs) -> dataarrayContractCreateHistoricalInvoicesResponse
post/v1/contracts/createHistoricalInvoices

Creates historical usage invoices for a contract

Parameters
invoicesarray
Array[{ contract_id, credit_type_id, customer_id, 7 more}]
Hide ParametersShow Parameters
contract_idString
formatuuid
credit_type_idString
formatuuid
customer_idString
formatuuid
exclusive_end_dateTime
formatdate-time
inclusive_start_dateTime
formatdate-time
issue_dateTime
formatdate-time
usage_line_itemsarray
Array[{ exclusive_end_date, inclusive_start_date, product_id, 4 more}]
Hide ParametersShow Parameters
exclusive_end_dateTime
formatdate-time
inclusive_start_dateTime
formatdate-time
product_idString
formatuuid
presentation_group_valueshash
optional
Hash[Symbol, String]
pricing_group_valueshash
optional
Hash[Symbol, String]
quantityFloat
optional
subtotals_with_quantityarray
optional
Array[{ exclusive_end_date, inclusive_start_date, quantity}]
Hide ParametersShow Parameters
exclusive_end_dateTime
formatdate-time
inclusive_start_dateTime
formatdate-time
quantityFloat
billable_statusunion
optional
:billable | :unbillable

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

Hide ParametersShow Parameters
:billable
:unbillable
breakdown_granularityunion
optional
:HOUR | :DAY
Hide ParametersShow Parameters
:HOUR
:DAY
custom_fieldshash
optional
Hash[Symbol, String]
previewbool
Returns
ContractCreateHistoricalInvoicesResponseclass
Hide ParametersShow Parameters
dataarray
Array[idStringcredit_typeCreditTypeDatacustomer_idStringline_itemsarraystatusStringtotalFloattypeStringamendment_idStringbillable_statusunioncontract_custom_fieldshashcontract_idStringcorrection_recordobjectcreated_atTimecustom_fieldshashcustomer_custom_fieldshashend_timestampTimeexternal_invoiceobjectinvoice_adjustmentsarrayissued_atTimenet_payment_terms_daysFloatnetsuite_sales_order_idStringplan_custom_fieldshashplan_idStringplan_nameStringreseller_royaltyobjectsalesforce_opportunity_idStringstart_timestampTimesubtotalFloatInvoice]
Hide ParametersShow Parameters
idString
formatuuid
credit_typeidStringnameStringCreditTypeData
customer_idString
formatuuid
line_itemsarray
Array[{ credit_type, name, total, 37 more}]
Hide ParametersShow Parameters
credit_typeidStringnameStringCreditTypeData
nameString
totalFloat
applied_commit_or_creditobject
optional
{ id, type}

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
idString
formatuuid
typeunion
:PREPAID | :POSTPAID | :CREDIT
Hide ParametersShow Parameters
:PREPAID
:POSTPAID
:CREDIT
commit_custom_fieldshash
optional
Hash[Symbol, String]
commit_idString
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_idString
optional
commit_netsuite_sales_order_idString
optional
commit_segment_idString
optional
formatuuid
commit_typeString
optional

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

custom_fieldshash
optional
Hash[Symbol, String]
discount_custom_fieldshash
optional
Hash[Symbol, String]
discount_idString
optional

ID of the discount applied to this line item.

formatuuid
ending_beforeTime
optional

The line item's end date (exclusive).

formatdate-time
group_keyString
optional
group_valueString
optional
is_proratedbool
optional

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

list_pricerate_typeunioncredit_typeCreditTypeDatacustom_ratehashis_proratedboolpriceFloatpricing_group_valueshashquantityFloattiersarrayuse_list_pricesboolRate
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.

metadataString
optional
netsuite_invoice_billing_endTime
optional

The end date for the billing period on the invoice.

formatdate-time
netsuite_invoice_billing_startTime
optional

The start date for the billing period on the invoice.

formatdate-time
netsuite_item_idString
optional
postpaid_commitobject
optional
{ id}

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

Hide ParametersShow Parameters
idString
formatuuid
presentation_group_valueshash
optional
Hash[Symbol, String]

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

pricing_group_valueshash
optional
Hash[Symbol, String]

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

product_custom_fieldshash
optional
Hash[Symbol, String]
product_idString
optional

ID of the product associated with the line item.

formatuuid
product_tagsarray
optional
Array[String]

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

product_typeString
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_fieldshash
optional
Hash[Symbol, String]
professional_service_idString
optional
formatuuid
quantityFloat
optional

The quantity associated with the line item.

reseller_typeunion
optional
:AWS | :AWS_PRO_SERVICE | :GCP | :GCP_PRO_SERVICE
Hide ParametersShow Parameters
:AWS
:AWS_PRO_SERVICE
:GCP
:GCP_PRO_SERVICE
scheduled_charge_custom_fieldshash
optional
Hash[Symbol, String]
scheduled_charge_idString
optional

ID of scheduled charge.

formatuuid
starting_atTime
optional

The line item's start date (inclusive).

formatdate-time
sub_line_itemsarray
optional
Array[{ custom_fields, name, quantity, 8 more}]
Hide ParametersShow Parameters
custom_fieldshash
Hash[Symbol, String]
nameString
quantityFloat
subtotalFloat
charge_idString
optional
formatuuid
credit_grant_idString
optional
formatuuid
end_dateTime
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_dateTime
optional

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

formatdate-time
tier_periodobject
optional
{ starting_at, ending_before}

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

Hide ParametersShow Parameters
starting_atTime
formatdate-time
ending_beforeTime
optional
formatdate-time
tiersarray
optional
Array[{ price, quantity, starting_at, subtotal}]
Hide ParametersShow Parameters
priceFloat
quantityFloat
starting_atFloat

at what metric amount this tier begins

subtotalFloat
subscription_custom_fieldshash
optional
Hash[Symbol, String]
tierobject
optional
{ level, starting_at, size}

Populated if the line item has a tiered price.

Hide ParametersShow Parameters
levelFloat
starting_atString
sizeString
optional
unit_priceFloat
optional

The unit price associated with the line item.

statusString
totalFloat
typeString
amendment_idString
optional
formatuuid
billable_statusunion
optional
:billable | :unbillable

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

Hide ParametersShow Parameters
:billable
:unbillable
contract_custom_fieldshash
optional
Hash[Symbol, String]
contract_idString
optional
formatuuid
correction_recordobject
optional
{ corrected_invoice_id, memo, reason, corrected_external_invoice}
Hide ParametersShow Parameters
corrected_invoice_idString
formatuuid
memoString
reasonString
corrected_external_invoiceobject
optional
{ billing_provider_type, external_status, invoice_id, issued_at_timestamp}
Hide ParametersShow Parameters
billing_provider_typeunion
:aws_marketplace | :stripe | :netsuite | 5 more
Hide ParametersShow Parameters
:aws_marketplace
:stripe
:netsuite
:custom
:azure_marketplace
:quickbooks_online
:workday
:gcp_marketplace
external_statusunion
optional
:DRAFT | :FINALIZED | :PAID | 8 more
Hide ParametersShow Parameters
:DRAFT
:FINALIZED
:PAID
:UNCOLLECTIBLE
:VOID
:DELETED
:PAYMENT_FAILED
:INVALID_REQUEST_ERROR
:SKIPPED
:SENT
:QUEUED
invoice_idString
optional
issued_at_timestampTime
optional
formatdate-time
created_atTime
optional

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

formatdate-time
custom_fieldshash
optional
Hash[Symbol, untyped]
customer_custom_fieldshash
optional
Hash[Symbol, String]
end_timestampTime
optional

End of the usage period this invoice covers (UTC)

formatdate-time
external_invoiceobject
optional
{ billing_provider_type, external_status, invoice_id, issued_at_timestamp}
Hide ParametersShow Parameters
billing_provider_typeunion
:aws_marketplace | :stripe | :netsuite | 5 more
Hide ParametersShow Parameters
:aws_marketplace
:stripe
:netsuite
:custom
:azure_marketplace
:quickbooks_online
:workday
:gcp_marketplace
external_statusunion
optional
:DRAFT | :FINALIZED | :PAID | 8 more
Hide ParametersShow Parameters
:DRAFT
:FINALIZED
:PAID
:UNCOLLECTIBLE
:VOID
:DELETED
:PAYMENT_FAILED
:INVALID_REQUEST_ERROR
:SKIPPED
:SENT
:QUEUED
invoice_idString
optional
issued_at_timestampTime
optional
formatdate-time
invoice_adjustmentsarray
optional
Array[{ credit_type, name, total, 2 more}]
Hide ParametersShow Parameters
credit_typeidStringnameStringCreditTypeData
nameString
totalFloat
credit_grant_custom_fieldshash
optional
Hash[Symbol, String]
credit_grant_idString
optional
issued_atTime
optional

When the invoice was issued (UTC)

formatdate-time
net_payment_terms_daysFloat
optional
netsuite_sales_order_idString
optional

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

plan_custom_fieldshash
optional
Hash[Symbol, String]
plan_idString
optional
formatuuid
plan_nameString
optional
reseller_royaltyobject
optional
{ fraction, netsuite_reseller_id, reseller_type, 2 more}

Only present for contract invoices with reseller royalties.

Hide ParametersShow Parameters
fractionString
netsuite_reseller_idString
reseller_typeunion
:AWS | :AWS_PRO_SERVICE | :GCP | :GCP_PRO_SERVICE
Hide ParametersShow Parameters
:AWS
:AWS_PRO_SERVICE
:GCP
:GCP_PRO_SERVICE
aws_optionsobject
optional
{ aws_account_number, aws_offer_id, aws_payer_reference_id}
Hide ParametersShow Parameters
aws_account_numberString
optional
aws_offer_idString
optional
aws_payer_reference_idString
optional
gcp_optionsobject
optional
{ gcp_account_id, gcp_offer_id}
Hide ParametersShow Parameters
gcp_account_idString
optional
gcp_offer_idString
optional
salesforce_opportunity_idString
optional

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

start_timestampTime
optional

Beginning of the usage period this invoice covers (UTC)

formatdate-time
subtotalFloat
optional
require "metronome_sdk"

metronome = MetronomeSDK::Client.new(bearer_token: "My Bearer Token")

response = metronome.v1.contracts.create_historical_invoices(
  invoices: [
    {
      contract_id: "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
      credit_type_id: "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
      customer_id: "13117714-3f05-48e5-a6e9-a66093f13b4d",
      exclusive_end_date: "2020-02-01T00:00:00.000Z",
      inclusive_start_date: "2020-01-01T00:00:00.000Z",
      issue_date: "2020-02-01T00:00:00.000Z",
      usage_line_items: [
        {
          exclusive_end_date: "2020-02-01T00:00:00.000Z",
          inclusive_start_date: "2020-01-01T00:00:00.000Z",
          product_id: "f14d6729-6a44-4b13-9908-9387f1918790"
        }
      ]
    }
  ],
  preview: false
)

puts(response)
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
    }
  ]
}