Cycle Object

A subscription cycle refers to one specific instance of the subscription plan's action - for e.g. a specific month's billing cycle. The subscription cycle object is generated from the subscription plan object where the subscription behaviour is defined.

Each object has the following structure:

Param	Type	Description
cycleId	String	Cycle ID
planId	String	AppotaPay-generated subscription plan ID
cycleNumber	Integer	Cycle number
currency	Integer	Currency unit
amount	Integer	Amount
attemptCount	Integer	Number of times the recurring action has been attempted for this recurring cycle object.
attemptDetails	Array	Detailed information of each action attempts
attemptDetails.*.attemptNumber	Integer	A numbering that tracks the order of cycle attempts. The first attempt will be 1 and subsequent attempts are dependent on retry configuration
attemptDetails.*.createdAt	String	ISO 8601 timestamp for attempted actions
attemptDetails.*.attemptId	Integer	Attempt ID
attemptDetails.*.type	String	Type of attempt - INITIAL: the first attempt with each cycle - RETRY: attempt with type INITIAL failed, then subsequent retry is set - PAYMENT_LINK: if you use paymentLinkForFailedAttempt while creating a plan, attempts using payment link will have this type - FORCED: if you perform a force cycle through the API we provide
attemptDetails.*.status	String	Attempt status: - PENDING: payment cycle is in progress - SUCCESS: attempt cycle successfully - FAILED: attempt cycle unsuccessfully
attemptDetails.*.nextRetryTime	String	ISO 8601 Estimated timestamp for next retry
scheduledAt	String	Schedule timestampt (format ISO-8601)
status	String	Cycle status: - SCHEDULED: cycle has been initialized and waiting for execution time - PENDING: recurring payment is in progress (cycle cannot be updated) - RETRYING: cycle needs to charge again - FAILED: all attempts/retries configured for the cycle have failed - SUCCEEDED: cycle is charge successfully - CANCELLED: cycle is canceled due to request from merchant
createdAt	String	Cycle creation time (standard format: ISO-8601)
updatedAt	String	Last updated time (standard format: ISO-8601)

Example

{
    "cycleId": "01HRVK2NEYCHVZYJG3CK3HEQMQ",
    "planId": "01HRVJZV0W9NK63SDDXHW04T9H",
    "cycleNumber": 3,
    "currency": "VND",
    "amount": 405100,
    "attemptCount": 5,
    "attemptDetails": [
        {
            "attemptNumber": 4,
            "createdAt": "2024-01-22T18:03:42+07:00",
            "attemptId": "01HRVK5AFCB5EJASJVEK48VD96",
            "type": "FORCED",
            "status": "FAILED",
            "nextRetryTime": null
        },
        {
            "attemptNumber": 2,
            "createdAt": "2024-01-22T18:03:20+07:00",
            "attemptId": "01HRVK5K8V0D7ZGNA6PSQGD1DF",
            "type": "FORCED",
            "status": "FAILED",
            "nextRetryTime": null
        }
    ],
    "scheduledAt": "2024-02-14T16:23:28+07:00",
    "status": "SCHEDULED",
    "createdAt": "2024-01-22T18:01:28+07:00",
    "updatedAt": "2024-01-22T18:03:58+07:00"
}