API Reference

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": "2024-12-21T11:46:27Z",
    "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": "2024-12-21T11:46:27Z",
      "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": "2024-12-21T11:46:27Z",
    "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": "2024-12-21T11:46:27Z",
    "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."
}

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": "2024-12-21T11:46:28Z",
    "active_interval_started_at": "2024-12-21T11:46:28Z",
    "active_interval_finishes_at": "2024-12-21T11:46:28Z",
    "cancelled_at": null,
    "created_at": "2024-12-21T11:46:28Z",
    "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": "2024-12-21T11:46:28Z",
      "active_interval_started_at": "2024-12-21T11:46:28Z",
      "active_interval_finishes_at": "2024-12-21T11:46:28Z",
      "cancelled_at": null,
      "created_at": "2024-12-21T11:46:28Z",
      "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."
}
Pin Payments acknowledges the Traditional Owners and Custodians of the Country throughout Australia and recognises their continuing connection to land, water and community.
We pay our respects to Aboriginal and Torres Strait Islander cultures, and to Elders past and present.