> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Subscriptions

> Automate recurring billing by letting Yuno's engine create, pause, resume, and cancel subscriptions on schedule

Yuno's subscription service lets you manage recurring payments and automate subscription billing for your customers.

> [!NOTE]
>
> **Subscriptions vs Stored Credentials**
>
> * **Subscriptions** (this page): Yuno's recurrence engine. You provide instructions and frequency once, then Yuno automatically sends transactions on your behalf.
> * **Stored Credentials**: You control the recurrence. You're responsible for sending each transaction according to your own schedule. See [Stored Credentials](https://docs.y.uno/docs/payment-features/stored-credentials.md).

## Yuno subscriptions

A subscription in Yuno's environment can go through several stages, starting with its creation status. When a subscription is created, it automatically receives the **CREATED** status. However, it is a transitory status that is active while the payment isn't processed. After that, the subscription will be **ACTIVE** or **CANCELED**, depending on the payment confirmation.

When the payment related to the subscription is confirmed, the subscription status changes to **ACTIVE** — or to **TRIALING** if it starts inside a plan's trial phase, which becomes **ACTIVE** on its own once the trial ends. It remains active while the subscription is within its availability date range and the customer pays the bills. From there it can change to four different statuses:

* **COMPLETED**: The subscription finish date was reached. In this case, the current subscription is terminated, and it is not possible to reactivate it. If your client wants to continue using your product/service using recurring payments, you need to create a new subscription.
* **PAUSED**: At any moment, you can pause the subscription. Use this option in case your customer has delayed a payment, for example. You can always activate a paused subscription.
* **PAST\_DUE**: A recurring charge failed and the subscription is awaiting recovery. It keeps billing, and the next successful charge returns it to the status it came from. This status is enabled per account — where it is not enabled, a failed charge leaves the subscription active while the retries run.
* **CANCELED**: If your customer decides to cancel the recurring payment, you can cancel the subscription. After canceling it, the subscription is terminated, and it is not possible to reactivate it.

