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_api_call_builder, #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.

This endpoint will trigger the creation of a consolidated proforma invoice asynchronously. It will return a 201 with no message, or a 422 with any errors. To find and view the new consolidated proforma invoice, you may poll the subscription group listing for proforma invoices; only one consolidated proforma invoice may 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



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

def create_consolidated_proforma_invoice(uid)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscription_groups/{uid}/proforma_invoices.json',
                                 Server::DEFAULT)
               .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

This endpoint will create a proforma invoice and return 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, please 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:



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

def create_proforma_invoice(subscription_id)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/proforma_invoices.json',
                                 Server::DEFAULT)
               .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

This endpoint is only available for Relationship Invoicing sites. It cannot be used to create consolidated proforma invoices or preview prepaid subscriptions. Create a proforma invoice to preview costs before a subscription’s signup. 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.

Parameters:

Returns:



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

def (body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/proforma_invoices.json',
                                 Server::DEFAULT)
               .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

#list_proforma_invoices(options = {}) ⇒ ListProformaInvoicesResponse

By default, proforma invoices returned on the index will 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:



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
209
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 183

def list_proforma_invoices(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}/proforma_invoices.json',
                                 Server::DEFAULT)
               .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

Only proforma invoices with a ‘consolidation_level` of parent are returned. 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:



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

def list_subscription_group_proforma_invoices(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscription_groups/{uid}/proforma_invoices.json',
                                 Server::DEFAULT)
               .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

Return a preview of 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:



271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 271

def preview_proforma_invoice(subscription_id)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/proforma_invoices/preview.json',
                                 Server::DEFAULT)
               .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

This endpoint is only available for Relationship Invoicing sites. It cannot be used to create consolidated proforma invoice previews or preview prepaid subscriptions. Create a signup preview in the format of a proforma invoice to preview costs before a subscription’s signup. You have the option of optionally 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`.

Parameters:

Returns:



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

def (include: nil,
                                    body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/proforma_invoices/preview.json',
                                 Server::DEFAULT)
               .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

Use this endpoint to read 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:



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

def read_proforma_invoice(proforma_invoice_uid)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/proforma_invoices/{proforma_invoice_uid}.json',
                                 Server::DEFAULT)
               .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

This endpoint will void 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

Parameters:

  • proforma_invoice_uid (String) —

    Required parameter: The uid of the

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

    Optional parameter: Example:

Returns:



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
249
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 224

def void_proforma_invoice(proforma_invoice_uid,
                          body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/proforma_invoices/{proforma_invoice_uid}/void.json',
                                 Server::DEFAULT)
               .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