Create Subscription

POST /subscriptions

Create Subscription

cURL

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"
    }
  ]
}
'

import requests

url = "https://api-sandbox.y.uno/v1/subscriptions"

payload = {
    "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"
        }
    ]
}
headers = {
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'public-api-key': '<api-key>',
    'private-secret-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'}]
  })
};

fetch('https://api-sandbox.y.uno/v1/subscriptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.y.uno/v1/subscriptions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "private-secret-key: <api-key>",
    "public-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.y.uno/v1/subscriptions"

	payload := strings.NewReader("{\n  \"name\": \"Test Subscription\",\n  \"description\": \"Subscription Test\",\n  \"merchant_reference\": \"subscription-ref-merchant-AA01\",\n  \"account_id\": \"493e9374-510a-4201-9e09-de669d75f256\",\n  \"country\": \"CL\",\n  \"amount\": {\n    \"currency\": \"CLP\",\n    \"value\": 15000\n  },\n  \"frequency\": {\n    \"type\": \"MONTH\",\n    \"value\": 1\n  },\n  \"billing_cycles\": {\n    \"total\": 12\n  },\n  \"customer_payer\": {\n    \"id\": \"a1d3b664-e32a-4508-9da1-9ede3e62a60c\"\n  },\n  \"payment_method\": {\n    \"type\": \"CARD\",\n    \"vaulted_token\": \"d4aa3586-def2-4705-b7cd-fe064bb764e6\",\n    \"card\": {\n      \"installments\": 3\n    }\n  },\n  \"availability\": {\n    \"start_at\": \"2024-11-01T00:00:00Z\"\n  },\n  \"trial_period\": {\n    \"billing_cycles\": 1,\n    \"amount\": {\n      \"currency\": \"CLP\",\n      \"value\": 0\n    }\n  },\n  \"metadata\": [\n    {\n      \"key\": \"plan\",\n      \"value\": \"gold\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("public-api-key", "<api-key>")
	req.Header.Add("private-secret-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.y.uno/v1/subscriptions")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Test Subscription\",\n  \"description\": \"Subscription Test\",\n  \"merchant_reference\": \"subscription-ref-merchant-AA01\",\n  \"account_id\": \"493e9374-510a-4201-9e09-de669d75f256\",\n  \"country\": \"CL\",\n  \"amount\": {\n    \"currency\": \"CLP\",\n    \"value\": 15000\n  },\n  \"frequency\": {\n    \"type\": \"MONTH\",\n    \"value\": 1\n  },\n  \"billing_cycles\": {\n    \"total\": 12\n  },\n  \"customer_payer\": {\n    \"id\": \"a1d3b664-e32a-4508-9da1-9ede3e62a60c\"\n  },\n  \"payment_method\": {\n    \"type\": \"CARD\",\n    \"vaulted_token\": \"d4aa3586-def2-4705-b7cd-fe064bb764e6\",\n    \"card\": {\n      \"installments\": 3\n    }\n  },\n  \"availability\": {\n    \"start_at\": \"2024-11-01T00:00:00Z\"\n  },\n  \"trial_period\": {\n    \"billing_cycles\": 1,\n    \"amount\": {\n      \"currency\": \"CLP\",\n      \"value\": 0\n    }\n  },\n  \"metadata\": [\n    {\n      \"key\": \"plan\",\n      \"value\": \"gold\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.y.uno/v1/subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Test Subscription\",\n  \"description\": \"Subscription Test\",\n  \"merchant_reference\": \"subscription-ref-merchant-AA01\",\n  \"account_id\": \"493e9374-510a-4201-9e09-de669d75f256\",\n  \"country\": \"CL\",\n  \"amount\": {\n    \"currency\": \"CLP\",\n    \"value\": 15000\n  },\n  \"frequency\": {\n    \"type\": \"MONTH\",\n    \"value\": 1\n  },\n  \"billing_cycles\": {\n    \"total\": 12\n  },\n  \"customer_payer\": {\n    \"id\": \"a1d3b664-e32a-4508-9da1-9ede3e62a60c\"\n  },\n  \"payment_method\": {\n    \"type\": \"CARD\",\n    \"vaulted_token\": \"d4aa3586-def2-4705-b7cd-fe064bb764e6\",\n    \"card\": {\n      \"installments\": 3\n    }\n  },\n  \"availability\": {\n    \"start_at\": \"2024-11-01T00:00:00Z\"\n  },\n  \"trial_period\": {\n    \"billing_cycles\": 1,\n    \"amount\": {\n      \"currency\": \"CLP\",\n      \"value\": 0\n    }\n  },\n  \"metadata\": [\n    {\n      \"key\": \"plan\",\n      \"value\": \"gold\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

200

{
  "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"
}

"{\n Refer to the HTTP Response Codes section for more details: 'https://docs.y.uno/reference/response-codes'\n}"

Subscription Completion

The 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.

Credential Usage for Previous CIT

If you create a CIT payment (e.g. Apple Pay or card) before creating the subscription and pass the resulting vaulted token into the subscription, you must include store_credentials.usage to indicate whether this is the first or a subsequent use. Without this, rebills will be treated as CITs and declined by the provider.

Required payload for new subscriptions:

{
  "payment_method": {
    "type": "CARD",
    "vaulted_token": "{{vaulted_token}}",
    "card": {
      "store_credentials": {
        "usage": "USED"
      }
    }
  }
}

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.

Show child attributes

payment_method · object · required

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

Show child attributes

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.

Show child attributes

frequency · object

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

Show child attributes

billing_cycles · object

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

Show child attributes

customer_payer · object

Specifies the customer_payer object to identify the customer.

Show child attributes

trial_period · object

Specifies the trial period object

Show child attributes

availability · object

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

Show child attributes

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.

Show child attributes

retries · object

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

Show child attributes

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.

Show child attributes

Response

200

application/json

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

Show child attributes

frequency · object

Show child attributes

billing_cycles · object

Show child attributes

customer_payer · object

Show child attributes

payment_method · object

Show child attributes

availability · object

Show child attributes

trial_period · object

Show child attributes

metadata · any

created_at · string

Example:

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

updated_at · string

Example:

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