Plans API

The plans API allows you to create, modify and examine recurring billing plans.

POST /plans

Creates a new plan and returns its details.

Parameters

name	The plan name
amount	The amount to charge in the currency’s base unit (e.g. cents for AUD, yen for JPY). There is a minimum charge amount for each currency; refer to the documentation on supported currencies.
currency	The three-character ISO 4217 currency code of one of our supported currencies, e.g. `AUD` or `USD`. Default value is `AUD`.
interval	The interval between each subsequent charge made to the customer during the period of subscription. This is an integral value that is interpreted in units specified via the interval_unit parameter.
interval_unit	The unit of measure applied to the interval amount. Valid units are day, week, month, or year.
Optional intervals	The number of intervals before a subscription is automatically cancelled. Default 0 (no limit).
Optional setup_amount	The amount the customer will be charged in the currency's base unit at the start of the first full interval. Default value is 0 (no setup fee).
Optional trial_amount	The amount the customer will be charged in the currency's base unit upon initiating a trial of this plan. Default value is 0 (no trial / free trial).
Optional trial_interval	The interval between the start of a trial period and beginning of the paid subscription proper. Default value is 0 (no trial).
Optional trial_interval_unit	The unit of measure applied to the trial_interval amount. Valid units are day, week, month, or year. Default value is an empty string.
Optional customer_permissions	An array of permissions the customer is allowed to perform. At present this must be an empty array or an array containing "cancel". Default value is ["cancel"].

Example

curl https://test-api.pinpayments.com/1/plans -u your-secret-api-key: \
 -d "name=Coffee Plan" \
 -d "amount=1000" \
 -d "currency=USD" \
 -d "interval=30" \
 -d "interval_unit=day" \
 -d "intervals=6" \
 -d "setup_amount=0" \
 -d "trial_amount=0" \
 -d "trial_interval=7" \
 -d "trial_interval_unit=day" \
 -d "customer_permissions[]=cancel"

201 Created

{
  "response": {
    "name": "Coffee Plan",
    "amount": 1000,
    "currency": "USD",
    "setup_amount": 0,
    "trial_amount": 0,
    "interval": 30,
    "interval_unit": "day",
    "intervals": 6,
    "trial_interval": 7,
    "trial_interval_unit": "day",
    "created_at": "2023-04-01T10:49:15Z",
    "token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_permissions": [
      "cancel"
    ],
    "subscription_counts": {
      "trial": 0,
      "active": 0,
      "cancelling": 0,
      "cancelled": 0
    }
  }
}

Error Responses

422	unprocessable_entity	`{...}` `{ "error": "unprocessable_entity", "error_description": "Validation failure" }`

GET /plans

Returns a paginated list of all plans.

Example

curl https://test-api.pinpayments.com/1/plans -u your-secret-api-key:

200 OK

{
  "response": [
    {
      "name": "Coffee Plan",
      "amount": 1000,
      "currency": "USD",
      "setup_amount": 0,
      "trial_amount": 0,
      "interval": 30,
      "interval_unit": "day",
      "intervals": 0,
      "trial_interval": 7,
      "trial_interval_unit": "day",
      "created_at": "2023-04-01T10:49:15Z",
      "token": "plan_ZyDee4HNeUHFHC4SpM2idg",
      "customer_permissions": [
        "cancel"
      ],
      "subscription_counts": {
        "trial": 0,
        "active": 0,
        "cancelling": 0,
        "cancelled": 0
      }
    }
  ],
  "pagination": {
    "count": 1,
    "per_page": 25,
    "current": 1
  }
}

GET /plans/plan-token

Returns the details of a specified plan.

Example

curl https://test-api.pinpayments.com/1/plans/plan_lfUYEBK14zotCTykezJkfg -u your-secret-api-key:

200 OK

{
  "response": {
    "name": "Coffee Plan",
    "amount": 1000,
    "currency": "USD",
    "setup_amount": 0,
    "trial_amount": 0,
    "interval": 30,
    "interval_unit": "day",
    "intervals": 0,
    "trial_interval": 7,
    "trial_interval_unit": "day",
    "created_at": "2023-04-01T10:49:15Z",
    "token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_permissions": [
      "cancel"
    ],
    "subscription_counts": {
      "trial": 0,
      "active": 0,
      "cancelling": 0,
      "cancelled": 0
    }
  }
}

Error Responses

404	not_found	`{...}` `{ "error": "not_found", "error_description": "The requested resource could not be found." }`

PUT /plans/plan-token

Update the specified plan.

Parameters

