> For the complete documentation index, see [llms.txt](https://docs.pliro.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pliro.co/api/endpoint-reference.md).
# Endpoint reference
Learn more about Pliro's API endpoints and how to use them.
This page lists all API endpoints sectioned by object type. You can set the following variables in your shell to allow copying and pasting the examples below:
```sh
PLIRO_API_BASE_URL=https://api.plirotest.com # Or api.pliro.co when working with production data.
PLIRO_API_KEY=example-api-key # View and manage API keys in the Pliro Dashboard.
```
## Members
Members replace customers as the representation of your publication's potential, current, and past subscribers.
### The member object
```json
{
"id": "memb_1CUCgU9jUQcdovHnXd638m",
"email": "jane@example.com",
"name": "Jane Doe",
"newsletter_slugs": ["example-newsletter"],
"plan_slug": "example-plan"
}
```
#### Properties
`id` **string**\
A unique identifier for this member.
`email` **string**\
The member's email address.
`name` **nullable string**\
The members's full name.
`newsletter_slugs` **array of strings**\
An array of slugs for newsletters the member subscribes to.
`plan_slug` **nullable string**\
The slug of the plan the member has an active subscription for.
### List all members
{% code title="GET /2023-04-11/members" %}
```sh
curl -G $PLIRO_API_BASE_URL/2023-04-11/members \
-u "$PLIRO_API_KEY:" \
-d limit=2
```
{% endcode %}
{% code title="Response" %}
```json
{
"objects": [
{
"id": "memb_1CUCgU9jUQcdovHnXd638m",
"email": "jane@example.com",
"name": "Jane Doe",
"newsletter_slugs": ["example-newsletter"],
"plan_slug": "example-plan"
},
{
"id": "memb_1CUCgigLsKNJdFw3nmsrHk",
"email": "john@example.com",
"name": "John Doe",
"newsletter_slugs": [],
"plan_slug": null
}
],
"next_page": "Y3VzXzFCeEVtM1I1bjRQU1lVN3ZwZWFpY3E"
}
```
{% endcode %}
#### Parameters
`limit` **integer**\
The maximum number of members to retrieve. Can range from 1 to 100 and defaults to 10.
`page` **string**\
Omit this parameter to request the first page. Use the `next_page` value returned in a previous response to request the next page.
#### Returns
A [page](/api/pagination.md#the-page-object) of member objects or an [error](/api/errors.md).
## Customers
Customers represent your publication's potential, current, and past subscribers.
### The customer object
```json
{
"id": "cus_1BxEmDZEfaMhFQxkysiGtm",
"email": "jane@example.com",
"name": "Jane Doe",
"newsletter_slugs": ["example-newsletter"],
"plan_slug": "example-plan",
"activation_url": null
}
```
#### Properties
`id` **string**\
A unique identifier for this customer.
`email` **nullable string**\
The customer's email address.
`name` **nullable string**\
The customer's full name.
`newsletter_slugs` **array of strings**\
An array of slugs for newsletters the customer subscribe to.
`plan_slug` **nullable string**\
The slug of the plan the customer has an active subscription for.
`activation_url` **nullable string**\
A url to which the customer can be directed to activate their account.
### List all customers
{% code title="GET /2023-04-11/customers" %}
```sh
curl -G $PLIRO_API_BASE_URL/2023-04-11/customers \
-u "$PLIRO_API_KEY:" \
-d limit=2
```
{% endcode %}
{% code title="Response" %}
```json
{
"objects": [
{
"id": "cus_1BxEmDZEfaMhFQxkysiGtm",
"email": "jane@example.com",
"name": "Jane Doe",
"newsletter_slugs": ["example-newsletter"],
"plan_slug": "example-plan",
"activation_url": null
},
{
"id": "cus_1BxEm4QKh4Rb5v6Qvu2THx",
"email": "john@example.com",
"name": "John Doe",
"newsletter_slugs": [],
"plan_slug": null,
"activation_url": null
}
],
"next_page": "Y3VzXzFCeEVtM1I1bjRQU1lVN3ZwZWFpY3E"
}
```
{% endcode %}
#### Parameters
`limit` **integer**\
The maximum number of customers to retrieve. Can range from 1 to 100 and defaults to 10.
`page` **string**\
Omit this parameter to request the first page. Use the `next_page` value returned in a previous response to request the next page.
#### Returns
A [page](/api/pagination.md#the-page-object) of customer objects or an [error](/api/errors.md).
### Create a customer
{% code title="POST /2023-04-11/customers" %}
```bash
curl $PLIRO_API_BASE_URL/2023-04-11/customers \
-u "$PLIRO_API_KEY:" \
--data-urlencode email='jane@example.com'
```
{% endcode %}
{% code title="Response" %}
```json
{
"id": "cus_1BxEmDZEfaMhFQxkysiGtm",
"email": "jane@example.com",
"name": null,
"newsletter_slugs": [],
"plan_slug": null,
"activation_url": null
}
```
{% endcode %}
#### Parameters
`email` **string** Required conditionally\
The customer's email address. Required unless `activation_code` is provided.
`name` **string**\
The customer's full name.
`activation_code` **string**\
A code that can be used to add an email address to this customer via the customer activation flow. Must be unique and at least eight characters long.
#### Returns
A [customer object](#the-customer-object) or an [error](/api/errors.md).
## Subscriptions
Subscriptions allow charging customers on a recurring basis.
### The subscription object
```json
{
"id": "sub_1CAYdVkJ4hgBkAUrugKwaj",
"status": "active",
"customer_id": "cus_1BxEmDZEfaMhFQxkysiGtm",
"plan_id": "plan_1CAYdcXnjeh3QDz5MZVPVu",
"price_id": "price_1CAYdeEnWTYzneWDJxYb6A",
"complimentary": false
}
```
#### Properties
`id` **string**\
A unique identifier for this subscription.
`status` **string**\
Possible values are `active` and `canceled`.
`customer_id` **string**\
The ID of the customer who owns this subscription.
`plan_id` **string**\
The ID of the plan that this subscription is for.
`price_id` **nullable string**\
The ID of the price that dictates the cost and recurrence interval of this subscription.
`complimentary` **boolean**\
Whether or not this subscription is provided to the customer free of charge. If `complimentary` is `true`, then `price_id` will be `null`.
### Create a subscription
{% code title="POST /2023-04-11/subscriptions" %}
```bash
curl $PLIRO_API_BASE_URL/2023-04-11/subscriptions \
-u "$PLIRO_API_KEY:" \
-d customer_id=cus_1BxEmDZEfaMhFQxkysiGtm \
-d plan_id=plan_1CAYdcXnjeh3QDz5MZVPVu \
-d price_id=price_1CAYdeEnWTYzneWDJxYb6A
```
{% endcode %}
{% code title="Response" %}
```json
{
"id": "sub_1CAYdVkJ4hgBkAUrugKwaj",
"status": "active",
"customer_id": "cus_1BxEmDZEfaMhFQxkysiGtm",
"plan_id": "plan_1CAYdcXnjeh3QDz5MZVPVu",
"price_id": "price_1CAYdeEnWTYzneWDJxYb6A",
"complimentary": false
}
```
{% endcode %}
#### Parameters
`customer_id` **string** Required\
The ID of the customer who should own this subscription.
`plan_id` **string** Required\
The ID of the plan that this subscription should be for.
`price_id` **string** Required conditionally\
The ID of the price that should dictate the cost and recurrence interval of this subscription. Required unless `complimentary` is `true`.
`complimentary` **boolean**\
Whether or not this subscription should be provided to the customer free of charge. This parameter defaults to `false`. If `complimentary` is `true`, then `price_id` must be `null`.
#### Returns
A [subscription object](#the-subscription-object) or an [error](/api/errors.md).
### Cancel a subscription
{% code title="POST /2023-04-11/subscriptions/:id/cancel" %}
```bash
curl $PLIRO_API_BASE_URL/2023-04-11/subscriptions/sub_1CAYdVkJ4hgBkAUrugKwaj/cancel \
-u "$PLIRO_API_KEY:"
```
{% endcode %}
{% code title="Response" %}
```json
{
"id": "sub_1CAYdVkJ4hgBkAUrugKwaj",
"status": "canceled",
"customer_id": "cus_1BxEmDZEfaMhFQxkysiGtm",
"plan_id": "plan_1CAYdcXnjeh3QDz5MZVPVu",
"price_id": "price_1CAYdeEnWTYzneWDJxYb6A",
"complimentary": false
}
```
{% endcode %}
#### Parameters
No parameters.
#### Returns
A [subscription object](#the-subscription-object) or an [error](/api/errors.md).