Subscriptions API Beta

The subscriptions API allows you to create subscriptions against plans and retrieve the details of existing subscriptions. It is currently in beta.

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 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/subscriptions -u your-secret-api-key: \
 -d "plan_token=plan_ZyDee4HNeUHFHC4SpM2idg" \
 -d "customer_token=cus_XZg1ULpWaROQCOT5PdwLkQ" \
 -d "card_token=card_nytGw7koRg23EEp9NTmz9w" \
 -d "include_setup_fee=false"
201 Created
{
  "response": {
    "state": "active",
    "trial_started_at": "2018-12-14T14:13:04Z",
    "trial_ended_at": null,
    "next_billing_date": "2018-12-14T14:13:04Z",
    "current_period_started_at": "2018-12-14T14:13:04Z",
    "current_period_ends_at": "2018-12-14T14:13:04Z",
    "cancelled_at": "2018-12-14T14:13:04Z",
    "created_at": "2018-12-14T14:13:04Z",
    "updated_at": "2018-12-14T14:13:04Z",
    "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",
      "trial_started_at": "2018-12-14T14:13:04Z",
      "trial_ended_at": null,
      "next_billing_date": "2018-12-14T14:13:04Z",
      "current_period_started_at": "2018-12-14T14:13:04Z",
      "current_period_ends_at": "2018-12-14T14:13:04Z",
      "cancelled_at": "2018-12-14T14:13:04Z",
      "created_at": "2018-12-14T14:13:04Z",
      "updated_at": "2018-12-14T14:13:04Z",
      "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",
    "trial_started_at": "2018-12-14T14:13:04Z",
    "trial_ended_at": null,
    "next_billing_date": "2018-12-14T14:13:04Z",
    "current_period_started_at": "2018-12-14T14:13:04Z",
    "current_period_ends_at": "2018-12-14T14:13:04Z",
    "cancelled_at": "2018-12-14T14:13:04Z",
    "created_at": "2018-12-14T14:13:04Z",
    "updated_at": "2018-12-14T14:13:04Z",
    "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",
    "trial_started_at": "2018-12-14T14:13:04Z",
    "trial_ended_at": null,
    "next_billing_date": "2018-12-14T14:13:04Z",
    "current_period_started_at": "2018-12-14T14:13:04Z",
    "current_period_ends_at": "2018-12-14T14:13:04Z",
    "cancelled_at": "2018-12-14T14:13:04Z",
    "created_at": "2018-12-14T14:13:04Z",
    "updated_at": "2018-12-14T14:13:04Z",
    "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": "active",
    "trial_started_at": "2018-12-14T14:13:04Z",
    "trial_ended_at": null,
    "next_billing_date": "2018-12-14T14:13:04Z",
    "current_period_started_at": "2018-12-14T14:13:04Z",
    "current_period_ends_at": "2018-12-14T14:13:04Z",
    "cancelled_at": "2018-12-14T14:13:04Z",
    "created_at": "2018-12-14T14:13:04Z",
    "updated_at": "2018-12-14T14:13:04Z",
    "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 PATCH
200 OK
{
  "response": {
    "state": "active",
    "trial_started_at": "2018-12-14T14:13:04Z",
    "trial_ended_at": null,
    "next_billing_date": "2018-12-14T14:13:04Z",
    "current_period_started_at": "2018-12-14T14:13:04Z",
    "current_period_ends_at": "2018-12-14T14:13:04Z",
    "cancelled_at": "2018-12-14T14:13:04Z",
    "created_at": "2018-12-14T14:13:04Z",
    "updated_at": "2018-12-14T14:13:04Z",
    "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/history

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

Example

curl https://test-api.pinpayments.com/1/subscriptions/sub_bZWXhTzHooKpk9FZjQfzqQ/history -u your-secret-api-key:
200 OK
{
  "response": [
    {
      "created_at": "2018-12-14T14:13:04Z",
      "type": "type",
      "amount": 1000,
      "currency": "AUD",
      "annotation": "Subscription to Coffee Plan"
    }
  ],
  "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 is owned and operated by
Southern Payment Systems Pty Ltd
ABN: 46 154 451 582
Level 1, 34 Queen St,
Melbourne VIC 3000

Privacy Policy Terms Security Status

Australia