The Subscription Object

Attributes

This object represents a subscription that can be associated with a customer.

string

The unique identifier of the subscription (MAX 64 ; MIN 36).Example: 7304911d-5df9-429e-8488-ad41abea1a4c

string

The subscription name (MAX 255; MIN 3).Example: sub_001

string

The subscription description (MAX 255; MIN 3).Example: Servicio de streaming

string

The unique identifier of the account that will have the subscription plan available to use (MAX 64 ; MIN 36).Example: 2404911d-5df9-429e-8488-ad41abea1a4b

string

Identification of the subscription plan (MAX 255; MIN 3).Example: 001_marzo_23

string

Statement descriptor shown on the cardholder’s bank statement (MAX 255). When set, it is propagated to every rebill payment generated by the subscription engine. Length and formatting limits vary by provider; see Statement descriptor on recurring payments.Example: ACME SUBSCRIPTION

string

The subscription’s country.Example: CO

enum

Status of the subscription.Possible values:

CREATED = Transitory status while the initial payment hasn’t been processed yet. Only occurs when the subscription is created with initial_payment_validation: true; it transitions to ACTIVE once the first payment succeeds (or to CANCELED if it fails and retries are exhausted).
ACTIVE = The subscription has been created with an associated customer and is already active.
TRIALING = The subscription is inside a plan’s leading trial phase (see plan_id/current_phase). Transitions to ACTIVE automatically once the trial ends — this is webhooked like any other status change.
PAUSED = The subscription has been paused and can be reactivated.
COMPLETED = The subscription is completed because it reached the end date and time.
CANCELED = Subscription canceled. See cancellation_source for what triggered it.

enum

What caused the subscription to be canceled. Only set once the subscription reaches CANCELED; null otherwise.Possible values:

MERCHANT = You canceled the subscription, through Cancel Subscription or the dashboard.
SYSTEM = Yuno canceled the subscription automatically. This includes a subscription created with initial_payment_validation: true whose first payment did not succeed.
PLAN_CHANGE = The subscription was replaced as part of a plan change. A new subscription continues the customer’s billing under the new plan.
RETRIES_EXHAUSTED = Retries for a billing cycle ended without a successful payment while the subscription had retries.cancel_on_exhausted_retries set to true. See Retries.

Treat this field as open-ended. New values can be introduced as Yuno adds cancellation behaviors, so handle an unrecognized value gracefully rather than switching exhaustively over the list above. RETRIES_EXHAUSTED is the most recent addition.

string

The unique identifier of the plan this subscription was created from, if any (MAX 64; MIN 36). Only present when the subscription is linked to a plan — absent (not null) for subscriptions created with a raw amount/frequency instead of a plan_id.Example: 00000000-0000-4000-8000-000000000001

Timestamp

When the subscription is linked to a plan, the moment the plan was attached — at creation from a plan, migration onto a plan, or a plan change. Only present on plan-linked subscriptions.

string

When this subscription was created by a plan change (switching an existing subscription to a different plan), this is the id of the subscription it replaced. Only present in that case.Scheduled changes made with the plan_change object on Update Subscription apply in place and never set this field.

enum

Which phase of the linked plan’s trial ladder the subscription is currently in. Only present on plan-linked subscriptions. Absent as well when the subscription was created by a plan change with skip_trial: true — that subscription is plan-linked and its plan has phases, but it never enters the ladder.Possible values: TRIAL, REGULAR.

array of objects

The plan’s leading TRIAL phases, snapshotted for this subscriber’s country at creation time. Only present on plan-linked subscriptions whose plan has phases. Absent as well when the subscription was created by a plan change with skip_trial: true — that subscription is plan-linked and its plan has phases, but it never enters the ladder.

The terminal REGULAR phase is never included here. Its price isn’t pinned at creation — it resolves from the plan at every billing, so plan price edits reach running subscriptions. When current_phase is REGULAR, the ladder is exhausted and the subscription bills the plan’s regular price; there’s no corresponding row in this array for that.

Show properties

int

enum

Always TRIAL — see the note above.

string

Mirrors the phase’s own required name.

object

Show properties

string

number

object

Show properties

enum

DAY, WEEK, MONTH, or YEAR.

int

object

Specifies the subscription amount object, with the value and currency.

Show properties

enum

The currency used to make the payment (MAX 3; MIN 3; ISO 4217).Possible enum values: Check the Country reference.

number

The payment amount (multiple of 0.0001).Example: 12100.00

object

The frequency defined for the payment subscription. If not set, defaults are MONTH for type and 1 for value.

Show properties

enum

The type of interval the subscription will have in time. If not set, always MONTH by default.Possible enum values: DAY, WEEK, MONTH, or YEAR.

int

The value between each interval the subscription will have in time. If not set, always 1 by default.Example: 1

object

Specifies the billing_cycles object.

Show properties

number

Total amount of billing cycles.Example: 10

number

