Subscriptions
Update Subscription
Updates a subscription’s fields, including retroactively adding stored credential usage data.
PATCH
/
subscriptions
/
{id}
Update Subscription
curl --request PATCH \
--url https://api-sandbox.y.uno/v1/subscriptions/{id} \
--header 'Content-Type: application/json' \
--header 'private-secret-key: <api-key>' \
--header 'public-api-key: <api-key>' \
--data '
{
"name": "<string>",
"description": "<string>",
"account_id": "<string>",
"merchant_reference": "<string>",
"soft_descriptor": "<string>",
"country": "<string>",
"billing_cycles": {
"total": 123
},
"payment_method": {
"type": "CARD",
"vaulted_token": "<string>",
"card": {
"verify": true,
"card_data": {
"number": "<string>",
"expiration_month": 123,
"expiration_year": 123,
"security_code": 123,
"holder_name": "<string>"
},
"store_credentials": {}
},
"": "<string>"
},
"availability": {
"start_at": "2023-11-07T05:31:56Z",
"finish_at": "2023-11-07T05:31:56Z"
},
"retries": {
"retry_on_decline": true,
"amount": 123
},
"metadata": {
"key": "<string>",
"value": "<string>"
}
}
'import requests
url = "https://api-sandbox.y.uno/v1/subscriptions/{id}"
payload = {
"name": "<string>",
"description": "<string>",
"account_id": "<string>",
"merchant_reference": "<string>",
"soft_descriptor": "<string>",
"country": "<string>",
"billing_cycles": { "total": 123 },
"payment_method": {
"type": "CARD",
"vaulted_token": "<string>",
"card": {
"verify": True,
"card_data": {
"number": "<string>",
"expiration_month": 123,
"expiration_year": 123,
"security_code": 123,
"holder_name": "<string>"
},
"store_credentials": {}
},
"": "<string>"
},
"availability": {
"start_at": "2023-11-07T05:31:56Z",
"finish_at": "2023-11-07T05:31:56Z"
},
"retries": {
"retry_on_decline": True,
"amount": 123
},
"metadata": {
"key": "<string>",
"value": "<string>"
}
}
headers = {
"public-api-key": "<api-key>",
"private-secret-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'public-api-key': '<api-key>',
'private-secret-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '<string>',
description: '<string>',
account_id: '<string>',
merchant_reference: '<string>',
soft_descriptor: '<string>',
country: '<string>',
billing_cycles: {total: 123},
payment_method: {
type: 'CARD',
vaulted_token: '<string>',
card: {
verify: true,
card_data: {
number: '<string>',
expiration_month: 123,
expiration_year: 123,
security_code: 123,
holder_name: '<string>'
},
store_credentials: {}
},
'': '<string>'
},
availability: {start_at: '2023-11-07T05:31:56Z', finish_at: '2023-11-07T05:31:56Z'},
retries: {retry_on_decline: true, amount: 123},
metadata: {key: '<string>', value: '<string>'}
})
};
fetch('https://api-sandbox.y.uno/v1/subscriptions/{id}', 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/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'account_id' => '<string>',
'merchant_reference' => '<string>',
'soft_descriptor' => '<string>',
'country' => '<string>',
'billing_cycles' => [
'total' => 123
],
'payment_method' => [
'type' => 'CARD',
'vaulted_token' => '<string>',
'card' => [
'verify' => true,
'card_data' => [
'number' => '<string>',
'expiration_month' => 123,
'expiration_year' => 123,
'security_code' => 123,
'holder_name' => '<string>'
],
'store_credentials' => [
]
],
'' => '<string>'
],
'availability' => [
'start_at' => '2023-11-07T05:31:56Z',
'finish_at' => '2023-11-07T05:31:56Z'
],
'retries' => [
'retry_on_decline' => true,
'amount' => 123
],
'metadata' => [
'key' => '<string>',
'value' => '<string>'
]
]),
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/{id}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"account_id\": \"<string>\",\n \"merchant_reference\": \"<string>\",\n \"soft_descriptor\": \"<string>\",\n \"country\": \"<string>\",\n \"billing_cycles\": {\n \"total\": 123\n },\n \"payment_method\": {\n \"type\": \"CARD\",\n \"vaulted_token\": \"<string>\",\n \"card\": {\n \"verify\": true,\n \"card_data\": {\n \"number\": \"<string>\",\n \"expiration_month\": 123,\n \"expiration_year\": 123,\n \"security_code\": 123,\n \"holder_name\": \"<string>\"\n },\n \"store_credentials\": {}\n },\n \"\": \"<string>\"\n },\n \"availability\": {\n \"start_at\": \"2023-11-07T05:31:56Z\",\n \"finish_at\": \"2023-11-07T05:31:56Z\"\n },\n \"retries\": {\n \"retry_on_decline\": true,\n \"amount\": 123\n },\n \"metadata\": {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api-sandbox.y.uno/v1/subscriptions/{id}")
.header("public-api-key", "<api-key>")
.header("private-secret-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"account_id\": \"<string>\",\n \"merchant_reference\": \"<string>\",\n \"soft_descriptor\": \"<string>\",\n \"country\": \"<string>\",\n \"billing_cycles\": {\n \"total\": 123\n },\n \"payment_method\": {\n \"type\": \"CARD\",\n \"vaulted_token\": \"<string>\",\n \"card\": {\n \"verify\": true,\n \"card_data\": {\n \"number\": \"<string>\",\n \"expiration_month\": 123,\n \"expiration_year\": 123,\n \"security_code\": 123,\n \"holder_name\": \"<string>\"\n },\n \"store_credentials\": {}\n },\n \"\": \"<string>\"\n },\n \"availability\": {\n \"start_at\": \"2023-11-07T05:31:56Z\",\n \"finish_at\": \"2023-11-07T05:31:56Z\"\n },\n \"retries\": {\n \"retry_on_decline\": true,\n \"amount\": 123\n },\n \"metadata\": {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.y.uno/v1/subscriptions/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"account_id\": \"<string>\",\n \"merchant_reference\": \"<string>\",\n \"soft_descriptor\": \"<string>\",\n \"country\": \"<string>\",\n \"billing_cycles\": {\n \"total\": 123\n },\n \"payment_method\": {\n \"type\": \"CARD\",\n \"vaulted_token\": \"<string>\",\n \"card\": {\n \"verify\": true,\n \"card_data\": {\n \"number\": \"<string>\",\n \"expiration_month\": 123,\n \"expiration_year\": 123,\n \"security_code\": 123,\n \"holder_name\": \"<string>\"\n },\n \"store_credentials\": {}\n },\n \"\": \"<string>\"\n },\n \"availability\": {\n \"start_at\": \"2023-11-07T05:31:56Z\",\n \"finish_at\": \"2023-11-07T05:31:56Z\"\n },\n \"retries\": {\n \"retry_on_decline\": true,\n \"amount\": 123\n },\n \"metadata\": {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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",
"soft_descriptor": "ACME SUBSCRIPTION",
"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
},
"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 TransitionThe 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.Retroactive Credential UpdateIf you have existing subscriptions that are failing rebills because of missing credential usage (e.g. from an initial CIT payment), you can use this
PATCH endpoint to add the store_credentials object retroactively to fix the issue.Authorizations
Path Parameters
The unique identifier of the subscription.
Body
application/json
The subscription plan name (MAX 255; MIN 3).
The subscription plan description (MAX 255; MIN 3).
The unique identifier of the account that will have the subscription plan available to use (MAX 64 ; MIN 36).
Identification of the subscription plan (MAX 255; MIN 3).
Statement descriptor shown on the cardholder's bank statement. Updating it changes the descriptor applied to subsequent rebills generated by the subscription engine. Length and formatting limits vary by provider (for example, Unlimit truncates to 22 characters and Airwallex to 30). Worldpay does not read this field; it builds the statement narrative from payment_description instead.
Maximum string length:
255The subscription's country.
Specifies the amount object, with the value of each subscription payment and the used currency.
Show child attributes
Show child attributes
Specifies the frequency object. Defines the billing frequency for the subscription. Including type and value.
Show child attributes
Show child attributes
Specifies the billing_cycles object. Defines the number of charges associated to the subscription.
Show child attributes
Show child attributes
Specifies the customer_payer object to identify the customer.
Show child attributes
Show child attributes
Specifies the payment_method object. Currently, only card as available as payment methods. You can use the card token, the vaulted_token or the card information using through the card object.
Show child attributes
Show child attributes
Specifies the availability object. Defines a date interval based on starting and ending dates when the subscription is available to use.
Show child attributes
Show child attributes
Specified the 'retries' object. If we need to retry declined transactions in Yuno and the amount if necessary. If modified, the retries will apply to the next payment intent.
Show child attributes
Show child attributes
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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
Show child attributes
Show child attributes
Response
200
Example:
"0c7fed3e-ee0d-4d34-9547-778be4ec0798"
Example:
"Test Subscription"
Example:
"493e9374-510a-4201-9e09-de669d75f256"
Example:
"US"
Example:
"Subscription Test"
Example:
"subscription-ref-merchant-AA01"
Example:
"ACME SUBSCRIPTION"
Example:
"ACTIVE"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Example:
"2024-09-30T12:04:23.265372Z"
Example:
"2024-09-30T12:04:23.265372Z"
Was this page helpful?
Previous
Retry SubscriptionManually retries a subscription's most recent declined payment for the current billing cycle.
Next
⌘I
Update Subscription
curl --request PATCH \
--url https://api-sandbox.y.uno/v1/subscriptions/{id} \
--header 'Content-Type: application/json' \
--header 'private-secret-key: <api-key>' \
--header 'public-api-key: <api-key>' \
--data '
{
"name": "<string>",
"description": "<string>",
"account_id": "<string>",
"merchant_reference": "<string>",
"soft_descriptor": "<string>",
"country": "<string>",
"billing_cycles": {
"total": 123
},
"payment_method": {
"type": "CARD",
"vaulted_token": "<string>",
"card": {
"verify": true,
"card_data": {
"number": "<string>",
"expiration_month": 123,
"expiration_year": 123,
"security_code": 123,
"holder_name": "<string>"
},
"store_credentials": {}
},
"": "<string>"
},
"availability": {
"start_at": "2023-11-07T05:31:56Z",
"finish_at": "2023-11-07T05:31:56Z"
},
"retries": {
"retry_on_decline": true,
"amount": 123
},
"metadata": {
"key": "<string>",
"value": "<string>"
}
}
'import requests
url = "https://api-sandbox.y.uno/v1/subscriptions/{id}"
payload = {
"name": "<string>",
"description": "<string>",
"account_id": "<string>",
"merchant_reference": "<string>",
"soft_descriptor": "<string>",
"country": "<string>",
"billing_cycles": { "total": 123 },
"payment_method": {
"type": "CARD",
"vaulted_token": "<string>",
"card": {
"verify": True,
"card_data": {
"number": "<string>",
"expiration_month": 123,
"expiration_year": 123,
"security_code": 123,
"holder_name": "<string>"
},
"store_credentials": {}
},
"": "<string>"
},
"availability": {
"start_at": "2023-11-07T05:31:56Z",
"finish_at": "2023-11-07T05:31:56Z"
},
"retries": {
"retry_on_decline": True,
"amount": 123
},
"metadata": {
"key": "<string>",
"value": "<string>"
}
}
headers = {
"public-api-key": "<api-key>",
"private-secret-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'public-api-key': '<api-key>',
'private-secret-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '<string>',
description: '<string>',
account_id: '<string>',
merchant_reference: '<string>',
soft_descriptor: '<string>',
country: '<string>',
billing_cycles: {total: 123},
payment_method: {
type: 'CARD',
vaulted_token: '<string>',
card: {
verify: true,
card_data: {
number: '<string>',
expiration_month: 123,
expiration_year: 123,
security_code: 123,
holder_name: '<string>'
},
store_credentials: {}
},
'': '<string>'
},
availability: {start_at: '2023-11-07T05:31:56Z', finish_at: '2023-11-07T05:31:56Z'},
retries: {retry_on_decline: true, amount: 123},
metadata: {key: '<string>', value: '<string>'}
})
};
fetch('https://api-sandbox.y.uno/v1/subscriptions/{id}', 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/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'account_id' => '<string>',
'merchant_reference' => '<string>',
'soft_descriptor' => '<string>',
'country' => '<string>',
'billing_cycles' => [
'total' => 123
],
'payment_method' => [
'type' => 'CARD',
'vaulted_token' => '<string>',
'card' => [
'verify' => true,
'card_data' => [
'number' => '<string>',
'expiration_month' => 123,
'expiration_year' => 123,
'security_code' => 123,
'holder_name' => '<string>'
],
'store_credentials' => [
]
],
'' => '<string>'
],
'availability' => [
'start_at' => '2023-11-07T05:31:56Z',
'finish_at' => '2023-11-07T05:31:56Z'
],
'retries' => [
'retry_on_decline' => true,
'amount' => 123
],
'metadata' => [
'key' => '<string>',
'value' => '<string>'
]
]),
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/{id}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"account_id\": \"<string>\",\n \"merchant_reference\": \"<string>\",\n \"soft_descriptor\": \"<string>\",\n \"country\": \"<string>\",\n \"billing_cycles\": {\n \"total\": 123\n },\n \"payment_method\": {\n \"type\": \"CARD\",\n \"vaulted_token\": \"<string>\",\n \"card\": {\n \"verify\": true,\n \"card_data\": {\n \"number\": \"<string>\",\n \"expiration_month\": 123,\n \"expiration_year\": 123,\n \"security_code\": 123,\n \"holder_name\": \"<string>\"\n },\n \"store_credentials\": {}\n },\n \"\": \"<string>\"\n },\n \"availability\": {\n \"start_at\": \"2023-11-07T05:31:56Z\",\n \"finish_at\": \"2023-11-07T05:31:56Z\"\n },\n \"retries\": {\n \"retry_on_decline\": true,\n \"amount\": 123\n },\n \"metadata\": {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("PATCH", 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.patch("https://api-sandbox.y.uno/v1/subscriptions/{id}")
.header("public-api-key", "<api-key>")
.header("private-secret-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"account_id\": \"<string>\",\n \"merchant_reference\": \"<string>\",\n \"soft_descriptor\": \"<string>\",\n \"country\": \"<string>\",\n \"billing_cycles\": {\n \"total\": 123\n },\n \"payment_method\": {\n \"type\": \"CARD\",\n \"vaulted_token\": \"<string>\",\n \"card\": {\n \"verify\": true,\n \"card_data\": {\n \"number\": \"<string>\",\n \"expiration_month\": 123,\n \"expiration_year\": 123,\n \"security_code\": 123,\n \"holder_name\": \"<string>\"\n },\n \"store_credentials\": {}\n },\n \"\": \"<string>\"\n },\n \"availability\": {\n \"start_at\": \"2023-11-07T05:31:56Z\",\n \"finish_at\": \"2023-11-07T05:31:56Z\"\n },\n \"retries\": {\n \"retry_on_decline\": true,\n \"amount\": 123\n },\n \"metadata\": {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.y.uno/v1/subscriptions/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"account_id\": \"<string>\",\n \"merchant_reference\": \"<string>\",\n \"soft_descriptor\": \"<string>\",\n \"country\": \"<string>\",\n \"billing_cycles\": {\n \"total\": 123\n },\n \"payment_method\": {\n \"type\": \"CARD\",\n \"vaulted_token\": \"<string>\",\n \"card\": {\n \"verify\": true,\n \"card_data\": {\n \"number\": \"<string>\",\n \"expiration_month\": 123,\n \"expiration_year\": 123,\n \"security_code\": 123,\n \"holder_name\": \"<string>\"\n },\n \"store_credentials\": {}\n },\n \"\": \"<string>\"\n },\n \"availability\": {\n \"start_at\": \"2023-11-07T05:31:56Z\",\n \"finish_at\": \"2023-11-07T05:31:56Z\"\n },\n \"retries\": {\n \"retry_on_decline\": true,\n \"amount\": 123\n },\n \"metadata\": {\n \"key\": \"<string>\",\n \"value\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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",
"soft_descriptor": "ACME SUBSCRIPTION",
"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
},
"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}"