Externally-Managed Subscriptions [Beta]
Beta
Please note that it is a Beta phase.
The lifecycle of externally-managed subscriptions [EMS] is outside of Cleengâs control. Itâs controlled by external parties, such as telcos and direct carriers, external payment gateways, mobile and TV apps.
Synchronize Externally-Managed Subscriptions
Cleeng harmonizes different platforms with API framework for synchronizing externally-managed subscriptions.
An external system may be directly integrated with Cleeng API, but a more common case is when a connector acts as a proxy between an external system and Cleeng API and synchronizes externally-managed purchases.
Once the accounts and payments are in sync, the endpoints below allow you to keep subscription up to date with the events taking place in the external system (e.g. inform about status changes such as new payment, refund, renewal or termination).
Create Externally-Managed Subscription
You can create externally-managed subscriptions with Create subscription endpoint (POST /3.1/subscriptions). It allows you to create subscriptions with provided captured payment.
Important Points
- External ID is required
- Payment method must be provided and must be configured for externally-managed subscriptions (EMS)
- Subscription can be created with or without payment
- When a subscription is created with payment - payment methods must match (payment method ID from create payment and create subscription must be the same)
- When expiration date is not provided, it will be calculated from offer period
- A subscription can be created in trial state
- An offer must be active
- External properties can be provided
Update Externally-Managed Subscription
You can update externally-managed subscriptions (including terminating them) with Update subscription endpoint (PATCH /3.1/subscriptions/{subscriptionId}).
Important Points
- Subscription status can be changed
- Subscription can be: cancelled (stopped), active, terminated
- Subscription can be extended (expiration date can be changed)
- It is a different process than subscription renewal - changed expiration date will not be treated as a new period (renewal), but as an extension
- Subscription trial status can be converted when it was created in trial
- External properties can be updated
List Externally-Managed Subscriptions
You can retrieve externally-managed subscriptions that match the specified criteria with the List subscriptions endpoint (GET /3.1/subscriptions).
Renew Externally-Managed Subscription
You can renew externally-managed subscriptions with the Renew subscription endpoint (POST /3.1/subscriptions/{subscriptionId}/renew).
Important Points
- Subscription can be renewed with and without payment
- Payment methods must match between payment and subscription
- Only captured payments can be used
- When expiration date is not provided, it will be calculated from offer
- Terminated subscription canât be renewed
- Only active and stopped subscriptions can be renewed
Transfer Externally-Managed Subscription
You can transfer externally-managed subscriptions with the Transfer subscription endpoint (POST /3.1/subscriptions/{subscriptionId}/transfer).
Subscription is transferred if there is already an active subscription in Cleeng that belongs to a customer with a different email address. Then a new subscription is created for the "new customer" (the one using the new email address) and the subscription assigned to the "old customer" (the one using the old email address) is terminated.
Important Points
- Transfer subscription endpoint doesnât check geo-restrictions from an offer
- Offer from subscription can be inactive
- Only active and stopped subscriptions can be transferred
- Terminated subscription will be rejected
Revive Externally-Managed Subscription
Some external sources allow you to reactivate previously terminated subscriptions and keep their subscriptionId
. In Cleeng, the revive process involves creating a new externally-managed subscription with a new subscriptionId
.
You can revive externally-managed subscriptions with the Revive subscription endpoint (POST /3.1/subscriptions/{subscriptionId}/revive).
Note: You can only revive terminated subscriptions.
A terminated externally-managed subscription is revived by creating a new subscription based on the terminated one.
The data is copied from the terminated subscription (e.g. original purchase date, payment details), however, the old expiration date will be overridden with a new one.
Important Points
- Expiration date in the future has to be provided
- Subscription to inactive offer canât be revived
- Subscription can be revived only once
- When subscription has already been revived or transferred, it cannot be revived again
Subscription Upgrade/Downgrade [EMS]
Externally-managed subscriptions can be changed thanks to the "Subscription Switch" feature. Subscription switches (upgrades and downgrades) for externally-managed subscriptions are limited to the following algorithms:
You can use the Switch subscription endpoint (POST /3.1/subscription_switches) to request upgrade or downgrade of an externally-managed subscription.
Switching an externally-managed subscription is a multi-step process:
Step 1: Request new subscription switch
Endpoint: Swith subscription (POST /3.1/subscription_switches)
- A new
in progress
switch will be created
Step 2: [Optional] Create payment for subscription
Endpoint: Create a payment for externally-managed purchase (POST /3.1/payments)
- A new payment will be created with payment operation
offer-switch
To register payment for an externally-managed subscription switch (upgrade or downgrade), the switch must be in inprogress
status. Then calling Create a payment (POST /3.1/payments) endpoint will create payment with proper payment operation (offer-switch
). After registering payment for the switch, a connector should finalize the switch.
â Note: Registering payment for an externally-managed subscription switch will not automatically finalize the switch.
Step 3: Finalize switch
Endpoint: Update switch (PATCH /3.1/subscription_switches/{subscriptionSwitchId})
- Changes status to
finished
Important Points
- Subscription upgrade and downgrade configuration is not required (configuration of what offer should switch to what offer)
- All switches between offers are allowed
- Subscription upgrade/downgrade doesnât change subscription lifecycle state
- It will not extend subscription
- External source integration needs to handle subscription lifecycle
- To register payment for subscription switch,
inprogress
switch has to exist
- This will not automatically finalize switch
Cancel a Switch [EMS]
While a switch is in inprogress
status, a customer can still cancel it, as inprogress
is the status when a switch is being processed. You can use the Update switch endpoint (PATCH /3.1/subscription_switches/{switchId}) to cancel an inprogress
switch for an externally-managed subscription.
Recurring Billing [EMS]
Webhooks [EMS]
Externally-managed subscriptions cannot trigger subscriptionReadyFor*
webhooks:
- subscriptionReadyForPaymentAuthorisation,
- subscriptionReadyForPaymentCapture,
- subscriptionReadyForTermination
If subscribed, externally-managed subscriptions will trigger subscription-related webhooks such as:
- subscriptionCreated
- subscriptionTerminated
- subscriptionRenewed
- paymentRefunded
- transactionCreated
- paymentRejected
Dunning Actions Settings [EMS]
Dunning Actions Settings in Cleeng cannot be created for externally-managed subscriptions.
Updated about 1 month ago