Import existing invoices

Metronome offers a unified source of truth for your customers’ billing history, even if you initially provisioned them outside of Metronome. You can easily import existing contracts and invoices into Metronome.

This guide describes how to import an example contract and its corresponding invoices with the Metronome API. You can also use the Metronome SDK to import existing invoices.

Use case

The fictional company used in this guide, called Acme Inc, is a new Metronome client. In this example, today's date is August 15, 2024. Acme Inc has a contract outside of Metronome with a monthly billing schedule that started on June 1, 2024. Invoices for June and July were already issued outside of Metronome.

Create the contract

First, create the contract using the /contracts/create endpoint, entering the original contract details (for example, starting commit/credit balances and start date). Set the usage_statement_schedule.invoice_generation_starting_at field to indicate when Metronome should begin generating invoices. In our example, that date is August 1, 2024, since the customer hasn’t been billed for August yet.

POST /v1/contracts/create HTTP/1.1
Host: api.metronome.com
Authorization: Bearer <TOKEN>
Content-Type: application/json

{
  "customer_id": "<the Metronome customer ID>",
  "rate_card_id": "<the Metronome rate card ID>",
  "starting_at": "2024-06-01T00:00:00.000Z",
  "usage_statement_schedule": {
    "frequency": "monthly",
    "invoice_generation_starting_at": "2024-08-01T00:00:00.000Z"
  }
}

With the contract created, Metronome generates a draft invoice for August. No invoices are created for June and July.

Import the invoices

After creating the contract, import the corresponding invoices with the /contracts/createHistoricalInvoices endpoint. All you'll need is the quantities for each line item on the invoice. Metronome combines these with the unit prices specified on the contract to calculate the total amount on the invoice and the effects on the customer's credit and commit balances.

POST /v1/contracts/createHistoricalInvoices HTTP/1.1
Host: api.metronome.com
Authorization: Bearer <TOKEN>
Content-Type: application/json

{
  "invoices": [
    {
      "customer_id": "<the Metronome customer ID>",
      "contract_id": "<the Metronome contract ID>",
      "credit_type_id": "<the Metronome credit type ID>",
      "inclusive_start_date": "2024-06-01T00:00:00.000Z",
      "exclusive_end_date": "2024-07-01T00:00:00.000Z",
      "issue_date": "2024-07-03T00:00:00.000Z",
      "usage_line_items": [
        {
          "product_id": "<the Metronome product ID>",
          "inclusive_start_date": "2024-06-01T00:00:00.000Z",
          "exclusive_end_date": "2024-07-01T00:00:00.000Z",
          "quantity": 10
        }
      ]
    },
    {
      "customer_id": "<the Metronome customer ID>",
      "contract_id": "<the Metronome contract ID>",
      "credit_type_id": "<the Metronome credit type ID>",
      "inclusive_start_date": "2024-07-01T00:00:00.000Z",
      "exclusive_end_date": "2024-08-01T00:00:00.000Z",
      "issue_date": "2024-08-03T00:00:00.000Z",
      "usage_line_items": [
        {
          "product_id": "<the Metronome product ID>",
          "inclusive_start_date": "2024-07-01T00:00:00.000Z",
          "exclusive_end_date": "2024-08-01T00:00:00.000Z",
          "quantity": 20
        }
      ]
    }
  ],
  "preview": true
}

tip

Use the preview option to perform a dry run of the import to verify any differences between the existing and imported invoices before saving them.

Access imported invoices on the Contracts page in the Metronome app or with the API.

(Optional) Import hourly or daily breakdowns

To use Metronome to retrieve hourly or daily breakdowns of customer usage and costs, specify time-windowed quantities by populating the subtotals_with_quantity field of the line item in lieu of the quantity field. Specify the breakdown_granularity of the invoice. When generating the invoice for the entire billing period, Metronome sums up the subtotals of each window.

POST /v1/contracts/createHistoricalInvoices HTTP/1.1
Host: api.metronome.com
Authorization: Bearer <TOKEN>
Content-Type: application/json

{
  "invoices": [
    {
      "customer_id": "<the Metronome customer ID>",
      "contract_id": "<the Metronome contract ID>",
      "credit_type_id": "<the Metronome credit type ID>",
      "inclusive_start_date": "2024-06-01T00:00:00.000Z",
      "exclusive_end_date": "2024-07-01T00:00:00.000Z",
      "issue_date": "2024-07-03T00:00:00.000Z",
      "breakdown_granularity": "day",
      "usage_line_items": [
        {
          "product_id": "<the Metronome product ID>",
          "inclusive_start_date": "2024-06-01T00:00:00.000Z",
          "exclusive_end_date": "2024-07-01T00:00:00.000Z",
          "subtotals_with_quantity": [
            {
              "inclusive_start_date": "2024-06-01T00:00:00.000Z",
              "exclusive_end_date": "2024-06-02T00:00:00.000Z",
              "quantity": 1
            }
          ]
        }
      ]
    }
  ],
  "preview": true
}

info

Metronome doesn't send imported invoices to the Stripe integration. This prevents sending duplicate invoices to customers.