Class: AdvancedBilling::ProformaInvoicesController

Inherits:
BaseController show all
Defined in:
lib/advanced_billing/controllers/proforma_invoices_controller.rb

Overview

ProformaInvoicesController

Constant Summary

Constants inherited from BaseController

BaseController::GLOBAL_ERRORS

Instance Attribute Summary

Attributes inherited from BaseController

#config, #http_call_back

Instance Method Summary collapse

Methods inherited from BaseController

#initialize, #new_parameter, #new_request_builder, #new_response_handler, user_agent, user_agent_parameters

Constructor Details

This class inherits a constructor from AdvancedBilling::BaseController

Instance Method Details

#create_consolidated_proforma_invoice(uid) ⇒ void

This method returns an undefined value.

Creates a consolidated proforma invoice asynchronously. To find and view the new consolidated proforma invoice, you can poll the subscription group listing for proforma invoices; only one consolidated proforma invoice can be created per group at a time. If the information becomes outdated, simply void the old consolidated proforma invoice and generate a new one.

Restrictions

Proforma invoices are only available on Relationship Invoicing sites. To create a proforma invoice, the subscription must not be prepaid, and must be in a live state. group

Parameters:

  • uid (String) —

    Required parameter: The uid of the subscription



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 22

def create_consolidated_proforma_invoice(uid)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscription_groups/{uid}/proforma_invoices.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(uid, key: 'uid')
                                .is_required(true)
                                .should_encode(true))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_response_void(true)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#create_proforma_invoice(subscription_id) ⇒ ProformaInvoice

Creates a proforma invoice and returns it as a response. If the information becomes outdated, simply void the old proforma invoice and generate a new one. If you would like to preview the next billing amounts without generating a full proforma invoice, use the renewal preview endpoint.

Restrictions

Proforma invoices are only available on Relationship Invoicing sites. To create a proforma invoice, the subscription must not be in a group, must not be prepaid, and must be in a live state. the subscription.

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

Returns:



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 123

def create_proforma_invoice(subscription_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/proforma_invoices.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ProformaInvoice.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#create_signup_proforma_invoice(body: nil) ⇒ ProformaInvoice

Creates a proforma invoice to preview costs before a subscription's signup. This endpoint is only available for Relationship Invoicing sites and cannot be used to create consolidated proforma invoices or preview prepaid subscriptions. Like other proforma invoices, it can be emailed to the customer, voided, and publicly viewed on the chargifypay domain. Pass a payload that resembles a subscription create or signup preview request. For example, you can specify components, coupons/a referral, offers, custom pricing, and an existing customer or payment profile to populate a shipping or billing address. A product and customer first name, last name, and email are the minimum requirements. We recommend associating the proforma invoice with a customer_id to easily find their proforma invoices, since the subscription_id will always be blank. description here

Parameters:

Returns:



350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 350

def (body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/proforma_invoices.json',
                                 Server::PRODUCTION)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ProformaInvoice.method(:from_hash))
                .local_error_template('400',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ProformaBadRequestErrorResponseException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorArrayMapResponseException))
    .execute
end

#deliver_proforma_invoice(proforma_invoice_uid, body: nil) ⇒ ProformaInvoice

Delivers a proforma invoice programmatically via email. Supports email delivery to direct recipients, carbon-copy (cc) recipients, and blind carbon-copy (bcc) recipients. If recipient_emails is omitted, the system will fall back to the primary recipient derived from the invoice or subscription. At least one recipient must be present, either via the request body or via this default behavior, so an empty body may still succeed when defaults are available. proforma invoice description here

Parameters:

  • proforma_invoice_uid (String) —

    Required parameter: The uid of the

  • body (DeliverProformaInvoiceRequest) (defaults to: nil) —

    Optional parameter: TODO: type

Returns:



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 223

def deliver_proforma_invoice(proforma_invoice_uid,
                             body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/proforma_invoices/{proforma_invoice_uid}/deliveries.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(proforma_invoice_uid, key: 'proforma_invoice_uid')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ProformaInvoice.method(:from_hash))
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#list_proforma_invoices(options = {}) ⇒ ListProformaInvoicesResponse

