Retry Subscription

POST

subscriptions

{subscription_id}

retry

Retry Subscription

curl --request POST \
  --url https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/retry \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>'

import requests

url = "https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/retry"

headers = {
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'public-api-key': '<api-key>', 'private-secret-key': '<api-key>'}
};

fetch('https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/retry', 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/{subscription_id}/retry",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "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"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/retry"

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

	req.Header.Add("public-api-key", "<api-key>")
	req.Header.Add("private-secret-key", "<api-key>")

	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/{subscription_id}/retry")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

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

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>'

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

{
  "id": "0054840f-bcd5-4d8e-b86c-c18ede81c556",
  "name": "Test Subscription",
  "account_id": "f7c5fe77-721b-49c2-84d3-957748df3c2c",
  "country": "CL",
  "description": "Subscription Test",
  "merchant_reference": "subscription-ref-merchant-AA01",
  "status": "ACTIVE",
  "amount": {
    "currency": "CLP",
    "value": 15000
  },
  "frequency": {
    "type": "MONTH",
    "value": 1
  },
  "billing_cycles": {
    "total": 12,
    "current": 2,
    "next_at": "2025-05-29T11:13:31.786421Z"
  },
  "customer_payer": {
    "id": "1c6d1a88-d8d5-4c09-b19c-852530d89f05"
  },
  "payment_method": {
    "type": "CARD",
    "vaulted_token": "743880c1-1bdb-4572-99a8-c4e5ce184895"
  },
  "availability": {
    "start_at": "2025-04-29T11:13:31.786421Z",
    "finish_at": null
  },
  "retries": {
    "retry_on_decline": false,
    "amount": 6
  },
  "metadata": null,
  "additional_data": null,
  "trial_period": {
    "billing_cycles": 1,
    "amount": {
      "value": 0,
      "currency": ""
    }
  },
  "initial_payment_validation": false,
  "created_at": "2025-04-29T11:13:31.786421Z",
  "updated_at": "2025-04-29T11:13:31.942325Z"
}

Use this endpoint to manually retry the most recent failed payment of a subscription. This is useful when a customer updates their payment method or resolves a payment issue (e.g., insufficient funds, expired card) mid-billing cycle, since subscription updates only take effect starting from the next billing cycle. Calling this endpoint forces a new charge attempt for the current cycle using the latest subscription configuration.

Only the most recent payment of the subscription can be retried.
Multiple manual retries can be executed only if the previous retry attempt resulted in a DECLINED status.
Manually triggering a retry stops the smart retry scheme for the corresponding payment. The following payments of the subscription will follow the smart retry scheme if enabled in the creation.
After the successful retry attempt, the system continues with the next scheduled subscription charge.
If neither condition is met, the request returns 400 with code INVALID_STATE and the message The last payment intent of the subscription does not support the action requested. The same error is returned when the subscription is canceled.
If no subscription matches subscription_id on the account, the request returns 400 with code SUBSCRIPTION_NOT_FOUND.

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-Account-Code

string

The account_id found in your Yuno Dashboard (UUID).

Path Parameters

subscription_id

string

required

The unique identifier of the subscription, see create subscription (UUID).

Response

200

string

Example:

"0054840f-bcd5-4d8e-b86c-c18ede81c556"

name

string

Example:

"Test Subscription"

account_id

string

Example:

"f7c5fe77-721b-49c2-84d3-957748df3c2c"

country

string

Example:

"CL"

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

retries

object

Show child attributes

metadata

any

additional_data

any

trial_period

object

Show child attributes

initial_payment_validation

boolean

default:true

Example:

false

created_at

string

Example:

"2025-04-29T11:13:31.786421Z"

updated_at

string

Example:

"2025-04-29T11:13:31.942325Z"

soft_descriptor

string | null

Example:

"ACME SUBSCRIPTION"

current_period_start

string | null

Start of the billing period the subscription is currently in, one cadence before current_period_end. Inside a trial or any other plan phase it follows that phase's cadence. A terminal subscription (CANCELED or COMPLETED) keeps its final window rather than going null. Null only for a subscription with no recurring cadence. Always returned together with current_period_end.

Example:

"2023-01-16T20:00:00.912480Z"

current_period_end

string | null

End of the billing period the subscription is currently in. Equal to billing_cycles.next_at. Always returned together with current_period_start.

Example:

"2023-02-16T20:00:00.786342Z"

billing_date

object | null

Only present on subscriptions billed on a fixed date instead of a frequency; mutually exclusive with frequency.

Show child attributes

reason

string | null

Free-form reason for the subscription's current status, when one was recorded; null otherwise.

Example:

"merchant request"

renewal_notification_days

integer | null

How many days before the next billing date the subscription.close_to_renewal webhook is sent. null means no renewal notification is sent.

Example:

3

payments

string[]

subscription_agreement_id

string | null

Example:

"sa_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa"

cancellation_time

string | null

When the subscription was canceled. Only set once it reaches CANCELED; null otherwise.

Example:

"2023-12-16T20:46:54.786342Z"

cancellation_source

string | null

What triggered the cancellation: MERCHANT, SYSTEM, PLAN_CHANGE or RETRIES_EXHAUSTED. Only set once the subscription reaches CANCELED; null otherwise. Treat as open-ended — handle unrecognized values gracefully.

Example:

"MERCHANT"

ending_time

string | null

When the subscription completed or expired. Only set once it reaches COMPLETED; null otherwise.

Example:

"2024-12-16T20:46:54.786342Z"

plan_id

string

Only present when the subscription is linked to a plan.

Example:

"00000000-0000-4000-8000-000000000001"

plan_assigned_at

string

Only present on plan-linked subscriptions. The moment the plan was attached — at creation from a plan, migration onto a plan, or a plan change.

Example:

"2023-12-16T20:46:54.786342Z"

previous_subscription_id

string | null

Only present when this subscription was created by a plan change (switching an existing subscription to a different plan).

phases

object[]

The linked plan's phase definitions, as the plan declares them — including the terminal REGULAR phase. Only present on plan-linked subscriptions whose plan has phases. This is the plan's own ladder, not this subscriber's snapshot: for what was pinned for this subscription at creation, use billing_phases.

Show child attributes

current_phase

string

Only present on plan-linked subscriptions.

Example:

"REGULAR"

current_phase_end

string | null

When the phase named by current_phase hands over to the next one — for a subscription in its trial, when it switches to the regular price. End of the last billing period the phase covers, so on the final period of a trial it equals current_period_end. Null for a subscription with no plan and for one that already left the phase ladder.

Example:

"2023-03-16T20:00:00.786342Z"

billing_phases

object[]

Only present on plan-linked subscriptions whose plan has phases. Contains the leading TRIAL phases only, snapshotted at creation — the terminal REGULAR phase is never included, since its price isn't pinned and instead resolves from the plan at every billing. current_phase: "REGULAR" is how you know the ladder is exhausted.

Show child attributes

pending_plan_change

object | null

The plan change scheduled for the next billing cycle, or null when none is pending. Schedule one with the plan_change block on Update Subscription.

Show child attributes

refund_rule

object

The stored refund rule used to resolve a CUSTOM cancel refund when the cancel request sends no refund_amount of its own. Present only when one is configured; omitted, not null, otherwise. Available to organizations enabled for it; contact Yuno.

Show child attributes

pause_until

string

When the subscription is scheduled to resume automatically. Present only on a subscription currently paused with a duration (pause_cycles or pause_until sent at pause); absent, not null, on every other read.

Example:

"2026-10-15T15:54:22.780166Z"

cancel_scheduled

object | null

null when no cancellation is pending.

Show child attributes

refund

object | null

null when refund was NONE or omitted. Present on the cancel response and on every later read once computed.

Show child attributes

unpaid_cycle

object

Present only when the current billing cycle is PAST_DUE and has not settled.

Show child attributes

⌘I

Retry Subscription

curl --request POST \
  --url https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/retry \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>'

import requests

url = "https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/retry"

headers = {
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'public-api-key': '<api-key>', 'private-secret-key': '<api-key>'}
};

