# Create subscription

A subscription is the union between a plan and a customer. The main characteristic of this contract is that it has a configured a payment method and is the basis for creating the invoices. You can also create a subscription without a plan.

**POST** `/preapproval`

## Request parameters

- `preapproval_plan_id` (string, optional)
  Unique subscription plan identifier. This is an optional field. Our model supports creating subscriptions with or without a plan. If you create a subscription with plan we will take the recurring settings from the plan to create the subscription. When you edit the plan we will update the subscriptions. Decide your best model depending on your business.

- `reason` (string, optional)
  It is a short description that the subscriber will see during the checkout process and in the notifications. It is only required for subscriptions without a plan.

- `external_reference` (string, optional)
  Reference to sync with your system. This is a free text field to help you with your integration to link the entities. It is only required for subscriptions without a plan.

- `payer_email` (string, optional)
  To create a subscription, it must be linked to an email address, which allows us to assign a unique identifier to the subscriber. For subscriptions without an associated plan, we validate during the payment process that the entered email matches the payer's email. If the email addresses don't match, the payment will be rejected.

- `card_token_id` (string, optional)
  The card_token_id is a token generated from the form submission with the capture of payment data. When submitting the form, a token is generated that securely represents the card data. To get the card_token_id, see the "Card" section of the Checkout API documentation and follow all the steps up to the "Initialize payment form" section. It is through this form that it will be possible to obtain the card_token_id.

- `auto_recurring` (object, optional)
  Configuration data for recurrence.

  - `auto_recurring.frequency` (number, optional)
  Indicates the frequency value. Along with frequency_type they define the invoice cycle that a subscription will have.

  - `auto_recurring.frequency_type` (string, optional)
  Indicates the type of frequency. Along with frequency they define the invoice cycle that a subscription will have.
Possible enum values:

  - `days`
  Indicate a frequency in units of days

  - `months`
  Indicate a frequency in units of months

  - `auto_recurring.start_date` (string, optional)
  Date from which the subscription will be active and we start collecting invoices. It is important to emphasize that this field only works together with the `end_date` parameter, that is, if `end_date` is not filled in, the `start_date` will not be recognized.

  - `auto_recurring.end_date` (string, optional)
  Date until which the subscription will be active and we will stop charging invoices.

  - `auto_recurring.transaction_amount` (number, optional)
  Amount we will charge on each invoice.

  - `auto_recurring.currency_id` (string, optional)
  ID of the currency used in the payment.

- `back_url` (string, optional)
  Successful return url. Use this setting to redirect your customers to your site after our checkout. It is only required for subscriptions without a plan.

- `status` (string, optional)
  When you create a subscription, you can make it pending or authorized. Authorized status requires you to indicate a payment method. A pending subscription is waiting for a payment method, that the customer can load into our checkout or by your integration tokenizing a card and adding it to the subscription.
Possible enum values:

  - `pending`
  Subscription without a payment method.

  - `authorized`
  Subscription with a payment method.

## Response parameters

- `id` (string, optional)
  Unique subscription identifier.

- `version` (number, optional)
  How many times the subscription was modified.

- `application_id` (number, optional)
  Unique ID that identifies your application/integration. One of the keys in the pair that make up the credentials that identify an application/integration in your account.

- `collector_id` (number, optional)
  Unique ID that identifies your user as a seller. This ID matches your User ID in our ecosystem.

- `preapproval_plan_id` (string, optional)
  Unique plan identifier.

- `reason` (string, optional)
  It is a short description that the subscriber will see during the checkout process and in the notifications. It is only required for subscriptions without a plan.

- `external_reference` (string, optional)
  Reference to sync with your system. This is a free text field to help you with your integration to link the entities.

- `back_url` (string, optional)
  Successful return URL. Use this setting to redirect your customers to your site after our checkout.

- `init_point` (string, optional)
  URL to checkout to add or modify payment method.

