API Tutorials
WE'RE HIRING!HELP CENTERINTEGRATIONSSTATUS PAGESIGN UP

Externally-Managed Subscriptions [Beta]

Suggest Edits

🚧

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

Dunning Actions Settings [EMS]

Dunning Actions Settings in Cleeng cannot be created for externally-managed subscriptions.

Updated 2 months ago