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



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 214

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_nullify404(true)
                .is_response_void(true)
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             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. subscription

Parameters:

  • subscription_id (String) —

    Required parameter: The Chargify id of the

Returns:



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

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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ProformaInvoice.method(:from_hash))
                .local_error('403',
                             'Forbidden',
                             APIException)
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             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:



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

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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ProformaInvoice.method(:from_hash))
                .local_error('400',
                             'Bad Request',
                             ProformaBadRequestErrorResponseException)
                .local_error('403',
                             'Forbidden',
                             APIException)
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             ErrorMapResponseException))
    .execute
end

#list_proforma_invoices(options = {}) ⇒ Array[ProformaInvoice]

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`. subscription for the invoice’s Due Date, in the YYYY-MM-DD format. invoice’s Due Date, in the YYYY-MM-DD format. 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 (String) —

    Required parameter: The Chargify id of the

  • start_date (String) —

    Optional parameter: The beginning date range

  • end_date (String) —

    Optional parameter: The ending date range for the

  • status (Status) —

    Optional parameter: The current status of the

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



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 127

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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ProformaInvoice.method(:from_hash))
                .is_response_array(true))
    .execute
end

#list_subscription_group_proforma_invoices(uid) ⇒ ProformaInvoice

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

Parameters:

  • uid (String) —

    Required parameter: The uid of the subscription

Returns:



241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 241

def list_subscription_group_proforma_invoices(uid)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscription_groups/{uid}/proforma_invoices.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(uid, key: 'uid')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ProformaInvoice.method(:from_hash))
                .local_error('403',
                             'Forbidden',
                             APIException)
                .local_error('404',
                             'Not Found',
                             APIException))
    .execute
end

#preview_proforma_invoice(subscription_id) ⇒ ProformaInvoicePreview

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

Parameters:

  • subscription_id (String) —

    Required parameter: The Chargify id of the

Returns:



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

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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ProformaInvoicePreview.method(:from_hash))
                .local_error('403',
                             'Forbidden',
                             APIException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             ErrorListResponseException))
    .execute
end

#preview_signup_proforma_invoice(include_next_proforma_invoice: 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. to include a proforma invoice preview for the first renewal

Parameters:

  • include_next_proforma_invoice (String) (defaults to: nil) —

    Optional parameter: Choose

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

    Optional parameter: Example:

Returns:



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 26

def (include_next_proforma_invoice: 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_next_proforma_invoice, key: 'include=next_proforma_invoice'))
               .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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SignupProformaPreviewResponse.method(:from_hash))
                .local_error('400',
                             'Bad Request',
                             ProformaBadRequestErrorResponseException)
                .local_error('403',
                             'Forbidden',
                             APIException)
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             ErrorMapResponseException))
    .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 (Integer) —

    Required parameter: The uid of the

Returns:



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

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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ProformaInvoice.method(:from_hash))
                .local_error('403',
                             'Forbidden',
                             APIException)
                .local_error('404',
                             'Not Found',
                             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:



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/advanced_billing/controllers/proforma_invoices_controller.rb', line 170

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
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ProformaInvoice.method(:from_hash))
                .local_error('403',
                             'Forbidden',
                             APIException)
                .local_error('404',
                             'Not Found',
                             APIException)
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             ErrorListResponseException))
    .execute
end