Reactivate Subscription - Yuno API Documentation

POST

subscriptions

{subscription_id}

reactivate

curl --request POST \
  --url https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/reactivate \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "billing_cycle_behavior": "RESTART"
}
'

{
  "id": "7304911d-5df9-429e-8488-ad41abea1a4c",
  "name": "SUB-111 merchant reactivate subject",
  "account_id": "2404911d-5df9-429e-8488-ad41abea1a4b",
  "country": "CO",
  "description": null,
  "merchant_reference": "pa-sub111-1789488115936-594232",
  "status": "ACTIVE",
  "amount": {
    "currency": "COP",
    "value": 45000
  },
  "frequency": {
    "type": "MONTH",
    "value": 1
  },
  "billing_cycles": {
    "total": 6,
    "current": 2,
    "paid": 0,
    "next_at": "2026-10-15T16:01:56.709393Z"
  },
  "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": "615803391389209",
      "usage": "USED"
    }
  },
  "availability": {
    "start_at": "2026-09-15T16:01:56.709393Z",
    "finish_at": null
  },
  "retries": {
    "retry_on_decline": false,
    "amount": 6,
    "strategy": "SMART",
    "schedule": null,
    "stop_on_hard_decline": null,
    "cancel_on_exhausted_retries": null
  },
  "metadata": null,
  "additional_data": null,
  "trial_period": {
    "billing_cycles": 1,
    "amount": {
      "value": 0,
      "currency": ""
    }
  },
  "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": "2026-09-15T16:01:56.709393Z",
  "updated_at": "2026-09-15T16:01:58.115702Z",
  "pending_plan_change": null,
  "current_period_start": "2026-09-15T16:01:56.709393Z",
  "current_period_end": "2026-10-15T16:01:56.709393Z"
}

Use this endpoint for win-back campaigns. Calling it returns a CANCELED or COMPLETED subscription to ACTIVE — or to TRIALING when a trial phase covers the reactivated cycle — keeping the same id and its full payment history. No successor subscription is ever created and previous_subscription_id is never set by this call. No charge is made on the call itself.

Allowlisted organizations onlyReactivation is gated per organization, and this is checked before the subscription’s status. If your calls return 409 "Subscription reactivation is not enabled for this organization.", contact your Yuno representative to have it enabled.

Which subscriptions can be reactivated

Current `status`	Result
`CANCELED`	Reactivated.
`COMPLETED`	Reactivated, if billing cycles remain — see When the billing cycles are used up below.
Any other status	`409` `INVALID_SUBSCRIPTION_STATUS`, naming the current status in `current_status`. A `PAUSED` subscription is resumed with Resume Subscription instead.

409 — status is not CANCELED or COMPLETED

{
  "code": "INVALID_SUBSCRIPTION_STATUS",
  "messages": [
    "Only a CANCELED or COMPLETED subscription can be reactivated."
  ],
  "current_status": "ACTIVE"
}

A subscription whose availability.finish_at has already passed is refused with 400 INVALID_DATE, whatever its status:

400 — availability window already closed

{
  "code": "INVALID_DATE",
  "messages": [
    "The subscription can not be resume due to a conflict with the availability dates. Please update availability dates and try again if you want to keep using the subscription"
  ]
}

When the billing cycles are used up

A COMPLETED subscription that used every cycle in billing_cycles.total is refused with 409 INVALID_SUBSCRIPTION_STATUS:

409 — no billing cycles left

{
  "code": "INVALID_SUBSCRIPTION_STATUS",
  "messages": [
    "The subscription exhausted its 1 billing cycles. Send billing_cycles.total greater than 1 in the reactivate body."
  ],
  "current_status": "COMPLETED"
}

Send billing_cycles.total with a value higher than the current one to raise the limit and reactivate in the same call. This does not create a successor — it raises the limit on the same subscription, keeping its id and history intact:

Raise the limit and reactivate

{
  "billing_cycles": { "total": 24 }
}

Sending billing_cycles.total:

Condition	Result
Not greater than the current total	`400` `BAD_REQUEST` — `"billing_cycles.total must be greater than the current total (N)."`
The subscription has no billing cycle limit at all	`400` `BAD_REQUEST` — `"billing_cycles.total cannot be set on a subscription without a billing cycle limit."`
Not a positive integer	`400` `BAD_REQUEST` — `"billing_cycles.total must be a positive integer."`

Sending billing_cycles.total for a subscription that still has cycles left is accepted the same way: it raises the limit, it is not restricted to exhausted subscriptions. An explicit billing_cycles.total: null is treated the same as omitting the field — the current total is left unchanged.

Choosing the next billing date

billing_cycle_behavior is the same axis used on resume and on plan changes.

{ "billing_cycle_behavior": "KEEP" }

// billing_cycles.next_at -> unchanged while it is still in the future,
// otherwise rolled forward to its next future occurrence

{ "billing_cycle_behavior": "RESTART" }

// billing_cycles.next_at -> the reactivation instant plus the subscription's frequency
// frequency.monthly_billing_day -> stamped to the day of the reactivation,
// on a monthly subscription that had none

No charge is made on the call either way. An invalid value returns 400 BAD_REQUEST — "billing_cycle_behavior must be one of KEEP, RESTART." Reactivate has no gateway-side validation of its own: the same text comes back unchanged through the gateway.

RESTART and the monthly billing dayOn a monthly subscription that had no frequency.monthly_billing_day set, RESTART stamps it to the day of the reactivation — the same rule Update Subscription and Resume Subscription apply. A subscription that already declares a billing day keeps it.

The payment method

The vaulted payment method is revalidated before the subscription is reactivated. If it is no longer enrolled, the call returns 400 PAYMENT_METHOD_STATUS_INVALID and the subscription is not modified — the payment method check runs before the status write:

