Change Subscription Plan - Yuno API Documentation

POST

subscriptions

{subscription_id}

plan

Change Subscription Plan

curl --request POST \
  --url https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/plan \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "skip_trial": false
}
'

import requests

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

payload = {
    "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "skip_trial": False
}
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({plan_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', skip_trial: false})
};

fetch('https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/plan', 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}/plan",
  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([
    'plan_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'skip_trial' => false
  ]),
  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/{subscription_id}/plan"

	payload := strings.NewReader("{\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"skip_trial\": false\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/{subscription_id}/plan")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"skip_trial\": false\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"skip_trial\": false\n}"

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

{
  "id": "8f11a2b0-6c1d-4a77-9f3e-2b5c8d0e91aa",
  "name": "sub_001",
  "account_id": "2404911d-5df9-429e-8488-ad41abea1a4b",
  "country": "US",
  "description": "streaming service",
  "merchant_reference": "001_marzo_23",
  "status": "TRIALING",
  "amount": {
    "currency": "USD",
    "value": 12100
  },
  "frequency": {
    "type": "MONTH",
    "value": 1
  },
  "billing_cycles": {
    "total": 8,
    "current": 1,
    "next_at": "2024-01-16T20:46:54.786342Z"
  },
  "customer_payer": {
    "id": "3t04911d-5df9-429e-8488-ad41abea1a2c"
  },
  "payment_method": {
    "type": "CARD",
    "vaulted_token": "6104911d-5df9-429e-8488-ad41abea1a4b",
    "card": {
      "installments": null,
      "network_transaction_id": null,
      "usage": "FIRST"
    }
  },
  "availability": {
    "start_at": "2024-01-16T20:46:54.786342Z",
    "finish_at": null
  },
  "retries": {
    "retry_on_decline": false,
    "amount": 6,
    "strategy": "DEFAULT",
    "schedule": null,
    "stop_on_hard_decline": null,
    "cancel_on_exhausted_retries": null
  },
  "metadata": [
    {
      "key": "sub_ext_id",
      "value": "AA001"
    }
  ],
  "additional_data": null,
  "trial_period": null,
  "initial_payment_validation": false,
  "reason": null,
  "subscription_agreement_id": null,
  "soft_descriptor": null,
  "renewal_notification_days": null,
  "cancellation_time": null,
  "cancellation_source": null,
  "ending_time": null,
  "created_at": "2023-12-16T20:46:54.786342Z",
  "updated_at": "2023-12-16T20:46:54.786342Z",
  "plan_id": "1904911d-5df9-429e-8488-ad41abea1a4d",
  "plan_assigned_at": "2023-12-16T20:46:54.786342Z",
  "previous_subscription_id": "7304911d-5df9-429e-8488-ad41abea1a4c",
  "phases": [
    {
      "order": 1,
      "name": "Intro",
      "type": "TRIAL",
      "duration": {
        "type": "MONTH",
        "value": 2
      },
      "frequency": {
        "type": "MONTH",
        "value": 1
      },
      "amount": {
        "value": 5000,
        "currency": "USD"
      },
      "total_payments": 2,
      "country_prices": []
    },
    {
      "order": 2,
      "name": "Regular",
      "type": "REGULAR",
      "duration": null,
      "frequency": null,
      "amount": null,
      "total_payments": null,
      "country_prices": []
    }
  ],
  "current_phase": "TRIAL",
  "billing_phases": [
    {
      "order": 1,
      "type": "TRIAL",
      "name": "Intro",
      "amount": {
        "value": 5000,
        "currency": "USD"
      },
      "frequency": {
        "type": "MONTH",
        "value": 1
      },
      "start_cycle": 1,
      "end_cycle": 2
    }
  ],
  "pending_plan_change": null
}

The change takes effect at the next renewalNo charge is made when you call this endpoint, and nothing is prorated or refunded. The subscription keeps billing on its existing schedule; the new plan’s price applies from the next renewal date onwards.

Two behaviors, one endpoint

Which one you get depends on whether the subscription is already on a plan.

Subscription	What happens	`id` in the response
Not on a plan	Attached to the plan in place	Unchanged
Already on a plan	Canceled and replaced by a new subscription on the target plan	New — the old `id` is in `previous_subscription_id`

In the replacement case the original subscription ends up CANCELED with a cancellation_source of PLAN_CHANGE, and the replacement inherits the original’s remaining billing cycles and its next renewal date — availability.start_at and billing_cycles.next_at on the replacement both equal the original’s next_at, and its billing_cycles.current restarts at 1. If that renewal date has already passed (for example on a long-paused subscription), the replacement instead starts about a minute from now and bills right away.

Store the returned id after a plan-to-plan changeThe replacement is a different subscription. If you keep the old id, subsequent calls will act on a canceled subscription.

Webhooks

A plan-to-plan change emits three events:

subscription.create for the replacement.
subscription.cancel for the original, with cancellation_source: PLAN_CHANGE. Do not count it as churn.
subscription.plan_changed for the replacement, with previous_subscription_id set.

The attach case emits none of them. Its only webhook is a status change, and only when the plan’s ladder promotes the subscription to TRIALING on this call.

Skipping the target plan’s trial

If the target plan defines trial or intro phases, the subscription adopts that whole ladder by default — which means a subscriber can change plans mid-trial and receive a fresh trial. Set skip_trial to true to prevent that. The replacement bills the target plan’s regular price from its first charge and its status stays ACTIVE rather than becoming TRIALING.

Change plan without granting a new trial

{
  "plan_id": "1904911d-5df9-429e-8488-ad41abea1a4d",
  "skip_trial": true
}

skip_trial defaults to false and applies only to plan-to-plan changes. Sending skip_trial: true on a subscription that is not on a plan returns 400 — false and an omitted flag are equivalent and are accepted everywhere. On a plan with no phases it makes no difference.

phases still describes the planWith skip_trial: true the response still lists the target plan’s phases — that array describes the plan, not what this subscription will be billed. The subscription-level signals are status, which stays ACTIVE instead of becoming TRIALING, and the absence of current_phase and billing_phases: both keys are omitted from the response rather than returned as null, so test for absence, not for null. A default change returns both populated.

Scheduling the change instead

Both mechanisms take billing effect at the next renewal — neither charges now. They differ in what happens to the subscription record. This endpoint restructures it immediately: an attach mutates the subscription in place, and a plan-to-plan change returns a new id with the original left CANCELED. The plan_change object on Update Subscription leaves the subscription untouched until the renewal and keeps the same id. plan_change is not a general substitute: it requires a subscription that is already on a plan and is ACTIVE or TRIALING. Attaching a plan to a subscription that has none, or changing plans from CREATED or PAUSED, is only possible through this endpoint. The two differ in their trial default, for backwards-compatibility reasons:

	Default
This endpoint	Adopts the target plan’s phases (`skip_trial: false`)
`plan_change` on Update Subscription	Skips them (`phases_behavior: "START_FROM_REGULAR"`)

Set skip_trial or phases_behavior explicitly whenever the trial behavior matters to you.

Repeated calls

While the subscription is in an accepted status, re-posting its current plan is an idempotent no-op that returns 200 with the subscription unchanged — including when you change only skip_trial, and including when that plan has since been canceled. A plan-to-plan change is not repeatable on the same subscription_id. Once it succeeds the original is CANCELED, so re-posting to that id returns 400 INVALID_STATE (The subscription status CANCELED does not support plan changes.) rather than replaying the first outcome. Treat that error as confirmation the change already landed, and point any follow-up call at the replacement id. If a call times out, reconcile with GET /v1/subscriptions/{subscription_id} instead of retrying blind: the original carries cancellation_source: PLAN_CHANGE once the change landed, and the replacement is the subscription whose previous_subscription_id is that id. An in-flight retry sent while the original is still changeable is safe — it is deduplicated as long as skip_trial is unchanged. A different skip_trial value is a different operation.

Requirements

The subscription must not be CANCELED or COMPLETED — those return 400 INVALID_STATE (The subscription status <STATUS> does not support plan changes.). This endpoint accepts CREATED and PAUSED subscriptions, which the plan_change object on Update Subscription does not. Both cases require the plan to be ACTIVE and to belong to the subscription’s account, and neither is available to subscriptions billed with frequency.execution: MERCHANT. Attaching a subscription that has no plan additionally requires that the plan’s cadence matches the subscription’s and that the resolved price is in the subscription’s currency. The subscription must not be in a trial period, must not already have billing phases, must not use a billing_date, and must not have a VARIABLE amount. The subscription adopts the target plan’s phase ladder from its next unbilled cycle, and that ladder must fit inside the subscription’s remaining billing cycles. If the ladder opens with a TRIAL phase covering the cycle in flight, an ACTIVE subscription becomes TRIALING on this same call; CREATED and PAUSED subscriptions are not promoted this way. skip_trial cannot suppress that — it is a plan-to-plan-only flag. Changing from one plan to another additionally requires that the subscription has at least one billing cycle left and that its availability window does not end before the next renewal. The target plan must accept the subscription’s payment-method type, if it restricts allowed_payment_methods, and the subscription must have a stored vaulted payment method. The target plan’s cadence and price apply as defined on that plan. If the subscription had a scheduled change pending, this call discards it without a subscription.plan_change_canceled webhook; the replacement starts with pending_plan_change: null.

Errors

HTTP	`code`	When
`404`	`PLAN_NOT_FOUND`	The target plan does not exist or is not linked to this account.
`400`	`INVALID_STATE`	The subscription’s status does not support plan changes; the target plan is not active; or the availability window ends before the next renewal.
`400`	`BAD_REQUEST`	`skip_trial: true` on a subscription that is not on a plan; no remaining billing cycles; the subscription is billed with `frequency.execution: MERCHANT`.
`400`	`INCORRECT_PAYMENT_METHOD_TYPE`	The target plan restricts `allowed_payment_methods` and the subscription’s payment-method type is not on the list.
`400`	`PAYMENT_METHOD_NOT_FOUND`	The subscription has no stored vaulted payment method.

Re-posting the subscription’s current plan here is a 200 no-op. The same intent expressed through the plan_change object on Update Subscription is rejected with 422 SAME_PLAN.

Authorizations

public-api-key

string

header

default:<Your public-api-key>

required

private-secret-key

string

header

default:<Your private-secret-key>

required

Path Parameters

subscription_id

string<uuid>

required

The unique identifier of a subscription.

Body

application/json

plan_id

string<uuid>

required

The unique identifier of the plan to move the subscription onto.

Example:

"1904911d-5df9-429e-8488-ad41abea1a4d"

skip_trial

boolean

default:false

Plan-to-plan changes only. When true, the replacement subscription does not adopt the target plan's trial or intro phases: it bills that plan's regular price from its first charge and its status stays ACTIVE instead of becoming TRIALING. Use it to stop subscribers from earning a fresh trial by switching plans. Sending true on a subscription that is not on a plan returns 400; false and an omitted flag are equivalent and always accepted.

Example:

true

Response

200

Change Subscription Plan

curl --request POST \
  --url https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/plan \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "skip_trial": false
}
'

