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

# Plans API Reference

## Overview

The Plans API enables developers to programmatically create and manage plans on the Publica.la store. This API is designed for store administrators and integration partners who need to automate plan creation and management.

:::info
Make sure you generated the **api_token** on your store. More info in the [API Authentication guide](overview.md)
:::

## Endpoint Reference

| Endpoint                                                                  | Method | Description                              |
| ------------------------------------------------------------------------- | ------ | ---------------------------------------- |
| [/integration-api/v1/dashboard/plans](#create)                            | POST   | Create a new plan                        |
| [/integration-api/v1/dashboard/plans](#retrieve)                          | GET    | Retrieve plans (with optional filtering) |
| [/integration-api/v1/dashboard/plans/(plan_id)](#update)                  | PUT    | Update an existing plan                  |
| [/integration-api/v1/dashboard/plans/collections](#assigning-collections) | GET    | Get available collections for plans      |

## Create a Plan {#create}

Create a new plan on your store.

**Endpoint:** `POST /integration-api/v1/dashboard/plans`

### Request Body

| Parameter           | Type              | Description                                                         |
| ------------------- | ----------------- | ------------------------------------------------------------------- |
| type                | string            | Plan type, either `recurring` or `prepaid`                          |
| name                | string            | Display name of the plan                                            |
| details             | string            | HTML description of the plan                                        |
| duration            | integer, nullable | Duration in months (required for prepaid plans, null for recurring) |
| recommended         | boolean           | Whether to mark this plan as recommended                            |
| private             | boolean           | Whether this plan is private (accessible only via direct link)      |
| assigns_collections | boolean           | Whether this plan is associated with specific collections           |
| concurrency_limit   | integer           | Maximum number of concurrent sessions allowed                       |
| collections         | array             | List of collection names to assign to this plan                     |
| download_files      | boolean           | Whether to allow content downloads on this plan                     |
| prices              | object            | Price mapping by currency code (amount in cents)                    |
| free_trial          | boolean           | Whether this plan offers a free trial                               |
| free_trial_days     | integer           | Number of free trial days (required if free_trial is true)          |

### Example Request

```json
{
  "type": "recurring",
  "name": "Demo Plan",
  "details": "<div><!--block-->This is the description of the Demo Plan</div>",
  "duration": null,
  "recommended": true,
  "private": false,
  "assigns_collections": true,
  "concurrency_limit": "1",
  "collections": ["Prepaid"],
  "download_files": false,
  "prices": {
    "ARS": 0,
    "USD": "1",
    "EUR": 0,
    "MXN": "1",
    "COP": 0,
    "PEN": 0,
    "CLP": 0,
    "AUD": 0,
    "UYU": 0,
    "BOB": 0,
    "PYG": 0,
    "BRL": 0,
    "INR": 0,
    "GTQ": 0,
    "HNL": 0
  },
  "free_trial": true,
  "free_trial_days": "15"
}
```

### Response Codes

| Code  | Description                            |
| :---- | :------------------------------------- |
| `201` | Plan created successfully              |
| `422` | Validation error (details in response) |
| `401` | Unauthorized (invalid API token)       |

## Assigning Collections {#assigning-collections}

To get available collections for assignment to plans:

**Endpoint:** `GET /integration-api/v1/dashboard/plans/collections`

### Example Response

```json
{
  "CODE": "success",
  "data": [
    "Collection 1",
    "Testing Collection 2",
    "Demo Collection",
    "Most Recent",
    "Most Read",
    "For Children"
  ]
}
```

## Retrieve Plans {#retrieve}

Get a list of plans with optional filtering.

**Endpoint:** `GET /integration-api/v1/dashboard/plans/`

### Query Parameters

| Parameter | Type   | Description                 | Example            |
| --------- | ------ | --------------------------- | ------------------ |
| query     | string | Search term to filter plans | `?query='Premium'` |

:::tip
The query parameter searches across plan name, type, and description fields.
:::

### Example Response

```json
{
  "CODE": "success",
  "data": {
    "assigns_collections": true,
    "collections": ["Demo Collection 1", "Demo Collection 2"],
    "concurrency_limit": 1,
    "created_at": "2021-05-21 15:34:36",
    "customer": null,
    "deleted_at": null,
    "details": "This is a plan for educational purposes",
    "download_files": 0,
    "duration": 12,
    "free_trial": 0,
    "free_trial_days": 0,
    "has_geolocalized_prices": false,
    "id": 2696,
    "name": "Test Plan Name",
    "prices": [],
    "private": 1,
    "recommended": false,
    "type": "prepaid",
    "updated_at": "2021-05-21 15:34:36",
    "url": "https://{store_final_domain}/subscribe/2696?signature={random_hash}"
  }
}
```

### Response Codes

| Code  | Description                      |
| :---- | :------------------------------- |
| `200` | Success                          |
| `404` | Object not found                 |
| `401` | Unauthorized (invalid API token) |

## Update a Plan {#update}

Update an existing plan by ID.

**Endpoint:** `PUT /integration-api/v1/dashboard/plans/\(plan_id)`

### Request Body

Same parameters as the [Create](#create) endpoint, plus:

| Parameter   | Type   | Description                             |
| ----------- | ------ | --------------------------------------- |
| customer    | string | Customer information for external plans |
| invoice     | string | Invoice reference for external plans    |
| file_name   | string | Name of file attachment                 |
| upload_file | file   | File attachment for the plan            |

### Example Request

```json
{
  "type": "recurring",
  "name": "Updated Demo Plan",
  "details": "<div><!--block-->This is the updated description</div>",
  "duration": null,
  "recommended": true,
  "private": false,
  "assigns_collections": true,
  "concurrency_limit": "1",
  "collections": ["Prepaid"],
  "download_files": false,
  "customer": "",
  "invoice": "",
  "file_name": "",
  "upload_file": false,
  "prices": {
    "ARS": 0,
    "USD": "1",
    "EUR": 0,
    "MXN": "1"
  },
  "free_trial": true,
  "free_trial_days": "15"
}
```

### Response Codes

| Code  | Description                            |
| :---- | :------------------------------------- |
| `204` | Plan updated successfully              |
| `422` | Validation error (details in response) |
| `404` | Plan not found                         |
| `401` | Unauthorized (invalid API token)       |

## Common Error Scenarios

| Error                   | Description                                   | Solution                                         |
| ----------------------- | --------------------------------------------- | ------------------------------------------------ |
| Invalid collection name | Collection specified in request doesn't exist | Use the /collections endpoint to get valid names |
| Invalid plan type       | Plan type must be 'recurring' or 'prepaid'    | Check value of type parameter                    |
| Missing duration        | Prepaid plans require a duration value        | Add duration parameter for prepaid plans         |
| Pricing error           | Currency codes or amounts are invalid         | Ensure all currency values are valid             |

## Integration Best Practices

1. **Validate collections** before creating plans by calling the collections endpoint
2. **Set appropriate concurrency limits** based on your business model
3. **Consider plan privacy** - use private plans for special offers
4. **Test free trials** thoroughly before deploying to production

## Related API Documentation

- [Orders API](../rest-api-v3/orders/orders-v3-overview.md): Manage orders associated with plans
- [Users API](./users.md): Manage users who subscribe to plans
- [Content API](../rest-api-v3/content/content-v3-overview.md): Manage content assigned to collections