fetch('https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/retry', 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/{subscription_id}/retry",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "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"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/retry"

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

	req.Header.Add("public-api-key", "<api-key>")
	req.Header.Add("private-secret-key", "<api-key>")

	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/{subscription_id}/retry")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

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

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>'

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

{
  "id": "0054840f-bcd5-4d8e-b86c-c18ede81c556",
  "name": "Test Subscription",
  "account_id": "f7c5fe77-721b-49c2-84d3-957748df3c2c",
  "country": "CL",
  "description": "Subscription Test",
  "merchant_reference": "subscription-ref-merchant-AA01",
  "status": "ACTIVE",
  "amount": {
    "currency": "CLP",
    "value": 15000
  },
  "frequency": {
    "type": "MONTH",
    "value": 1
  },
  "billing_cycles": {
    "total": 12,
    "current": 2,
    "next_at": "2025-05-29T11:13:31.786421Z"
  },
  "customer_payer": {
    "id": "1c6d1a88-d8d5-4c09-b19c-852530d89f05"
  },
  "payment_method": {
    "type": "CARD",
    "vaulted_token": "743880c1-1bdb-4572-99a8-c4e5ce184895"
  },
  "availability": {
    "start_at": "2025-04-29T11:13:31.786421Z",
    "finish_at": null
  },
  "retries": {
    "retry_on_decline": false,
    "amount": 6
  },
  "metadata": null,
  "additional_data": null,
  "trial_period": {
    "billing_cycles": 1,
    "amount": {
      "value": 0,
      "currency": ""
    }
  },
  "initial_payment_validation": false,
  "created_at": "2025-04-29T11:13:31.786421Z",
  "updated_at": "2025-04-29T11:13:31.942325Z"
}

Getting Started

Reference

Customers

Network Tokens

Customer Sessions (Enrollment)

Checkout Sessions

Payment Methods (Checkout)

Checkout Builder

Payment Methods (Direct Workflow)

PCI Proxy

Payments

Pre-Debit Notifications

3DS2 Setup

Unreferenced Refunds

Dry-run

Transaction Reporting

Routing Recommendations

Payment Links

Recipients for Marketplace

Sellers (Franchise)

Subscriptions Plans

Subscriptions

Payouts

Organizations

Reports

Installments

AI Caller

Communications Campaigns

Conversion Rate

FX Rates

Banking Connectivity

Webhooks

Authorizations

Headers

Path Parameters

Response