The next billing cycle to be charged — not the cycle currently in progress.Subscriptions are billed in advance: the charge for a cycle fires at the start of the period it pays for, and the counter moves on as soon as that charge is dispatched. While the subscriber is inside the period paid for by cycle N, this field therefore already reads N + 1. The cycle in progress is current - 1. One exception: the counter stops on the last cycle. Once current reaches billing_cycles.total — or availability.finish_at passes — the subscription is marked COMPLETED and current is frozen at total for the whole of that final period, so there the cycle in progress is current, not current - 1.A subscription created with a two-cycle trial reads current: 2 for the whole of the first trial period, and current: 3 during the second — the trial is still running even though current has passed the trial cycle count. current_period_start and current_period_end tell you when the current period runs; they do not tell you whether the subscription is still in its trial. To locate the trial, compare the cycle in progress (current - 1) against trial_period.billing_cycles — legacy trial_period subscriptions stay ACTIVE and carry no current_phase while trialing.Because the counter advances when a charge is dispatched rather than when it succeeds, a failed cycle never rolls it back — current has already moved on before the first retry runs, and it stays there whether or not the retries eventually collect.The first cycle is the other exception: when initial_payment_validation is true, its counter moves only once that first charge succeeds. While the charge is pending or being retried, current stays 1; if it is never collected the subscription is cancelled with current still 1. From the second cycle onward the dispatch-time rule applies.Example: 2

Timestamp

The date of the next payment for the subscription. Always present. When current_period_end is returned it is this same instant.Example: 2023-02-16T20:00:00.786342Z

Timestamp

The start of the billing period currently in progress — the timestamp of that cycle’s first (non-retry) payment attempt. Zero-amount cycles, such as a free trial phase, open a period the same way even though no charge is sent.Returned only by Retrieve Subscription — GET /v1/subscriptions/{subscription_id} — and only once the first cycle has been charged. Every other response omits the pair regardless of how many cycles have been charged: create, update, pause, resume, cancel and retry. It is never populated on subscription list responses or on webhook payloads.On REST responses the keys are omitted entirely when unresolved; webhook payloads may carry them as null. Treat null and missing as the same thing.Example: 2023-01-16T20:00:00.912480Z

Timestamp

The end of the billing period currently in progress, which is also when the next charge is scheduled. Always equal to billing_cycles.next_at.This pair describes the period the subscription is scheduled into, not one that is necessarily paid for: if a cycle’s charge failed and its retries are still running, the window has already moved to the period that charge was meant to open.Absent under the same conditions as current_period_start; the two are always present or absent together.These values are only meaningful while the subscription is live. A CANCELED or COMPLETED subscription keeps whatever window it last had; current_period_end then refers to a charge that will not be taken, and on a completed fixed-term subscription it can fall before current_period_start.Example: 2023-02-16T20:00:00.786342Z

object

[Optional] Specifies the billing_date object. Mutually exclusive with the frequency object.

Show properties

number

The type of billing_date the subscription will have in time. PREPAID, POSTDATE, DAY. If not set, the creation date for the plan will be set by default.Example: PLAN_CREATION_DATE

number

The day of the month to charge the subscription if the type is set to DAY. Always 1 by default.Example: 2

object

Specifies the customer_payer object.

Show properties

string

The unique identifier of the customer (MAX 255; MIN 3).Example: 3t04911d-5df9-429e-8488-ad41abea1a2c

object

Specifies the payment_method object.

Show properties

enum

Type of the payment method.Possible enum values: CARD

string

The one-time use payment method token provided by Yuno SDK (MAX 64; MIN 36).Example: 9104911d-5df9-429e-8488-ad41abea1a4b

string

The vaulted token of the stored payment method (MAX: 64; MIN: 36).Example: 6104911d-5df9-429e-8488-ad41abea1a4b

object

Specifies the card object.

Show properties

boolean

Using amount = 0 and verify = true, you can verify the user’s card without authorizing a real amount.Possible values: true or false.

object

Specifies the card_data object.

Show properties

string

Card’s number without any separators (MAX 19; MIN 8) - only available for PCI certified merchants.Example: 4507990000000010

number

Card’s expiration month - MM (MAX 2; MIN 2) - only available for PCI certified merchants.Example: 10

number

Card’s expiration year - YYYY (MAX 4; MIN 4) - only available for PCI certified merchants.Example: 2025

number

Card’s security code (MAX 4; MIN 3) - only available for PCI certified merchants.Example: 123

string

Cardholder’s full name as it appears on the card (MAX 26; MIN 3) - only available for PCI certified merchants.Example: JOHN DOE

object

Specifies the trial_period object.

Show properties

number

Total amount of billing cycles the free_trial should apply to.Example: 1

object

Amount to be discounted for the trial period.

Show properties

string

The currency used to make the trial period. (ISO 4217 MAX 3; MIN 3).Example: COP

number

The trial period amount value (multiple of 0.0001).Example: 10

object

Specifies the availability object. The dates that the subscription will be available. If null the start date will be the day of the creation and it will not have a finish date.

Show properties

Timestamp

The start date that the subscription will be available to use.Example: 2024-01-16T00:00:00.786342Z

Timestamp

The end date until the subscription will be available to use.Example: 2024-05-26T20:00:00.786342Z

object

