> ## 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.
# Update Subscription
**Subscription Transition**
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`.
**Retroactive Credential Update**
If you have existing subscriptions that are failing rebills because of missing credential usage (e.g. from an initial CIT payment), you can use this `PATCH` endpoint to add the `store_credentials` object retroactively to fix the issue.
## OpenAPI
````yaml openapi/subscriptions/update-subscription.json PATCH /subscriptions/{id}
openapi: 3.1.0
info:
title: subscription
version: 1.0.2
servers:
- url: https://api-sandbox.y.uno/v1
security:
- sec0: []
sec1: []
paths:
/subscriptions/{id}:
patch:
summary: Update Subscription
operationId: update-subscription
parameters:
- name: id
in: path
description: The unique identifier of the subscription.
schema:
type: string
required: true
requestBody:
content:
application/json:
schema:
type: object
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 (MAX 64 ; MIN 36).
merchant_reference:
type: string
description: Identification of the subscription plan (MAX 255; MIN 3).
country:
type: string
description: The subscription's country.
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
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, always MONTH by default.
enum:
- DAY
- WEEK
- MONTH
value:
type: integer
description: >-
The value between each interval the subscription will
have in time. The system will use the default value of 1
if not set.
format: int32
monthly_billing_day:
type: integer
description: >-
The day of the month when billing is processed. (MAX 31;
MIN 1)
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.
format: int32
customer_payer:
type: object
description: >-
Specifies the `customer_payer` object to identify the
customer.
required:
- id
properties:
id:
type: string
description: The unique identifier of the customer (MAX 255; MIN 3).
payment_method:
type: object
description: >-
Specifies the `payment_method` object. Currently, only card
as available as payment methods. You can use the card
`token`, the `vaulted_token` or the card information using
through the card object.
properties:
type:
type: string
description: Payment method type.
enum:
- CARD
vaulted_token:
type: string
description: 'The vaulted token (MAX: 64; MIN: 36).'
card:
type: object
description: Specifies the card object.
properties:
verify:
type: boolean
description: >-
Using `amount` = 0 and `verify` = true, you can
verify the user´s card without authorizing a real
amount.
card_data:
type: object
description: Specifies the card data object.
properties:
number:
type: string
description: >-
Card’s number without any separators. (MAX 19;
MIN 8) - only available for PCI certified
merchants.
expiration_month:
type: integer
description: >-
Card’s expiration month - MM (MAX 2; MIN 2) -
only available for PCI certified merchants
format: int32
expiration_year:
type: integer
description: >-
Card’s expiration year in the YYYY format (MAX
4; MIN 4) - only available for PCI certified
merchants
format: int32
security_code:
type: integer
description: >-
Card’s security code (MAX 4; MIN 3) - only
available for PCI certified merchants.
format: int32
holder_name:
type: string
description: >-
Cardholder’s full name as it appears on the card
(MAX 26; MIN 3) - only available for PCI
certified merchants
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
'':
type: string
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
retries:
type: object
description: >-
Specified the 'retries' object. If we need to retry declined
transactions in Yuno and the amount if necessary. If
modified, the retries will apply to the next payment intent.
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 completion. If not set, or higher than 7, 7 will
be defined as default. Max: 7
format: int32
metadata:
type: object
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. Individual keys can be
unset by posting an empty value to them. All keys can be
unset by posting an empty value to metadata.
properties:
key:
type: string
description: >-
Object title that represents the key-value pair inside
the metadata (MAX 48 ; MIN 1).
value:
type: string
description: Object value for the key defined (MAX 512 ; MIN 1).
responses:
'200':
description: '200'
content:
application/json:
examples:
UPDATE 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
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: {}
metadata: {}
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'
}
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:
````