Invoice
Create a one-off invoice
API documentation
Alert
Customer
- GETList customers
- POSTCreate customer
- GETFetch customer by external ID
- PUTUpdate customer by external ID
- GETFetch customer costs by external ID
- POSTUpdate payment methods from payment provider
- GETFetch customer
- PUTUpdate customer
- DELDelete customer
- GETList balance transactions
- POSTCreate customer balance transaction
- GETFetch customer costs
- POSTUpdate payment methods from payment provider
Credit
- GETFetch customer credit balance by external customer id
- GETFetch customer credits ledger by external ID
- POSTCreate ledger entry by external ID
- GETList top-ups by external ID
- POSTCreate top-up by external ID
- DELDeactivate top-up by external ID
- GETFetch customer credit balance
- GETFetch customer credits ledger
- POSTCreate ledger entry
- GETList top-ups
- POSTCreate top-up
- DELDeactivate top-up
Dimensional Price Group
Event
Invoice
Availability
Plan
Price
Subscription Change
Subscription
- GETList subscriptions
- POSTCreate subscription
- GETFetch subscription
- PUTUpdate subscription
- POSTCancel subscription
- GETFetch subscription costs
- GETFetch subscription schedule
- POSTSchedule plan change
- POSTTrigger phase
- POSTUnschedule subscription cancellation
- POSTUnschedule fixed fee quantity updates
- POSTUnschedule plan change
- POSTUpdate price quantity
- POSTUpdate trial for subscription
- GETFetch subscription usage
Price interval
Invoice
Create a one-off invoice
This endpoint is used to create a one-off invoice for a customer.
POST
/
invoices
curl --request POST \
--url https://api.withorb.com/v1/invoices \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"metadata": {},
"customer_id": "4khy3nwzktxv7",
"external_customer_id": "external-customer-id",
"currency": "USD",
"memo": "An optional memo for my invoice.",
"will_auto_issue": false,
"invoice_date": "2023-09-22",
"net_terms": 0,
"line_items": [
{
"start_date": "2023-09-22",
"end_date": "2023-09-22",
"quantity": 1,
"name": "Line Item Name",
"item_id": "4khy3nwzktxv7",
"model_type": "unit",
"unit_config": {
"unit_amount": "<string>"
}
}
],
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
}
}'
{
"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": "8.00",
"created_at": "2022-05-01T07:01:31+00:00",
"currency": "USD",
"customer": {
"id": "<string>",
"external_customer_id": "<string>"
},
"discount": "<any>",
"discounts": [
{
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
}
],
"due_date": "2022-05-30T07:00:00+00:00",
"id": "<string>",
"invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
"invoice_number": "JYEFHK-00001",
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum_amount": "<string>",
"line_items": [
{
"amount": "7.00",
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
},
"end_date": "2022-02-01T08:00:00+00:00",
"grouping": "<string>",
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum_amount": "<string>",
"adjustments": [
{
"id": "<string>",
"is_invoice_level": true,
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"reason": "<string>",
"adjustment_type": "usage_discount",
"usage_discount": 123,
"amount": "<string>"
}
],
"name": "Fixed Fee",
"quantity": 1,
"start_date": "2022-02-01T08:00:00+00:00",
"subtotal": "9.00",
"adjusted_subtotal": "5.00",
"credits_applied": "6.00",
"partially_invoiced_amount": "4.00",
"sub_line_items": [
{
"amount": "9.00",
"name": "Tier One",
"quantity": 5,
"grouping": {
"key": "region",
"value": "west"
},
"type": "matrix",
"matrix_config": {
"dimension_values": [
"<string>"
]
}
}
],
"tax_amounts": [
{
"tax_rate_description": "<string>",
"tax_rate_percentage": "<string>",
"amount": "<string>"
}
],
"id": "<string>",
"price": {
"metadata": {},
"id": "<string>",
"name": "<string>",
"external_price_id": "<string>",
"price_type": "usage_price",
"model_type": "unit",
"created_at": "2023-11-07T05:31:56Z",
"cadence": "one_time",
"billing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"invoicing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"billable_metric": {
"id": "<string>"
},
"dimensional_price_configuration": {
"dimensional_price_group_id": "<string>",
"dimension_values": [
"<string>"
]
},
"fixed_price_quantity": 123,
"plan_phase_order": 123,
"currency": "<string>",
"conversion_rate": 123,
"item": {
"id": "<string>",
"name": "<string>"
},
"credit_allocation": {
"currency": "<string>",
"allows_rollover": true
},
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
},
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum_amount": "<string>",
"unit_config": {
"unit_amount": "<string>"
}
},
"usage_customer_ids": [
"<string>"
],
"filter": "<string>"
}
],
"subscription": {
"id": "VDGsT23osdLb84KD"
},
"subtotal": "8.00",
"total": "8.00",
"customer_balance_transactions": [
{
"id": "cgZa3SXcsPTVyC4Y",
"created_at": "2022-05-01T07:01:31+00:00",
"starting_balance": "33.00",
"ending_balance": "22.00",
"amount": "11.00",
"action": "applied_to_invoice",
"description": "An optional description",
"invoice": {
"id": "gXcsPTVyC4YZa3Sc"
},
"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"
}
],
"invoice_date": "2022-05-01T07:00:00+00:00"
}
Authorizations
API Keys can be issued in the Orb's web application.
Body
application/json
Response
201
application/json
Created
An Invoice
is a fundamental billing entity, representing the request for payment for
a single subscription. This includes a set of line items, which correspond to prices in the subscription's plan and
can represent fixed recurring fees or usage-based fees. They are generated at the end of a billing period, or as
the result of an action, such as a cancellation.
Was this page helpful?
curl --request POST \
--url https://api.withorb.com/v1/invoices \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"metadata": {},
"customer_id": "4khy3nwzktxv7",
"external_customer_id": "external-customer-id",
"currency": "USD",
"memo": "An optional memo for my invoice.",
"will_auto_issue": false,
"invoice_date": "2023-09-22",
"net_terms": 0,
"line_items": [
{
"start_date": "2023-09-22",
"end_date": "2023-09-22",
"quantity": 1,
"name": "Line Item Name",
"item_id": "4khy3nwzktxv7",
"model_type": "unit",
"unit_config": {
"unit_amount": "<string>"
}
}
],
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
}
}'
{
"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": "8.00",
"created_at": "2022-05-01T07:01:31+00:00",
"currency": "USD",
"customer": {
"id": "<string>",
"external_customer_id": "<string>"
},
"discount": "<any>",
"discounts": [
{
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
}
],
"due_date": "2022-05-30T07:00:00+00:00",
"id": "<string>",
"invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
"invoice_number": "JYEFHK-00001",
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum_amount": "<string>",
"line_items": [
{
"amount": "7.00",
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
},
"end_date": "2022-02-01T08:00:00+00:00",
"grouping": "<string>",
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum_amount": "<string>",
"adjustments": [
{
"id": "<string>",
"is_invoice_level": true,
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
],
"reason": "<string>",
"adjustment_type": "usage_discount",
"usage_discount": 123,
"amount": "<string>"
}
],
"name": "Fixed Fee",
"quantity": 1,
"start_date": "2022-02-01T08:00:00+00:00",
"subtotal": "9.00",
"adjusted_subtotal": "5.00",
"credits_applied": "6.00",
"partially_invoiced_amount": "4.00",
"sub_line_items": [
{
"amount": "9.00",
"name": "Tier One",
"quantity": 5,
"grouping": {
"key": "region",
"value": "west"
},
"type": "matrix",
"matrix_config": {
"dimension_values": [
"<string>"
]
}
}
],
"tax_amounts": [
{
"tax_rate_description": "<string>",
"tax_rate_percentage": "<string>",
"amount": "<string>"
}
],
"id": "<string>",
"price": {
"metadata": {},
"id": "<string>",
"name": "<string>",
"external_price_id": "<string>",
"price_type": "usage_price",
"model_type": "unit",
"created_at": "2023-11-07T05:31:56Z",
"cadence": "one_time",
"billing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"invoicing_cycle_configuration": {
"duration": 123,
"duration_unit": "day"
},
"billable_metric": {
"id": "<string>"
},
"dimensional_price_configuration": {
"dimensional_price_group_id": "<string>",
"dimension_values": [
"<string>"
]
},
"fixed_price_quantity": 123,
"plan_phase_order": 123,
"currency": "<string>",
"conversion_rate": 123,
"item": {
"id": "<string>",
"name": "<string>"
},
"credit_allocation": {
"currency": "<string>",
"allows_rollover": true
},
"discount": {
"discount_type": "percentage",
"applies_to_price_ids": [
"h74gfhdjvn7ujokd",
"7hfgtgjnbvc3ujkl"
],
"reason": "<string>",
"percentage_discount": 0.15
},
"minimum": {
"minimum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"minimum_amount": "<string>",
"maximum": {
"maximum_amount": "<string>",
"filters": [
{
"field": "price_id",
"operator": "includes",
"values": [
"<string>"
]
}
]
},
"maximum_amount": "<string>",
"unit_config": {
"unit_amount": "<string>"
}
},
"usage_customer_ids": [
"<string>"
],
"filter": "<string>"
}
],
"subscription": {
"id": "VDGsT23osdLb84KD"
},
"subtotal": "8.00",
"total": "8.00",
"customer_balance_transactions": [
{
"id": "cgZa3SXcsPTVyC4Y",
"created_at": "2022-05-01T07:01:31+00:00",
"starting_balance": "33.00",
"ending_balance": "22.00",
"amount": "11.00",
"action": "applied_to_invoice",
"description": "An optional description",
"invoice": {
"id": "gXcsPTVyC4YZa3Sc"
},
"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"
}
],
"invoice_date": "2022-05-01T07:00:00+00:00"
}