Specifies the retries object. If we need to retry declined transactions in Yuno and the amount if necessary.

Show properties

bool

If we should retry a payment or not after a first decline. False by default.Example: TRUE

number

The number of retries that the subscription plan will have to completion. The maximum equals your environment’s configured retry schedule length (6 in production). A value above the cap is rejected with 400 (Max retries attempts exceeded). Max: 6Example: 4

string

How the timing of each retry is decided. One of:

DEFAULT — the fixed retry schedule.
SMART — machine-learning-based retry timing, applied from the second retry onward. Available to all accounts.
CUSTOM_SCHEDULE — the per-attempt schedule array you provide.

Treat this field as open-ended. New values can be introduced as Yuno adds retry behaviors, so handle an unrecognized value gracefully rather than switching exhaustively over the list above. SMART is the most recent addition.Example: SMART

bool

When true and a hard decline is detected, retries stop for the current billing cycle only. On its own, the subscription stays ACTIVE and billing advances to the next cycle. If cancel_on_exhausted_retries is also true, the subscription is canceled instead.Example: TRUE

bool

When true, the subscription is canceled once retries for a billing cycle end without a successful payment, instead of advancing to the next cycle. cancellation_source is set to RETRIES_EXHAUSTED and a single SUBSCRIPTION.CANCEL webhook is emitted. Defaults to false. Can be set at creation or changed later via Update Subscription; the cancellation itself is final — see Retries.Example: TRUE

bool

Flag to identify if the subscription should wait for the first payment in order to continue. False by default.Example: false

object

The plan change scheduled for the next billing cycle, or null when none is pending. Schedule one with the plan_change block on PATCH /v1/subscriptions/{id}; undo it with "plan_change": null.A scheduled change is applied to this same subscription — no new subscription is created, and neither previous_subscription_id nor cancellation_source: PLAN_CHANGE is set.

Show properties

string

The identifier of the target plan.

string

The name of the target plan.

string

UPGRADE or DOWNGRADE. A longer billing frequency is an upgrade; on the same frequency, a higher resolved price is an upgrade. Informational only.

string

When the change applies. NEXT_BILLING_CYCLE is the only supported value: the current cycle bills the current plan’s price.

string

What happens when the target plan has phases. START_FROM_REGULAR (default) enters the regular phase directly; HONOR_PHASES enters through the target plan’s phase schedule — which sets status to TRIALING, current_phase to TRIAL, and repopulates billing_phases.

Timestamp

The billing event the change will take effect on — the subscription’s next billing date.

Timestamp

When the change was scheduled.

array of objects

Specifies the metadata array.

Show properties

string

This value serves as a name or identifier for the metadata. Use a descriptive term. (MAX 48; MIN 1).Example: sub_ext_id

string

The information you wish to store within the metadata. (MAX 512; MIN 1).Example: AA001

string

Links this subscription to the initial payment created with the same agreement ID. Used for tracking, reconciliation, and chargeback handling (MAX 255).The value must exactly match the subscription_agreement_id sent in payment_method.detail.card.stored_credentials.subscription_agreement_id on the originating payment.Example: sa_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa

Array of strings

Specifies the payments array.

This array is currently always empty in webhook payloads. Subscribe to payment.* webhooks to track charges. For the subscription’s full charge history (amounts, provider, phase context), use List Subscription Payments instead of this field.

Example: [“5104911d-5df9-229e-8468-bd41abea1a4s”]

Timestamp

Subscription creation date and time (ISO 8601 MAX 27; MIN 27).Example: 2023-12-16T20:46:54.786342Z

Timestamp

Subscription last updated date and time (ISO 8601 MAX 27; MIN 27).Example: 2023-12-16T21:00:54.786342Z

object

Specifies the additional_data object. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

Show properties

object

Specifies the order object.

Show properties

array of object

Specifies the item’s object.

Show properties

string

The unique identifier of the item (MAX 255; MIN 3).Example: 3214

string

The name of the item (MAX 255; MIN 3).Example: iPhone 12 Pro Max

int

The quantity of the item (MAX 999; MIN 1).Example: 1

float

The unit amount of the item (multiple of 0.0001).Example: 550

string

The category of the item (MAX 255; MIN 3).Possible values: Check the Item category list.

string

The brand of the item (MAX 255; MIN 3).Example: Apple

string

The stock keeping unit (SKU) of the item (MAX 255; MIN 3).Example: A2342

string

The manufacture part number of the item (MAX 255; MIN 3).Example: 345621234

Getting Started

Reference

Customers

Network Tokens

Customer Sessions (Enrollment)

Checkout Sessions

Payment Methods (Checkout)

Checkout Builder

Payment Methods (Direct Workflow)

PCI Proxy

Payments

Pre-Debit Notifications

3DS2 Setup

Unreferenced Refunds

Dry-run

Payment Links

Recipients for Marketplace

Sellers (Franchise)

Subscriptions Plans

Subscriptions

Payouts

Organizations

Reports

Installments

AI Caller

Communications Campaigns

Conversion Rate

Banking Connectivity

Webhooks

Attributes

​Attributes

Attributes