Lists proforma invoices for a subscription. By default, results only include totals, not detailed breakdowns for line_items, discounts, taxes, credits, payments, or custom_fields. To include breakdowns, pass the specific field as a key in the query with a value set to true. the subscription. for the invoice's Due Date, in the YYYY-MM-DD format. invoice's Due Date, in the YYYY-MM-DD format. status of the invoice. Allowed Values: draft, open, paid, pending, voided pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query page=1. many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query per_page=200. returned invoices. line items data. discounts data. data. credits data. payments data. custom fields data.

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

  • start_date (String) —

    Optional parameter: The beginning date range

  • end_date (String) —

    Optional parameter: The ending date range for the

  • status (ProformaInvoiceStatus) —

    Optional parameter: The current

  • page (Integer) —

    Optional parameter: Result records are organized in

  • per_page (Integer) —

    Optional parameter: This parameter indicates how

  • direction (Direction) —

    Optional parameter: The sort direction of the

  • line_items (TrueClass | FalseClass) —

    Optional parameter: Include

  • discounts (TrueClass | FalseClass) —

    Optional parameter: Include

  • taxes (TrueClass | FalseClass) —

    Optional parameter: Include taxes

  • credits (TrueClass | FalseClass) —

    Optional parameter: Include

  • payments (TrueClass | FalseClass) —

    Optional parameter: Include

  • custom_fields (TrueClass | FalseClass) —

    Optional parameter: Include

Returns:



182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 182

def list_proforma_invoices(options = {})
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}/proforma_invoices.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(options['subscription_id'], key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(options['start_date'], key: 'start_date'))
               .query_param(new_parameter(options['end_date'], key: 'end_date'))
               .query_param(new_parameter(options['status'], key: 'status'))
               .query_param(new_parameter(options['page'], key: 'page'))
               .query_param(new_parameter(options['per_page'], key: 'per_page'))
               .query_param(new_parameter(options['direction'], key: 'direction'))
               .query_param(new_parameter(options['line_items'], key: 'line_items'))
               .query_param(new_parameter(options['discounts'], key: 'discounts'))
               .query_param(new_parameter(options['taxes'], key: 'taxes'))
               .query_param(new_parameter(options['credits'], key: 'credits'))
               .query_param(new_parameter(options['payments'], key: 'payments'))
               .query_param(new_parameter(options['custom_fields'], key: 'custom_fields'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ListProformaInvoicesResponse.method(:from_hash)))
    .execute
end

#list_subscription_group_proforma_invoices(options = {}) ⇒ ListProformaInvoicesResponse

Lists proforma invoices with a consolidation_level of parent for the subscription group. By default, proforma invoices returned on the index will only include totals, not detailed breakdowns for line_items, discounts, taxes, credits, payments, custom_fields. To include breakdowns, pass the specific field as a key in the query with a value set to true. group line items data. discounts data. data. credits data. payments data. custom fields data.

Parameters:

  • uid (String) —

    Required parameter: The uid of the subscription

  • line_items (TrueClass | FalseClass) —

    Optional parameter: Include

  • discounts (TrueClass | FalseClass) —

    Optional parameter: Include

  • taxes (TrueClass | FalseClass) —

    Optional parameter: Include taxes

  • credits (TrueClass | FalseClass) —

    Optional parameter: Include

  • payments (TrueClass | FalseClass) —

    Optional parameter: Include

  • custom_fields (TrueClass | FalseClass) —

    Optional parameter: Include

Returns:



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 61

def list_subscription_group_proforma_invoices(options = {})
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscription_groups/{uid}/proforma_invoices.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(options['uid'], key: 'uid')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(options['line_items'], key: 'line_items'))
               .query_param(new_parameter(options['discounts'], key: 'discounts'))
               .query_param(new_parameter(options['taxes'], key: 'taxes'))
               .query_param(new_parameter(options['credits'], key: 'credits'))
               .query_param(new_parameter(options['payments'], key: 'payments'))
               .query_param(new_parameter(options['custom_fields'], key: 'custom_fields'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ListProformaInvoicesResponse.method(:from_hash))
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException))
    .execute
