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:



497
498
499
 
# File 'lib/orb/resources/invoices.rb', line 497

def initialize(client:)
  @client = client
end

Instance Method Details

#`void` ⇒ Object 



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

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. Must be i

  • 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, this invoice will be submitted for issuance upon creation. When false

  • 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:



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

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, request_options: {}) ⇒ Orb::Models::Invoice

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

Parameters:

Returns:

See Also:



222
223
224
225
226
227
228
229
 
# File 'lib/orb/resources/invoices.rb', line 222

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

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

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

Parameters:

Returns:

See Also:



243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/orb/resources/invoices.rb', line 243

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:



276
277
278
279
280
281
282
283
284
285
 
# File 'lib/orb/resources/invoices.rb', line 276

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:



311
312
313
314
315
316
317
318
319
320
 
# File 'lib/orb/resources/invoices.rb', line 311

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, 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)
  • 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:



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

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:



387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
 
# File 'lib/orb/resources/invoices.rb', line 387

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:



427
428
429
430
431
432
433
434
435
436
 
# File 'lib/orb/resources/invoices.rb', line 427

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:



454
455
456
457
458
459
460
461
462
463
 
# File 'lib/orb/resources/invoices.rb', line 454

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

#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:



485
486
487
488
489
490
491
492
 
# File 'lib/orb/resources/invoices.rb', line 485

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