Invoices

The Invoices API lets you manage invoice data for your account. You can list invoices imported from your data sources, or perform bulk upserts (insert or update) of invoices.
Invoices are typically tied to customers and plans, and can represent subscription charges, one-time payments, refunds, or cancellations.

List invoices

Retrieve recent invoices stored in your connected data sources. You can optionally filter by data source or limit the number of returned invoices.

Endpoint: GET /data/invoices

Query parameters:

Example request:

GET /data/invoices?source=2f7a9e3e-4f6d-4a3c-8b2a-0f1b4e7d8c9a&limit=5
Authorization: Bearer YOUR_API_KEY

Example response

{
  "result": {
    "count": 2,
    "list": [
      {
        "source_id": "2f7a9e3e-4f6d-4a3c-8b2a-0f1b4e7d8c9a",
        "customer_id": "cus_123",
        "id": "inv_001",
        "type": "subscription",
        "date": "2024-07-01T00:00:00Z",
        "amount_cents": 9900,
        "currency": "USD",
        "plan_id": "plan_123",
        "subscription_id": "sub_001",
        "start_date": "2024-07-01T00:00:00Z",
        "end_date": "2024-08-01T00:00:00Z",
        "quantity": 1,
        "discount": 0
      },
      {
        "source_id": "2f7a9e3e-4f6d-4a3c-8b2a-0f1b4e7d8c9a",
        "customer_id": "cus_456",
        "id": "inv_002",
        "type": "one-time",
        "date": "2024-07-02T00:00:00Z",
        "amount_cents": 15000,
        "currency": "USD",
        "start_date": "2024-07-02T00:00:00Z",
        "end_date": "2024-07-02T00:00:00Z"
      }
    ]
  }
}

Create or bulk upsert invoices

Add new invoices or update existing ones in bulk. Each invoice must include id, customer_id, data_source, type, date, amount_cents, currency, start_date, and end_date.

Endpoint: POST /data/invoices

Request body (single invoice example):

{
  "id": "inv_001",
  "customer_id": "cus_123",
  "data_source": "stripe",
  "type": "subscription",
  "date": "2024-07-01T00:00:00Z",
  "amount_cents": 9900,
  "currency": "USD",
  "plan_id": "plan_123",
  "subscription_id": "sub_001",
  "start_date": "2024-07-01T00:00:00Z",
  "end_date": "2024-08-01T00:00:00Z",
  "quantity": 1,
  "discount": 0
}

Request body (bulk example):

[
  {
    "id": "inv_001",
    "customer_id": "cus_123",
    "data_source": "stripe",
    "type": "subscription",
    "date": "2024-07-01T00:00:00Z",
    "amount_cents": 9900,
    "currency": "USD",
    "plan_id": "plan_123",
    "subscription_id": "sub_001",
    "start_date": "2024-07-01T00:00:00Z",
    "end_date": "2024-08-01T00:00:00Z"
  },
  {
    "id": "inv_002",
    "customer_id": "cus_456",
    "data_source": "stripe",
    "type": "one-time",
    "date": "2024-07-02T00:00:00Z",
    "amount_cents": 15000,
    "currency": "USD",
    "start_date": "2024-07-02T00:00:00Z",
    "end_date": "2024-07-02T00:00:00Z"
  }
]

Example response

{
  "result": [
    { "id": "inv_001", "import_status": "inserted" },
    { "id": "inv_002", "import_status": "inserted" }
  ]
}

Validation errors

Validation errors are returned if required fields are missing, dates are invalid, or referenced customers or plans do not exist.

{
  "result": [
    {
      "id": "inv_003",
      "import_status": "error",
      "import_error": "Missing invoice ID"
    },
    {
      "id": "inv_004",
      "import_status": "error",
      "import_error": "Plan ID plan_999 does not exist"
    }
  ]
}

Notes

• type must be one of: "subscription", "one-time", "refund", or "cancellation".
• amount_cents must be a non-negative number.
• currency must be a 3-letter ISO currency code.
• customer_id must exist in your imported customers list.
• plan_id must exist in your imported plans list.
• When invoices are inserted or updated, related customers are automatically queued for metric recalculation. This process happens asynchronously after the API call returns.

Example unchanged and updated responses

If you send an invoice identical to an existing one:

{
  "result": [
    { "id": "inv_001", "import_status": "unchanged" }
  ]
}

If you update an existing invoice:

{
  "result": [
    { "id": "inv_001", "import_status": "updated" }
  ]
}