> ## Documentation Index
> Fetch the complete documentation index at: https://yuno-3979e326-fix-create-subscription-card-usage.mintlify.site/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. If not set, or higher than 7, 7 will be defined as default. Max: 7

      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="payments" type="Array of strings">
  Specifies the payments array.

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