# Endpoint reference

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** <mark style="color:red;">Required conditionally</mark>\
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** <mark style="color:red;">Required</mark>\
The ID of the customer who should own this subscription.

`plan_id` **string** <mark style="color:red;">Required</mark>\
The ID of the plan that this subscription should be for.

`price_id` **string** <mark style="color:red;">Required conditionally</mark>\
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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pliro.co/api/endpoint-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.