![Subscription lifecycle: CREATED to TRIALING or ACTIVE, with PAUSED, PAST\_DUE, COMPLETED and CANCELED, plus a transversal ERROR state](https://mintcdn.com/yuno-3979e326/wA4Ab8L1XjhA_l4r/images/reference/status-subscriptions/subscription-lifecycle.svg?fit=max\&auto=format\&n=wA4Ab8L1XjhA_l4r\&q=85\&s=15649c49fb37728f7351e6366a453efc)

A subscription in the trial phase behaves like an active one: it can be paused, it enters `PAST_DUE` on a failed charge and returns to `TRIALING` when a later charge succeeds. Any non-terminal status can be canceled, and a subscription created with `initial_payment_validation: true` goes straight from `CREATED` to `CANCELED` if the first payment fails.

Learn more about the status of the subscription on the [Subscription Status](https://docs.y.uno/reference/subscriptions/status-subscriptions.md) page.

## Subscription integration

To start using the subscriptions feature, you need a Yuno account and integration with the Yuno API. The Yuno API provides the following operations to manage your subscriptions:

* **Create**: Use the [Create a Subscription endpoint](https://docs.y.uno/reference/subscriptions/create-subscription.md) to subscribe a customer.
* **Create with the first payment**: Send a `subscription` block on [Create Payment](https://docs.y.uno/reference/payments/create-payment.md) to charge the customer and create the subscription in a single call. See [Start a subscription with the first payment](https://docs.y.uno/docs/payment-features/subscriptions/start-with-payment.md).
* **Pause**: Pause an active subscription with the [Pause Subscription endpoint](https://docs.y.uno/reference/subscriptions/pause-subscription.md).
* **Resume**: Resume a previously paused subscription with the [Resume Subscription endpoint](https://docs.y.uno/reference/subscriptions/resume-subscription.md).
* **Cancel**: Cancel an active subscription with the [Cancel Subscription endpoint](https://docs.y.uno/reference/subscriptions/cancel-subscription.md).
* **Retrieve**: Use the [Retrieve Subscription endpoint](https://docs.y.uno/reference/subscriptions/retrieve-subscription.md) to get the details of a subscription.
* **List**: Use the [List Subscriptions endpoint](https://docs.y.uno/reference/subscriptions/list-subscriptions.md) to page through an account's subscriptions, filtered by customer, status, plan, creation date or payment method type.
* **Keep an external billing engine**: If Stripe Billing already owns your plans, invoices and dunning, Yuno can process every charge while Stripe stays the subscription engine. See [Process Stripe Billing subscriptions with Yuno](https://docs.y.uno/docs/payment-features/subscriptions/stripe-billing.md).

## New concepts

* **Subscriptions**: A subscription involves recurring charges directly tied to a customer and a particular payment method. When stopping or updating, the impact is solely on the same.
* **Payment methods available**
  * **Enrolled**: Customers can pay with a previously enrolled payment method. Only the vaulted token is needed when creating the subscription to associate it with the charges.
* **Capabilities**:
  * **Frequency**: Define the frequency at which subscription charges will occur — daily, weekly, monthly, or yearly (see [Create Subscription](https://docs.y.uno/reference/subscriptions/create-subscription.md) for the values each endpoint accepts) — specifying the amount that needs to be charged for the next billing cycle.
  * **Billing cycles**: The number of billing cycles (following the frequency criterion) that will be completed to fulfill the subscription. If neither an `end_date` is sent nor defined, we will continue attempting charges until it is stopped.
  * **Billing date**: By specifying the `billing_date` object, the merchant can define the logic behind the exact date for the billing of the subscription. This is mutually exclusive with the frequency object.
  * **Availability**: The start and end dates of the subscription. If they are not defined, nor the billing cycles, charges will continue until it is stopped.
    * The fields `billing_cycles` and `availability.finish_at` impact each other. If both are completed during the subscription creation, it will transition to the COMPLETED state upon reaching the nearest event defined in these fields, whether it is the billing cycle or the corresponding `finish_at`.
  * **Trial periods**: This feature lets you define a period where your customers can benefit from a reduced amount. It could be partial or total (for example, a free trial). You need to determine the value to be reduced from the total amount of each subscription charge and the billing cycles it should apply to.
  * **Initial payment validation**: A flag to identify if the subscription should wait for the first payment to continue. False by default. If the field is set to true, the subscription should remain in the CREATED status while waiting for the first payment of the subscription.
    * If the first payment succeeds (SUCCEEDED), the subscription transitions to ACTIVE.
    * If the first payment fails (DECLINED/REJECTED), the subscription transitions to CANCELED.

## Using Yuno subscription solution

Yuno provides subscription management functionalities through its API. You can use this API to create, update, and manage subscriptions, as well as retrieve subscription details and usage.

To use the subscription solution, normally, you will follow the steps described below:

1. To begin, [Create a Customer](https://docs.y.uno/reference/customers/create-customer.md). You will need to provide personal customer information and the `merchant_customer_id`, a unique identifier for the customer used in your system. Upon completing the customer creation process, you will receive an `id` that identifies the user within the Yuno system. This `id` will be used to create the subscription.
2. After creating the customer, you will need to [enroll a credit card](https://docs.y.uno/docs/payment-features/enrollment/enroll-payment-methods.md) to generate a `vaulted_token` for use in the subscription creation.
3. [Create a Subscription](https://docs.y.uno/reference/subscriptions/create-subscription.md) for your customer and the enrolled card. At this step, you will configure the subscription and define the payment method. When creating the subscription, you can customize:
   * The amount the subscription charges.
   * The billing frequency: daily, weekly, monthly, or yearly (see [Create Subscription](https://docs.y.uno/reference/subscriptions/create-subscription.md) for the values each endpoint accepts).
   * The total number of billing cycles.
   * The subscription availability to define the start and end date.

> [!NOTE]
>
> **You can also do this in one call**
>
> The steps above take the customer through enrollment and subscription creation separately. If the customer is signing up and paying right now, you can instead send the recurrence instructions on the payment itself — Yuno charges the card and creates the subscription from that same charge, and nothing starts billing if the payment fails. That route is documented for frictionless card payments only. See [Start a subscription with the first payment](https://docs.y.uno/docs/payment-features/subscriptions/start-with-payment.md).

> [!NOTE]
>
> **Available Payment Methods**
>
> Subscriptions support `CARD`, `PAYPAL_ENROLLMENT` and `PIX_AUTOMATIC` as payment methods, all three through previously enrolled (vaulted) instruments.
>
> `PIX_AUTOMATIC` bills a Brazilian Pix Automático mandate. The rail restricts it to weekly, monthly, quarterly, half-yearly or yearly billing with a frequency value of `1`, and Yuno hands each debit instruction to the rail four days ahead of the debit date, so it does not bill like a card. See [Pix Automático](https://docs.y.uno/docs/payment-features/subscriptions/pix-automatico.md).

> [!CAUTION]
>
> **Declined Payments**
>
> If a payment from a subscription created with [Create Subscription](https://docs.y.uno/reference/subscriptions/create-subscription.md) is declined (including the first payment attempt), the subscription will continue its schedule for future payment attempts, giving the merchant the possibility to charge the client the pending amount through a different process and continue with the ongoing subscription. If you want to cancel a subscription, feel free to use the [cancel subscription endpoint](https://docs.y.uno/reference/subscriptions/cancel-subscription.md).
>
> On the one-call route a declined first charge creates no subscription at all — see [Start a subscription with the first payment](https://docs.y.uno/docs/payment-features/subscriptions/start-with-payment.md).

In the response to the [Create Subscription](https://docs.y.uno/reference/subscriptions/create-subscription.md) endpoint, you receive an `id` which is used to identify the created subscription. You will use the `id` if you decide to pause, resume, or cancel the subscription. If you created the subscription with the first payment, the same identifier comes back as `subscription_code` on the payment response.

## Renewal events

`subscription.active` is sent when the subscription first becomes active (at `billing_cycles.current` = 2); it is not re-sent on subsequent renewals. Track each renewal via the per-cycle `payment.purchase` webhook (outcome in `status`/`sub_status`). `$0`/trial cycles generate no payment webhook by design — on plan-based subscriptions they are reported as `subscription.cycle_executed` instead.

A failed renewal charge also emits `subscription.past_due` where that status is enabled for the account, and `subscription.active` — or `subscription.trialing` — again once a later charge recovers the subscription. See [Webhooks](https://docs.y.uno/docs/webhooks.md#subscription-events) for the full event list.

> [!NOTE]
>
> **`code` vs `id` mapping**
>
> Subscription webhook payloads use `code` while the API uses `id`, and they are the same values: `subscription.code` equals the `id` returned from `POST /v1/subscriptions`, and `customer_payer.code` equals the customer `id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.