Create a Subscription

Set up recurring billing by enrolling a payment method and creating a subscription with Yuno’s API.

Overview

Creating a subscription involves two steps: enrolling a customer’s payment method for recurring use, and then creating the subscription with your desired billing configuration. This guide walks through both steps with complete API examples.

Step 1: Enroll a Payment Method

Before creating a subscription, you need a reusable payment method token. Use the enrollment flow to securely capture and tokenize the customer’s payment details.

cURL

curl --request POST \
  --url https://api.y.uno/v1/customers/{customer_id}/payment-methods \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{
    "type": "CARD",
    "vaulted_token": "tok_card_abc123",
    "country": "US"
  }'

When using Yuno’s Checkout SDK, the enrollment flow is handled automatically. The SDK returns a vaulted_token that you can use for subscription creation.

Step 2: Create the Subscription

With an enrolled payment method, create a subscription specifying the billing amount, interval, and duration.

cURL

curl --request POST \
  --url https://api.y.uno/v1/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{
    "customer_id": "cust_abc123",
    "payment_method_id": "pm_enrolled_xyz789",
    "amount": {
      "value": 29.99,
      "currency": "USD"
    },
    "country": "US",
    "interval": "MONTHLY",
    "interval_count": 1,
    "start_date": "2026-03-01T00:00:00Z",
    "description": "Premium Plan - Monthly",
    "metadata": {
      "plan": "premium",
      "tier": "monthly"
    }
  }'

Billing Intervals

Interval	interval Value	interval_count Example	Billing Frequency
Daily	DAILY	1	Every day
Weekly	WEEKLY	1	Every 7 days
Bi-weekly	WEEKLY	2	Every 14 days
Monthly	MONTHLY	1	Every month
Quarterly	MONTHLY	3	Every 3 months
Annual	YEARLY	1	Every year

Managing Subscriptions

Pause a Subscription

curl --request POST \
  --url https://api.y.uno/v1/subscriptions/sub_premium_001/pause \
  --header 'X-Api-Key: YOUR_API_KEY'

Resume a Subscription

curl --request POST \
  --url https://api.y.uno/v1/subscriptions/sub_premium_001/resume \
  --header 'X-Api-Key: YOUR_API_KEY'

Cancel a Subscription

curl --request POST \
  --url https://api.y.uno/v1/subscriptions/sub_premium_001/cancel \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{ "reason": "Customer requested cancellation" }'

Cancellation is irreversible. Once cancelled, a new subscription must be created if the customer wishes to re-subscribe.

Update Payment Method

If a customer’s card expires or they want to switch payment methods:

curl --request PATCH \
  --url https://api.y.uno/v1/subscriptions/sub_premium_001 \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{
    "payment_method_id": "pm_new_card_456"
  }'

Proactively prompt customers to update their payment method before card expiration to avoid payment failures and involuntary churn.