> ## 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.

# The Subscription Object

## Attributes

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

<ParamField body="id" type="string">
  The unique identifier of the subscription (MAX 64 ; MIN 36).

  Example: 7304911d-5df9-429e-8488-ad41abea1a4c
</ParamField>

<ParamField body="name" type="string">
  The subscription name (MAX 255; MIN 3).

  Example: sub\_001
</ParamField>

<ParamField body="description" type="string">
  The subscription description (MAX 255; MIN 3).

  Example: Servicio de streaming
</ParamField>

<ParamField body="account_id" type="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
</ParamField>

<ParamField body="merchant_reference" type="string">
  Identification of the subscription plan (MAX 255; MIN 3).

  Example: 001\_marzo\_23
</ParamField>

<ParamField body="country" type="string">
  The subscription's country.

  Example: CO
</ParamField>

<ParamField body="status" type="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.
</ParamField>

<ParamField body="amount" type="object">
  Specifies the subscription amount object, with the value and currency.

  <Expandable title="properties">
    <ParamField body="currency" type="enum">
      The currency used to make the payment (MAX 3; MIN 3; <a href="/reference/country-reference">ISO 4217</a>).

      Possible enum values: Check the <a href="/reference/country-reference">Country reference</a>.
    </ParamField>

    <ParamField body="value" type="number">
      The payment amount (multiple of 0.0001).

      Example: 12100.00
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="frequency" type="object">
  The frequency defined for the payment subscription. If not set, defaults are MONTH for type and 1 for value.

  <Expandable title="properties">
    <ParamField body="type" 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`.
    </ParamField>

    <ParamField body="value" type="int">
      The value between each interval the subscription will have in time. If not set, always 1 by default.

      Example: 1
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="billing_cycles" type="object">
  Specifies the billing\_cycles object.

  <Expandable title="properties">
    <ParamField body="total" type="number">
      Total amount of billing cycles.

      Example: 10
    </ParamField>

    <ParamField body="current" type="number">
      Value of the current billing cycle.

      Example: 2
    </ParamField>

    <ParamField body="next_at" type="Timestamp">
      The date of the next payment for the subscription.

      Example: 2023-02-16T20:00:00.786342Z
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="billing_date" type="object">
  \[Optional] Specifies the billing\_date object. Mutually exclusive with the frequency object.

  <Expandable title="properties">
    <ParamField body="type" 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
    </ParamField>

    <ParamField body="day" type="number">
      The day of the month to charge the subscription if the type is set to DAY. Always 1 by default.

      Example: 2
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="customer_payer" type="object">
  Specifies the customer\_payer object.

  <Expandable title="properties">
    <ParamField body="id*" type="string">
      The unique identifier of the customer (MAX 255; MIN 3).

      Example: 3t04911d-5df9-429e-8488-ad41abea1a2c
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="payment_method" type="array of objects">
  Specifies the payment\_method object.

  <Expandable title="properties">
    <ParamField body="type" type="enum">
      Type of the payment method.

      Possible enum values: `CARD`
    </ParamField>

    <ParamField body="token" type="string">
      The one-time use payment method token provided by Yuno SDK (MAX 64; MIN 36).

      Example: 9104911d-5df9-429e-8488-ad41abea1a4b
    </ParamField>

    <ParamField body="vaulted_token" type="string">
      The vaulted token of the stored payment method (MAX: 64; MIN: 36).

      Example: 6104911d-5df9-429e-8488-ad41abea1a4b
    </ParamField>

    <ParamField body="card" type="object">
      Specifies the card object.

      <Expandable title="properties">
        <ParamField body="verify" type="boolean">
          Using amount = 0 and verify = true, you can verify the user's card without authorizing a real amount.

          Possible values: `true` or `false`.
        </ParamField>

        <ParamField body="card_data" type="object">
          Specifies the card\_data object.

          <Expandable title="properties">
            <ParamField body="number" type="string">
              Card's number without any separators (MAX 19; MIN 8) - only available for PCI certified merchants.

              Example: 4507990000000010
            </ParamField>

            <ParamField body="expiration_month" type="number">
              Card's expiration month - MM (MAX 2; MIN 2) - only available for PCI certified merchants.

              Example: 10
            </ParamField>

            <ParamField body="expiration_year" type="number">
              Card's expiration year - YYYY (MAX 4; MIN 4) - only available for PCI certified merchants.

              Example: 2025
            </ParamField>

            <ParamField body="security_code" type="number">
              Card's security code (MAX 4; MIN 3) - only available for PCI certified merchants.

              Example: 123
            </ParamField>

            <ParamField body="holder_name" type="string">
              Cardholder's full name as it appears on the card (MAX 26; MIN 3) - only available for PCI certified merchants.

              Example: JOHN DOE
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="trial_period" type="object">
  Specifies the trial\_period object.

  <Expandable title="properties">
    <ParamField body="billing_cycles" type="number">
      Total amount of billing cycles the free\_trial should apply to.

      Example: 1
    </ParamField>

    <ParamField body="amount" type="object">
      Amount to be discounted for the trial period.

      <Expandable title="properties">
        <ParamField body="currency" type="string">
          The currency used to make the trial period. (ISO 4217 MAX 3; MIN 3).

          Example: COP
        </ParamField>

        <ParamField body="value" type="number">
          The trial period amount value (multiple of 0.0001).

          Example: 10
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="availability" type="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.

  <Expandable title="properties">
    <ParamField body="start_at" type="Timestamp">
      The start date that the subscription will be available to use.

      Example: 2024-01-16T00:00:00.786342Z
    </ParamField>

    <ParamField body="finish_at" type="Timestamp">
      The end date until the subscription will be available to use.

      Example: 2024-05-26T20:00:00.786342Z
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="retries" type="object">
  Specifies the retries object. If we need to retry declined transactions in Yuno and the amount if necessary.

  <Expandable title="properties">
    <ParamField body="retry_on_decline" type="bool">
      If we should retry a payment or not after a first decline. False by default.

      Example: TRUE
    </ParamField>

    <ParamField body="amount" type="number">
      The number of retries that the subscription plan will have to completion. The maximum equals your environment's configured retry schedule length (6 in production). Values above the cap are clamped to it. Max: 6

      Example: 4
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="initial_payment_validation" type="bool">
  Flag to identify if the subscription should wait for the first payment in order to continue. False by default.

  Example: false
</ParamField>

<ParamField body="metadata" type="object">
  Specifies the metadata object.

  <Expandable title="properties">
    <ParamField body="key" type="string">
      This value serves as a name or identifier for the metadata. Use a descriptive term. (MAX 48; MIN 1).

      Example: sub\_ext\_id
    </ParamField>

    <ParamField body="value" type="string">
      The information you wish to store within the metadata. (MAX 512; MIN 1).

      Example: AA001
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="subscription_agreement_id" type="string">
  Links this subscription to the initial payment created with the same agreement ID. Used for tracking, reconciliation, and chargeback handling (MAX 255).

  The value must exactly match the `subscription_agreement_id` sent in `payment_method.detail.card.stored_credentials.subscription_agreement_id` on the originating payment.

  Example: sa\_6af2dfcd-44c0-4f16-a331-8bed3ed9c9fa
</ParamField>

<ParamField body="payments" type="Array of strings">
  Specifies the payments array.

  <Note>
    This array is currently always empty in webhook payloads. Subscribe to `payment.*` webhooks to track charges.
  </Note>

  <Expandable title="properties">
    <ParamField body="id*" type="string">
      The unique identifier of the payment (MAX 64 ; MIN 36).

      Example: 5104911d-5df9-229e-8468-bd41abea1a4s
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="created_at" type="Timestamp">
  Subscription creation date and time (<a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601</a> MAX 27; MIN 27).

  Example: 2023-12-16T20:46:54.786342Z
</ParamField>

<ParamField body="updated_at" type="Timestamp">
  Subscription last updated date and time (<a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601</a> MAX 27; MIN 27).

  Example: 2023-12-16T21:00:54.786342Z
</ParamField>

<ParamField body="additional_data" type="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.

  <Expandable title="properties">
    <ParamField body="order" type="object">
      Specifies the order object.

      <Expandable title="properties">
        <ParamField body="items" type="array of object">
          Specifies the item's object.

          <Expandable title="properties">
            <ParamField body="id" type="string">
              The unique identifier of the item (MAX 255; MIN 3).

              Example: 3214
            </ParamField>

            <ParamField body="name" type="string">
              The name of the item (MAX 255; MIN 3).

              Example: iPhone 12 Pro Max
            </ParamField>

            <ParamField body="quantity" type="int">
              The quantity of the item (MAX 999; MIN 1).

              Example: 1
            </ParamField>

            <ParamField body="unit_amount" type="float">
              The unit amount of the item (multiple of 0.0001).

              Example: 550
            </ParamField>

            <ParamField body="category" type="string">
              The category of the item (MAX 255; MIN 3).

              Possible values: Check the <a href="/reference/items-category-list">Item category list</a>.
            </ParamField>

            <ParamField body="brand" type="string">
              The brand of the item (MAX 255; MIN 3).

              Example: Apple
            </ParamField>

            <ParamField body="sku_code" type="string">
              The stock keeping unit (SKU) of the item (MAX 255; MIN 3).

              Example: A2342
            </ParamField>

            <ParamField body="manufacture_part_number" type="string">
              The manufacture part number of the item (MAX 255; MIN 3).

              Example: 345621234
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>