@maxio-com/advanced-billing-sdk
Version:
Ultimate billing and pricing flexibility for B2B SaaS. Maxio integrates directly into your product, so you can seamlessly manage your product catalog, bill customers, and collect payments.
523 lines • 28.9 kB
JavaScript
"use strict";
/**
* AdvancedBilling
*
* This file was automatically generated for Maxio by APIMATIC v3.0 ( https://www.apimatic.io ).
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.SubscriptionStatusController = void 0;
var tslib_1 = require("tslib");
var core_js_1 = require("../core.js");
var cancellationRequest_js_1 = require("../models/cancellationRequest.js");
var delayedCancellationResponse_js_1 = require("../models/delayedCancellationResponse.js");
var pauseRequest_js_1 = require("../models/pauseRequest.js");
var reactivateSubscriptionRequest_js_1 = require("../models/reactivateSubscriptionRequest.js");
var renewalPreviewRequest_js_1 = require("../models/renewalPreviewRequest.js");
var renewalPreviewResponse_js_1 = require("../models/renewalPreviewResponse.js");
var resumptionCharge_js_1 = require("../models/resumptionCharge.js");
var subscriptionResponse_js_1 = require("../models/subscriptionResponse.js");
var schema_js_1 = require("../schema.js");
var baseController_js_1 = require("./baseController.js");
var core_1 = require("@apimatic/core");
var errorListResponseError_js_1 = require("../errors/errorListResponseError.js");
var SubscriptionStatusController = /** @class */ (function (_super) {
tslib_1.__extends(SubscriptionStatusController, _super);
function SubscriptionStatusController() {
return _super !== null && _super.apply(this, arguments) || this;
}
/**
* 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-Post-Authentication-Flow) article in the product documentation to learn how to manage the
* redirect flow.
*
* @param subscriptionId The Chargify id of the subscription.
* @return Response from the API call
*/
SubscriptionStatusController.prototype.retrySubscription = function (subscriptionId, requestOptions) {
return tslib_1.__awaiter(this, void 0, void 0, function () {
var req, mapped;
return tslib_1.__generator(this, function (_a) {
req = this.createRequest('PUT');
mapped = req.prepareArgs({
subscriptionId: [subscriptionId, (0, schema_js_1.number)()],
});
req.appendTemplatePath(templateObject_1 || (templateObject_1 = tslib_1.__makeTemplateObject(["/subscriptions/", "/retry.json"], ["/subscriptions/", "/retry.json"])), mapped.subscriptionId);
req.throwOn(422, errorListResponseError_js_1.ErrorListResponseError, true, "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.");
req.authenticate([{ basicAuth: true }]);
return [2 /*return*/, req.callAsJson(subscriptionResponse_js_1.subscriptionResponseSchema, requestOptions)];
});
});
};
/**
* 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.
*
* @param subscriptionId The Chargify id of the subscription.
* @param body
* @return Response from the API call
*/
SubscriptionStatusController.prototype.cancelSubscription = function (subscriptionId, body, requestOptions) {
return tslib_1.__awaiter(this, void 0, void 0, function () {
var req, mapped;
return tslib_1.__generator(this, function (_a) {
req = this.createRequest('DELETE');
mapped = req.prepareArgs({
subscriptionId: [subscriptionId, (0, schema_js_1.number)()],
body: [body, (0, schema_js_1.optional)(cancellationRequest_js_1.cancellationRequestSchema)],
});
req.header('Content-Type', 'application/json');
req.json(mapped.body);
req.appendTemplatePath(templateObject_2 || (templateObject_2 = tslib_1.__makeTemplateObject(["/subscriptions/", ".json"], ["/subscriptions/", ".json"])), mapped.subscriptionId);
req.throwOn(404, core_1.ApiError, true, "Not Found:'{$response.body}'");
req.throwOn(422, core_1.ApiError, true, "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.");
req.authenticate([{ basicAuth: true }]);
return [2 /*return*/, req.callAsJson(subscriptionResponse_js_1.subscriptionResponseSchema, requestOptions)];
});
});
};
/**
* 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.
*
* @param subscriptionId The Chargify id of the subscription.
* @param calendarBillingResumptionCharge (For calendar billing subscriptions only) The
* way that the resumed subscription's charge should
* be handled.
* @return Response from the API call
*/
SubscriptionStatusController.prototype.resumeSubscription = function (subscriptionId, calendarBillingResumptionCharge, requestOptions) {
return tslib_1.__awaiter(this, void 0, void 0, function () {
var req, mapped;
return tslib_1.__generator(this, function (_a) {
req = this.createRequest('POST');
mapped = req.prepareArgs({
subscriptionId: [subscriptionId, (0, schema_js_1.number)()],
calendarBillingResumptionCharge: [
calendarBillingResumptionCharge,
(0, schema_js_1.optional)(resumptionCharge_js_1.resumptionChargeSchema),
],
});
req.query("calendar_billing['resumption_charge']", mapped.calendarBillingResumptionCharge, core_js_1.commaPrefix);
req.appendTemplatePath(templateObject_3 || (templateObject_3 = tslib_1.__makeTemplateObject(["/subscriptions/", "/resume.json"], ["/subscriptions/", "/resume.json"])), mapped.subscriptionId);
req.throwOn(422, errorListResponseError_js_1.ErrorListResponseError, true, "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.");
req.authenticate([{ basicAuth: true }]);
return [2 /*return*/, req.callAsJson(subscriptionResponse_js_1.subscriptionResponseSchema, requestOptions)];
});
});
};
/**
* 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.
*
* @param subscriptionId The Chargify id of the subscription.
* @param body
* @return Response from the API call
*/
SubscriptionStatusController.prototype.pauseSubscription = function (subscriptionId, body, requestOptions) {
return tslib_1.__awaiter(this, void 0, void 0, function () {
var req, mapped;
return tslib_1.__generator(this, function (_a) {
req = this.createRequest('POST');
mapped = req.prepareArgs({
subscriptionId: [subscriptionId, (0, schema_js_1.number)()],
body: [body, (0, schema_js_1.optional)(pauseRequest_js_1.pauseRequestSchema)],
});
req.header('Content-Type', 'application/json');
req.json(mapped.body);
req.appendTemplatePath(templateObject_4 || (templateObject_4 = tslib_1.__makeTemplateObject(["/subscriptions/", "/hold.json"], ["/subscriptions/", "/hold.json"])), mapped.subscriptionId);
req.throwOn(422, errorListResponseError_js_1.ErrorListResponseError, true, "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.");
req.authenticate([{ basicAuth: true }]);
return [2 /*return*/, req.callAsJson(subscriptionResponse_js_1.subscriptionResponseSchema, requestOptions)];
});
});
};
/**
* 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.
*
* @param subscriptionId The Chargify id of the subscription.
* @param body
* @return Response from the API call
*/
SubscriptionStatusController.prototype.updateAutomaticSubscriptionResumption = function (subscriptionId, body, requestOptions) {
return tslib_1.__awaiter(this, void 0, void 0, function () {
var req, mapped;
return tslib_1.__generator(this, function (_a) {
req = this.createRequest('PUT');
mapped = req.prepareArgs({
subscriptionId: [subscriptionId, (0, schema_js_1.number)()],
body: [body, (0, schema_js_1.optional)(pauseRequest_js_1.pauseRequestSchema)],
});
req.header('Content-Type', 'application/json');
req.json(mapped.body);
req.appendTemplatePath(templateObject_5 || (templateObject_5 = tslib_1.__makeTemplateObject(["/subscriptions/", "/hold.json"], ["/subscriptions/", "/hold.json"])), mapped.subscriptionId);
req.throwOn(422, errorListResponseError_js_1.ErrorListResponseError, true, "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.");
req.authenticate([{ basicAuth: true }]);
return [2 /*return*/, req.callAsJson(subscriptionResponse_js_1.subscriptionResponseSchema, requestOptions)];
});
});
};
/**
* 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-Post-Authentication-Flow) article in the product documentation to learn how to manage the
* redirect flow.
*
* @param subscriptionId The Chargify id of the subscription.
* @param body
* @return Response from the API call
*/
SubscriptionStatusController.prototype.reactivateSubscription = function (subscriptionId, body, requestOptions) {
return tslib_1.__awaiter(this, void 0, void 0, function () {
var req, mapped;
return tslib_1.__generator(this, function (_a) {
req = this.createRequest('PUT');
mapped = req.prepareArgs({
subscriptionId: [subscriptionId, (0, schema_js_1.number)()],
body: [body, (0, schema_js_1.optional)(reactivateSubscriptionRequest_js_1.reactivateSubscriptionRequestSchema)],
});
req.header('Content-Type', 'application/json');
req.json(mapped.body);
req.appendTemplatePath(templateObject_6 || (templateObject_6 = tslib_1.__makeTemplateObject(["/subscriptions/", "/reactivate.json"], ["/subscriptions/", "/reactivate.json"])), mapped.subscriptionId);
req.throwOn(422, errorListResponseError_js_1.ErrorListResponseError, true, "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.");
req.authenticate([{ basicAuth: true }]);
return [2 /*return*/, req.callAsJson(subscriptionResponse_js_1.subscriptionResponseSchema, requestOptions)];
});
});
};
/**
* 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.
*
* @param subscriptionId The Chargify id of the subscription.
* @param body
* @return Response from the API call
*/
SubscriptionStatusController.prototype.initiateDelayedCancellation = function (subscriptionId, body, requestOptions) {
return tslib_1.__awaiter(this, void 0, void 0, function () {
var req, mapped;
return tslib_1.__generator(this, function (_a) {
req = this.createRequest('POST');
mapped = req.prepareArgs({
subscriptionId: [subscriptionId, (0, schema_js_1.number)()],
body: [body, (0, schema_js_1.optional)(cancellationRequest_js_1.cancellationRequestSchema)],
});
req.header('Content-Type', 'application/json');
req.json(mapped.body);
req.appendTemplatePath(templateObject_7 || (templateObject_7 = tslib_1.__makeTemplateObject(["/subscriptions/", "/delayed_cancel.json"], ["/subscriptions/", "/delayed_cancel.json"])), mapped.subscriptionId);
req.throwOn(404, core_1.ApiError, true, "Not Found:'{$response.body}'");
req.throwOn(422, errorListResponseError_js_1.ErrorListResponseError, true, "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.");
req.authenticate([{ basicAuth: true }]);
return [2 /*return*/, req.callAsJson(delayedCancellationResponse_js_1.delayedCancellationResponseSchema, requestOptions)];
});
});
};
/**
* 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.
*
* @param subscriptionId The Chargify id of the subscription.
* @return Response from the API call
*/
SubscriptionStatusController.prototype.cancelDelayedCancellation = function (subscriptionId, requestOptions) {
return tslib_1.__awaiter(this, void 0, void 0, function () {
var req, mapped;
return tslib_1.__generator(this, function (_a) {
req = this.createRequest('DELETE');
mapped = req.prepareArgs({
subscriptionId: [subscriptionId, (0, schema_js_1.number)()],
});
req.appendTemplatePath(templateObject_8 || (templateObject_8 = tslib_1.__makeTemplateObject(["/subscriptions/", "/delayed_cancel.json"], ["/subscriptions/", "/delayed_cancel.json"])), mapped.subscriptionId);
req.throwOn(404, core_1.ApiError, true, "Not Found:'{$response.body}'");
req.authenticate([{ basicAuth: true }]);
return [2 /*return*/, req.callAsJson(delayedCancellationResponse_js_1.delayedCancellationResponseSchema, requestOptions)];
});
});
};
/**
* Cancels the active dunning process for a subscription and sets it to active.
*
* @param subscriptionId The Chargify id of the subscription.
* @return Response from the API call
*/
SubscriptionStatusController.prototype.cancelDunning = function (subscriptionId, requestOptions) {
return tslib_1.__awaiter(this, void 0, void 0, function () {
var req, mapped;
return tslib_1.__generator(this, function (_a) {
req = this.createRequest('POST');
mapped = req.prepareArgs({
subscriptionId: [subscriptionId, (0, schema_js_1.number)()],
});
req.appendTemplatePath(templateObject_9 || (templateObject_9 = tslib_1.__makeTemplateObject(["/subscriptions/", "/cancel_dunning.json"], ["/subscriptions/", "/cancel_dunning.json"])), mapped.subscriptionId);
req.throwOn(422, errorListResponseError_js_1.ErrorListResponseError, true, "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.");
req.authenticate([{ basicAuth: true }]);
return [2 /*return*/, req.callAsJson(subscriptionResponse_js_1.subscriptionResponseSchema, requestOptions)];
});
});
};
/**
* 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 our documentation [here](https://maxio.zendesk.
* com/hc/en-us/articles/24252493695757-Subscriber-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. This method
* allows you to preview data, but does not log any changes against a subscription.
*
* @param subscriptionId The Chargify id of the subscription.
* @param body
* @return Response from the API call
*/
SubscriptionStatusController.prototype.previewRenewal = function (subscriptionId, body, requestOptions) {
return tslib_1.__awaiter(this, void 0, void 0, function () {
var req, mapped;
return tslib_1.__generator(this, function (_a) {
req = this.createRequest('POST');
mapped = req.prepareArgs({
subscriptionId: [subscriptionId, (0, schema_js_1.number)()],
body: [body, (0, schema_js_1.optional)(renewalPreviewRequest_js_1.renewalPreviewRequestSchema)],
});
req.header('Content-Type', 'application/json');
req.json(mapped.body);
req.appendTemplatePath(templateObject_10 || (templateObject_10 = tslib_1.__makeTemplateObject(["/subscriptions/", "/renewals/preview.json"], ["/subscriptions/", "/renewals/preview.json"])), mapped.subscriptionId);
req.throwOn(422, errorListResponseError_js_1.ErrorListResponseError, true, "HTTP Response Not OK. Status code: {$statusCode}. Response: '{$response.body}'.");
req.authenticate([{ basicAuth: true }]);
return [2 /*return*/, req.callAsJson(renewalPreviewResponse_js_1.renewalPreviewResponseSchema, requestOptions)];
});
});
};
return SubscriptionStatusController;
}(baseController_js_1.BaseController));
exports.SubscriptionStatusController = SubscriptionStatusController;
var templateObject_1, templateObject_2, templateObject_3, templateObject_4, templateObject_5, templateObject_6, templateObject_7, templateObject_8, templateObject_9, templateObject_10;
//# sourceMappingURL=subscriptionStatusController.js.map