Skip to main content
POST
/
v1
/
subscriptions
Create subscription
curl --request POST \
  --url https://api-sandbox.y.uno/v1/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'account-code: <api-key>' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "customer_id": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f",
  "amount": {
    "currency": "BRL",
    "value": 49.9
  },
  "country": "BR",
  "interval": "MONTHLY",
  "payment_method_id": "pm_1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "description": "Premium Plan - Monthly"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "ACTIVE",
  "amount": {
    "currency": "BRL",
    "value": 100
  },
  "interval": "DAILY",
  "next_payment_date": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}
Subscription CompletionThe fields billing_cycles and availability.finish_at have an impact on 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.
Refer to the HTTP Response Codes section for details on possible error outcomes.

Authorizations

​
public-api-key
string
header
required

Your public API key from the Yuno Dashboard

​
private-secret-key
string
header
required

Your private secret key (server-side only)

​
account-code
string
header
required

Your account identifier. The alias X-Account-Code is also accepted.

Body

application/json
​
customer_id
string<uuid>
required

The customer for this subscription

Example:

"c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f"

​
amount
object
required
Example:
{ "currency": "BRL", "value": 100 }
​
country
string
required

ISO 3166-1 alpha-2 country code

Pattern: ^[A-Z]{2}$
Example:

"BR"

​
interval
enum<string>
required

Billing interval

Available options:
DAILY,
WEEKLY,
MONTHLY,
YEARLY
Example:

"MONTHLY"

​
payment_method_id
string<uuid>

Enrolled payment method to charge

Example:

"pm_1a2b3c4d-5e6f-7890-abcd-ef1234567890"

​
description
string

Subscription description

Example:

"Premium Plan - Monthly"

​
start_date
string<date-time>

When to start billing

Example:

"2026-03-01T00:00:00.000Z"

Response

Subscription created successfully

​
id
string<uuid>
​
status
enum<string>
Available options:
ACTIVE,
PAUSED,
CANCELLED,
PAST_DUE,
EXPIRED
​
amount
object
Example:
{ "currency": "BRL", "value": 100 }
​
interval
enum<string>
Available options:
DAILY,
WEEKLY,
MONTHLY,
YEARLY
​
next_payment_date
string<date-time>
​
created_at
string<date-time>
​
updated_at
string<date-time>