Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: pinch-api Subscriptions API
version: '2020.1'
servers:
- url: https://api.getpinch.com.au/test
security:
- sec0: []
tags:
- name: Subscriptions
paths:
/subscriptions/{id}:
delete:
summary: Cancel Subscription
description: ''
operationId: cancel-subscription
parameters:
- name: id
in: path
description: Subscription Id in sub_XXXXXXXXXXXXXX format
schema:
type: string
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: '[no body]'
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "{\n \"errorMessages\": [\n {\n \"propertyName\": \"\",\n \"errorMessage\": \"Could not find subscription with id: sub_XXXXXXXXXXXXXX\",\n \"attemptedValue\": null,\n \"customState\": null,\n \"severity\": 0,\n \"errorCode\": null,\n \"formattedMessageArguments\": null,\n \"formattedMessagePlaceholderValues\": null,\n \"resourceName\": null\n }\n ],\n \"successful\": false\n}"
schema:
type: object
properties:
errorMessages:
type: array
items:
type: object
properties:
propertyName:
type: string
example: ''
errorMessage:
type: string
example: 'Could not find subscription with id: sub_XXXXXXXXXXXXXX'
attemptedValue: {}
customState: {}
severity:
type: integer
example: 0
default: 0
errorCode: {}
formattedMessageArguments: {}
formattedMessagePlaceholderValues: {}
resourceName: {}
successful:
type: boolean
example: false
default: true
deprecated: false
tags:
- Subscriptions
get:
summary: Get Subscription
description: ''
operationId: get-subscription
parameters:
- name: id
in: path
description: Subscription Id in sub_XXXXXXXXXXXXXX format
schema:
type: string
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"id\": \"sub_XXXXXXXXXXXXXX\",\n \"payer\": {\n \"id\": \"pyr_XXXXXXXXXXXXXX\",\n \"firstName\": \"Ben\",\n \"lastName\": \"Hotdog\",\n \"emailAddress\": \"ben.hotdog@mailinator.com\",\n \"mobileNumber\": null,\n \"streetAddress\": null,\n \"suburb\": null,\n \"postcode\": null,\n \"state\": null,\n \"country\": null,\n \"companyName\": null,\n \"companyRegistrationNumber\": null,\n \"metadata\": null\n },\n \"planId\": \"pln_XXXXXXXXXXXXXX\",\n \"planName\": \"25% Deposit with 10% Monthly\",\n \"status\": \"active\",\n \"startDate\": \"2021-05-21T14:00:00.0000000Z\",\n \"freePeriods\": [\n {\n \"startDate\": \"2021-05-21T14:00:00.0000000Z\",\n \"durationOffset\": 1,\n \"durationInterval\": \"months\",\n \"metadata\": \"\"\n }\n ],\n \"fixedPayments\": [\n {\n \"amount\": 25000,\n \"description\": \"Upfront deposit\",\n \"cancelPlanOnFailure\": true,\n \"metadata\": null,\n \"transactionDate\": \"2021-05-21T14:00:00.0000000Z\"\n }\n ],\n \"recurringPayment\": {\n \"amount\": 10000,\n \"endAfterNumberOfPayments\": null,\n \"endAfterTotalAmount\": null,\n \"frequencyInterval\": \"months\",\n \"frequencyOffset\": 1,\n \"description\": \"Monthly Repayment\",\n \"cancelPlanOnFailure\": false,\n \"metadata\": null,\n \"endAfterDate\": null,\n \"startDate\": \"2021-06-21T14:00:00.0000000Z\"\n },\n \"totalAmount\": 100000,\n \"metadata\": \"\",\n \"surcharge\": [\n \"bank-account\",\n \"credit-card\"\n ]\n}"
schema:
type: object
properties:
id:
type: string
example: sub_XXXXXXXXXXXXXX
payer:
type: object
properties:
id:
type: string
example: pyr_XXXXXXXXXXXXXX
firstName:
type: string
example: Ben
lastName:
type: string
example: Hotdog
emailAddress:
type: string
example: ben.hotdog@mailinator.com
mobileNumber: {}
streetAddress: {}
suburb: {}
postcode: {}
state: {}
country: {}
companyName: {}
companyRegistrationNumber: {}
metadata: {}
planId:
type: string
example: pln_XXXXXXXXXXXXXX
planName:
type: string
example: 25% Deposit with 10% Monthly
status:
type: string
example: active
startDate:
type: string
example: '2021-05-21T14:00:00.0000000Z'
freePeriods:
type: array
items:
type: object
properties:
startDate:
type: string
example: '2021-05-21T14:00:00.0000000Z'
durationOffset:
type: integer
example: 1
default: 0
durationInterval:
type: string
example: months
metadata:
type: string
example: ''
fixedPayments:
type: array
items:
type: object
properties:
amount:
type: integer
example: 25000
default: 0
description:
type: string
example: Upfront deposit
cancelPlanOnFailure:
type: boolean
example: true
default: true
metadata: {}
transactionDate:
type: string
example: '2021-05-21T14:00:00.0000000Z'
recurringPayment:
type: object
properties:
amount:
type: integer
example: 10000
default: 0
endAfterNumberOfPayments: {}
endAfterTotalAmount: {}
frequencyInterval:
type: string
example: months
frequencyOffset:
type: integer
example: 1
default: 0
description:
type: string
example: Monthly Repayment
cancelPlanOnFailure:
type: boolean
example: false
default: true
metadata: {}
endAfterDate: {}
startDate:
type: string
example: '2021-06-21T14:00:00.0000000Z'
totalAmount:
type: integer
example: 100000
default: 0
metadata:
type: string
example: ''
surcharge:
type: array
items:
type: string
example: bank-account
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "[\n {\n \"propertyName\": \"SubscriptionId\",\n \"errorMessage\": \"Subscription Id sub_XXXXXXXXXXXXXX not found.\",\n \"attemptedValue\": null,\n \"customState\": null,\n \"severity\": 0,\n \"errorCode\": null,\n \"formattedMessageArguments\": null,\n \"formattedMessagePlaceholderValues\": null,\n \"resourceName\": null\n }\n]"
schema:
type: array
items:
type: object
properties:
propertyName:
type: string
example: SubscriptionId
errorMessage:
type: string
example: Subscription Id sub_XXXXXXXXXXXXXX not found.
attemptedValue: {}
customState: {}
severity:
type: integer
example: 0
default: 0
errorCode: {}
formattedMessageArguments: {}
formattedMessagePlaceholderValues: {}
resourceName: {}
deprecated: false
tags:
- Subscriptions
/subscriptions:
post:
summary: Create Subscription
description: ''
operationId: create-subscription
requestBody:
content:
application/json:
schema:
type: object
required:
- planId
- payerId
properties:
planId:
type: string
description: Plan Id in pln_XXXXXXXXXXXXXX format
payerId:
type: string
description: Payer Id in pyr_XXXXXXXXXXXXXX format
totalAmount:
type: integer
description: If the plan needs a total amount (percentage based plans) you must supply it here in cents. This will override the end date settings on a recurring plan to end after this total amount is paid.
format: int32
startDate:
type: string
description: When the subscription should start. Leave blank for immediately.
format: date
surcharge:
type: array
description: If you wish to pass on the fees for certain payment methods, specify them here. Values can be "bank-account" and/or "credit-card".
items:
type: string
sourceId:
type: string
description: Source Id in src_XXXXXXXXX format. If you want to use a specific Source, otherwise a Source will be automatically selected. If the Source is removed the Subscription will no longer be able to complete.
examples:
Request Example:
value:
planId: pln_ZW7iySHhEZwldh
payerId: pyr_vliHRkOJIHvN6b
totalAmount: 100000
startDate: '2020-05-22'
surcharge:
- bank-account
- credit-card
responses:
'201':
description: '201'
content:
application/json:
examples:
Result:
value: "{\n \"id\": \"sub_ICbooeBtI7YE5I\",\n \"payer\": {\n \"id\": \"pyr_vliHRkOJIHvN6b\",\n \"firstName\": \"New\",\n \"lastName\": \"Payer 3\",\n \"emailAddress\": \"np3@mailinator.com\",\n \"mobileNumber\": null\n },\n \"planId\": \"pln_ZW7iySHhEZwldh\",\n \"planName\": \"25% Deposit with 10% Monthly\",\n \"status\": \"active\",\n \"startDate\": \"2020-05-21T14:00:00.0000000Z\",\n \"freePeriods\": [],\n \"fixedPayments\": [{\n \"amount\": 25000,\n \"description\": \"Upfront deposit\",\n \"cancelPlanOnFailure\": true,\n \"metadata\": null,\n \"transactionDate\": \"2020-05-21T14:00:00.0000000Z\"\n }],\n \"recurringPayment\": {\n \"amount\": 10000,\n \"endAfterNumberOfPayments\": null,\n \"endAfterTotalAmount\": null,\n \"frequencyInterval\": \"months\",\n \"frequencyOffset\": 1,\n \"description\": \"Monthly Repayment\",\n \"cancelPlanOnFailure\": false,\n \"metadata\": null,\n \"endAfterDate\": null,\n \"startDate\": \"2020-06-21T14:00:00.0000000Z\"\n },\n \"totalAmount\": 100000,\n \"metadata\": null,\n \"surcharge\": [\"bank-account\",\"credit-card\"]\n}"
schema:
type: object
properties:
id:
type: string
example: sub_ICbooeBtI7YE5I
payer:
type: object
properties:
id:
type: string
example: pyr_vliHRkOJIHvN6b
firstName:
type: string
example: New
lastName:
type: string
example: Payer 3
emailAddress:
type: string
example: np3@mailinator.com
mobileNumber: {}
planId:
type: string
example: pln_ZW7iySHhEZwldh
planName:
type: string
example: 25% Deposit with 10% Monthly
status:
type: string
example: active
startDate:
type: string
example: '2020-05-21T14:00:00.0000000Z'
freePeriods:
type: array
fixedPayments:
type: array
items:
type: object
properties:
amount:
type: integer
example: 25000
default: 0
description:
type: string
example: Upfront deposit
cancelPlanOnFailure:
type: boolean
example: true
default: true
metadata: {}
transactionDate:
type: string
example: '2020-05-21T14:00:00.0000000Z'
recurringPayment:
type: object
properties:
amount:
type: integer
example: 10000
default: 0
endAfterNumberOfPayments: {}
endAfterTotalAmount: {}
frequencyInterval:
type: string
example: months
frequencyOffset:
type: integer
example: 1
default: 0
description:
type: string
example: Monthly Repayment
cancelPlanOnFailure:
type: boolean
example: false
default: true
metadata: {}
endAfterDate: {}
startDate:
type: string
example: '2020-06-21T14:00:00.0000000Z'
totalAmount:
type: integer
example: 100000
default: 0
metadata: {}
surcharge:
type: array
items:
type: string
example: bank-account
'400':
description: '400'
content:
application/json:
examples:
Result:
value: "[\n {\n \"propertyName\": \"\",\n \"errorMessage\": \"Could not find a plan with id: pln_XXXXXX\",\n \"attemptedValue\": null,\n \"customState\": null,\n \"severity\": 0,\n \"errorCode\": null,\n \"formattedMessageArguments\": null,\n \"formattedMessagePlaceholderValues\": null,\n \"resourceName\": null\n }\n]"
schema:
type: array
items:
type: object
properties:
propertyName:
type: string
example: ''
errorMessage:
type: string
example: 'Could not find a plan with id: pln_XXXXXX'
attemptedValue: {}
customState: {}
severity:
type: integer
example: 0
default: 0
errorCode: {}
formattedMessageArguments: {}
formattedMessagePlaceholderValues: {}
resourceName: {}
deprecated: false
tags:
- Subscriptions
get:
summary: List Subscriptions
description: ''
operationId: list-subscriptions
parameters:
- name: page
in: query
description: The current page
schema:
type: integer
format: int32
default: 1
- name: pageSize
in: query
description: How many items to return for each page. Maximum 500.
schema:
type: integer
format: int32
default: 50
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1,\n \"data\": [\n {\n \"id\": \"sub_\",\n \"payer\": {\n \"id\": \"pyr_\",\n \"firstName\": \"Ben\",\n \"lastName\": \"Hotdog\",\n \"emailAddress\": \"ben.hotdog@mailinator.com\",\n \"mobileNumber\": null,\n \"streetAddress\": null,\n \"suburb\": null,\n \"postcode\": null,\n \"state\": null,\n \"country\": null,\n \"companyName\": null,\n \"companyRegistrationNumber\": null,\n \"metadata\": null\n },\n \"planId\": \"pln_rp0JFLx6qYaPGS\",\n \"planName\": \"25% Deposit with 10% Monthly\",\n \"status\": \"active\",\n \"startDate\": \"2021-05-21T14:00:00.0000000Z\",\n \"freePeriods\": [\n {\n \"startDate\": \"2021-05-21T14:00:00.0000000Z\",\n \"durationOffset\": 1,\n \"durationInterval\": \"months\",\n \"metadata\": \"\"\n }\n ],\n \"fixedPayments\": [\n {\n \"amount\": 25000,\n \"description\": \"Upfront deposit\",\n \"cancelPlanOnFailure\": true,\n \"metadata\": null,\n \"transactionDate\": \"2021-05-21T14:00:00.0000000Z\"\n }\n ],\n \"recurringPayment\": {\n \"amount\": 10000,\n \"endAfterNumberOfPayments\": null,\n \"endAfterTotalAmount\": null,\n \"frequencyInterval\": \"months\",\n \"frequencyOffset\": 1,\n \"description\": \"Monthly Repayment\",\n \"cancelPlanOnFailure\": false,\n \"metadata\": null,\n \"endAfterDate\": null,\n \"startDate\": \"2021-06-21T14:00:00.0000000Z\"\n },\n \"totalAmount\": 100000,\n \"metadata\": \"\",\n \"surcharge\": [\n \"bank-account\",\n \"credit-card\"\n ]\n }\n ]\n}"
schema:
type: object
properties:
page:
type: integer
example: 1
default: 0
pageSize:
type: integer
example: 50
default: 0
totalPages:
type: integer
example: 1
default: 0
totalItems:
type: integer
example: 1
default: 0
data:
type: array
items:
type: object
properties:
id:
type: string
example: sub_
payer:
type: object
properties:
id:
type: string
example: pyr_
firstName:
type: string
example: Ben
lastName:
type: string
example: Hotdog
emailAddress:
type: string
example: ben.hotdog@mailinator.com
mobileNumber: {}
streetAddress: {}
suburb: {}
postcode: {}
state: {}
country: {}
companyName: {}
companyRegistrationNumber: {}
metadata: {}
planId:
type: string
example: pln_rp0JFLx6qYaPGS
planName:
type: string
example: 25% Deposit with 10% Monthly
status:
type: string
example: active
startDate:
type: string
example: '2021-05-21T14:00:00.0000000Z'
freePeriods:
type: array
items:
type: object
properties:
startDate:
type: string
example: '2021-05-21T14:00:00.0000000Z'
durationOffset:
type: integer
example: 1
default: 0
durationInterval:
type: string
example: months
metadata:
type: string
example: ''
fixedPayments:
type: array
items:
type: object
properties:
amount:
type: integer
example: 25000
default: 0
description:
type: string
example: Upfront deposit
cancelPlanOnFailure:
type: boolean
example: true
default: true
metadata: {}
transactionDate:
type: string
example: '2021-05-21T14:00:00.0000000Z'
recurringPayment:
type: object
properties:
amount:
type: integer
example: 10000
default: 0
endAfterNumberOfPayments: {}
endAfterTotalAmount: {}
frequencyInterval:
type: string
example: months
frequencyOffset:
type: integer
example: 1
default: 0
description:
type: string
example: Monthly Repayment
cancelPlanOnFailure:
type: boolean
example: false
default: true
metadata: {}
endAfterDate: {}
startDate:
type: string
example: '2021-06-21T14:00:00.0000000Z'
totalAmount:
type: integer
example: 100000
default: 0
metadata:
type: string
example: ''
surcharge:
type: array
items:
type: string
example: bank-account
deprecated: false
tags:
- Subscriptions
components:
securitySchemes:
sec0:
type: oauth2
flows: {}
x-readme:
headers:
- key: pinch-version
value: '2020.1'
explorer-enabled: true
proxy-enabled: true