Class: AdvancedBilling::SubscriptionStatusController

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

Overview

SubscriptionStatusController

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

#cancel_delayed_cancellation(subscription_id) ⇒ DelayedCancellationResponse

Removing the delayed cancellation on a subscription will ensure that it doesn’t get canceled at the end of the period that it is in. The request will reset the ‘cancel_at_end_of_period` flag to `false`. This endpoint is idempotent. If the subscription was not set to cancel in the future, removing the delayed cancellation has no effect and the call will be successful. the subscription

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

Returns:



388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 388

def cancel_delayed_cancellation(subscription_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/subscriptions/{subscription_id}/delayed_cancel.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(DelayedCancellationResponse.method(:from_hash))
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException))
    .execute
end

#cancel_dunning(subscription_id) ⇒ SubscriptionResponse

If a subscription is currently in dunning, the subscription will be set to active and the active Dunner will be resolved. the subscription

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

Returns:



412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 412

def cancel_dunning(subscription_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/cancel_dunning.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(SubscriptionResponse.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#cancel_subscription(subscription_id, body: nil) ⇒ SubscriptionResponse

The DELETE action causes the cancellation of the Subscription. This means, the method sets the Subscription state to “canceled”. the subscription description here

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

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

    Optional parameter: TODO: type

Returns:



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 45

def cancel_subscription(subscription_id,
                        body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/subscriptions/{subscription_id}.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: '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(SubscriptionResponse.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}\'.',
                                      APIException))
    .execute
end

#initiate_delayed_cancellation(subscription_id, body: nil) ⇒ DelayedCancellationResponse

Advanced Billing offers the ability to cancel a subscription at the end of the current billing period. This period is set by its current product. Requesting to cancel the subscription at the end of the period sets the ‘cancel_at_end_of_period` flag to true. Note that you cannot set `cancel_at_end_of_period` at subscription creation, or if the subscription is past due. the subscription description here

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

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

    Optional parameter: TODO: type

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
377
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 352