end

#preview_proforma_invoice(subscription_id) ⇒ ProformaInvoice

Previews the data that will be included on a given subscription's proforma invoice if one were to be generated. It will have similar line items and totals as a renewal preview, but the response will be presented in the format of a proforma invoice. Consequently it will include additional information such as the name and addresses that will appear on the proforma invoice. The preview endpoint is subject to all the same conditions as the proforma invoice endpoint. For example, previews are only available on the Relationship Invoicing architecture, and previews cannot be made for end-of-life subscriptions. If all the data returned in the preview is as expected, you may then create a static proforma invoice and send it to your customer. The data within a preview will not be saved and will not be accessible after the call is made. Alternatively, if you have some proforma invoices already, you may make a preview call to determine whether any billing information for the subscription's upcoming renewal has changed. the subscription.

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

Returns:



311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 311

def preview_proforma_invoice(subscription_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/proforma_invoices/preview.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ProformaInvoice.method(:from_hash))
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#preview_signup_proforma_invoice(include: nil, body: nil) ⇒ SignupProformaPreviewResponse

Creates a signup preview in the format of a proforma invoice to preview costs before a subscription's signup. This endpoint is only available for Relationship Invoicing sites and cannot be used to create consolidated proforma invoice previews or preview prepaid subscriptions. You have the option of previewing the first renewal's costs as well. The proforma invoice preview will not be persisted. Pass a payload that resembles a subscription create or signup preview request. For example, you can specify components, coupons/a referral, offers, custom pricing, and an existing customer or payment profile to populate a shipping or billing address. A product and customer first name, last name, and email are the minimum requirements. Choose to include a proforma invoice preview for the first renewal. Use in query include=next_proforma_invoice. description here

Parameters:

Returns:



392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 392

def (include: nil,
                                    body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/proforma_invoices/preview.json',
                                 Server::PRODUCTION)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .query_param(new_parameter(include, key: 'include'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SignupProformaPreviewResponse.method(:from_hash))
                .local_error_template('400',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ProformaBadRequestErrorResponseException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorArrayMapResponseException))
    .execute
end

#read_proforma_invoice(proforma_invoice_uid) ⇒ ProformaInvoice

Returns the details of an existing proforma invoice.

Restrictions

Proforma invoices are only available on Relationship Invoicing sites. proforma invoice

Parameters:

  • proforma_invoice_uid (String) —

    Required parameter: The uid of the

Returns:



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 92

def read_proforma_invoice(proforma_invoice_uid)
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/proforma_invoices/{proforma_invoice_uid}.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(proforma_invoice_uid, key: 'proforma_invoice_uid')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ProformaInvoice.method(:from_hash))
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException))
    .execute
end

#void_proforma_invoice(proforma_invoice_uid, body: nil) ⇒ ProformaInvoice

Voids a proforma invoice that has the status "draft".

Restrictions

Proforma invoices are only available on Relationship Invoicing sites. Only proforma invoices that have the appropriate status may be reopened. If the invoice identified by uid does not have the appropriate status, the response will have HTTP status code 422 and an error message. A reason for the void operation is required to be included in the request body. If one is not provided, the response will have HTTP status code 422 and an error message. proforma invoice description here

Parameters:

  • proforma_invoice_uid (String) —

    Required parameter: The uid of the

  • body (VoidInvoiceRequest) (defaults to: nil) —

    Optional parameter: TODO: type

Returns:



264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 264

def void_proforma_invoice(proforma_invoice_uid,
                          body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/proforma_invoices/{proforma_invoice_uid}/void.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(proforma_invoice_uid, key: 'proforma_invoice_uid')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ProformaInvoice.method(:from_hash))
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end