Subscription

​

Overview

A subscription is an agreement where a customer pays a recurring fee (for example daily, weekly, monthly, quarterly, half-yearly, yearly, or custom) to access a product, service, or content. Key characteristics of subscriptions include:

• Recurring Payments: Customers are billed regularly.
• Continuous Access: Subscribers receive ongoing access to the product or service as long as payments are made.
• Flexibility: Subscriptions may offer options to upgrade, downgrade, or cancel at any time, depending on the provider’s terms.

​

Subscription Data

​

Status

• Incomplete: The subscription was created, but the checkout session was not paid successfully.
• Incomplete Expired: The subscription is incomplete and has been closed because the checkout session expired.
• Active: The subscription is active with no outstanding bills.
• Trialing: The subscription is in a free trial period. No payments have been attempted yet, but the customer has provided payment information.
• Past Due: Payment attempts for renewal have failed, but the subscription remains active and will retry.
• Canceled: The subscription has been terminated.

​

Product & Price

The product represents the service that customer and merchant have agreed upon. The price contains information about the billing cycle and the payment amount to maintain the agreement. Supported recurring intervals are day, week, month, quarter, half_year, year, and custom. Custom intervals use interval_count to define the cycle length in days.

​

Customer

A subscription contains a customer ID, representing the real-world client who agrees to pay periodically for the merchant service. The customer owns the payment instrument used for recurring payments. If a customer deletes the payment instrument associated with the subscription but has other payment instruments available, Clink will use the default payment instrument for renewal.

​

Subscription Management

​

Create a Subscription by API

Use the Create Subscription API to create a subscription directly. The request requires a product, a recurring price, a payment method type, a payment currency, and at least one customer identifier. For CASHAPP, GCASH, you can omit paymentInstrumentId; Clink automatically creates the payment instrument and returns its ID in the response. Other payment methods still require an existing paymentInstrumentId. You can optionally provide billingAddress for the payment instrument and first-invoice tax calculation. The request address takes precedence over the existing payment instrument address, customer billing address, and request IP country. If Clink automatically creates the payment instrument, the address is saved to it. If you provide an existing paymentInstrumentId, the request address is used for the first invoice but does not update that payment instrument. You can also include scheduledPhases when creating a subscription to schedule future plan changes at billing period boundaries. Each phase uses a target priceSnapshotId, quantity, and an effectiveCycle that counts renewals from subscription creation. The subscription response returns remaining scheduledPhases and elapsedCycles, so you can tell how many billing cycles have already passed before the next scheduled change takes effect. Scheduled phases must be ordered by strictly increasing sequence and effectiveCycle, with a maximum of 10 phases. The target price snapshot must support the subscription’s paymentCurrency.

​

Listing and Querying

Subscriptions can be viewed under the Subscriptions tab. By default, subscriptions are listed chronologically based on their creation time. You can filter subscriptions using the following criteria:

• Amount: The monetary value of the product
• Currency: The currency used in the agreement
• Customer ID: The customer ID associated with the subscription
• Created Date: The time period when subscriptions were created
• Status: The current subscription status

​

Subscription Detail

Clicking on any subscription from the list will display its detailed information, including:

• Product & Price
• Customer and the payment instrument
• Invoices and the billing cycle coverage

​

Cancel a Subscription

To cancel a subscription:

1. Go to the Subscriptions tab
2. Locate the subscription using the search function and open the details page
3. Click on the Action button on the top right
4. Select Cancel subscription from the dropdown list
5. Select the reason for cancellation in the popup window
6. Click the OK button

​

Downgrade or Upgrade a Subscription

Use the Preview Subscription Update API to calculate the target plan, proration, tax, discount, and whether the change takes effect immediately. The target price must be a recurring price owned by your merchant account and support the subscription’s payment currency. After reviewing the preview, call the Confirm Subscription Update API with the returned priceSnapshotId. Send the same quantity, promotionCode, immediate, billingCycleAnchor, and prorationBehavior values used in the preview request, including leaving omitted options omitted. The price snapshot does not store these options, and confirmation recalculates the update. Immediate updates may require payment and can return a next action; period-end updates are scheduled for the next billing boundary. If you need to revoke a pending period-end change before it takes effect, call the Cancel Subscription Update API.

​

Update Timing and Billing

Both preview and confirmation accept these optional parameters:

• immediate: true requests an immediate update; false schedules it for the end of the current billing or trial period. Omitted or null lets the system decide. Explicit true requires both current and target prices to use flat_rate pricing. Outside a free trial, the target full-cycle amount (unitAmount multiplied by quantity) must be greater than the current full-cycle amount; immediate downgrades and equal-amount changes are rejected.
• billingCycleAnchor: now starts a new full billing cycle at the update time; unchanged preserves the current period end. Outside a free trial, omitted or null uses unchanged.
• prorationBehavior: always_invoice applies proration; none charges the target plan’s full-cycle amount without credit for unused time on the current plan. Outside a free trial, omitted or null uses always_invoice.

Non-null billingCycleAnchor and prorationBehavior values require an explicit immediate: true. Otherwise, the request is rejected. For immediate updates outside a free trial, the combinations below determine the amount before discounts and tax: Unused-time credit is based on the current plan’s amount after its discount and is capped at the target-plan charge. Excess credit does not generate a refund or customer balance. Applicable discounts and tax are then applied to the amount due. none does not mean that payment is skipped. For an immediate update during a free trial, if the target plan still has trial days remaining after subtracting days already used, leave billingCycleAnchor and prorationBehavior omitted or null. If the update switches directly to paid billing, the effective combination is now + none, and a full cycle of the target plan is charged before discounts and tax. In that case, you may omit the options or explicitly send only those values; conflicting values are rejected. The preview response includes the effective billingCycleAnchor and prorationBehavior for immediate updates outside a free trial, and for trial updates that start paid billing with a positive charge before discounts. These fields are not populated for deferred updates or trial updates without a charge. Use the response to review the result, and retain the original request options when confirming. Customers can still use the customer portal for self-service plan changes when your portal configuration allows it.

​

Invoice

An invoice is generated on every billing cycle for the subscription. Customers can download invoices for expense purposes, proof of payments, etc.

​

Status

• Open: The initial status of an invoice, indicating it is waiting for payment.
• Paid: The bill amount has been received.
• Void: The invoice is closed but unpaid.

​

Invoice Management

Invoices are generated automatically when the service is initially subscribed to or when renewal is triggered. We do not currently support manual invoice creation. Invoices are strongly tied to subscriptions. To view the list of invoices, navigate to the subscription details page and scroll down.