- `auto_recurring` (object, optional)
  Configuration data for recurrence.

  - `auto_recurring.frequency` (number, optional)
  Indicates the frequency value. Together with frequency_type they define the invoice cycle that a subscription will have.

  - `auto_recurring.frequency_type` (string, optional)
  Indicates the type of frequency. Together with frequency they define the invoice cycle that a subscription will have.
Possible enum values:

  - `days`
  Indicate a frequency in units of days.

  - `months`
  Indicate a frequency in units of months

  - `auto_recurring.start_date` (string, optional)
  Date from which the subscription will be active and we start collecting invoices.

  - `auto_recurring.end_date` (string, optional)
  Date until which the subscription will be active and we will stop charging invoices.

  - `auto_recurring.currency_id` (string, optional)
  ID of the currency used in the payment.

  - `auto_recurring.transaction_amount` (number, optional)
  Amount we will charge on each invoice.

  - `auto_recurring.free_trial` (object, optional)
  Free trial data.

  - `auto_recurring.free_trial.frequency` (number, optional)
  Indicates the frequency value. Together with frequency_type they define the invoice cycle that a subscription will have.

  - `auto_recurring.free_trial.frequency_type` (string, optional)
  Indicates the type of frequency. Together with frequency they define the invoice cycle that a subscription will have.
Possible enum values:

  - `days`
  Indicate a frequency in units of days.

  - `months`
  Indicate a frequency in units of months.

- `payer_id` (number, optional)
  Unique customer identifier. This is created from the email you used to create the subscription.

- `card_id` (number, optional)
  Unique identifier to retrieve data from the card used as a payment method.

- `payment_method_id` (number, optional)
  Payment method configured.

- `next_payment_date` (string, optional)
  Date of the next payment debit.

- `date_created` (string, optional)
  Creation date.

- `last_modified` (string, optional)
  Date of last modification.

- `status` (string, optional)
  Status
Possible enum values:

  - `pending`
  Subscription without a payment method

  - `authorized`
  Subscription with a payment method.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | 400 | Bad-Request |
| 401 | 401 | Unauthorized |
| 403 | 403 | Forbidden |
| 500 | 500 | Error |

## Request example

### cURL

```bash
curl -X POST \
  'https://api.mercadopago.com/preapproval' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "preapproval_plan_id": "2c938084726fca480172750000000000",
  "reason": "Yoga classes",
  "external_reference": "YG-1234",
  "payer_email": "test@testuser.com",
  "card_token_id": "e3ed6f098462036dd2cbabe314b9de2a",
  "auto_recurring": {
  "frequency": 1,
  "frequency_type": "months",
  "start_date": "2020-06-02T13:07:14.260Z",
  "end_date": "2022-07-20T15:59:52.581Z",
  "transaction_amount": 10,
  "currency_id": "COP"
  },
  "back_url": "https://www.mercadopago.com.ar",
  "status": "authorized"
  }'
```

## Response example

```json
{
  "id": "2c938084726fca480172750000000000",
  "version": 0,
  "application_id": 1234567812345678,
  "collector_id": 100200300,
  "preapproval_plan_id": "2c938084726fca480172750000000000",
  "reason": "Yoga classes.",
  "external_reference": 23546246234,
  "back_url": "https://www.mercadopago.com.ar",
  "init_point": "https://www.mercadopago.com.ar/subscriptions/checkout?preapproval_id=2c938084726fca480172750000000000",
  "auto_recurring": {
  "frequency": 1,
  "frequency_type": "months",
  "start_date": "2020-06-02T13:07:14.260Z",
  "end_date": "2022-07-20T15:59:52.581Z",
  "currency_id": "ARS",
  "transaction_amount": "24.50",
  "free_trial": {
  "frequency": 1,
  "frequency_type": "months"
  }
  },
  "payer_id": 123123123,
  "card_id": 123123123,
  "payment_method_id": "master",
  "next_payment_date": "2022-01-01T11:12:25.892-04:00",
  "date_created": "2022-01-01T11:12:25.892-04:00",
  "last_modified": "2022-01-01T11:12:25.892-04:00",
  "status": "pending"
}
```