400 — payment method no longer enrolled

{
  "code": "PAYMENT_METHOD_STATUS_INVALID",
  "messages": [
    "The payment method is a state that does not allow payments to be made."
  ]
}

What reactivation clears

Reactivating a subscription clears:

cancellation_time
cancellation_source
ending_time
reason
any scheduled cancellation (cancel_scheduled)
any pause that was scheduled to end on its own — a reactivated subscription never carries pause_until

The subscription.reactivate webhook fires once, carrying the reactivated subscription.

Errors

HTTP	`code`	When
`409`	`INVALID_SUBSCRIPTION_STATUS`	Reactivation is not enabled for the organization.
`409`	`INVALID_SUBSCRIPTION_STATUS`	The subscription’s status is not `CANCELED` or `COMPLETED`.
`409`	`INVALID_SUBSCRIPTION_STATUS`	The subscription used up every billing cycle in `billing_cycles.total` and the request did not raise it.
`400`	`INVALID_DATE`	`availability.finish_at` has already passed.
`400`	`BAD_REQUEST`	`billing_cycles.total` is not greater than the current total, is sent on a subscription with no cycle limit, or is not a positive integer.
`400`	`BAD_REQUEST`	`billing_cycle_behavior` is not `KEEP` or `RESTART`.
`400`	`BAD_REQUEST`	An unrecognized top-level key, caught by the gateway’s own JSON binding before the call reaches the engine — `"Bad request"`
`400`	`BAD_REQUEST`	A key other than `total` inside `billing_cycles`, forwarded raw to the engine and refused there — `"Unknown field(s): foo."`
`400`	`PAYMENT_METHOD_STATUS_INVALID`	The vaulted payment method is no longer enrolled.
`400`	`OPERATION_IN_PROCESS`	Another write against the same subscription is still in progress — `"Operation over the same subscription is already in process. Try again in a few seconds."`

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

required

The unique identifier of a subscription.

Body

application/json

billing_cycle_behavior

enum<string>

RESTART re-anchors the next charge to now plus the subscription's frequency (and stamps frequency.monthly_billing_day on a monthly subscription that had none). KEEP or omitted: the stored anchor is left untouched while it is still in the future, otherwise rolled forward to its next future occurrence. No charge is made on the call either way.

Available options:

KEEP,

RESTART

Example:

"RESTART"

billing_cycles

object

Raises the subscription's cycle limit so it can be reactivated. Only the nested total is allowed.

Show child attributes

Response

200

string

Example:

"7304911d-5df9-429e-8488-ad41abea1a4c"

name

string

Example:

"sub_001"

description

string | null

Example:

"streaming service"

account_id

string

Example:

"2404911d-5df9-429e-8488-ad41abea1a4b"

country

string

The subscription's country (ISO 3166-1 alpha-2).

Example:

"US"

merchant_reference

string

Example:

"001_marzo_23"

soft_descriptor

string | null

Example:

"ACME SUBSCRIPTION"

status

string

Example:

"ACTIVE"

amount

object

Show child attributes

frequency

object

Show child attributes

billing_cycles

object

Show child attributes

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

customer_payer

object

Show child attributes

payment_method

object

Show child attributes

availability

object

Show child attributes

retries

object | null

The retry policy applied when a recurring charge is declined. See Retries.

Show child attributes

trial_period

object

Show child attributes

metadata

object[] | null

Show child attributes

additional_data

object | null

The optional order enrichment sent at creation, echoed back. See The Subscription Object for its full shape.

initial_payment_validation

boolean

Whether the subscription waited for its first payment to succeed before activating. false by default.

Example:

false

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

created_at

string

Example:

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

updated_at

string

Example:

"2023-12-16T21:00:54.786342Z"

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

curl --request POST \
  --url https://api-sandbox.y.uno/v1/subscriptions/{subscription_id}/reactivate \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "billing_cycle_behavior": "RESTART"
}
'

{
  "id": "7304911d-5df9-429e-8488-ad41abea1a4c",
  "name": "SUB-111 merchant reactivate subject",
  "account_id": "2404911d-5df9-429e-8488-ad41abea1a4b",
  "country": "CO",
  "description": null,
  "merchant_reference": "pa-sub111-1789488115936-594232",
  "status": "ACTIVE",
  "amount": {
    "currency": "COP",
    "value": 45000
  },
  "frequency": {
    "type": "MONTH",
    "value": 1
  },
  "billing_cycles": {
    "total": 6,
    "current": 2,
    "paid": 0,
    "next_at": "2026-10-15T16:01:56.709393Z"
  },
  "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": "615803391389209",
      "usage": "USED"
    }
  },
  "availability": {
    "start_at": "2026-09-15T16:01:56.709393Z",
    "finish_at": null
  },
  "retries": {
    "retry_on_decline": false,
    "amount": 6,
    "strategy": "SMART",
    "schedule": null,
    "stop_on_hard_decline": null,
    "cancel_on_exhausted_retries": null
  },
  "metadata": null,
  "additional_data": null,
  "trial_period": {
    "billing_cycles": 1,
    "amount": {
      "value": 0,
      "currency": ""
    }
  },
  "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": "2026-09-15T16:01:56.709393Z",
  "updated_at": "2026-09-15T16:01:58.115702Z",
  "pending_plan_change": null,
  "current_period_start": "2026-09-15T16:01:56.709393Z",
  "current_period_end": "2026-10-15T16:01:56.709393Z"
}

​Which subscriptions can be reactivated

​When the billing cycles are used up

​Choosing the next billing date

​The payment method

​What reactivation clears

​Errors

Authorizations

Path Parameters

Body

Response

Which subscriptions can be reactivated

When the billing cycles are used up

Choosing the next billing date

The payment method

What reactivation clears

Errors