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

Removes the delayed cancellation from a subscription, ensuring it is not canceled at the end of the current period. 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:



404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 404

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

Cancels the active dunning process for a subscription and sets it to active. the subscription.

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

Returns:



428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 428

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

Cancels the Subscription. The Delete method sets the Subscription state to canceled. To cancel the subscription immediately, omit any schedule parameters from the request. To use the schedule options, the Schedule Subscription Cancellation feature must be enabled on your site. the subscription. description here

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

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

    Optional parameter: TODO: type

Returns:



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 53

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

Cancels a subscription at the end of the current billing period based on the subscription's current product. 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:



368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 368

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

Places the subscription on hold, preventing it from renewing.

Limitations

You may not place a subscription on hold if the next_billing_at 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:



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

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

Previews a subscription’s next renewal assessment. 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, see [Subscriber Interface Overview](https://maxio.zendesk.com/hc/en-us/articles/24252493695757-Subsc riber-Interface-Overview).

Optional Component Fields

This endpoint is particularly useful because it returns the computed billing amount for the base product and the components which are in use by a subscriber. By default, the preview includes 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. End-of-period values for components are not predicted, so metered or events-based usage may be less than it will eventually be at the end of the period. Optionally, you can 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.

Preview Behavior

Sending a POST request to this endpoint returns preview data without modifying the subscription. This method previews data, but does 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:



485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 485

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

Reactivates a previously canceled subscription. For details on how the reactivation works, and how to reactivate subscriptions through the application, see [reactivation](https://maxio.zendesk.com/hc/en-us/articles/24252109503629- Reactivating-and-Resuming). 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. If a reactivation with resume: false, or where 'resume' is omitted were attempted, then Advanced Billing would reactivate the subscription with a new billing period regardless of whether or not resuming the previous billing period was possible.

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: https://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 https://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 https://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 https://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 https://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 https://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 https://acme.chargify.com/subscriptions/{subscription_id}/reactivate.json ?resume[require_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 https://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 https://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

3D Secure (3DS) Authentication post-authentication flow

When a payment requires 3DS Authentication to adhere to Strong Customer Authentication (SCA), the request enters a post-authentication flow where a 422 Unprocessable Entity status is returned with an action_link that will direct the customer through 3DS Authentication. See the [3D Secure Post-Authentication Flow](https://docs.maxio.com/hc/en-us/articles/44277749524365-3D-Secure-Po st-Authentication-Flow) article in the product documentation to learn how to manage the redirect flow. the subscription. description here

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

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

    Optional parameter: TODO: type

Returns:



335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 335

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

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



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

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

Retries collecting the balance due on a past-due subscription without waiting for the next scheduled attempt.

3D Secure (3DS) Authentication post-authentication flow

When a payment requires 3DS Authentication to adhere to Strong Customer Authentication (SCA), the request enters a post-authentication flow where a 422 Unprocessable Entity status is returned with an action_link that will direct the customer through 3DS Authentication. See the [3D Secure Post-Authentication Flow](https://docs.maxio.com/hc/en-us/articles/44277749524365-3D-Secure-Po st-Authentication-Flow) article in the product documentation to learn how to manage the redirect flow. the subscription.

Parameters:

  • subscription_id (Integer) —

    Required parameter: The Chargify id of

Returns:



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

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

Updates the date on which a paused subscription will automatically resume. To update a subscription's resume date, use this method to change or update the automatically_resume_at date.

Remove the resume date

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



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/advanced_billing/controllers/subscription_status_controller.rb', line 156

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