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.promotion with an id or a code to apply a promotion that is attached to the plan. The first charge carries the discount. The subscription must be on a plan that has the promotion attached. The subscription stores its own copy of the promotion, which is not edited afterwards. See Promotions on subscription plans.AUTOMATIC promotion attached to the plan applies on its own when the subscription is created on that plan. If the request also sends a promotion, the larger discount wins; the two do not stack.Promotion errors
Creating a subscription withpromotion can fail with the codes below. In each case, nothing is created.
AUTOMATIC promotion attached to the plan is handled differently. If it cannot be applied, because it is disabled, expired, or has no uses left, the subscription is created without it, and the request still succeeds. The same happens when the promotions service does not find the attached promotion. Only a 503 or 504 stops the creation.
Refer to the HTTP Response Codes section for details on possible error outcomes.
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's country (MAX 2; MIN 2; ISO 3166-1).
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.
255The 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.
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.
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).
Applies a promotion attached to the plan this subscription is created on. Send exactly one of id or code. The promotion starts with the subscription and discounts the first charge. If it cannot be applied (it is not attached to the plan, has expired, is disabled, has not started, or has no uses left), the request is rejected and nothing is created. If the plan also has an automatic promotion, the larger discount on the first charge applies, and the promotion you send wins a tie. See Promotions on subscription plans.
Response
201
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"
The retry policy applied when a recurring charge is declined. See Retries.
The optional order enrichment sent at creation, echoed back. See The Subscription Object for its full shape.
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"