Custom subscription platform

ProsperStack allows for custom integration with subscription platforms that are not natively supported. When using a custom integration, your application will be responsible for processing cancellations, fulfilling accepted offers and making any other subscription modifications.

Integrating the cancellation flow

Embedding the flow

Embedding the cancellation flow with a custom subscription platform is largely the same as with a supported subscription platform, but instead of supplying a subscription platform subscription ID, you'll provide ProsperStack with basic details about the subscription being canceled.

Details must include the subscriber's internalId, name and email. Optionally include subscription context such as mrr, currency and trial, plus custom properties.

See the flow embed documentation for details on the required properties.

Handling cancellations

With a custom integration, ProsperStack records the customer's actions but does not make the corresponding change in your billing system.

When a cancellation session is complete, the response from the ProsperStack library contains a status property which indicates what your application should do:

Status	Action
canceled	Cancel the subscription.
saved	Apply the accepted offer found in flowSession.offer_accepted.
deflected	No subscription change required.
incomplete	No subscription change required.

See the flow embed documentation for details on the response object.

Handling offers

When you create an offer, you'll specify details about the offer that will be returned as part of the flow response payload. You can use these details to process the offer and apply it to your customer's subscription.

Offer details

The accepted offer is available at flowSession.offer_accepted. Its details object contains a type property that identifies the payload shape.

The details returned for offer types commonly used with a custom integration include:

Coupons

• coupon_type: string — percentage or fixed
• amount_off: string — The discount amount to apply, either as a percentage for percentage type coupons or dollars for fixed type coupons
• duration: string — once, forever or repeating
• months: number | null — If duration is repeating, the number of months the coupon should be valid
• platform_coupon_id: string — The coupon's ID or code from your subscription platform, if provided

Change plan

• platform_plan_id: string — The plan ID to switch the customer's subscription to
• prorate: boolean — Whether or not to prorate charges or credits when changing plans

Trial extension

• days: number — The number of days to extend the trial

Pause subscription

• interval: string — day, week, month, indefinitely or billing_cycle
• interval_count: number — The number of intervals to pause the subscription for
• pause_at: string — immediately or period_end

Offer metadata

In addition to the offer details, you can also specify metadata when creating or editing an offer. This metadata will be returned in the flow response payload along with the offer details.

You can use offer metadata to pass any arbitrary data back to your application along with an accepted offer.

Pause subscription and change frequency offers can also include metadata for each option. When a customer selects an option, use its returned metadata to distinguish between the configured pause durations or billing frequencies.

Complete integration example

For a complete example of handling the result from a cancellation flow with a custom billing integration, see the flow embed documentation.

API reference

For full details of the offer payload, see the API reference documentation.