Skip to main content
GET
/
invoices
List invoices
curl --request GET \
  --url https://api.withorb.com/v1/invoices \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "metadata": {},
      "voided_at": "2023-11-07T05:31:56Z",
      "paid_at": "2023-11-07T05:31:56Z",
      "issued_at": "2023-11-07T05:31:56Z",
      "scheduled_issue_at": "2023-11-07T05:31:56Z",
      "auto_collection": {
        "next_attempt_at": "2023-11-07T05:31:56Z",
        "previously_attempted_at": "2023-11-07T05:31:56Z",
        "enabled": true,
        "num_attempts": 123
      },
      "issue_failed_at": "2023-11-07T05:31:56Z",
      "sync_failed_at": "2023-11-07T05:31:56Z",
      "payment_failed_at": "2023-11-07T05:31:56Z",
      "payment_started_at": "2023-11-07T05:31:56Z",
      "amount_due": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "currency": "<string>",
      "customer": {
        "id": "<string>",
        "external_customer_id": "<string>"
      },
      "due_date": "2022-05-30T07:00:00+00:00",
      "id": "<string>",
      "invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
      "invoice_number": "<string>",
      "subscription": {
        "id": "<string>"
      },
      "total": "<string>",
      "customer_balance_transactions": [
        {
          "id": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "starting_balance": "<string>",
          "ending_balance": "<string>",
          "amount": "<string>",
          "action": "applied_to_invoice",
          "description": "An optional description",
          "invoice": {
            "id": "<string>"
          },
          "type": "increment",
          "credit_note": {
            "id": "<string>"
          }
        }
      ],
      "status": "issued",
      "invoice_source": "subscription",
      "shipping_address": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
      },
      "billing_address": {
        "line1": "<string>",
        "line2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
      },
      "hosted_invoice_url": "<string>",
      "will_auto_issue": true,
      "eligible_to_issue_at": "2023-11-07T05:31:56Z",
      "customer_tax_id": {
        "country": "AD",
        "type": "ad_nrt",
        "value": "<string>"
      },
      "memo": "<string>",
      "credit_notes": [
        {
          "id": "<string>",
          "credit_note_number": "<string>",
          "reason": "<string>",
          "total": "<string>",
          "voided_at": "2022-05-01T07:01:31+00:00",
          "type": "<string>",
          "memo": "<string>"
        }
      ],
      "payment_attempts": [
        {
          "id": "<string>",
          "payment_provider": "stripe",
          "payment_provider_id": "<string>",
          "amount": "<string>",
          "succeeded": true,
          "created_at": "2023-11-07T05:31:56Z",
          "receipt_pdf": "https://assets.withorb.com/receipt/rUHdhmg45vY45DX/qEAeuYePaphGMdFb"
        }
      ],
      "discount": "<unknown>",
      "discounts": [
        {
          "discount_type": "percentage",
          "percentage_discount": 0.5,
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "reason": "<string>"
        }
      ],
      "minimum": {
        "minimum_amount": "<string>",
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ]
      },
      "minimum_amount": "<string>",
      "maximum": {
        "maximum_amount": "<string>",
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ]
      },
      "maximum_amount": "<string>",
      "line_items": [
        {
          "amount": "<string>",
          "end_date": "2023-11-07T05:31:56Z",
          "grouping": "<string>",
          "adjustments": [
            {
              "id": "<string>",
              "is_invoice_level": true,
              "filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "applies_to_price_ids": [
                "<string>"
              ],
              "reason": "<string>",
              "replaces_adjustment_id": "<string>",
              "adjustment_type": "usage_discount",
              "usage_discount": 123,
              "amount": "<string>"
            }
          ],
          "name": "<string>",
          "quantity": 123,
          "start_date": "2023-11-07T05:31:56Z",
          "subtotal": "<string>",
          "adjusted_subtotal": "<string>",
          "credits_applied": "<string>",
          "partially_invoiced_amount": "<string>",
          "sub_line_items": [
            {
              "amount": "<string>",
              "name": "<string>",
              "quantity": 123,
              "grouping": {
                "key": "<string>",
                "value": "west"
              },
              "type": "matrix",
              "matrix_config": {
                "dimension_values": [
                  "<string>"
                ]
              },
              "scaled_quantity": 123
            }
          ],
          "tax_amounts": [
            {
              "tax_rate_description": "<string>",
              "tax_rate_percentage": "<string>",
              "amount": "<string>"
            }
          ],
          "id": "<string>",
          "price": {
            "model_type": "unit",
            "unit_config": {
              "unit_amount": "<string>",
              "prorated": false
            },
            "metadata": {},
            "id": "<string>",
            "name": "<string>",
            "external_price_id": "<string>",
            "replaces_price_id": "<string>",
            "price_type": "usage_price",
            "created_at": "2023-11-07T05:31:56Z",
            "cadence": "one_time",
            "billing_mode": "in_advance",
            "billing_cycle_configuration": {
              "duration": 123,
              "duration_unit": "day"
            },
            "invoicing_cycle_configuration": {
              "duration": 123,
              "duration_unit": "day"
            },
            "billable_metric": {
              "id": "<string>"
            },
            "fixed_price_quantity": 123,
            "plan_phase_order": 123,
            "currency": "<string>",
            "conversion_rate": 123,
            "conversion_rate_config": {
              "conversion_rate_type": "unit",
              "unit_config": {
                "unit_amount": "<string>"
              }
            },
            "item": {
              "id": "<string>",
              "name": "<string>"
            },
            "credit_allocation": {
              "currency": "<string>",
              "allows_rollover": true,
              "custom_expiration": {
                "duration": 123,
                "duration_unit": "day"
              },
              "filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ]
            },
            "composite_price_filters": [
              {
                "field": "price_id",
                "operator": "includes",
                "values": [
                  "<string>"
                ]
              }
            ],
            "discount": {
              "discount_type": "percentage",
              "percentage_discount": 0.5,
              "applies_to_price_ids": [
                "h74gfhdjvn7ujokd",
                "7hfgtgjnbvc3ujkl"
              ],
              "filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "reason": "<string>"
            },
            "minimum": {
              "minimum_amount": "<string>",
              "filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "applies_to_price_ids": [
                "<string>"
              ]
            },
            "minimum_amount": "<string>",
            "maximum": {
              "maximum_amount": "<string>",
              "filters": [
                {
                  "field": "price_id",
                  "operator": "includes",
                  "values": [
                    "<string>"
                  ]
                }
              ],
              "applies_to_price_ids": [
                "<string>"
              ]
            },
            "maximum_amount": "<string>",
            "dimensional_price_configuration": {
              "dimensional_price_group_id": "<string>",
              "dimension_values": [
                "<string>"
              ]
            }
          },
          "usage_customer_ids": [
            "<string>"
          ],
          "filter": "<string>"
        }
      ],
      "subtotal": "<string>",
      "invoice_date": "2023-11-07T05:31:56Z"
    }
  ],
  "pagination_metadata": {
    "has_more": true,
    "next_cursor": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

API Keys can be issued in the Orb's web application.

Query Parameters

​
customer_id
string | null
​
external_customer_id
string | null
​
subscription_id
string | null
​
status
enum<string> | null
Available options:
draft,
issued,
paid,
synced,
void
​
status[]
enum<string>[] | null
Available options:
draft,
issued,
paid,
synced,
void
​
due_date_window
string | null

Filters invoices by their due dates within a specific time range in the past. Specify the range as a number followed by 'd' (days) or 'm' (months). For example, '7d' filters invoices due in the last 7 days, and '2m' filters those due in the last 2 months.

​
date_type
enum<string> | null
default:invoice_date
Available options:
due_date,
invoice_date
​
due_date
string<date> | null
​
due_date[gt]
string<date> | null
​
due_date[lt]
string<date> | null
​
amount
string | null
​
amount[gt]
string | null
​
amount[lt]
string | null
​
is_recurring
boolean | null
​
limit
integer
default:20

The number of items to fetch. Defaults to 20.

Required range: 1 <= x <= 100
​
cursor
string | null

Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.

​
invoice_date[gte]
string<date-time> | null
​
invoice_date[gt]
string<date-time> | null
​
invoice_date[lt]
string<date-time> | null
​
invoice_date[lte]
string<date-time> | null

Response

OK

​
data
Invoice · object[]
required
​
pagination_metadata
PaginationMetadata · object
required