def initiate_delayed_cancellation(subscription_id,
                                  body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/delayed_cancel.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: '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(DelayedCancellationResponse.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

#pause_subscription(subscription_id, body: nil) ⇒ SubscriptionResponse

This will place the subscription in the on_hold state and it will not renew. ## Limitations You may not place a subscription on hold if the ‘next_billing` date is within 24 hours. the subscription here

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

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

    Optional parameter: TODO: type description

Returns:



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 114

def pause_subscription(subscription_id,
                       body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/hold.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: '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(SubscriptionResponse.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#preview_renewal(subscription_id, body: nil) ⇒ RenewalPreviewResponse

The Chargify API allows you to preview a renewal by posting to the renewals endpoint. Renewal Preview is an object representing a subscription’s next assessment. You can retrieve it to see a snapshot of how much your customer will be charged on their next renewal. The “Next Billing” amount and “Next Billing” date are already represented in the UI on each Subscriber’s Summary. For more information, please see our documentation [here](maxio.zendesk.com/hc/en-us/articles/24252493695757-Subscrib er-Interface-Overview). ## Optional Component Fields This endpoint is particularly useful due to the fact that it will return the computed billing amount for the base product and the components which are in use by a subscriber. By default, the preview will include billing details for all components _at their current quantities_. This means:

  • Current ‘allocated_quantity` for quantity-based components

  • Current enabled/disabled status for on/off components

  • Current metered usage ‘unit_balance` for metered components

  • Current metric quantity value for events recorded thus far for

events-based components In the above statements, “current” means the quantity or value as of the call to the renewal preview endpoint. We do not predict end-of-period values for components, so metered or events-based usage may be less than it will eventually be at the end of the period. Optionally, **you may provide your own custom quantities** for any component to see a billing preview for non-current quantities. This is accomplished by sending a request body with data under the ‘components` key. See the request body documentation below. ## Subscription Side Effects You can request a `POST` to obtain this data from the endpoint without any side effects. Plain and simple, this will preview data, not log any changes against a subscription. the subscription description here

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

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

    Optional parameter: TODO: type

Returns:



469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 469

def preview_renewal(subscription_id,
                    body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/renewals/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: '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(RenewalPreviewResponse.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#reactivate_subscription(subscription_id, body: nil) ⇒ SubscriptionResponse

Advanced Billing offers the ability to reactivate a previously canceled subscription. For details on how the reactivation works, and how to reactivate subscriptions through the application, see [reactivation](maxio.zendesk.com/hc/en-us/articles/24252109503629- Reactivating-and-Resuming). **Please note: The term “resume” is used also during another process in Advanced Billing. This occurs when an on-hold subscription is “resumed”. This returns the subscription to an active state.** + The response returns the subscription object in the ‘active` or `trialing` state. + The `canceled_at` and `cancellation_message` fields do not have values. + The method works for “Canceled” or “Trial Ended” subscriptions. + It will not work for items not marked as “Canceled”, “Unpaid”, or “Trial Ended”. ## Resume the current billing period for a subscription A subscription is considered “resumable” if you are attempting to reactivate within the billing period the subscription was canceled in. A resumed subscription’s billing date remains the same as before it was canceled. In other words, it does not start a new billing period. Payment may or may not be collected for a resumed subscription, depending on whether or not the subscription had a balance when it was canceled (for example, if it was canceled because of dunning). Consider a subscription which was created on June 1st, and would renew on July 1st. The subscription is then canceled on June 15. If a reactivation with ‘resume: true` were attempted before what would have been the next billing date of July 1st, then Advanced Billing would resume the subscription. If a reactivation with `resume: true` were attempted after what would have been the next billing date of July 1st, then Advanced Billing would not resume the subscription, and instead it would be reactivated with a new billing period. | Canceled | Reactivation | Resumable? | |—|—|—| | Jun 15 | June 28 | Yes | | Jun 15 | July 2 | No | ## Reactivation Scenarios ### Reactivating Canceled Subscription While Preserving Balance + Given you have a product that costs $20 + Given you have a canceled subscription to the $20 product

+ 1 charge should exist for $20
+ 1 payment should exist for $20

+ When the subscription has canceled due to dunning, it retained a negative balance of $20 #### Results The resulting charges upon reactivation will be: + 1 charge for $20 for the new product + 1 charge for $20 for the balance due + Total charges = $40 + The subscription will transition to active + The subscription balance will be zero ### Reactivating a Canceled Subscription With Coupon + Given you have a canceled subscription + It has no current period defined + You have a coupon code “EARLYBIRD” + The coupon is set to recur for 6 periods PUT request sent to: ‘acme.chargify.com/subscriptions/subscription_id/reactivate.json ?coupon_code=EARLYBIRD` #### Results + The subscription will transition to active + The subscription should have applied a coupon with code “EARLYBIRD” ### Reactivating Canceled Subscription With a Trial, Without the include_trial Flag + Given you have a canceled subscription + The product associated with the subscription has a trial + PUT request to `acme.chargify.com/subscriptions/subscription_id/reactivate.json ` #### Results + The subscription will transition to active ### Reactivating Canceled Subscription With Trial, With the include_trial Flag + Given you have a canceled subscription + The product associated with the subscription has a trial + Send a PUT request to `acme.chargify.com/subscriptions/subscription_id/reactivate.json ?include_trial=1` #### Results + The subscription will transition to trialing ### Reactivating Trial Ended Subscription + Given you have a trial_ended subscription + Send a PUT request to `acme.chargify.com/subscriptions/subscription_id/reactivate.json ` #### Results + The subscription will transition to active ### Resuming a Canceled Subscription + Given you have a `canceled` subscription and it is resumable + Send a PUT request to `acme.chargify.com/subscriptions/subscription_id/reactivate.json ?resume=true` #### Results + The subscription will transition to active + The next billing date should not have changed ### Attempting to resume a subscription which is not resumable + Given you have a `canceled` subscription, and it is not resumable + Send a PUT request to `acme.chargify.com/subscriptions/subscription_id/reactivate.json ?resume=true` #### Results + The subscription will transition to active, with a new billing period. ### Attempting to resume but not reactivate a subscription which is not resumable + Given you have a `canceled` subscription, and it is not resumable + Send a PUT request to `acme.chargify.com/subscriptions/subscription_id/reactivate.json ?resume=true` + The response status should be “422 UNPROCESSABLE ENTITY” + The subscription should be canceled with the following response “`

{
  "errors": ["Request was 'resume only', but this subscription cannot be

resumed.“]

}

“‘ #### Results + The subscription should remain `canceled` + The next billing date should not have changed ### Resuming Subscription Which Was Trialing + Given you have a `trial_ended` subscription, and it is resumable + And the subscription was canceled in the middle of a trial + And there is still time left on the trial + Send a PUT request to `acme.chargify.com/subscriptions/subscription_id/reactivate.json ?resume=true` #### Results + The subscription will transition to trialing + The next billing date should not have changed ### Resuming Subscription Which Was trial_ended + Given you have a `trial_ended` subscription, and it is resumable + Send a PUT request to `acme.chargify.com/subscriptions/subscription_id/reactivate.json ?resume=true` #### Results + The subscription will transition to active + The next billing date should not have changed + Any product-related charges should have been collected the subscription description here

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

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

    Optional parameter: TODO: type

Returns:



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

def reactivate_subscription(subscription_id,
                            body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/subscriptions/{subscription_id}/reactivate.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: '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(SubscriptionResponse.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#resume_subscription(subscription_id, calendar_billing_resumption_charge: ResumptionCharge::PRORATED) ⇒ SubscriptionResponse

Resume a paused (on-hold) subscription. If the normal next renewal date has not passed, the subscription will return to active and will renew on that date. Otherwise, it will behave like a reactivation, setting the billing date to ‘now’ and charging the subscriber. the subscription parameter: (For calendar billing subscriptions only) The way that the resumed subscription’s charge should be handled

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

  • calendar_billing_resumption_charge (ResumptionCharge) (defaults to: ResumptionCharge::PRORATED) —

    Optional

Returns:



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 82

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

#retry_subscription(subscription_id) ⇒ SubscriptionResponse

Advanced Billing offers the ability to retry collecting the balance due on a past due Subscription without waiting for the next scheduled attempt. ## Successful Reactivation The response will be ‘200 OK` with the updated Subscription. ## Failed Reactivation The response will be `422 “Unprocessable Entity`. the subscription

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

Returns:



18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 18

def retry_subscription(subscription_id)
  @api_call
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/subscriptions/{subscription_id}/retry.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(SubscriptionResponse.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end

#update_automatic_subscription_resumption(subscription_id, body: nil) ⇒ SubscriptionResponse

Once a subscription has been paused / put on hold, you can update the date which was specified to automatically resume the subscription. To update a subscription’s resume date, use this method to change or update the ‘automatically_resume_at` date. ### Remove the resume date Alternately, you can change the `automatically_resume_at` to `null` if you would like the subscription to not have a resume date. the subscription here

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

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

    Optional parameter: TODO: type description

Returns:



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 150

def update_automatic_subscription_resumption(subscription_id,
                                             body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/subscriptions/{subscription_id}/hold.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: '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(SubscriptionResponse.method(:from_hash))
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      ErrorListResponseException))
    .execute
end