Create subscription

Use this endpoint to create externally-managed subscriptions. The life cycle of externally-managed subscriptions is managed outside of Cleeng so it is up to a publisher to notify Cleeng about subscription status changes (e.g. subscription termination).

You can create multiple subscriptions for the same offer and customer with this endpoint. But the endpoint prevents duplicate subscriptions with the same external ID and source. It only allows new subscriptions if there isn't already an active subscription from the same source and with the same external ID.

** Important**
This endpoint can only be used for creating subscriptions (offers with recurring payments). It cannot be used for one-time payment offers such as passes, live pay-per-view, or TVOD. (For more information on offers, see What is a Cleeng offer?).

Response description

Response

Type

Description

subscriptionId

integer

Subscription identifier in Cleeng.

publisherId

integer

The identifier of publisher in Cleeng.

customerId

integer

The identifier of Cleeng customer.

status

string

The current status of a subscription. Allowed values: active, stopped, terminated, paused.

dateFrom

integer

Start of a subscription period (in UNIX timestamp format).

dateTo

integer

End of a subscription period (in UNIX timestamp format).

subscriptionExternalId

string

The external identifier of a subscription.
(For Cleeng-managed subscriptions this will be filled with ID generated by Cleeng.)

offerId

string

The identifier of Cleeng offer, e.g. S123123123_US.

paymentCountry

string

The country of the last payment.

ipAddress

string

The last IP address of a customer.

inTrial

boolean

Subscription trial status.

couponCode

string

Applied coupon code.

coupon deprecated

object

An object with discountRate and usageLeft properties. These fields are retained only for payload consistency and backward compatibility, but they do not provide valid values.

-discountRate

number

Offer discount, e.g. 0.1 means 10% discount. Allowed values: 0.01 - 1.

-usageLeft

integer

The number of times left that a customer can enter the coupon code.

pendingSwitchId

string

The identifier of a subscription switch (upgrade or downgrade) with status pending (the status of the switch between the subscription switch request and the actual switch processing).

paymentMethodId

integer

The identifier of the payment method, provided by Cleeng.

paymentDetailsId

integer

The identifier of Cleeng payment details connected to Cleeng customer. Here: null.

nextPaymentAction

string

A kind of the next payment action, either authorisation or capture.

nextPaymentActionDate

integer

The date of the next payment action (authorisation or capture) (in UNIX timestamp format).

externalProperties

object

External properties that can be used to store additional metadata from the external system, ex. partnerID, externalProductId, partnerCode, etc.

isExternallyManaged

boolean

Whether a subscription is externally-managed or not.

latestPaymentExternalId

string

The identifier from external payment gateway system for the latest payment associated with a given subscription.

replacedBy

An object with properties that refer to processes where one subscription replaces another one. Subscription resource payload will be returned in response with non-empty replacedBy property after a subscription revival and transfer.

  • subscriptionId

integer

Subscription identifier in Cleeng. The identifier of a new subscription (transferred or revived).

  • reason

string

Reason for subscription replacement: transfer if a subscription has been transferred or revival if a subscription has been revived.

  • date

integer

The date of subscription replacement (in UNIX timestamp format).

originatedFrom

An object with properties that refer to processes where one subscription replaces another one.

  • subscriptionId

integer

Subscription identifier in Cleeng. The identifier of the previous subscription - the one that has been transferred or revived.

  • reason

string

Reason for subscription replacement: transfer if a subscription has been transferred or revival if a subscription has been revived.

  • date

integer

The date of subscription replacement (in UNIX timestamp format).

source

string

A system that initiates and manages subscription lifecycle and/or payments. It can be an internal source - cleeng - for Cleeng-managed subscriptions or an external source - e.g. samsung - for externally-managed subscriptions.

renewalCycle

An object with properties that refer to a subscription renewal cycle.

  • completed

integer

The number of completed renewal cycles - it specifies how many times a given subscription has been renewed.

At subscription creation, the number defaults to zero and is further increased by one after each subscription renewal, including uses of 100% coupons.

  • unit

string

A unit of a subscription renewal cycle, one of day, week, month, year, season.

  • amount

integer

The number of subscription renewal cycle units. The value is always >= 1.

For example, for a monthly subscription it is 1 (unit / amount: month / 1), for a 6-month subscription it is 6 (unit / amount: month / 6).

terminationType

string

Indicates termination type.
Possible values:

  • userCancel - a subscription was first canceled by a user and then terminated
  • transferCancel - an externally-managed subscription was transferred to another user (another email address)
  • publisherCancel - a subscription was terminated via Terminate subscription API
  • finished - a Cleeng-managed pass to which access already expired
  • paymentCancel - a subscription was terminated after there was no recurring payment on time
  • null - if a subscription/ Cleeng-managed pass is not terminated

pause

object

Returns information about subscription pause.
null value is returned when there is no scheduled pause or subscription was resumed from pause.

  • requestedAt

integer

The date when subscription pause was requested (in UNIX timestamp format).

  • pauseDate

integer

The date when the subscription pause starts (in UNIX timestamp format).
The date can be:

  • in the future - for a scheduled subscription pause
  • in the past - for a subscription pause that is in progress.
  • resumeDate

integer

The date of subscription scheduled resume after a pause (in UNIX timestamp format).

  • failedResumes

array of integers/timestamps

The list of failed attempts to resume subscription after a pause.
An empty array is returned if there were no failed attempts.


Language
Credentials
Header
Click Try It! to start a request and see the response here!