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.

Members

Members replace customers as the representation of your publication's potential, current, and past subscribers.

The member object

{
  "id": "memb_1CUCgU9jUQcdovHnXd638m",
  "email": "[email protected]",
  "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

GET /2023-04-11/members

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

Response

{
  "objects": [
    {
      "id": "memb_1CUCgU9jUQcdovHnXd638m",
      "email": "[email protected]",
      "name": "Jane Doe",
      "newsletter_slugs": ["example-newsletter"],
      "plan_slug": "example-plan"
    },
    {
      "id": "memb_1CUCgigLsKNJdFw3nmsrHk",
      "email": "[email protected]",
      "name": "John Doe",
      "newsletter_slugs": [],
      "plan_slug": null
    }
  ],
  "next_page": "Y3VzXzFCeEVtM1I1bjRQU1lVN3ZwZWFpY3E"
}

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

Customers

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

The customer object

{
  "id": "cus_1BxEmDZEfaMhFQxkysiGtm",
  "email": "[email protected]",
  "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

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": "[email protected]",
      "name": "Jane Doe",
      "newsletter_slugs": ["example-newsletter"],
      "plan_slug": "example-plan",
      "activation_url": null
    },
    {
      "id": "cus_1BxEm4QKh4Rb5v6Qvu2THx",
      "email": "[email protected]",
      "name": "John Doe",
      "newsletter_slugs": [],
      "plan_slug": null,
      "activation_url": 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='[email protected]'

Response

{
  "id": "cus_1BxEmDZEfaMhFQxkysiGtm",
  "email": "[email protected]",
  "name": null,
  "newsletter_slugs": [],
  "plan_slug": null,
  "activation_url": 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 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 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 plan_id=plan_1CAYdcXnjeh3QDz5MZVPVu \
  -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 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 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.