Class: Orb::Resources::Invoices

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

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:



314
315
316
 
# File 'lib/orb/resources/invoices.rb', line 314

def initialize(client:)
  @client = client
end

Instance Method Details

#create(currency: , invoice_date: , line_items: , customer_id: nil, discount: 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) —

    Optional invoice date to set. Must be in the past, if not set, ‘invoice_date` is

  • line_items (Array<Orb::Models::InvoiceCreateParams::LineItem>)
  • 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, nil) —

    An optional discount to attach to the invoice.

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

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

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

  • net_terms (Integer, nil) —

    Determines the difference between the invoice issue date for subscription invoic

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



38
39
40
41
 
# File 'lib/orb/resources/invoices.rb', line 38

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

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

This endpoint is used to fetch an [‘Invoice`](/core-concepts#invoice) given an identifier.

Parameters:

Returns:

See Also:



169
170
171
172
173
174
175
176
 
# File 'lib/orb/resources/invoices.rb', line 169

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](/core-concepts#invoice) for the current billing period given a subscription.

Parameters:

Returns:

See Also:



190
191
192
193
194
195
196
197
198
199
 
# File 'lib/orb/resources/invoices.rb', line 190

def fetch_upcoming(params)
  parsed, options = Orb::InvoiceFetchUpcomingParams.dump_request(params)
  @client.request(
    method: :get,
    path: "invoices/upcoming",
    query: parsed,
    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:



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

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

#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 [‘Invoice`](/core-concepts#invoice)s 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`](/api-reference/pagination), 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::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:



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/orb/resources/invoices.rb', line 137

def list(params = {})
  parsed, options = Orb::InvoiceListParams.dump_request(params)
  @client.request(
    method: :get,
    path: "invoices",
    query: parsed.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

#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 the ‘paid` status. This can only be done to invoices that are in the `issued` 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:



251
252
253
254
255
256
257
258
259
260
 
# File 'lib/orb/resources/invoices.rb', line 251

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

This endpoint collects payment for an invoice using the customer’s default payment method. This action can only be taken on invoices with status “issued”.

Parameters:

Returns:

See Also:



273
274
275
276
277
278
279
280
 
# File 'lib/orb/resources/invoices.rb', line 273

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

#update(invoice_id, metadata: 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`, and `due_date` 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` and `due_date` can only be modified if the invoice is in a `draft` state.

Parameters:

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

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

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

Returns:

See Also:



64
65
66
67
68
69
70
71
72
73
 
# File 'lib/orb/resources/invoices.rb', line 64

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



302
303
304
305
306
307
308
309
 
# File 'lib/orb/resources/invoices.rb', line 302

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