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"
{
"response": {
"state": "active",
"next_billing_date": "2024-12-11T07:07:18Z",
"active_interval_started_at": "2024-12-11T07:07:18Z",
"active_interval_finishes_at": "2024-12-11T07:07:18Z",
"cancelled_at": null,
"created_at": "2024-12-11T07:07:18Z",
"token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
"plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
"customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"card_token": "card_nytGw7koRg23EEp9NTmz9w"
}
}
Error Responses
400 | invalid_request |
{...}
|
---|---|---|
404 | resource_not_found |
{...}
|
GET /subscriptions
Returns a paginated list of all subscriptions.
Example
curl https://test-api.pinpayments.com/1/subscriptions -u your-secret-api-key:
{
"response": [
{
"state": "active",
"next_billing_date": "2024-12-11T07:07:18Z",
"active_interval_started_at": "2024-12-11T07:07:18Z",
"active_interval_finishes_at": "2024-12-11T07:07:18Z",
"cancelled_at": null,
"created_at": "2024-12-11T07:07:18Z",
"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:
{
"response": {
"state": "active",
"next_billing_date": "2024-12-11T07:07:18Z",
"active_interval_started_at": "2024-12-11T07:07:18Z",
"active_interval_finishes_at": "2024-12-11T07:07:18Z",
"cancelled_at": null,
"created_at": "2024-12-11T07:07:18Z",
"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"
{
"response": {
"state": "active",
"next_billing_date": "2024-12-11T07:07:18Z",
"active_interval_started_at": "2024-12-11T07:07:18Z",
"active_interval_finishes_at": "2024-12-11T07:07:18Z",
"cancelled_at": null,
"created_at": "2024-12-11T07:07:18Z",
"token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
"plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
"customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"card_token": "card_nytGw7koRg23EEp9NTmz9w"
}
}
Error Responses
400 | invalid_request |
{...}
|
---|---|---|
404 | resource_not_found |
{...}
|
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
{
"response": {
"state": "cancelled",
"next_billing_date": null,
"active_interval_started_at": "2024-12-11T07:07:18Z",
"active_interval_finishes_at": "2024-12-11T07:07:18Z",
"cancelled_at": "2024-12-11T07:07:18Z",
"created_at": "2024-12-11T07:07:18Z",
"token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
"plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
"customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"card_token": "card_nytGw7koRg23EEp9NTmz9w"
}
}
Error Responses
400 | invalid_state |
{...}
|
---|---|---|
404 | not_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
{
"response": {
"state": "active",
"next_billing_date": "2024-12-11T07:07:18Z",
"active_interval_started_at": "2024-12-11T07:07:18Z",
"active_interval_finishes_at": "2024-12-11T07:07:18Z",
"cancelled_at": null,
"created_at": "2024-12-11T07:07:18Z",
"token": "sub_bZWXhTzHooKpk9FZjQfzqQ",
"plan_token": "plan_ZyDee4HNeUHFHC4SpM2idg",
"customer_token": "cus_XZg1ULpWaROQCOT5PdwLkQ",
"card_token": "card_nytGw7koRg23EEp9NTmz9w"
}
}
Error Responses
404 | not_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:
{
"response": [
{
"created_at": "2024-12-11T07:07:18Z",
"type": "credit",
"amount": 1000,
"currency": "AUD",
"annotation": "charge_credit"
}
],
"count": 1,
"pagination": {
"count": 1,
"per_page": 25,
"current": 1
}
}
Error Responses
404 | not_found |
{...}
|
---|