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:

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.

Customers

Customers represent your publication's potential, current, and past subscribers.

The customer object

{
  "id": "cus_1BxEmDZEfaMhFQxkysiGtm",
  "email": "[e-mail]",
  "name": "Jane Doe",
  "newsletter_slugs": ["example-newsletter"],
  "plan_slug": "example-plan"
}

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.

List all customers

GET /2023-04-11/customers

curl -G $PLIRO_API_BASE_URL/2023-04-11/customers \
  -u "$PLIRO_API_KEY:" \
  -d limit=2

Response

{
  "objects": [
    {
      "id": "cus_1BxEmDZEfaMhFQxkysiGtm",
      "email": "[e-mail]",
      "name": "Jane Doe",
      "newsletter_slugs": ["example-newsletter"],
      "plan_slug": "example-plan"
    },
    {
      "id": "cus_1BxEm4QKh4Rb5v6Qvu2THx",
      "email": "[e-mail]",
      "name": "John Doe",
      "newsletter_slugs": [],
      "plan_slug": null
    }
  ],
  "next_page": "Y3VzXzFCeEVtM1I1bjRQU1lVN3ZwZWFpY3E"
}

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 of customer objects or an error.

Create a customer

POST /2023-04-11/customers

curl $PLIRO_API_BASE_URL/2023-04-11/customers \
  -u "$PLIRO_API_KEY:" \
  --data-urlencode email='[e-mail]'

Response

{
  "id": "cus_1BxEmDZEfaMhFQxkysiGtm",
  "email": "[e-mail]",
  "name": null,
  "newsletter_slugs": [],
  "plan_slug": null
}

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 Required conditionally A code that can be used to add an email address to this customer via the customer activation flow. Required unless email is provided.

Returns

A customer object or an error.

Subscriptions

Subscriptions allow charging customers on a recurring basis.

The subscription object

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

POST /2023-04-11/subscriptions

curl $PLIRO_API_BASE_URL/2023-04-11/subscriptions \
  -u "$PLIRO_API_KEY:" \
  -d customer_id=cus_1BxEmDZEfaMhFQxkysiGtm \
  -d price_id=price_1CAYdeEnWTYzneWDJxYb6A

Response

{
  "id": "sub_1CAYdVkJ4hgBkAUrugKwaj",
  "status": "active",
  "customer_id": "cus_1BxEmDZEfaMhFQxkysiGtm",
  "plan_id": "plan_1CAYdcXnjeh3QDz5MZVPVu",
  "price_id": "price_1CAYdeEnWTYzneWDJxYb6A",
  "complimentary": false
}

Parameters

customer_id string Required The ID of the customer who should own this subscription.

plan_id string Required conditionally The ID of the plan that this subscription should be for. Required when complimentary is true.

price_id string Required conditionally The ID of the price that should dictate the cost and recurrence interval of this subscription. Required when complimentary is false.

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 or an error.

Cancel a subscription

POST /2023-04-11/subscriptions/:id/cancel

curl $PLIRO_API_BASE_URL/2023-04-11/subscriptions/sub_1CAYdVkJ4hgBkAUrugKwaj/cancel \
  -u "$PLIRO_API_KEY:"

Response

{
  "id": "sub_1CAYdVkJ4hgBkAUrugKwaj",
  "status": "canceled",
  "customer_id": "cus_1BxEmDZEfaMhFQxkysiGtm",
  "plan_id": "plan_1CAYdcXnjeh3QDz5MZVPVu",
  "price_id": "price_1CAYdeEnWTYzneWDJxYb6A",
  "complimentary": false
}

Parameters

No parameters.

Returns

A subscription object or an error.