Subscription Lifecycle

This page explains the public Subscription objects, status values, and the action a merchant should take.

Use Subscription status to control customer access, Invoice status for billing facts, and Payment Order status for the collection result. Browser returns and Operation success are not substitutes for these object states.

Object Model

Merchant Customer 1 ── N Subscription
Plan              1 ── N Subscription
Checkout Session  1 ── 1 Subscription
Subscription      1 ── N Invoice
Invoice           1 ── N Payment Attempt
Invoice           1 ── 0..1 Payment Order

Object	Merchant meaning
Merchant Customer	Your customer, identified by stable merchantCustomerNo. There is no separate Customer API.
Plan	Price, currency, and billing interval used for new Subscriptions.
Checkout Session	One hosted checkout attempt that creates a real Subscription initially in PENDING_CHECKOUT.
Subscription	The continuing contract used to decide whether access is active.
Invoice	The billing fact for a Subscription period.
Payment Attempt	One attempt to collect an Invoice.
Payment Order	The payment result object associated with a paid Invoice.

Persist platform identifiers returned by creation and events. Current list APIs do not support lookup by every merchant-side identifier.

Plan Status

Value	Name	Meaning
0	UNKNOWN	Do not create a new Subscription.
1	CREATING	Creation is in progress.
2	ACTIVE	May be used to create Checkout Sessions.
3	ARCHIVED	Cannot be used for new Checkout Sessions. Existing Subscriptions are not canceled.
4	CREATE_FAILED	Creation failed.
5	CHANNEL_UNKNOWN	The processing result is unresolved; query or contact support.

Archiving a Plan also triggers closure of its unfinished Checkout Links. Stop presenting previously issued checkoutUrl values after archive. This does not cancel established Subscriptions.

Updating a Plan changes only name, description, and metadataJson. The update request requires name. Omitting description or sending an empty string keeps the old value. Omitting metadataJson or sending an empty string also keeps the old value; send the string "{}" to replace metadata with an empty object.

Checkout Session Status

Value	Name	Meaning
0	UNKNOWN	Session state is unknown.
1	CREATED	The hosted link was created.
2	REDIRECTED	Reserved; not currently a stable observable state.
3	VERIFYING	DEEPayment received a completion signal and is verifying the result.
4	COMPLETED	Checkout was verified. Confirm the Subscription state before granting access.
5	FAILED	Checkout failed.
6	EXPIRED	Reserved; the current flow does not guarantee this state is written.

Use the response expiresAt as the DEEPayment Session validity deadline. Do not redirect after that time. The request does not allow merchants to customize this value.

linkStatus values are UNKNOWN(0), ENABLED(1), DISABLING(2), DISABLED(3), and DISABLE_FAILED(4). Do not redirect to a disabled link.

Subscription Status

Value	Name	Merchant action
0	UNKNOWN	Do not grant access; query again.
1	PENDING_CHECKOUT	Wait for the customer to complete checkout.
2	ACTIVATING	Confirmation is in progress; do not grant access early.
3	ACTIVE	Grant normal Subscription access.
4	PAST_DUE	Apply your grace-period policy and inspect current Invoices.
5	UNPAID	Stop or restrict normal access.
6	CANCELED	Stop Subscription access.
7	FAILED	Subscription creation failed.
8	TRIALING	Reserved status. Merchants cannot actively create it and must not grant access based on it.

Only ACTIVE is the current positive access state. The browser return, a completed Checkout Session, or operation=SUCCEEDED alone does not grant access.

Subscription query and list responses include statusVersion. The status and version come from the same snapshot. Compare versions only within the same subscriptionNo.

Invoice Status

Value	Name	Meaning
0	UNKNOWN	Billing state is unknown.
1	DRAFT	Draft billing fact.
2	OPEN	Issued and awaiting payment.
3	PAID	The Invoice is paid.
4	VOID	The Invoice is void.
5	UNCOLLECTIBLE	The Invoice cannot be collected.
6	PAYMENT_FAILED	The current Invoice collection failed.

Payment Attempt Status

Value	Name	Meaning
0	UNKNOWN	Attempt state is unknown.
1	PENDING	Waiting for processing.
2	PROCESSING	Collection is in progress.
3	SUCCEEDED	This collection attempt succeeded.
4	FAILED	This attempt failed; inspect the current Invoice and Subscription states.
5	ACTION_REQUIRED	Additional customer action is required.
6	CANCELED	This attempt was canceled.

Payment Order

Order value	Name	Meaning
0	UNKNOWN	Unknown.
1	CREATED	Order was created.
2	PAYING	Payment is processing.
3	SUCCESS	Payment succeeded.
11	FAILED	Payment failed.
12	EXPIRED	Reserved; current channel results may be normalized to failure.
13	CANCELED	Reserved; current channel results may be normalized to failure.
14	EXCEPTION	The platform must handle an exception.

An invoice.paid event means the Invoice is paid and linked to a successful Payment Order. Settlement status is not exposed by the current Subscription API, so these payment states must not be used as settlement confirmation.

Operation Status

Create and change APIs may return an Operation inside an HTTP 200 response.

Value	Name	Meaning
0	UNKNOWN	Unknown Operation state.
1	PENDING	Waiting to execute.
2	RUNNING	Execution is in progress.
3	SUCCEEDED	The Operation is confirmed successful.
4	FAILED	The Operation is confirmed failed.
5	CHANNEL_UNKNOWN	The processing result is unknown. Do not create a replacement object.

HTTP status describes the API response; Operation status describes an already-recorded side effect. HTTP 200 does not make a FAILED or CHANNEL_UNKNOWN Operation successful.

Cancellation

The merchant action is “cancel the Subscription.” The request contains only an optional reason; end-of-period cancellation is not supported.

The cancel request is asynchronous in business meaning: keep the current access decision until the Subscription is confirmed as CANCELED by the response, a signed event, or a query. Once confirmed, stop access immediately rather than keeping it until currentPeriodEnd. Cancellation does not refund or reverse historical billing objects.

List Query Rules

All lists default to page=1, pageSize=20, and accept at most 100 items per page. All times use Unix milliseconds.

List	Supported business filters
Plans	status
Subscriptions	merchantCustomerNo, planNo, merchantPlanNo, status
Invoices	subscriptionNo, merchantSubscriptionNo, status
Payment Orders	merchantCustomerNo, subscriptionNo, merchantSubscriptionNo

Subscription and Payment Order lists require both startTime and endTime when no owner filter is provided. The range cannot exceed 90 days.

Payment Order pagination currently uses candidate Invoices. A page may therefore contain fewer orders than pageSize, or even no orders while paging.total > 0. Continue according to paging.page and paging.totalPages; do not stop because orders.length is short.