Import existing invoices

---

Metronome allows you to easily import existing contracts and invoices, providing a unified source of truth for your customers’ billing history.

Example scenario:

• Current date: August 15, 2024
• Acme Inc, a new Metronome client, has a contract outside of Metronome with a monthly billing schedule that started on June 1, 2024.
• Invoices for June and July have already been issued outside of Metronome.

In this tutorial, we'll walk through the steps to import this contract and the corresponding invoices via Metronome’s API.

tip

You can also use the Metronome SDK instead of the API to complete the following steps.

Step 1: Create the Contract

First, create the contract using the /contracts/create API endpoint, ensuring you input the original contract details (e.g., 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 would be August 1, 2024, since the customer hasn’t been billed for August yet.

Request:

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"
  },
  "commits": [
    // Add commits here
  ],
  "credits": [
    // Add credits here
  ]
}

Once this contract is created, a draft invoice will be generated for August, while no invoices will be created for June and July.

Step 2: Import the invoices

After the contract is imported, you can import the corresponding invoices through the /contracts/createHistoricalInvoices API endpoint. All you'll need is the quantities for each line item on the invoice, which Metronome will combine 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.

Request:

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
        },
        // Add other line items here
      ]
    },
    {
      "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
        },
        // Add other line items here
      ]
    }
  ],
  "preview": true
}

info

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

Optional: Import Hourly or Daily Breakdowns

If you are interested in using Metronome to retrieve hourly or daily breakdowns of customer usage and costs, you can also specify time-windowed quantities by populating the subtotals_with_quantity field of the line item in lieu of the quantity field, while also specifying the breakdown_granularity of the invoice. When generating the invoice for the entire billing period, Metronome will sum up the subtotals of each window.

Request:

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
            },
            // Additional subtotals here
          ]
        }
      ]
    }
  ],
  "preview": true
}

info

Metronome does not send imported invoices to our Stripe integration to avoid sending duplicate invoices to customers.

That’s it! The imported invoices should now appear on the contract page in Metronome and can be accessed via the API.