---
title: "Create Subscription"
method: POST
path: "/subscriptions"
---

# Create Subscription

`POST /subscriptions`

## Headers

- `x-idempotency-key` string

## Request body

- object
  - `name` string, required — The subscription plan name (MAX 255; MIN 3).
  - `description` string — The subscription plan description (MAX 255; MIN 3).
  - `account_id` string, required — The unique identifier of the account that will have the subscription plan available to use (UUID, 36 chars).
  - `merchant_reference` string — Identification of the subscription plan (MAX 255; MIN 3).
  - `soft_descriptor` string — 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.
  - `country` string, required — The subscription's country (MAX 2; MIN 2; [ISO 3166-1](/reference/country-reference)).
  - `amount` object, required — Specifies 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.
    - `currency` string, required — The currency used to make the payment (MAX 3; MIN 3; [ISO 4217](/reference/country-reference)).
    - `value` number, float, required — The value of each payment of the subscription (multiple of 0.0001).
  - `plan_id` string — The unique identifier of a [plan](/reference/plans/the-plan-object) 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.
  - `additional_data` object — 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.
    - `order` object — Specifies the order object.
      - `items` object[] — Specifies the item's object.
        - `id` string — The unique identifier of the item (MAX 255; MIN 3).
        - `name` string — The name of the item (MAX 255; MIN 3).
        - `quantity` integer — The quantity of the item.
        - `unit_amount` number — The unit amount of the item (multiple of 0.0001).
        - `category` 'art' | 'baby' | 'coupons' | 'beauty_&_personal_care' | 'donations' | 'computing' | 'books' | 'grocery_&_gourmet_food' | 'cameras' | 'video_games' | 'television' | 'car_electronics' | 'electronics' | 'automotive' | 'toys_&_games' | 'musical_instruments' | 'handmade' | 'garden_&_outdoor' | 'entertainment' | 'industrial_&_scientific' | 'fashion' | 'games' | 'pet_supplies' | 'home' | 'musical' | 'phones' | 'services' | 'learnings' | 'tickets' | 'travels' | 'virtual_goods' | 'others' — The category of the item. Check the Item category reference.
        - `brand` string — The brand of the item (MAX 255; MIN 3).
        - `sku_code` string — The stock keeping unit (SKU) of the item (MAX 255; MIN 3).
        - `manufacture_part_number` string — The manufacture part number of the item.
  - `frequency` object — Specifies the `frequency` object. Defines the billing frequency for the subscription. Including type and value.
    - `type` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR', required — The type of interval the subscription will have in time (DAY, WEEK, MONTH, YEAR). If not set, defaults to MONTH.
    - `value` integer — The value between each interval. Min 1. Defaults to 1 if not set.
  - `billing_cycles` object — Specifies the `billing_cycles` object. Defines the number of charges associated to the subscription.
    - `total` integer — The total number of billing cycles for the subscription (MIN 1).
  - `customer_payer` object — Specifies the `customer_payer` object to identify the customer.
    - `id` string — The unique identifier of the customer (UUID, 36 chars).
  - `payment_method` object, required — Specifies the `payment_method` object. Currently, only card is available as a payment method using previously enrolled cards (`vaulted_token`)
    - `type` 'CARD', required — Payment method type.
    - `vaulted_token` string — The vaulted token (UUID, 36 chars).
    - `card` object
      - `installments` integer — The number of installments (MAX 50; MIN 1).
      - `network_transaction_id` string — The ID provided by Visa/Mastercard in the response of the initial payment (MAX 256; MIN 1).
      - `store_credentials` object — Specifies the credential usage for the card.
        - `usage` 'FIRST' | 'USED' — Indicates whether this is the first or a subsequent use. Required if a CIT payment was created before the subscription.
  - `trial_period` object — Specifies the trial period object
    - `billing_cycles` integer — The amount of cycles the trial period will have in time. If not set, defaults to 1 (MIN 1).
    - `amount` object — Amount to be discounted for the trial period
      - `currency` string, required — The currency used to make the payment (MAX 3; MIN 3; [ISO 4217](/reference/country-reference)).
      - `value` number, float, required — The value of each payment of the subscription (multiple of 0.0001).
  - `availability` object — Specifies the `availability` object. Defines a date interval based on starting and ending dates when the subscription is available to use.
    - `start_at` string, date-time — The start date that the subscription plan will be available to use. If not set, the subscription is available from the moment it is created.
    - `finish_at` string, date-time — The end date until the subscription plan will be available to use. If not defined, the subscription does not have an expiration date.
  - `metadata` object[] — 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.
    - `key` string — The metadata key (MAX 48).
    - `value` string — The metadata key value (MAX 512).
  - `retries` object — Specified the 'retries' object. If we need to retry declined transactions in Yuno and the amount if necessary
    - `retry_on_decline` boolean — If we should retry a payment or not after a first decline. False by default.
    - `amount` integer — The number of retries that the subscription plan will have to complete. 6 will be defined as default if this value is not set or higher than 6. (MAX 6).
    - `strategy` 'DEFAULT' | 'CUSTOM_SCHEDULE' — The retry strategy. Allowed values: DEFAULT (the fixed retry schedule; not ML-based timing) or CUSTOM_SCHEDULE (uses the per-attempt schedule array you provide).
    - `schedule` object[] — Object that define the schedule strategy for each retry event, the amounts of objects should match the amount of retries defined.
      - `attempt` number — Number of the retry attempt
      - `delay_seconds` number — Specifies the amount of seconds between each retry.
    - `stop_on_hard_decline` boolean — When true, the retry schedule stops for the current billing cycle after a hard decline. The subscription remains ACTIVE and billing advances to the next cycle; no subscription is canceled or paused and no subscription webhook is emitted.
  - `initial_payment_validation` boolean — Flag to identify if the subscription should wait for the first payment in order to continue. False by default.
  - `billing_date` object — Specifies the `billing_date` object. Defines the type of date use for the subscription logic. Mutually exclusive with the frequency object.
    - `type` string — The type of billing_date the subscription will have in time. PREPAID, POSTDATE, DAY. If not set, the creation date for the plan will be set by default.
    - `day` integer — [Conditional] The day of the month to charge the subscription if type is DAY. Default is 1. Range 1 - 31.
  - `subscription_agreement_id` string — 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).

