Create subscription

Use this endpoint to create externally-managed subscriptions - subscriptions whose lifecycle is managed outside of Cleeng.

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 events (previously called live pay-per-view), or one-time purchase (previously called TVOD). (For more information on offers, see What is a Cleeng offer?).

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Response description

ResponseTypeDescription
subscriptionIdintegerSubscription identifier in Cleeng.
publisherIdintegerThe identifier of publisher in Cleeng.
customerIdintegerThe identifier of Cleeng customer.
statusstringThe current status of a subscription. Allowed values: active, stopped, terminated, paused.
dateFromintegerStart of a subscription period (in UNIX timestamp format).
dateTointegerEnd of a subscription period (in UNIX timestamp format).
subscriptionExternalIdstringThe external identifier of a subscription.
(For Cleeng-managed subscriptions this will be filled with ID generated by Cleeng.)
offerIdstringThe identifier of Cleeng offer, e.g. S123123123_US.
paymentCountrystringThe country of the last payment.
ipAddressstringThe last IP address of a customer.
inTrialbooleanSubscription trial status.
couponCodestringApplied coupon code.
coupondeprecatedobjectAn object with discountRate and usageLeft properties. These fields are retained only for payload consistency and backward compatibility, but they do not provide valid values.
-discountRatenumberOffer discount, e.g. 0.1 means 10% discount. Allowed values: 0.01 - 1.
-usageLeftintegerThe number of times left that a customer can enter the coupon code.
pendingSwitchIdstringThe 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).
paymentMethodIdintegerThe identifier of the payment method, provided by Cleeng.
paymentDetailsIdintegerThe identifier of Cleeng payment details connected to Cleeng customer. Here: null.
nextPaymentActionstringA kind of the next payment action, either authorisation or capture.
nextPaymentActionDateintegerThe date of the next payment action (authorisation or capture) (in UNIX timestamp format).
externalPropertiesobjectExternal properties that can be used to store additional metadata from the external system, ex. partnerID, externalProductId, partnerCode, etc.
isExternallyManagedbooleanWhether a subscription is externally-managed or not.
latestPaymentExternalIdstringThe identifier from external payment gateway system for the latest payment associated with a given subscription.
replacedByAn 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
integerSubscription identifier in Cleeng. The identifier of a new subscription (transferred or revived).
  • reason
stringReason for subscription replacement: transfer if a subscription has been transferred or revival if a subscription has been revived.
  • date
integerThe date of subscription replacement (in UNIX timestamp format).
originatedFromAn object with properties that refer to processes where one subscription replaces another one.
  • subscriptionId
integerSubscription identifier in Cleeng. The identifier of the previous subscription - the one that has been transferred or revived.
  • reason
stringReason for subscription replacement: transfer if a subscription has been transferred or revival if a subscription has been revived.
  • date
integerThe date of subscription replacement (in UNIX timestamp format).
sourcestringA 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.
renewalCycleAn 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
stringA 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).

terminationTypestringIndicates 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
pauseobjectReturns information about subscription pause.
null value is returned when there is no scheduled pause or subscription was resumed from pause.
  • requestedAt
integerThe date when subscription pause was requested (in UNIX timestamp format).
  • pauseDate
integerThe 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
integerThe date of subscription scheduled resume after a pause (in UNIX timestamp format).
  • failedResumes
array of integers/timestampsThe list of failed attempts to resume subscription after a pause.
An empty array is returned if there were no failed attempts.
gracePeriodEndDateinteger (Unix timestamp)The date and time when the active grace period ends, expressed as a Unix timestamp (seconds since epoch). Returns null when the subscription is not currently in a grace period.

Body Params
int32
required

The identifier of Cleeng customer. Minimum: 100000000, maximum: 999999999.

string
required

The identifier of Cleeng offer. It must be offerId of a subscription offer.

int32
required

The identifier of the payment method configured for externally-managed subscriptions; provided by Cleeng.

string
required

The external identifier of a subscription. The identifier must be unique for a given payment method (i.e. you can't have two identical identifiers for the same payment method).

int32

Expiration time in UNIX timestamp format. If not provided, the subscription will have its expiration date set in the following way: it will be pushed from the current time by offer cycle length.

boolean

Subscription trial status. The default value is false.

externalProperties
object

Any properties of a subscription.

int32

The identifier of Cleeng payment. (Payment must be created with the same paymentMethodId as specified here).

Responses

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json