Optional name	The plan name
Optional customer_permissions	An array of permissions the customer is allowed to perform. At present this must be an empty array or an array containing "cancel". Default value is ["cancel"].

Example

curl https://test-api.pinpayments.com/1/plans/plan_lfUYEBK14zotCTykezJkfg -u your-secret-api-key: -X PUT \
 -d "name=Updated Coffee Plan" \
 -d "customer_permissions[]=cancel"

200 OK

{
  "response": {
    "name": "Updated Coffee Plan",
    "amount": 1000,
    "currency": "USD",
    "setup_amount": 0,
    "trial_amount": 0,
    "interval": 30,
    "interval_unit": "day",
    "intervals": 0,
    "trial_interval": 7,
    "trial_interval_unit": "day",
    "created_at": "2023-04-01T10:49:15Z",
    "token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_permissions": [
      "cancel"
    ],
    "subscription_counts": {
      "trial": 0,
      "active": 0,
      "cancelling": 0,
      "cancelled": 0
    }
  }
}

Error Responses

404	not_found	`{...}` `{ "error": "not_found", "error_description": "The requested resource could not be found." }`
422	unprocessable_entity	`{...}` `{ "error": "unprocessable_entity", "error_description": "Validation failure" }`

DELETE /plans/plan-token

Deletes a plan and all of its subscriptions. You will not be able to recover this. Plans can only be deleted if they have no running subscriptions.

Example

curl https://test-api.pinpayments.com/1/plans/plan_lfUYEBK14zotCTykezJkfg -u your-secret-api-key: -X DELETE

204 No Content

No response body.

Error Responses

400	cannot_delete_plan	`{...}` `{ "error": "cannot_delete_plan", "error_description": "Cannot delete a plan with active or trial subscriptions" }`
404	not_found	`{...}` `{ "error": "not_found", "error_description": "The requested resource could not be found." }`

400

cannot_delete_plan

{...}

{
  "error": "cannot_delete_plan",
  "error_description": "Cannot delete a plan with active or trial subscriptions"
}

404

not_found

{...}

{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

POST /plans/plan-token/subscriptions

Creates a new subscription to the specified plan

Parameters

customer_token	The token of the customer to be subscribed, as returned from the customers API.
Optional card_token	A card token belonging to the customer that will be charged for this subscription. If omitted the customer's default card is charged.
Optional include_setup_fee	Whether the setup fee should be applied to this subscription. Default value is `true`.

Example

curl https://test-api.pinpayments.com/1/plans/plan_lfUYEBK14zotCTykezJkfg/subscriptions -u your-secret-api-key: \
 -d "customer_token=cus_XZg1ULpWaROQCOT5PdwLkQ" \
 -d "card_token=card_nytGw7koRg23EEp9NTmz9w" \
 -d "include_setup_fee=false"

200 OK

{
  "response": {
    "state": "active",
    "next_billing_date": "2023-04-01T10:49:15Z",
    "active_interval_started_at": "2023-04-01T10:49:15Z",
    "active_interval_finishes_at": "2023-04-01T10:49:15Z",
    "cancelled_at": null,
    "created_at": "2023-04-01T10:49:15Z",
    "token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
    "plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "card_token": "card_nytGw7koRg23EEp9NTmz9w"
  }
}

Error Responses

404	not_found	`{...}` `{ "error": "not_found", "error_description": "The requested resource could not be found." }`

GET /plans/plan-token/subscriptions

Returns a paginated list of subscriptions for a plan

Example

curl https://test-api.pinpayments.com/1/plans/plan_lfUYEBK14zotCTykezJkfg/subscriptions -u your-secret-api-key:

200 OK

{
  "response": [
    {
      "state": "active",
      "next_billing_date": "2023-04-01T10:49:15Z",
      "active_interval_started_at": "2023-04-01T10:49:15Z",
      "active_interval_finishes_at": "2023-04-01T10:49:15Z",
      "cancelled_at": null,
      "created_at": "2023-04-01T10:49:15Z",
      "token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
      "plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
      "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
      "card_token": "card_nytGw7koRg23EEp9NTmz9w"
    }
  ],
  "count": 1,
  "pagination": {
    "count": 1,
    "per_page": 25,
    "current": 1
  }
}

Error Responses

404	not_found	`{...}` `{ "error": "not_found", "error_description": "The requested resource could not be found." }`

API Reference

Plans API

POST /plans

Parameters

Example

GET /plans

Example

GET /plans/plan-token

Example

PUT /plans/plan-token

Parameters

Example

DELETE /plans/plan-token

Example

POST /plans/plan-token/subscriptions

Parameters

Example

GET /plans/plan-token/subscriptions

Example