Skip to main content
POST
/
subscriptions
Create Subscription
curl --request POST \
  --url https://api-sandbox.y.uno/v1/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "name": "Test Subscription",
  "description": "Subscription Test",
  "merchant_reference": "subscription-ref-merchant-AA01",
  "account_id": "493e9374-510a-4201-9e09-de669d75f256",
  "country": "CL",
  "amount": {
    "currency": "CLP",
    "value": 15000
  },
  "frequency": {
    "type": "MONTH",
    "value": 1
  },
  "billing_cycles": {
    "total": 12
  },
  "customer_payer": {
    "id": "a1d3b664-e32a-4508-9da1-9ede3e62a60c"
  },
  "payment_method": {
    "type": "CARD",
    "vaulted_token": "d4aa3586-def2-4705-b7cd-fe064bb764e6",
    "card": {
      "installments": 3
    }
  },
  "availability": {
    "start_at": "2024-11-01T00:00:00Z"
  },
  "trial_period": {
    "billing_cycles": 1,
    "amount": {
      "currency": "CLP",
      "value": 0
    }
  },
  "metadata": [
    {
      "key": "plan",
      "value": "gold"
    }
  ]
}
'
{
  "id": "0c7fed3e-ee0d-4d34-9547-778be4ec0798",
  "name": "Test Subscription",
  "account_id": "493e9374-510a-4201-9e09-de669d75f256",
  "country": "US",
  "description": "Subscription Test",
  "merchant_reference": "subscription-ref-merchant-AA01",
  "status": "ACTIVE",
  "amount": {
    "currency": "USD",
    "value": 15000
  },
  "frequency": {
    "type": "MONTH",
    "value": 1
  },
  "billing_cycles": {
    "total": 12,
    "current": 1,
    "next_at": "2024-09-30T12:04:23.265393Z"
  },
  "customer_payer": {
    "id": "a1d3b664-e32a-4508-9da1-9ede3e62a60c"
  },
  "payment_method": {
    "type": "CARD",
    "vaulted_token": "d4aa3586-def2-4705-b7cd-fe064bb764e6"
  },
  "availability": {
    "start_at": "2024-09-30T12:04:23.265393Z",
    "finish_at": null
  },
  "trial_period": {
    "billing_cycles": 1,
    "amount": {
      "value": 0,
      "currency": ""
    }
  },
  "metadata": null,
  "created_at": "2024-09-30T12:04:23.265372Z",
  "updated_at": "2024-09-30T12:04:23.265372Z"
}
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
default:<Your public-api-key>
required
​
private-secret-key
string
header
default:<Your private-secret-key>
required

Headers

​
x-idempotency-key
string
default:{$randomUUID}

A unique identifier for the request. Must be different each time (UUID). See authentication.

Body

application/json
​
name
string
required

The subscription plan name (MAX 255; MIN 3).

​
account_id
string
required

The unique identifier of the account that will have the subscription plan available to use (UUID, 36 chars).

​
country
string
required

The subscription's country (MAX 2; MIN 2; ISO 3166-1).

​
amount
object
required

Specifies the amount object, with the value of each subscription payment and the used currency.

​
payment_method
object
required

Specifies the payment_method object. Currently, only card is available as a payment method using previously enrolled cards (vaulted_token)

​
description
string

The subscription plan description (MAX 255; MIN 3).

​
merchant_reference
string

Identification of the subscription plan (MAX 255; MIN 3).

​
additional_data
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.

​
frequency
object

Specifies the frequency object. Defines the billing frequency for the subscription. Including type and value.

​
billing_cycles
object

Specifies the billing_cycles object. Defines the number of charges associated to the subscription.

​
customer_payer
object

Specifies the customer_payer object to identify the customer.

​
trial_period
object

Specifies the trial period object

​
availability
object

Specifies the availability object. Defines a date interval based on starting and ending dates when the subscription is available to use.

​
metadata
object[]

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Keys can be unset by posting an empty value to metadata. You can add up to 50 metadata objects.

​
retries
object

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

​
initial_payment_validation
boolean

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

​
billing_date
object

Specifies the billing_date object. Defines the type of date use for the subscription logic. Mutually exclusive with the frequency object.

Response

200

​
id
string
Example:

"0c7fed3e-ee0d-4d34-9547-778be4ec0798"

​
name
string
Example:

"Test Subscription"

​
account_id
string
Example:

"493e9374-510a-4201-9e09-de669d75f256"

​
country
string
Example:

"US"

​
description
string
Example:

"Subscription Test"

​
merchant_reference
string
Example:

"subscription-ref-merchant-AA01"

​
status
string
Example:

"ACTIVE"

​
amount
object
​
frequency
object
​
billing_cycles
object
​
customer_payer
object
​
payment_method
object
​
availability
object
​
trial_period
object
​
metadata
any
​
created_at
string
Example:

"2024-09-30T12:04:23.265372Z"

​
updated_at
string
Example:

"2024-09-30T12:04:23.265372Z"