Class: Orb::Resources::Invoices

Inherits:
Object
  • Object
show all
Defined in:
lib/orb/resources/invoices.rb,
sig/orb/resources/invoices.rbs

Overview

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.

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Invoices

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Invoices.

Parameters:



596
597
598
 
# File 'lib/orb/resources/invoices.rb', line 596

def initialize(client:)
  @client = client
end

Instance Method Details

#`void` ⇒ Object 



131
 
# File 'sig/orb/resources/invoices.rbs', line 131

def `void`: (

#create(currency:, invoice_date:, line_items:, auto_collection: nil, customer_id: nil, discount: nil, due_date: nil, external_customer_id: nil, memo: nil, metadata: nil, net_terms: nil, will_auto_issue: nil, request_options: {}) ⇒ Orb::Models::Invoice

Some parameter documentations has been truncated, see Models::InvoiceCreateParams for more details.

This endpoint is used to create a one-off invoice for a customer.

Parameters:

  • currency (String) —

    An ISO 4217 currency string. Must be the same as the customer's currency if it i

  • invoice_date (Time) —

    An ISO 8601 date or timestamp, interpreted in the customer's timezone. If a date

  • line_items (Array<Orb::Models::InvoiceCreateParams::LineItem>)
  • auto_collection (Boolean, nil) —

    Determines whether this invoice will automatically attempt to charge a saved pay

  • customer_id (String, nil) —

    The id of the Customer to create this invoice for. One of customer_id and `e

  • discount (Orb::Models::PercentageDiscount, Orb::Models::TrialDiscount, Orb::Models::UsageDiscount, Orb::Models::AmountDiscount, Orb::Models::Discount::TieredPercentage, nil) —

    An optional discount to attach to the invoice.

  • due_date (Date, Time, nil) —

    An optional custom due date for the invoice. If not set, the due date will be ca

  • external_customer_id (String, nil) —

    The external_customer_id of the Customer to create this invoice for. One of

  • memo (String, nil) —

    An optional memo to attach to the invoice. If no memo is provided, we will attac

  • metadata (Hash{Symbol=>String, nil}, nil) —

    User-specified key/value pairs for the resource. Individual keys can be removed

  • net_terms (Integer, nil) —

    The net terms determines the due date of the invoice. Due date is calculated bas

  • will_auto_issue (Boolean) —

    When true, auto-issues the invoice on the invoice date. If the invoice date is t

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



47
48
49
50
 
# File 'lib/orb/resources/invoices.rb', line 47

def create(params)
  parsed, options = Orb::InvoiceCreateParams.dump_request(params)
  @client.request(method: :post, path: "invoices", body: parsed, model: Orb::Invoice, options: options)
end

#delete_line_item(line_item_id, invoice_id:, request_options: {}) ⇒ nil

This endpoint deletes an invoice line item from a draft invoice.

This endpoint only allows deletion of one-off line items (not subscription-based line items). The invoice must be in a draft status for this operation to succeed.

Parameters:

  • line_item_id (String)
  • invoice_id (String)
  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



199
200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/orb/resources/invoices.rb', line 199

def delete_line_item(line_item_id, params)
  parsed, options = Orb::InvoiceDeleteLineItemParams.dump_request(params)
  invoice_id =
    parsed.delete(:invoice_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :delete,
    path: ["invoices/%1$s/invoice_line_items/%2$s", invoice_id, line_item_id],
    model: NilClass,
    options: options
  )
end

#fetch(invoice_id, include_zero_quantity_line_items: nil, request_options: {}) ⇒ Orb::Models::Invoice

Some parameter documentations has been truncated, see Models::InvoiceFetchParams for more details.

This endpoint is used to fetch an Invoice given an identifier.

Parameters:

  • invoice_id (String)
  • include_zero_quantity_line_items (Boolean, nil) —

    Whether to return line items with a quantity of zero. When omitted, Orb returns

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/orb/resources/invoices.rb', line 230

def fetch(invoice_id, params = {})
  parsed, options = Orb::InvoiceFetchParams.dump_request(params)
  query = Orb::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["invoices/%1$s", invoice_id],
    query: query,
    model: Orb::Invoice,
    options: options
  )
end

#fetch_upcoming(subscription_id:, include_zero_quantity_line_items: nil, request_options: {}) ⇒ Orb::Models::InvoiceFetchUpcomingResponse

Some parameter documentations has been truncated, see Models::InvoiceFetchUpcomingParams for more details.

This endpoint can be used to fetch the upcoming invoice for the current billing period given a subscription.

Parameters:

  • subscription_id (String)
  • include_zero_quantity_line_items (Boolean, nil) —

    Whether to return line items with a quantity of zero. When omitted, Orb returns

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/orb/resources/invoices.rb', line 260

def fetch_upcoming(params)
  parsed, options = Orb::InvoiceFetchUpcomingParams.dump_request(params)
  query = Orb::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "invoices/upcoming",
    query: query,
    model: Orb::Models::InvoiceFetchUpcomingResponse,
    options: options
  )
end

#issue(invoice_id, synchronous: nil, request_options: {}) ⇒ Orb::Models::Invoice

Some parameter documentations has been truncated, see Models::InvoiceIssueParams for more details.

This endpoint allows an eligible invoice to be issued manually. This is only possible with invoices where status is draft, will_auto_issue is false, and an eligible_to_issue_at is a time in the past. Issuing an invoice could possibly trigger side effects, some of which could be customer-visible (e.g. sending emails, auto-collecting payment, syncing the invoice to external providers, etc).

Parameters:

  • invoice_id (String)
  • synchronous (Boolean) —

    If true, the invoice will be issued synchronously. If false, the invoice will be

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



293
294
295
296
297
298
299
300
301
302
 
# File 'lib/orb/resources/invoices.rb', line 293

def issue(invoice_id, params = {})
  parsed, options = Orb::InvoiceIssueParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["invoices/%1$s/issue", invoice_id],
    body: parsed,
    model: Orb::Invoice,
    options: options
  )
end

#issue_summary(invoice_id, synchronous: nil, request_options: {}) ⇒ Orb::Models::InvoiceIssueSummaryResponse

Some parameter documentations has been truncated, see Models::InvoiceIssueSummaryParams for more details.

This endpoint allows an eligible invoice to be issued manually. This is only possible with invoices where status is draft, will_auto_issue is false, and an eligible_to_issue_at is a time in the past. Issuing an invoice could possibly trigger side effects, some of which could be customer-visible (e.g. sending emails, auto-collecting payment, syncing the invoice to external providers, etc).

This is a lighter-weight alternative to the issue invoice endpoint, returning an invoice summary without any line item details.

Parameters:

  • invoice_id (String)
  • synchronous (Boolean) —

    If true, the invoice will be issued synchronously. If false, the invoice will be

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



328
329
330
331
332
333
334
335
336
337
 
# File 'lib/orb/resources/invoices.rb', line 328

def issue_summary(invoice_id, params = {})
  parsed, options = Orb::InvoiceIssueSummaryParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["invoices/summary/%1$s/issue", invoice_id],
    body: parsed,
    model: Orb::Models::InvoiceIssueSummaryResponse,
    options: options
  )
end

#list(amount: nil, amount_gt: nil, amount_lt: nil, cursor: nil, customer_id: nil, date_type: nil, due_date: nil, due_date_window: nil, due_date_gt: nil, due_date_lt: nil, external_customer_id: nil, include_zero_quantity_line_items: nil, invoice_date_gt: nil, invoice_date_gte: nil, invoice_date_lt: nil, invoice_date_lte: nil, is_recurring: nil, limit: nil, status: nil, subscription_id: nil, request_options: {}) ⇒ Orb::Internal::Page<Orb::Models::Invoice>

Some parameter documentations has been truncated, see Models::InvoiceListParams for more details.

This endpoint returns a list of all Invoices for an account in a list format.

The list of invoices is ordered starting from the most recently issued invoice date. The response also includes pagination_metadata, which lets the caller retrieve the next page of results if they exist.

By default, this only returns invoices that are issued, paid, or synced.

When fetching any draft invoices, this returns the last-computed invoice values for each draft invoice, which may not always be up-to-date since Orb regularly refreshes invoices asynchronously.

If you don't need line item details, minimums, maximums, or discounts, prefer the list invoices summary endpoint for better performance.

Parameters:

  • amount (String, nil)
  • amount_gt (String, nil)
  • amount_lt (String, nil)
  • cursor (String, nil) —

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

  • customer_id (String, nil)
  • date_type (Symbol, Orb::Models::InvoiceListParams::DateType, nil)
  • due_date (Date, nil)
  • due_date_window (String, nil) —

    Filters invoices by their due dates within a specific time range in the past. Sp

  • due_date_gt (Date, nil)
  • due_date_lt (Date, nil)
  • external_customer_id (String, nil)
  • include_zero_quantity_line_items (Boolean, nil) —

    Whether to return line items with a quantity of zero. When omitted, Orb returns

  • invoice_date_gt (Time, nil)
  • invoice_date_gte (Time, nil)
  • invoice_date_lt (Time, nil)
  • invoice_date_lte (Time, nil)
  • is_recurring (Boolean, nil)
  • limit (Integer) —

    The number of items to fetch. Defaults to 20.

  • status (Array<Symbol, Orb::Models::InvoiceListParams::Status>, nil)
  • subscription_id (String, nil)
  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/orb/resources/invoices.rb', line 162

def list(params = {})
  parsed, options = Orb::InvoiceListParams.dump_request(params)
  query = Orb::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "invoices",
    query: query.transform_keys(
      amount_gt: "amount[gt]",
      amount_lt: "amount[lt]",
      due_date_gt: "due_date[gt]",
      due_date_lt: "due_date[lt]",
      invoice_date_gt: "invoice_date[gt]",
      invoice_date_gte: "invoice_date[gte]",
      invoice_date_lt: "invoice_date[lt]",
      invoice_date_lte: "invoice_date[lte]"
    ),
    page: Orb::Internal::Page,
    model: Orb::Invoice,
    options: options
  )
end

#list_summary(amount: nil, amount_gt: nil, amount_lt: nil, cursor: nil, customer_id: nil, date_type: nil, due_date: nil, due_date_window: nil, due_date_gt: nil, due_date_lt: nil, external_customer_id: nil, invoice_date_gt: nil, invoice_date_gte: nil, invoice_date_lt: nil, invoice_date_lte: nil, is_recurring: nil, limit: nil, status: nil, subscription_id: nil, request_options: {}) ⇒ Orb::Internal::Page<Orb::Models::InvoiceListSummaryResponse>

Some parameter documentations has been truncated, see Models::InvoiceListSummaryParams for more details.

This is a lighter-weight endpoint that returns a list of all Invoice summaries for an account in a list format.

These invoice summaries do not include line item details, minimums, maximums, and discounts, making this endpoint more efficient.

The list of invoices is ordered starting from the most recently issued invoice date. The response also includes pagination_metadata, which lets the caller retrieve the next page of results if they exist.

By default, this only returns invoices that are issued, paid, or synced.

When fetching any draft invoices, this returns the last-computed invoice values for each draft invoice, which may not always be up-to-date since Orb regularly refreshes invoices asynchronously.

Parameters:

  • amount (String, nil)
  • amount_gt (String, nil)
  • amount_lt (String, nil)
  • cursor (String, nil) —

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

  • customer_id (String, nil)
  • date_type (Symbol, Orb::Models::InvoiceListSummaryParams::DateType, nil)
  • due_date (Date, nil)
  • due_date_window (String, nil) —

    Filters invoices by their due dates within a specific time range in the past. Sp

  • due_date_gt (Date, nil)
  • due_date_lt (Date, nil)
  • external_customer_id (String, nil)
  • invoice_date_gt (Time, nil)
  • invoice_date_gte (Time, nil)
  • invoice_date_lt (Time, nil)
  • invoice_date_lte (Time, nil)
  • is_recurring (Boolean, nil)
  • limit (Integer) —

    The number of items to fetch. Defaults to 20.

  • status (Symbol, Orb::Models::InvoiceListSummaryParams::Status, nil)
  • subscription_id (String, nil)
  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
 
# File 'lib/orb/resources/invoices.rb', line 404

def list_summary(params = {})
  parsed, options = Orb::InvoiceListSummaryParams.dump_request(params)
  query = Orb::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "invoices/summary",
    query: query.transform_keys(
      amount_gt: "amount[gt]",
      amount_lt: "amount[lt]",
      due_date_gt: "due_date[gt]",
      due_date_lt: "due_date[lt]",
      invoice_date_gt: "invoice_date[gt]",
      invoice_date_gte: "invoice_date[gte]",
      invoice_date_lt: "invoice_date[lt]",
      invoice_date_lte: "invoice_date[lte]"
    ),
    page: Orb::Internal::Page,
    model: Orb::Models::InvoiceListSummaryResponse,
    options: options
  )
end

#mark_paid(invoice_id, payment_received_date:, external_id: nil, notes: nil, request_options: {}) ⇒ Orb::Models::Invoice

This endpoint allows an invoice's status to be set to the paid status. This can only be done to invoices that are in the issued or synced status.

Parameters:

  • invoice_id (String)
  • payment_received_date (Date) —

    A date string to specify the date of the payment.

  • external_id (String, nil) —

    An optional external ID to associate with the payment.

  • notes (String, nil) —

    An optional note to associate with the payment.

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



444
445
446
447
448
449
450
451
452
453
 
# File 'lib/orb/resources/invoices.rb', line 444

def mark_paid(invoice_id, params)
  parsed, options = Orb::InvoiceMarkPaidParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["invoices/%1$s/mark_paid", invoice_id],
    body: parsed,
    model: Orb::Invoice,
    options: options
  )
end

#pay(invoice_id, shared_payment_token_id:, request_options: {}) ⇒ Orb::Models::Invoice

This endpoint collects payment for an invoice. By default, it uses the customer's default payment method. Optionally, a shared payment token (SPT) can be provided to pay using agent-granted credentials instead. This action can only be taken on invoices with status "issued".

Parameters:

  • invoice_id (String)
  • shared_payment_token_id (String) —

    The ID of a shared payment token granted by an agent to use for this payment.

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



471
472
473
474
475
476
477
478
479
480
 
# File 'lib/orb/resources/invoices.rb', line 471

def pay(invoice_id, params)
  parsed, options = Orb::InvoicePayParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["invoices/%1$s/pay", invoice_id],
    body: parsed,
    model: Orb::Invoice,
    options: options
  )
end

#regenerate_invoice_pdf(invoice_id, request_options: {}) ⇒ Orb::Models::Invoice

This endpoint triggers a regeneration of the PDF for a finalized invoice.

The invoice must be finalized (issued, paid, synced, or void) and must already have an existing PDF. The original PDF is archived (not permanently deleted) to maintain an audit trail.

Important Legal Considerations:

Regenerating invoice PDFs may not be permitted in all jurisdictions. Many tax authorities require that issued invoices remain unmodified. Before using this endpoint, ensure that:

  • Your local tax regulations permit modification of issued billing documents
  • You have a legitimate business reason (e.g., fixing template errors, updating branding)
  • You maintain proper records of the original PDF (archived automatically by Orb)

Recommended use cases:

  • Correcting template rendering issues
  • Applying updated company branding
  • Updating customer data that was incorrect at issuance

Parameters:

Returns:

See Also:



514
515
516
517
518
519
520
521
 
# File 'lib/orb/resources/invoices.rb', line 514

def regenerate_invoice_pdf(invoice_id, params = {})
  @client.request(
    method: :post,
    path: ["invoices/%1$s/regenerate_invoice_pdf", invoice_id],
    model: Orb::Invoice,
    options: params[:request_options]
  )
end

#regenerate_receipt_pdf(invoice_id, request_options: {}) ⇒ Orb::Models::Invoice

This endpoint triggers a regeneration of the receipt PDF for a paid invoice.

The invoice must be in paid status and must already have an existing receipt PDF. The original PDF is archived (not permanently deleted) to maintain an audit trail.

Important Legal Considerations:

Regenerating receipt PDFs may not be permitted in all jurisdictions. Many tax authorities require that issued receipts remain unmodified. Before using this endpoint, ensure that:

  • Your local tax regulations permit modification of issued billing documents
  • You have a legitimate business reason (e.g., fixing template errors, updating branding)
  • You maintain proper records of the original PDF (archived automatically by Orb)

Recommended use cases:

  • Correcting template rendering issues
  • Applying updated company branding
  • Updating customer data that was incorrect at issuance

Parameters:

Returns:

See Also:



555
556
557
558
559
560
561
562
 
# File 'lib/orb/resources/invoices.rb', line 555

def regenerate_receipt_pdf(invoice_id, params = {})
  @client.request(
    method: :post,
    path: ["invoices/%1$s/regenerate_receipt_pdf", invoice_id],
    model: Orb::Invoice,
    options: params[:request_options]
  )
end

#update(invoice_id, auto_collection: nil, due_date: nil, invoice_date: nil, metadata: nil, net_terms: nil, request_options: {}) ⇒ Orb::Models::Invoice

Some parameter documentations has been truncated, see Models::InvoiceUpdateParams for more details.

This endpoint allows you to update the metadata, net_terms, due_date, invoice_date, and auto_collection properties on an invoice. If you pass null for the metadata value, it will clear any existing metadata for that invoice.

metadata can be modified regardless of invoice state. net_terms, due_date, invoice_date, and auto_collection can only be modified if the invoice is in a draft state. invoice_date can only be modified for non-subscription invoices.

Parameters:

  • invoice_id (String)
  • auto_collection (Boolean, nil) —

    Determines whether this invoice will automatically attempt to charge a saved pay

  • due_date (Date, Time, nil) —

    An optional custom due date for the invoice. If not set, the due date will be ca

  • invoice_date (Date, Time, nil) —

    The date of the invoice. Can only be modified for one-off draft invoices.

  • metadata (Hash{Symbol=>String, nil}, nil) —

    User-specified key/value pairs for the resource. Individual keys can be removed

  • net_terms (Integer, nil) —

    The net terms determines the due date of the invoice. Due date is calculated bas

  • request_options (Orb::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



83
84
85
86
87
88
89
90
91
92
 
# File 'lib/orb/resources/invoices.rb', line 83

def update(invoice_id, params = {})
  parsed, options = Orb::InvoiceUpdateParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["invoices/%1$s", invoice_id],
    body: parsed,
    model: Orb::Invoice,
    options: options
  )
end

#void(invoice_id, request_options: {}) ⇒ Orb::Models::Invoice

This endpoint allows an invoice's status to be set to the void status. This can only be done to invoices that are in the issued status.

If the associated invoice has used the customer balance to change the amount due, the customer balance operation will be reverted. For example, if the invoice used $10 of customer balance, that amount will be added back to the customer balance upon voiding.

If the invoice was used to purchase a credit block, but the invoice is not yet paid, the credit block will be voided. If the invoice was created due to a top-up, the top-up will be disabled.

Parameters:

Returns:

See Also:



584
585
586
587
588
589
590
591
 
# File 'lib/orb/resources/invoices.rb', line 584

def void(invoice_id, params = {})
  @client.request(
    method: :post,
    path: ["invoices/%1$s/void", invoice_id],
    model: Orb::Invoice,
    options: params[:request_options]
  )
end