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

Endpoint Reference

Endpoint	Method	Description
/integration-api/v1/dashboard/plans	POST	Create a new plan
/integration-api/v1/dashboard/plans	GET	Retrieve plans (with optional filtering)
/integration-api/v1/dashboard/plans/(plan_id)	PUT	Update an existing plan
/integration-api/v1/dashboard/plans/collections	GET	Get available collections for plans

Create a Plan

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

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

To get available collections for assignment to plans:

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

Example Response

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

Retrieve Plans

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

{
  "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://example.publica.la/subscribe/2696?signature={random_hash}"
  }
}

Response Codes

Code	Description
200	Success
404	Object not found
401	Unauthorized (invalid API token)

Update a Plan

Update an existing plan by ID.

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

Request Body

Same parameters as the 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

{
   "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: Manage orders associated with plans
• Users API: Manage users who subscribe to plans
• Content API: Manage content assigned to collections