API Reference

Subscriptions API

The subscriptions API allows you to create subscriptions against plans and retrieve the details of existing subscriptions.

POST /subscriptions

Activate a new subscription and returns its details. The customer’s card will immediately be billed the initial plan amount, unless there’s a trial period.

Parameters

plan_token The token of the plan to subscribe to, as returned from the plans API.
customer_token The token of the customer to be subscribed, as returned from the customers API.
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/subscriptions -u your-secret-api-key: \
 -d "plan_token=plan_ZyDee4HNeUHFHC4SpM2idg" \
 -d "customer_token=cus_XZg1ULpWaROQCOT5PdwLkQ" \
 -d "include_setup_fee=false"
201 Created 
{
  "response": {
    "state": "active",
    "next_billing_date": "2024-12-21T12:23:17Z",
    "active_interval_started_at": "2024-12-21T12:23:17Z",
    "active_interval_finishes_at": "2024-12-21T12:23:17Z",
    "cancelled_at": null,
    "created_at": "2024-12-21T12:23:17Z",
    "token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
    "plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "card_token": "card_nytGw7koRg23EEp9NTmz9w"
  }
}

Error Responses

400 invalid_request {...} 
{
  "error": "invalid_resource",
  "error_description": "One or more parameters are missing or invalid.",
  "messages": [
    {
      "param": "plan_token",
      "message": "must be present"
    }
  ]
}
404 resource_not_found {...} 
{
  "error": "resource_not_found",
  "error_description": "No resource was found at this URL."
}

GET /subscriptions

Returns a paginated list of all subscriptions.

Example

curl https://test-api.pinpayments.com/1/subscriptions -u your-secret-api-key:
200 OK 
{
  "response": [
    {
      "state": "active",
      "next_billing_date": "2024-12-21T12:23:17Z",
      "active_interval_started_at": "2024-12-21T12:23:17Z",
      "active_interval_finishes_at": "2024-12-21T12:23:17Z",
      "cancelled_at": null,
      "created_at": "2024-12-21T12:23:17Z",
      "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
  }
}

GET /subscriptions/sub-token

Returns the details of the subscription identified by subscription token.

Example

curl https://test-api.pinpayments.com/1/subscriptions/sub_bZWXhTzHooKpk9FZjQfzqQ -u your-secret-api-key:
200 OK 
{
  "response": {
    "state": "active",
    "next_billing_date": "2024-12-21T12:23:17Z",
    "active_interval_started_at": "2024-12-21T12:23:17Z",
    "active_interval_finishes_at": "2024-12-21T12:23:17Z",
    "cancelled_at": null,
    "created_at": "2024-12-21T12:23:17Z",
    "token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
    "plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "card_token": "card_nytGw7koRg23EEp9NTmz9w"
  }
}

PUT /subscriptions/sub-token

Updates the card associated with a subscription identified by subscription token.

card_token A card token belonging to the customer that will be charged for this subscription. Setting to null will use the customer's default card.

Example

curl https://test-api.pinpayments.com/1/subscriptions/sub_bZWXhTzHooKpk9FZjQfzqQ -u your-secret-api-key: -X PUT \
 -d "card_token=card_nytGw7koRg23EEp9NTmz9w"
200 OK 
{
  "response": {
    "state": "active",
    "next_billing_date": "2024-12-21T12:23:17Z",
    "active_interval_started_at": "2024-12-21T12:23:17Z",
    "active_interval_finishes_at": "2024-12-21T12:23:17Z",
    "cancelled_at": null,
    "created_at": "2024-12-21T12:23:17Z",
    "token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
    "plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "card_token": "card_nytGw7koRg23EEp9NTmz9w"
  }
}

Error Responses

400 invalid_request {...} 
{
  "error": "invalid_resource",
  "error_description": "One or more parameters are missing or invalid.",
  "messages": [
    {
      "param": "card_token",
      "message": "must be present"
    }
  ]
}
404 resource_not_found {...} 
{
  "error": "resource_not_found",
  "error_description": "No resource was found at this URL."
}

DELETE /subscriptions/sub-token

Cancels the subscription identified by subscription token. Subscriptions can only be cancelled if they are in trial or active state.

Example

curl https://test-api.pinpayments.com/1/subscriptions/sub_bZWXhTzHooKpk9FZjQfzqQ -u your-secret-api-key: -X DELETE
200 OK 
{
  "response": {
    "state": "cancelled",
    "next_billing_date": null,
    "active_interval_started_at": "2024-12-21T12:23:17Z",
    "active_interval_finishes_at": "2024-12-21T12:23:17Z",
    "cancelled_at": "2024-12-21T12:23:17Z",
    "created_at": "2024-12-21T12:23:17Z",
    "token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
    "plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
    "customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
    "card_token": "card_nytGw7koRg23EEp9NTmz9w"
  }
}

Error Responses

400 invalid_state {...} 
{
  "error": "invalid_state",
  "error_description": "Cannot cancel subscription when state is cancelled"
}
404 not_found {...} 
{
  "error": "not_found",
  "error_description": "The requested resource could not be found."
}

PUT /subscriptions/sub-token/reactivate

Reactivates the subscription identified by subscription token, returning the details of the subscription.

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/subscriptions/sub_bZWXhTzHooKpk9FZjQfzqQ/reactivate -u your-secret-api-key: -X PUT
200 OK 
{
  "response": {
    "state": "active",
    "next_billing_date": "2024-12-21T12:23:17Z",
    "active_interval_started_at": "2024-12-21T12:23:17Z",
    "active_interval_finishes_at": "2024-12-21T12:23:17Z",
    "cancelled_at": null,
    "created_at": "2024-12-21T12:23:17Z",
    "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 /subscriptions/sub-token/ledger

Fetch the ledger entries relating to a subscription identified by subscription token.

Example

curl https://test-api.pinpayments.com/1/subscriptions/sub_bZWXhTzHooKpk9FZjQfzqQ/ledger -u your-secret-api-key:
200 OK 
{
  "response": [
    {
      "created_at": "2024-12-21T12:23:17Z",
      "type": "credit",
      "amount": 1000,
      "currency": "AUD",
      "annotation": "charge_credit"
    }
  ],
  "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.