## Response `200`

200

- object
  - `id` string
  - `name` string
  - `account_id` string
  - `country` string
  - `description` string
  - `merchant_reference` string
  - `soft_descriptor` string
  - `status` string
  - `amount` object
    - `currency` string
    - `value` integer
  - `frequency` object
    - `type` string
    - `value` integer
  - `billing_cycles` object
    - `total` integer
    - `current` integer
    - `next_at` string
  - `customer_payer` object
    - `id` string
  - `payment_method` object
    - `type` string
    - `vaulted_token` string
  - `availability` object
    - `start_at` string
    - `finish_at` unknown
  - `trial_period` object
    - `billing_cycles` integer
    - `amount` object
      - `value` integer
      - `currency` string
  - `metadata` unknown
  - `plan_id` string — Only present when the subscription is linked to a plan.
  - `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.
  - `previous_subscription_id` string — Only present when this subscription was created by a plan change (switching an existing subscription to a different plan).
  - `current_phase` string — Only present on plan-linked subscriptions.
  - `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.
    - `order` integer
    - `type` string — Always TRIAL — the terminal REGULAR phase is never in this array.
    - `name` string
    - `amount` object
      - `currency` string
      - `value` number
    - `frequency` object
      - `type` string
      - `value` integer
    - `start_cycle` integer
    - `end_cycle` integer
  - `subscription_agreement_id` string
  - `created_at` string
  - `updated_at` string

## Other responses

- `400` — 400

---

[API](https://skmtc.net/y/apis/ai-caller.md) · [All operations](https://skmtc.net/y/apis/ai-caller/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/y/ai-caller/revisions/05b629819b49/schema)