> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Subscription
**Subscription Completion**
The fields `billing_cycles` and `availability.finish_at` have an impact on each other. If both are completed during the subscription creation, it will transition to the `COMPLETED` state upon reaching the nearest event defined in these fields, whether it is the billing cycle or the corresponding `finish_at`.
**Credential Usage for Previous CIT**
If you create a CIT payment (e.g. Apple Pay or card) *before* creating the subscription and pass the resulting vaulted token into the subscription, you **must** include `store_credentials.usage` to indicate whether this is the first or a subsequent use. Without this, rebills will be treated as CITs and declined by the provider.
Required payload for new subscriptions:
```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
"payment_method": {
"type": "CARD",
"vaulted_token": "{{vaulted_token}}",
"card": {
"store_credentials": {
"usage": "USED"
}
}
}
}
```
Refer to the [HTTP Response Codes](/reference/response-codes) section for details on possible error outcomes.
## OpenAPI
````yaml openapi/subscriptions/create-subscription.json POST /subscriptions
openapi: 3.1.0
info:
title: subscription
version: 1.0.2
servers:
- url: https://api-sandbox.y.uno/v1
security:
- sec0: []
sec1: []
paths:
/subscriptions:
post:
summary: Create Subscription
operationId: create-subscription
parameters:
- in: header
name: x-idempotency-key
schema:
type: string
default: '{$randomUUID}'
description: >-
A unique identifier for the request. Must be different each time
(UUID). See [authentication](/reference/authentication#idempotency).
requestBody:
content:
application/json:
schema:
type: object
required:
- name
- account_id
- country
- amount
- payment_method
properties:
name:
type: string
description: The subscription plan name (MAX 255; MIN 3).
description:
type: string
description: The subscription plan description (MAX 255; MIN 3).
account_id:
type: string
description: >-
The unique identifier of the account that will have the
subscription plan available to use (UUID, 36 chars).
merchant_reference:
type: string
description: Identification of the subscription plan (MAX 255; MIN 3).
country:
type: string
description: >-
The subscription's country (MAX 2; MIN 2; [ISO
3166-1](/reference/country-reference)).
amount:
type: object
description: >-
Specifies the `amount` object, with the value of each
subscription payment and the used currency.
required:
- currency
- value
properties:
currency:
type: string
description: >-
The currency used to make the payment (MAX 3; MIN 3;
[ISO 4217](/reference/country-reference)).
value:
type: number
description: >-
The value of each payment of the subscription (multiple
of 0.0001).
format: float
additional_data:
type: object
description: >-
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.
properties:
order:
type: object
description: Specifies the order object.
properties:
items:
type: array
description: Specifies the item's object.
items:
properties:
id:
type: string
description: >-
The unique identifier of the item (MAX 255;
MIN 3).
name:
type: string
description: The name of the item (MAX 255; MIN 3).
quantity:
type: integer
description: The quantity of the item.
format: int32
unit_amount:
type: number
description: >-
The unit amount of the item (multiple of
0.0001).
category:
type: string
description: >-
The category of the item. Check the Item
category reference.
enum:
- 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
brand:
type: string
description: The brand of the item (MAX 255; MIN 3).
sku_code:
type: string
description: >-
The stock keeping unit (SKU) of the item (MAX
255; MIN 3).
manufacture_part_number:
type: string
description: The manufacture part number of the item.
type: object
frequency:
type: object
description: >-
Specifies the `frequency` object. Defines the billing
frequency for the subscription. Including type and value.
required:
- type
properties:
type:
type: string
description: >-
The type of interval the subscription will have in time
(DAY, WEEK, MONTH). If not set, defaults to MONTH.
enum:
- DAY
- WEEK
- MONTH
value:
type: integer
description: >-
The value between each interval. Min 1. Defaults to 1 if
not set.
format: int32
billing_cycles:
type: object
description: >-
Specifies the `billing_cycles` object. Defines the number of
charges associated to the subscription.
properties:
total:
type: integer
description: >-
The total number of billing cycles for the subscription
(MIN 1).
format: int32
customer_payer:
type: object
description: >-
Specifies the `customer_payer` object to identify the
customer.
properties:
id:
type: string
description: The unique identifier of the customer (UUID, 36 chars).
payment_method:
type: object
description: >-
Specifies the `payment_method` object. Currently, only card
is available as a payment method using previously enrolled
cards (`vaulted_token`)
required:
- type
properties:
type:
type: string
description: Payment method type.
enum:
- CARD
vaulted_token:
type: string
description: The vaulted token (UUID, 36 chars).
card:
type: object
properties:
installments:
type: integer
description: The number of installments (MAX 50; MIN 1).
network_transaction_id:
type: string
description: >-
The ID provided by Visa/Mastercard in the response
of the initial payment (MAX 256; MIN 1).
store_credentials:
type: object
description: Specifies the credential usage for the card.
properties:
usage:
type: string
description: >-
Indicates whether this is the first or a
subsequent use. Required if a CIT payment was
created before the subscription.
enum:
- FIRST
- USED
trial_period:
type: object
description: Specifies the trial period object
properties:
billing_cycles:
type: integer
description: >-
The amount of cycles the trial period will have in time.
If not set, defaults to 1 (MIN 1).
format: int32
amount:
type: object
description: Amount to be discounted for the trial period
required:
- currency
- value
properties:
currency:
type: string
description: >-
The currency used to make the payment (MAX 3; MIN 3;
[ISO 4217](/reference/country-reference)).
value:
type: number
description: >-
The value of each payment of the subscription
(multiple of 0.0001).
format: float
availability:
type: object
description: >-
Specifies the `availability` object. Defines a date interval
based on starting and ending dates when the subscription is
available to use.
properties:
start_at:
type: string
description: >-
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.
format: date-time
finish_at:
type: string
description: >-
The end date until the subscription plan will be
available to use. If not defined, the subscription does
not have an expiration date.
format: date-time
metadata:
type: array
description: >-
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.
items:
properties:
key:
type: string
description: The metadata key (MAX 48).
value:
type: string
description: The metadata key value (MAX 512).
type: object
retries:
type: object
description: >-
Specified the 'retries' object. If we need to retry declined
transactions in Yuno and the amount if necessary
properties:
retry_on_decline:
type: boolean
description: >-
If we should retry a payment or not after a first
decline. False by default.
amount:
type: integer
description: >-
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).
format: int32
strategy:
type: string
description: >-
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).
enum:
- DEFAULT
- CUSTOM_SCHEDULE
schedule:
type: array
description: >-
Object that define the schedule strategy for each retry
event, the amounts of objects should match the amount of
retries defined.
items:
properties:
attempt:
type: number
description: Number of the retry attempt
delay_seconds:
type: number
description: >-
Specifies the amount of seconds between each
retry.
type: object
stop_on_hard_decline:
type: boolean
description: >-
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:
type: boolean
description: >-
Flag to identify if the subscription should wait for the
first payment in order to continue. False by default.
billing_date:
type: object
description: >-
Specifies the `billing_date` object. Defines the type of
date use for the subscription logic. Mutually exclusive with
the frequency object.
properties:
type:
type: string
description: >-
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:
type: integer
description: >-
[Conditional] The day of the month to charge the
subscription if type is DAY. Default is 1. Range 1 - 31.
subscription_agreement_id:
type: string
description: >-
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).
examples:
Subscription:
value:
name: Test Subscription
description: Subscription Test
merchant_reference: subscription-ref-merchant-AA01
account_id: 493e9374-510a-4201-9e09-de669d75f256
country: CL
amount:
currency: CLP
value: 15000
frequency:
type: MONTH
value: 1
billing_cycles:
total: 12
customer_payer:
id: a1d3b664-e32a-4508-9da1-9ede3e62a60c
payment_method:
type: CARD
vaulted_token: d4aa3586-def2-4705-b7cd-fe064bb764e6
card:
installments: 3
availability:
start_at: '2024-11-01T00:00:00Z'
trial_period:
billing_cycles: 1
amount:
currency: CLP
value: 0
metadata:
- key: plan
value: gold
responses:
'200':
description: '200'
content:
application/json:
examples:
CREATE SUBSCRIPTION:
value:
id: 0c7fed3e-ee0d-4d34-9547-778be4ec0798
name: Test Subscription
account_id: 493e9374-510a-4201-9e09-de669d75f256
country: US
description: Subscription Test
merchant_reference: subscription-ref-merchant-AA01
status: ACTIVE
amount:
currency: USD
value: 15000
frequency:
type: MONTH
value: 1
billing_cycles:
total: 12
current: 1
next_at: '2024-09-30T12:04:23.265393Z'
customer_payer:
id: a1d3b664-e32a-4508-9da1-9ede3e62a60c
payment_method:
type: CARD
vaulted_token: d4aa3586-def2-4705-b7cd-fe064bb764e6
availability:
start_at: '2024-09-30T12:04:23.265393Z'
finish_at: null
trial_period:
billing_cycles: 1
amount:
value: 0
currency: ''
metadata: null
created_at: '2024-09-30T12:04:23.265372Z'
updated_at: '2024-09-30T12:04:23.265372Z'
schema:
type: object
properties:
id:
type: string
example: 0c7fed3e-ee0d-4d34-9547-778be4ec0798
name:
type: string
example: Test Subscription
account_id:
type: string
example: 493e9374-510a-4201-9e09-de669d75f256
country:
type: string
example: US
description:
type: string
example: Subscription Test
merchant_reference:
type: string
example: subscription-ref-merchant-AA01
status:
type: string
example: ACTIVE
amount:
type: object
properties:
currency:
type: string
example: USD
value:
type: integer
example: 15000
default: 0
frequency:
type: object
properties:
type:
type: string
example: MONTH
value:
type: integer
example: 1
default: 0
billing_cycles:
type: object
properties:
total:
type: integer
example: 12
default: 0
current:
type: integer
example: 1
default: 0
next_at:
type: string
example: '2024-09-30T12:04:23.265393Z'
customer_payer:
type: object
properties:
id:
type: string
example: a1d3b664-e32a-4508-9da1-9ede3e62a60c
payment_method:
type: object
properties:
type:
type: string
example: CARD
vaulted_token:
type: string
example: d4aa3586-def2-4705-b7cd-fe064bb764e6
availability:
type: object
properties:
start_at:
type: string
example: '2024-09-30T12:04:23.265393Z'
finish_at: {}
trial_period:
type: object
properties:
billing_cycles:
type: integer
example: 1
default: 0
amount:
type: object
properties:
value:
type: integer
example: 0
default: 0
currency:
type: string
example: ''
metadata: {}
subscription_agreement_id:
type: string
example: sa_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa
created_at:
type: string
example: '2024-09-30T12:04:23.265372Z'
updated_at:
type: string
example: '2024-09-30T12:04:23.265372Z'
'400':
description: '400'
content:
application/json:
examples:
Result:
value: |-
{
Refer to the HTTP Response Codes section for more details: 'https://docs.y.uno/reference/response-codes'
}
summary: Result
deprecated: false
components:
securitySchemes:
sec0:
type: apiKey
in: header
name: public-api-key
x-default:
sec1:
type: apiKey
in: header
name: private-secret-key
x-default:
````