# 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](https://docs.pliro.co/pagination#the-page-object) of member objects or an [error](https://docs.pliro.co/api/errors).

## 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](https://docs.pliro.co/pagination#the-page-object) of customer objects or an [error](https://docs.pliro.co/api/errors).

### 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](https://docs.pliro.co/api/errors).

## 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](https://docs.pliro.co/api/errors).

### 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](https://docs.pliro.co/api/errors).