API Reference
Status PageDashboardBook a Demo
Start typing to search…

The Subscription Object

Attributes

This object represents a subscription that can be associated with a customer.

id string
The unique identifier of the subscription (MAX 64 ; MIN 36).
Example: 7304911d-5df9-429e-8488-ad41abea1a4c

name string
The subscription name (MAX 255; MIN 3).
Example: sub_001

description string
The subscription description (MAX 255; MIN 3).
Example: Servicio de streaming

account_id string
The unique identifier of the account that will have the subscription plan available to use (MAX 64 ; MIN 36).
Example: 2404911d-5df9-429e-8488-ad41abea1a4b

merchant_reference string
Identification of the subscription plan (MAX 255; MIN 3).
Example: 001_marzo_23

country string
The subscription's country.
Example: CO

status enum
Status of the subscription.
Possible values:

  • ACTIVE=The subscription has been created with an associated customer and is already active.
  • PAUSED=The subscription has been paused and can be reactivated.
  • COMPLETED=The subscription is completed because it reached the end date and time.
  • CANCELED=Subscription canceled.

amount object

Specifies the subscription amount object, with the value and currency.

currency enum
The currency used to make the payment (MAX 3; MIN 3; ISO 4217).
Possible enum values: Check the Country reference.

value number
The payment amount (multiple of 0.0001).
Example: 12100.00

frequency object

The frequency defined for the payment subscription.
If not set, defaults are MONTH for type and 1 for value.

type enum
The type of interval the subscription will have in time (DAY, WEEK, MONTH). If not set, always MONTH by default.
Possible enum values: DAY, MONTH, or YEAR.

value int
The value between each interval the subscription will have in time. If not set, always 1 by default.
Example: 1

billing_cycles object

Specifies the billing_cycles object.

total number
Total amount of billing cycles.
Example: 10

current number
Value of the current billing cycle.
Example: 2

next_at Timestamp
The date of the next payment for the subscription.
Example: 2023-02-16T20:00:00.786342Z

billing_date object

[Optional] Specifies the billing_date object. Mutually exclusive with the frequency object.

type number
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.
Example: PLAN_CREATION_DATE

day number
The day of the month to charge the subscription if the type is set to DAY. Always 1 by default.
Example: 2

customer_payer object

Specifies the customer_payer object.

id* string
The unique identifier of the customer (MAX 255; MIN 3).
Example: 3t04911d-5df9-429e-8488-ad41abea1a2c

payment_method array of objects

Specifies the payment_method object.

type enum
Type of the payment method.
Possible enum values: CARD

token string
The one-time use payment method token provided by Yuno SDK (MAX 64; MIN 36).
Example: 9104911d-5df9-429e-8488-ad41abea1a4b

vaulted_token string
The vaulted token of the stored payment method (MAX: 64; MIN: 36).
Example: 6104911d-5df9-429e-8488-ad41abea1a4b

card object

Specifies the card object.

verify boolean
Using amount = 0 and verify = true, you can verify the user's card without authorizing a real amount.
Possible values: ture or false.

card_data object

Specifies the card_data object.

number string
Card's number without any separators (MAX 19; MIN 8) - only available for PCI certified merchants.
Example: 4507990000000010

expiration_month number
Card's expiration month - MM (MAX 2; MIN 2) - only available for PCI certified merchants.
Example: 10

expiration_year number
Card's expiration year - YYYY (MAX 4; MIN 4) - only available for PCI certified merchants.
Example: 2025

security_code number
Card's security code (MAX 4; MIN 3) - only available for PCI certified merchants.
Example: 123

holder_name string
Cardholder's full name as it appears on the card (MAX 26; MIN 3) - only available for PCI certified merchants.
Example: JOHN DOE

trial_period object

Specifies the trial_period object.

billing_cycles number
Total amount of billing cycles the free_trial should apply to.
Example: 1

amount object

Amount to be discounted for the trial period.

currency string
The currency used to make the trial period. (ISO 4217 MAX 3; MIN 3).
Example: COP

value number
Card's expiration month - MM (MAX 2; MIN 2) - only available for PCI certified merchants.
Example: 10

availability object

Specifies the availability object. The dates that the subscription will be available. If null the start date will be the day of the creation and it will not have a finish date.

start_at Timestamp
The start date that the subscription will be available to use.
Example: 2024-01-16T00:00:00.786342Z

finish_at Timestamp
The end date until the subscription will be available to use.
Example: 2024-05-26T20:00:00.786342Z

retries object

Specifies the retries object. If we need to retry declined transactions in Yuno and the amount if necessary.

retry_on_decline bool
If we should retry a payment or not after a first decline. False by default..
Example: TRUE

amount number
The number of retries that the subscription plan will have to completion. If not set, or higher than 7, 7 will be defined as default. Max: 7
Example: 4

initial_payment_validation bool
Flag to identify if the subscription should wait for the first payment in order to continue. False by default. MIN 27).
Example: false

metadata object

Specifies the metadata object. Set of key-value pairs that you can be attached to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

key string
Object title that represents the key-value pair inside the metadata (MAX 48; MIN 1).
Example: sub_ext_id

value string
Object value for the key defined (MAX 512; MIN 1).
Example: AA001

payments Array of strings

Specifies the payments array.

id* string
The unique identifier of the payment (MAX 64 ; MIN 36).
Example: 5104911d-5df9-229e-8468-bd41abea1a4s

created_at Timestamp
Subscription creation date and time (ISO 8601 MAX 27; MIN 27).
Example: 2023-12-16T20:46:54.786342Z

updated_at Timestamp
Subscription last updated date and time (ISO 8601 MAX 27; MIN 27).
Example: 2023-12-16T21:00:54.786342Z

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 array of object

Specifies the item's object.

id string
The unique identifier of the item (MAX 255; MIN 3).
Example: 3214

name string
The name of the item (MAX 255; MIN 3).
Example: iPhone 12 Pro Max

quantity int
The quantity of the item (MAX 999; MIN 1).
Example: 1

unit_amount float
The unit amount of the item (multiple of 0.0001).
Example: 550

category string
The category of the item (MAX 255; MIN 3).
Possible values: Check the Item category list.

brand string
The brand of the item (MAX 255; MIN 3).
Example: Apple

sku_code string
The stock keeping unit (SKU) of the item (MAX 255; MIN 3).
Example: A2342

manufacture_part_number string
The manufacture part number of the item (MAX 255; MIN 3).
Example: 345621234