Create Subscription
Creates a recurring subscription plan with billing cycles, trial periods, and stored payment credentials.
vaulted_token you already hold. If the customer is signing up and paying at the same time, you can instead send a subscription block on Create Payment — one call charges the card and creates the subscription from that same charge. That route is documented for frictionless card payments only. See Start a subscription with the first payment.Setting a refund rule
refund_rule can be set at creation to configure how a CUSTOM refund is sized when a later cancel request carries no refund_amount of its own:
PERCENT and FIXED are exclusive: a PERCENT rule carries only percent (0–100), a FIXED rule only amount. A FIXED rule’s amount.currency must equal the subscription’s own currency.
It can be changed or cleared later on Update Subscription, and is described on the Subscription object. See Cancel Subscription for how it is used. Available to organizations enabled for it; contact Yuno — for others, sending refund_rule is silently ignored and nothing is stored.Authorizations
Headers
A unique identifier for the request. Must be different each time (UUID). See authentication.
Body
The subscription plan name (MAX 255; MIN 3).
The unique identifier of the account that will have the subscription plan available to use (UUID, 36 chars).
The subscription's country (MAX 2; MIN 2; ISO 3166-1).
Specifies the customer_payer object to identify the customer. Required. Note that validation errors on this object name the field customer_payer.code, not customer_payer.id — for example 400 BAD_REQUEST ("customer_payer.code field is required") when it is omitted.
Specifies the payment_method object. Supported types are CARD, PAYPAL_ENROLLMENT and PIX_AUTOMATIC, all using previously enrolled payment methods (vaulted_token)
The subscription plan description (MAX 255; MIN 3).
Identification of the subscription plan (MAX 255; MIN 3).
Statement descriptor shown on the cardholder's bank statement. When set, it is persisted on the subscription and propagated to every rebill payment 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.
255Specifies the amount object, with the value of each subscription payment and the used currency. Mutually exclusive with plan_id — send exactly one of the two.
The unique identifier of a plan to subscribe this customer to. Mutually exclusive with amount — send exactly one of the two. Omit trial_period and billing_date when set: both are inherited from the plan and the request is rejected with 400 BAD_REQUEST if you send them. Also omit frequency — it's inherited from the plan too, but sending it anyway is not rejected: it's silently ignored and overridden by the plan's frequency. If the plan has its own retry configuration, also omit retries: the subscription inherits the plan's retries, and sending both is rejected with 400 INVALID_PARAMETERS.
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.
Specifies the frequency object. Defines the billing frequency for the subscription. Including type and value.
Specifies the billing_cycles object. Defines the number of charges associated to the subscription. If omitted, the subscription has no cycle limit and keeps billing until it is canceled or reaches availability.finish_at, if one is set.
Specifies the trial period object
Specifies the availability object. Defines a date interval based on starting and ending dates when the subscription is available to use.
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.
Specified the 'retries' object. If we need to retry declined transactions in Yuno and the amount if necessary. With plan_id, send retries only when the plan has no retry configuration of its own. If the plan defines retries, the subscription inherits them and a request that also sends retries is rejected with 400 INVALID_PARAMETERS.
Flag to identify if the subscription should wait for the first payment in order to continue. False by default.
Specifies the billing_date object. Defines the type of date use for the subscription logic. Mutually exclusive with the frequency object.
Links this subscription to the initial payment created with the same agreement ID. Used for tracking, reconciliation, and chargeback handling. Must exactly match the subscription_agreement_id sent in payment_method.detail.card.stored_credentials.subscription_agreement_id on the originating payment (MAX 255).
Configures the refund rule used to resolve a later CUSTOM cancel refund when that cancel request sends no refund_amount of its own. Available to organizations enabled for it; contact Yuno.
Response
201
"0c7fed3e-ee0d-4d34-9547-778be4ec0798"
"Test Subscription"
"493e9374-510a-4201-9e09-de669d75f256"
"US"
"Subscription Test"
"subscription-ref-merchant-AA01"
"ACME SUBSCRIPTION"
"ACTIVE"
Only present when the subscription is linked to a plan.
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.
Only present when this subscription was created by a plan change (switching an existing subscription to a different plan).
Only present on plan-linked subscriptions.
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.
"sa_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa"
"2024-09-30T12:04:23.265372Z"
"2024-09-30T12:04:23.265372Z"
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.
"2023-01-16T20:00:00.912480Z"
End of the billing period the subscription is currently in. Equal to billing_cycles.next_at. Always returned together with current_period_start.
"2023-02-16T20:00:00.786342Z"
Only present on subscriptions billed on a fixed date instead of a frequency; mutually exclusive with frequency.
The optional order enrichment sent at creation, echoed back. See The Subscription Object for its full shape.
Whether the subscription waited for its first payment to succeed before activating. false by default.
false
Free-form reason for the subscription's current status, when one was recorded; null otherwise.
"merchant request"
How many days before the next billing date the subscription.close_to_renewal webhook is sent. null means no renewal notification is sent.
3
When the subscription was canceled. Only set once it reaches CANCELED; null otherwise.
"2023-12-16T20:46:54.786342Z"
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.
"MERCHANT"
When the subscription completed or expired. Only set once it reaches COMPLETED; null otherwise.
"2024-12-16T20:46:54.786342Z"
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.
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.
"2023-03-16T20:00:00.786342Z"
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.
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.
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.
"2026-10-15T15:54:22.780166Z"
null when no cancellation is pending.
null when refund was NONE or omitted. Present on the cancel response and on every later read once computed.
Present only when the current billing cycle is PAST_DUE and has not settled.