> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plude.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Introduction to subscription

# Subscription

The `subscription` define a contract between a `customer` and a set of chargeable items. A `subscription` define a minimum term, defined by a `start date`. Any subscription without an `end date` is referred as an *evergreen* subscription.

Evergreen subscriptions never renew, and continue to bill until they are cancelled. The alternative, a termed `subscription`, hold an additional date, the `end date`. Termed subscription renew on a cycle.

Use the following snippet to create an evergreen subscription:

```bash theme={null}
curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer {your_token_here}" \
     -H "X-environment: {your_environment_id_here}" \
     -H "X-version: 2022-03" \
     -d '{ "customerId": "{your_customer_id_here}", "currency": "eur", "start" : "2022-01-01" }' \
     https://api.plude.io/subscriptions/
```

You will get a response as follows:

```json theme={null}
{
    "Id" : "b56a179f-d408-4788-a899-a4fa3dcf8087",
    "CustomerId" : "{your_customer_id_here",
    "Currency" : "eur",
    "Start" : "2022-01-01"
}
```

## Properties of a subscription

| **property** | **description**                                                                                                                | **mandatory** |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| handle       | A unique reference to the subscription. If not provided when creating the subscription, Plude automatically assigns a new one. | yes           |
| term date    | Start date of the current period.                                                                                              | yes           |
| term end     | End date of the current period if the subscription is termed.                                                                  | no            |
| auto renewal | Only valid for termed subscriptions. If true, the renewal process is automatic.                                                | no            |
| currency     | Describes the currency used for the subscription. `Price` must have a currency matching                                        | yes           |
| description  | A short description of for the subscription.                                                                                   | no            |

## Subscription renewals

For termed subscriptions, renewals happen on the `end date` if `auto renewal` is true. The renewal process is automatic at which the `start date` becomes the `end date` and the `end date` is moved forward with the same period. In addition, a notification event is sent and any renewal trigger items are billed immediately. You can always retrieve the first start date from `historic start`.

# Subscription items

A `subscription` may hold none or more billable items. These are called `subscriptionItem` and they bind the subscription with `price` and a `product`.

In the following chapter, we will learn how to apply changes to `subscriptionItem`.