# Search subscription plans

Search for subscription plans by different parameters.

**GET** `/preapproval_plan/search`

## Request parameters

### Path

- `status` (string, optional)
  Specifies the status of the plan you want to get.

- `q` (string, optional)
  Free search field.

- `sort` (string, optional)
  Specifies the name of the field by which the results are to be sorted according to a criteria.

- `criteria` (string, optional)
  Specifies the order criteria of the results.

- `offset` (number, optional)
  Specifies the offset of the first item in the collection to return.

- `limit` (number, optional)
  Specifies the maximum number of items to return.

## Response parameters

- `paging` (object, optional)
  Information for pagination of search results.

  - `paging.offset` (number, optional)
  The offset of the first item in the collection to return.

  - `paging.limit` (number, optional)
  The maximum number of entries to return.

  - `paging.total` (number, optional)
  The total number of items in the collection.

- `results` (array, optional)
  The page of items. This will be an empty array if there are no results.

  - `results[].id` (string, optional)
  Unique subscription plan identifier.

  - `results[].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.

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

  - `results[].reason` (string, optional)
  It is a short description that the subscriber will see during the checkout process and in the notifications.

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

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

  - `results[].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.

  - `results[].auto_recurring.repetitions` (number, optional)
  It is optional and is used to create a limited subscription. Indicates the number of times that we will repeat the recurrence cycle. If this param is not defined, subscription does not end until some of the parties cancel it.

  - `results[].auto_recurring.billing_day` (number, optional)
  Day of the month that the subscription will always be charged. It only accepts values between 1 and 28.

  - `results[].auto_recurring.billing_day_proportional` (boolean, optional)
  Charge a proportional amount to the billing day at the time of registration.
Possible enum values:

  - `true`
  Charge a proportional amount based on the days remaining in the next billing cycle. Billing cycles are always calculated on a 30-day basis.

  - `false`
  Charge the amount of the subscription regardless of when in the billing cycle customer subscribe.

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

  - `results[].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.

  - `results[].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.

  - `results[].auto_recurring.free_trial.first_invoice_offset` (number, optional)
  Number of days to collect the first invoice.

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

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

  - `results[].payment_methods_allowed` (object, optional)
  Payment methods enabled at checkout.

  - `results[].payment_methods_allowed.payment_types` (array, optional)
  Payment types allowed in the payment flow.

  - `results[].payment_methods_allowed.payment_types.id` (string, optional)
  Payment type identifier.

  - `results[].payment_methods_allowed.payment_methods` (array, optional)
  Payment methods allowed in the payment flow.

  - `results[].payment_methods_allowed.payment_methods.id` (string, optional)
  Payment method identifier.

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

  - `results[].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.

  - `results[].init_point` (string, optional)
  URL to start the subscription flow.

  - `results[].date_created` (string, optional)
  Creation date.

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

  - `results[].subscribed` (number, optional)
  Number of customers subscribed to the plan.

  - `results[].status` (string, optional)
  Status of the plan.
Possible enum values:

  - `active`
  Plan available to create subscriptions.

  - `canceled`
  Plan not available to create subscriptions.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | 400 | Bad-request |
| 401 | 401 | Unauthorized |
| 500 | 500 | Error |

## Request example

### cURL

```bash
curl -X GET \
  'https://api.mercadopago.com/preapproval_plan/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

## Response example

```json
{
  "paging": {
  "offset": 0,
  "limit": 20,
  "total": 100
  },
  "results": [
  {
  "id": "2c938084726fca480172750000000000",
  "application_id": 1234567812345678,
  "collector_id": 100200300,
  "reason": "Yoga classes",
  "auto_recurring": {
  "frequency": 1,
  "frequency_type": "months",
  "repetitions": 12,
  "billing_day": 10,
  "billing_day_proportional": true,
  "free_trial": {
  "frequency": null,
  "frequency_type": null,
  "first_invoice_offset": null
  },
  "transaction_amount": "24.50",
  "currency_id": "ARS"
  },
  "payment_methods_allowed": {
  "payment_types": {
  "id": null
  },
  "payment_methods": {
  "id": null
  }
  },
  "back_url": "https://www.mercadopago.com.ar",
  "external_reference": "23546246234",
  "init_point": "https://www.mercadopago.com.ar/subscriptions/checkout?preapproval_plan_id=2c938084726fca480172750000000000",
  "date_created": "2022-01-01T11:12:25.892-04:00",
  "last_modified": "2022-01-01T11:12:25.892-04:00",
  "subscribed": 50,
  "status": "active"
  }
  ]
}
```