import requests

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

payload = {
    "plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "skip_trial": False
}
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({plan_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', skip_trial: false})
};

fetch('https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/plan', 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}/plan",
  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([
    'plan_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'skip_trial' => false
  ]),
  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/{subscription_id}/plan"

	payload := strings.NewReader("{\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"skip_trial\": false\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/{subscription_id}/plan")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"skip_trial\": false\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"skip_trial\": false\n}"

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

{
  "id": "8f11a2b0-6c1d-4a77-9f3e-2b5c8d0e91aa",
  "name": "sub_001",
  "account_id": "2404911d-5df9-429e-8488-ad41abea1a4b",
  "country": "US",
  "description": "streaming service",
  "merchant_reference": "001_marzo_23",
  "status": "TRIALING",
  "amount": {
    "currency": "USD",
    "value": 12100
  },
  "frequency": {
    "type": "MONTH",
    "value": 1
  },
  "billing_cycles": {
    "total": 8,
    "current": 1,
    "next_at": "2024-01-16T20:46:54.786342Z"
  },
  "customer_payer": {
    "id": "3t04911d-5df9-429e-8488-ad41abea1a2c"
  },
  "payment_method": {
    "type": "CARD",
    "vaulted_token": "6104911d-5df9-429e-8488-ad41abea1a4b",
    "card": {
      "installments": null,
      "network_transaction_id": null,
      "usage": "FIRST"
    }
  },
  "availability": {
    "start_at": "2024-01-16T20:46:54.786342Z",
    "finish_at": null
  },
  "retries": {
    "retry_on_decline": false,
    "amount": 6,
    "strategy": "DEFAULT",
    "schedule": null,
    "stop_on_hard_decline": null,
    "cancel_on_exhausted_retries": null
  },
  "metadata": [
    {
      "key": "sub_ext_id",
      "value": "AA001"
    }
  ],
  "additional_data": null,
  "trial_period": null,
  "initial_payment_validation": false,
  "reason": null,
  "subscription_agreement_id": null,
  "soft_descriptor": null,
  "renewal_notification_days": null,
  "cancellation_time": null,
  "cancellation_source": null,
  "ending_time": null,
  "created_at": "2023-12-16T20:46:54.786342Z",
  "updated_at": "2023-12-16T20:46:54.786342Z",
  "plan_id": "1904911d-5df9-429e-8488-ad41abea1a4d",
  "plan_assigned_at": "2023-12-16T20:46:54.786342Z",
  "previous_subscription_id": "7304911d-5df9-429e-8488-ad41abea1a4c",
  "phases": [
    {
      "order": 1,
      "name": "Intro",
      "type": "TRIAL",
      "duration": {
        "type": "MONTH",
        "value": 2
      },
      "frequency": {
        "type": "MONTH",
        "value": 1
      },
      "amount": {
        "value": 5000,
        "currency": "USD"
      },
      "total_payments": 2,
      "country_prices": []
    },
    {
      "order": 2,
      "name": "Regular",
      "type": "REGULAR",
      "duration": null,
      "frequency": null,
      "amount": null,
      "total_payments": null,
      "country_prices": []
    }
  ],
  "current_phase": "TRIAL",
  "billing_phases": [
    {
      "order": 1,
      "type": "TRIAL",
      "name": "Intro",
      "amount": {
        "value": 5000,
        "currency": "USD"
      },
      "frequency": {
        "type": "MONTH",
        "value": 1
      },
      "start_cycle": 1,
      "end_cycle": 2
    }
  ],
  "pending_plan_change": null
}

​Two behaviors, one endpoint

​Webhooks

​Skipping the target plan’s trial

​Scheduling the change instead

​Repeated calls

​Requirements

​Errors

Authorizations

Path Parameters

Body

Response

Two behaviors, one endpoint

Webhooks

Skipping the target plan’s trial

Scheduling the change instead

Repeated calls

Requirements

Errors