Payment Schedules API
Subsbase allows you to customize your billing frequency for your customers through payment schedules. You can also create templates to be used later on when creating new payment schedules. To learn more about Payment Schedules, Payment Schedule Templates and how to create them, please check out Schedules.
The Payment Schedules API is an integral component of the core
service. As a result, all requests should be directed to: https://api.subsbase.io/core/v2/graphql
.
The core service expects 2 headers, the X-SITE-ID
and Authorization
so the request would be:
POST https://api.subsbase.io/core/v2/graphql
Authorization: Bearer {server token}
X-SITE-ID: {your site id}
Consuming the Payment Schedules API requires that a server token is used to authenticate the request. The server token is expected in the Authorization header.
Queries
Payment Schedules
query GetPaymentSchedules($siteId: String!,$filter: FilterGQLInputType,$pagination: PaginationGQLInputType,$sorting: [SortingGQLInputType]) {
paymentSchedules (siteId: $siteId,filter: $filter,pagination: $pagination,sorting: $sorting) {
isSuccess
pagination
data{
id
#All properties are found in the PaymentScheduleGQLType
}
message
}
}
### variables
{ "siteId": "", "filter": "", "pagination": "", "sorting": "" }
- Returns an array of payment schedules.
- You can specify any of the fields detailed in the Payment Schedule Type Definition.
- For details about Pagination, Sorting, and Filtering Input Types, please check out PaginationGQLInputType, SortingGQLInputType, FilteringGQLInputType.
Payment Schedule
query GetPaymentSchedule($siteId: String!,$paymentScheduleId: String!) {
paymentSchedule (siteId: $siteId,paymentScheduleId: $paymentScheduleId) {
siteId
id
name
#All properties are found in the PaymentScheduleGQLType
}
### variables
{
"siteId": "test-site",
"paymentScheduleId": "d6c1d09b-c27b-4d2b-8ea1-1afed93038a3"
}
- Returns a specific payment schedule.
- You can specify any of the fields detailed in the Payment Schedule Type Definition.
Payment Schedules by Id
query GetPaymentSchedulesById($siteId: String!,$ids: [String]!,$pagination: PaginationGQLInputType,$sorting: [SortingGQLInputType]) {
paymentSchedulesById (siteId: $siteId,ids: $ids,pagination: $pagination,sorting: $sorting) {
isSuccess
pagination
data{
id
#All properties are found in the PaymentScheduleGQLType
}
message
}
}
### variables
{"siteId":"","ids":"","pagination":"","sorting":""}
- Returns an array of payment schedules by Id.
- You can specify any of the fields detailed in the Payment Schedule Type Definition.
- For details about Pagination, Sorting, and Filtering Input Types, please check out PaginationGQLInputType, SortingGQLInputType, FilteringGQLInputType.
Payment Schedule
query GetPaymentSchedule($siteId: String!,$paymentScheduleId: String!) {
paymentSchedule (siteId: $siteId,paymentScheduleId: $paymentScheduleId) {
siteId
id
name
#All properties are found in the PaymentScheduleGQLType
}
### variables
{
"siteId": "site Id",
"paymentScheduleId": "d6c1d09b-c27b-4d2b-8ea1-1afed93038a3"
}
- Returns a specific payment schedule.
- You can specify any of the fields detailed in the Payment Schedule Type Definition.
Payment Schedule Templates
query GetPaymentScheduleTemplates($siteId: String!,$filter: FilterGQLInputType,$pagination: PaginationGQLInputType,$sorting: [SortingGQLInputType]) {
paymentScheduleTemplates (siteId: $siteId,filter: $filter,pagination: $pagination,sorting: $sorting) {
isSuccess
pagination
data{
id
#All properties are found in the PaymentScheduleTemplateGQLType
}
message
}
}
### variables
{ "siteId": "", "filter": "", "pagination": "", "sorting": "" }
- Returns an array of payment schedule templates.
- You can specify any of the fields detailed in the Payment Schedule Template Type Definition.
- For details about Pagination, Sorting, and Filtering Input Types, please check out PaginationGQLInputType, SortingGQLInputType, FilteringGQLInputType.
Payment Schedule Template
query GetPaymentScheduleTemplate($siteId: String!,$paymentScheduleTemplateId: String!) {
paymentScheduleTemplate (siteId: $siteId,paymentScheduleTemplateId: $paymentScheduleTemplateId) {
id
siteId
name
description
data
payments
#All properties are found in the PaymentScheduleTemplateGQLType
}
}
### variables
{
"siteId": "site Id",
"paymentScheduleTemplateId": ""
}
- Returns a specific payment schedule template.
Site Payment Methods
These are the saved payment methods for recurring payments on your site, like wallets and cards, which are automatically collected.
query GetSitePaymentMethods($siteId: String!) {
getSitePaymentMethods(siteId: $siteId) {
id
siteId
paymentProviderCode
#All properties are found in the SitePaymentMethodGQLType
}
}
### variables
{ "siteId": "" }
Site Manual Payment Methods
- These are the unsaved payment methods on your site, like cash, direct debit and cheques, which are not automatically collected and need to be manually marked as paid on your site.
query GetSiteManualPaymentMethods($siteId: String!) {
getSiteManualPaymentMethods(siteId: $siteId) {
id
siteId
paymentProviderCode
displayText
displayImage
properties
}
}
### variables
{ "siteId": "" }
Dunning Profiles
query GetDunningProfiles($siteId: String!,$filter: FilterGQLInputType,$pagination: PaginationGQLInputType,$sorting: [SortingGQLInputType]) {
dunningProfiles (siteId: $siteId,filter: $filter,pagination: $pagination,sorting: $sorting) {
isSuccess
pagination
data{
id
#All properties are found in the DunningProfileGQLType
}
message
}
}
### variables
{"siteId":"","filter":"","pagination":"","sorting":""}
- Returns an array of dunning profiles.
- You can specify any of the fields detailed in the Dunning Profile Type Definition.
- For details about Pagination, Sorting, and Filtering Input Types, please check out PaginationGQLInputType, SortingGQLInputType, FilteringGQLInputType.
Dunning Profile
query GetDunningProfile($siteId: String!, $dunningProfileId: String!) {
dunningProfile(siteId: $siteId, dunningProfileId: $dunningProfileId) {
id
siteId
name
dunningFailAction
trials
}
}
### variables
{ "siteId": "", "dunningProfileId": "" }
- Returns a specific dunning profile.
- You can specify any of the fields detailed in the Dunning Profile Type Definition.
Mutations
Payment Schedule
Create Payment Schedule
- To create a payment schedule, you need to use the following Mutation. It is advisable to use
variables
in this case since the input types are more complex than just strings:
mutation CreateCustomerPaymentSchedules(
$siteId: String!
$customerId: String!
$paymentSchedule: PaymentScheduleGQLInputType!
) {
customer(siteId: $siteId, customerId: $customerId) {
paymentSchedules {
create(paymentSchedule: $paymentSchedule) {
isSuccess
message
value {
id
#All properties are found in the PaymentScheduleGQLType
}
}
}
}
}
### variables
{
"siteId": "site Id",
"customerId": "site Id_c5f19dd38d4840ce831d85e0326e58dd",
"paymentSchedule": {
"siteId": "site Id",
"name": "three-month-schedule",
"product": "product",
"currencyCode": "sar",
"paymentMethod": {
"id": "341fd466-38f0-46a7-850f-afeaa526555b",
"displayText": "8769",
"isDefault": true,
"type": "Visa Card",
"metaData": null,
"identifier": "",
"providerReference": null,
"sitePaymentMethodId": "",
"billingInfo": null
},
"data": {
"invoicing": "InvoicePerPayment",
"allowPaymentMethodChange": true
},
"scheduledPayments": [
{
"name": "3 #1",
"date": "2023-05-08T21:00:00.000Z",
"amount": 3,
"siteId": "site Id",
"status": "NotPaid"
},
{
"name": "3 #2",
"date": "2023-11-08T22:00:00.000Z",
"amount": 3,
"siteId": "site Id",
"status": "NotPaid"
},
{
"name": "3 #3",
"date": "2024-05-08T21:00:00.000Z",
"amount": 3,
"siteId": "site Id",
"status": "NotPaid"
}
]
}
}
- You can specify any of the fields detailed in the Payment Schedule.
Update Payment Schedule
mutation UpdatePaymentSchedule(
$siteId: String!
$paymentScheduleId: String!
$paymentSchedule: PaymentScheduleGQLInputType!
) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
update(paymentSchedule: $paymentSchedule) {
isSuccess
message
value {
id
#All properties are found in the PaymentScheduleGQLType
}
}
}
}
### variables
{
"siteId": "site Id",
"paymentScheduleId": "42d2032e-9946-4fa0-9e4b-7d0e536cde0c",
"paymentSchedule": {
"siteId": "site Id",
"id": "42d2032e-9946-4fa0-9e4b-7d0e536cde0c",
"name": "three-month-schedule",
"product": "test",
"currencyCode": "egp",
"paymentMethod": {
"id": "d6c67f77-be9f-43a8-b775-979d88e5083b",
"type": "card",
"metaData": "",
"isDefault": true,
"identifier": "",
"billingInfo": null,
"displayText": "4242",
"providerReference": "site Id_fad0c134205747a4839396a0654ffef0",
"sitePaymentMethodId": "40103eb9-af57-484e-a0b3-c62b7f6dbd66"
},
"customerId": "ca6256f7-5683-4d28-ba52-b0b17be8b1a5",
"data": {
"invoicing": "NoInvoice",
"extraDetails": "test",
"allowPaymentMethodChange": false,
"status": "NotAccepted"
},
"scheduledPayments": [
{
"id": "cbc7322f-c895-4cb4-a2ee-93506660c31f",
"siteId": "site Id",
"name": "Payment #1",
"reference": null,
"date": "2023-06-30T21:00:00",
"amount": 0.834,
"status": "NotPaid"
},
{
"id": "9fc8b01d-c4bc-4e3e-9ef6-a6659247049a",
"siteId": "site Id",
"name": "Payment #2",
"reference": null,
"date": "2023-07-31T21:00:00",
"amount": 0.833,
"status": "NotPaid"
},
{
"id": "13e1f17e-87db-481e-b3c9-3bef782129a0",
"siteId": "site Id",
"name": "Payment #3",
"reference": null,
"date": "2023-08-31T21:00:00",
"amount": 0.833,
"status": "NotPaid"
},
],
"dunningProfileId": null
}
}
Create Payment Schedule From Template
- Instead of creating scheduled payments from scratch, you can use one of the previously made templates.
- For more details about templates, please check out below the Payment Schedule Templates section.
- To create a payment schedule from an already existing template, you need to use the following Mutation. It is advisable to use
variables
in this case since the input types are more complex than just strings:
mutation CreateCustomerPaymentSchedulesFromTemplate(
$siteId: String!
$customerId: String!
$paymentScheduleFromTemplate: PaymentScheduleFromTemplateGQLInputType!
) {
customer(siteId: $siteId, customerId: $customerId) {
paymentSchedules {
createFromTemplate(
paymentScheduleFromTemplate: $paymentScheduleFromTemplate
) {
isSuccess
message
value {
id
#All properties are found in the PaymentSchedulesTemplateGQLType
}
}
}
}
### variables
{
"siteId": "site Id",
"customerId": "site Id_341f7f56d2304428a19c85b6d6274322",
"paymentScheduleFromTemplate": {
"paymentScheduleTemplateId": "b54b9110-2627-45fd-a6d8-fa9374cb4578",
"customerId": "site Id_341f7f56d2304428a19c85b6d6274322",
"baseDate": "2023-02-28T22:00:00.000Z",
"baseAmount": 20,
"currencyCode": "egp",
"product": "test-schedule-payment2",
"selectedPaymentMethodId": "9392e570-f006-41c0-bbba-8705ce0030b8"
}
}
- You can specify any of the fields detailed in the Payment Schedule Template.
Payment Schedule Template
Create Payment Schedule Template
- To create a payment schedule template, you need to use the following Mutation. It is advisable to use
variables
in this case since the input types are more complex than just strings:
mutation CreatePaymentScheduleTemplate(
$siteId: String!
$paymentScheduleTemplate: PaymentScheduleTemplateGQLInputType!
) {
paymentScheduleTemplates(siteId: $siteId) {
create(paymentScheduleTemplate: $paymentScheduleTemplate) {
isSuccess
message
value {
id
#All properties are found in the PaymentScheduleTemplateGQLType
}
}
}
### variables
{
"siteId": "site Id",
"paymentScheduleTemplate": {
"siteId": "site Id",
"name": "birthday gift",
"payments": [
{
"order": 1,
"name": "birthday #1",
"intervalDuration": 1,
"intervalUnit": "Day",
"percentageAmount": 0.5
},
{
"order": 2,
"name": "birthday #1",
"intervalDuration": 1,
"intervalUnit": "Day",
"percentageAmount": 0.5
}
]
}
}
- You can specify any of the fields detailed in the Payment Schedule Template.
Update Payment Schedule Template
- This operation updates the infofields of an existing payment schedule template.
- To update an existing payment schedule template, you need to use the following Mutation. It is advisable to use
variables
in this case since the input types are more complex than just strings:
mutation UpdatePaymentScheduleTemplate(
$siteId: String!
$PaymentScheduleTemplateId: String!
$paymentScheduleTemplate: PaymentScheduleTemplateGQLInputType!
) {
paymentScheduleTemplate(
siteId: $siteId
paymentScheduleTemplateId: $PaymentScheduleTemplateId
) {
update(paymentScheduleTemplate: $paymentScheduleTemplate) {
isSuccess
message
value {
id
#All properties are found in the PaymentScheduleTemplateGQLType
}
}
}
}
### variables
{
"siteId": "site Id",
"PaymentScheduleTemplateId": "ec33559c-fd36-410b-ae63-b7b47b02e216",
"paymentScheduleTemplate": {
"siteId": "site Id",
"id": "ec33559c-fd36-410b-ae63-b7b47b02e216",
"name": "birthday gift",
"description": "birthday gift",
"payments": [
{
"order": 1,
"name": "birthday #1",
"intervalUnit": "Day",
"intervalDuration": 1,
"percentageAmount": 0.5
},
{
"order": 2,
"name": "birthday #1",
"intervalUnit": "Day",
"intervalDuration": 1,
"percentageAmount": 0.5
}
]
}
}
- You can specify any of the fields detailed in the Payment Schedule Template.
Scheduled Payments
Create Scheduled Payment
- Creates a scheduled payment under a specific payment schedule.
mutation CreateScheduledPayment(
$siteId: String!
$paymentScheduleId: String!
$scheduledPayment: ScheduledPaymentGQLInputType!
) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
scheduledPayments {
create(scheduledPayment: $scheduledPayment) {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "site Id",
"paymentScheduleId": "42d2032e-9946-4fa0-9e4b-7d0e536cde0c",
"scheduledPayment": {
"name": "test2",
"date": "2023-06-06T21:00:00.000Z",
"amount": 12,
"siteId": "site Id",
"status": "NotPaid"
}
}
- You can specify any of the fields detailed in the Payment Schedules.
Update Scheduled Payment
- To update a scheduled payment, you need to use the following:
mutation UpdateScheduledPayment(
$siteId: String!
$paymentScheduleId: String!
$scheduledPayment: ScheduledPaymentGQLInputType!
) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
scheduledPayment(scheduledPayment: $scheduledPayment) {
update {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "site Id",
"paymentScheduleId": "1234-1324-1324-134",
"scheduledPayment": {
"amount": 199,
"date": "2023-04-17T22:00:00.000Z",
"name": "payment",
"paymentScheduleId": "bd2aa887-1598-4c16-928e-395a9c5e1148",
"reference": "54654",
"siteId": "site Id",
"status": "NotPaid"
}
}
- You can specify any of the fields detailed in the Payment Schedules.
Cancel Scheduled Payments
Cancel Batch
- To cancel a batch of scheduled payments, you need to use the following:
mutation CancelScheduledPayments($siteId: String!, $paymentScheduleId: String!, $ids: [String!]!) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
scheduledPaymentList(ids: $ids) {
cancel {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "test-site",
"paymentScheduleId": "adsbd-dlskfj-23-sdfklj204fj"
"ids": ["1123-2343-2343-2334-23423", "1324-1324-1324-2343"]
}
Cancel Single
- To cancel a single scheduled payment, you need to use the following:
mutation CancelScheduledPayment(
$siteId: String!
$scheduledPaymentId: String!
$paymentScheduleId: String!
) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
scheduledPayment(scheduledPaymentId: $scheduledPaymentId) {
cancel {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "test-site",
"paymentScheduleId": "adsbd-dlskfj-23-sdfklj204fj",
"scheduledPaymentId": "adsbd-dlskfj-23-sdfklj204kk"
}
Send Scheduled Payment Link
- To send a scheduled payment link, you need to use the following:
mutation SendScheduledPaymentLink(
$siteId: String!, $scheduledPaymentId: String!, $paymentScheduleId: String!) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
scheduledPayment(scheduledPaymentId: $scheduledPaymentId) {
sendPaymentLink {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "test-site",
"paymentScheduleId": "adsbd-dlskfj-23-sdfklj204fj"
"scheduledPaymentId": "1123-2343-2343"
}
Mark as Paid
- You can choose to mark a specific payment as paid or a batch/list of payments.
Single Payment Mark as Paid
mutation MarkScheduledPaymentAsPaid(
$siteId: String!
$paymentScheduledId: String!
$scheduledPaymentId: String!
) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
scheduledPayment(scheduledPaymentId: $scheduledPaymentId) {
markAsPaid {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "site Id",
"paymentScheduleId": "adsbd-dlskfj-23-sdfklj204fj"
"ids": ["1123-2343-2343-2334-23423", "1324-1324-1324-2343"]
}
Batch Payments Mark as Paid
mutation MarkScheduledPaymentsAsPaid(
$siteId: String!
$ids: [String!]!
$paymentScheduledId: String!
) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
scheduledPaymentList(ids: $ids) {
markAsPaid {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "site Id",
"paymentScheduleId": "adsbd-dlskfj-23-sdfklj204fj"
"ids": ["1123-2343-2343-2334-23423", "1324-1324-1324-2343"]
}
Payment Methods
Change Payment Method
- This operation changes/updates the infofields of an existing payment method.
- For more details about payment methods, please check out Payment Method.
- To change/update an existing payment method, you need to use the following Mutation. It is advisable to use
variables
in this case since the input types are more complex than just strings:
mutation ChangePaymentMethod(
$siteId: String!
$paymentScheduleId: String!
$paymentMethod: PaymentMethodGQLInputType!
) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
changePaymentMethod(paymentMethod: $paymentMethod) {
isSuccess
message
}
}
}
### variables
{
"siteId": "site Id",
"paymentScheduleId": "d6c1d09b-c27b-4d2b-8ea1-1afed93038a3",
"paymentMethod": {
"id": "240500c1-aa93-418a-9963-19dcd4aea238",
"displayText": "8769",
"isDefault": true,
"type": "Visa Card",
"sitePaymentMethodId": "182687d0-7ce2-4312-b589-ec911cb10cdc"
}
}
Custom Fields
Add Custom Field
mutation AddPaymentScheduleCustomField(
$siteId: String!
$paymentScheduleId: String!
$customField: KeyValuePairGQLInputType!
) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
customFields {
add(customField: $customField) {
isSuccess
message
}
}
}
}
### variables
variables: {
"siteId": "site Id",
"paymentScheduleId": "",
"customField": {
"key": "custom field key",
"value": "custom field value"
}
}
Update Custom Field
mutation UpdatePaymentScheduleCustomField(
$siteId: String!
$paymentScheduleId: String!
$name: String!
$customField: KeyValuePairGQLInputType!
) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
customField(name: $name) {
update(customField: $customField) {
isSuccess
message
}
}
}
}
### variables
variables: {
"siteId": "site Id",
"paymentScheduleId": "",
"name": "custom field name",
"customField": {
"key": "custom field key",
"value": "custom field new value"
}
}
Delete Custom Field
mutation DeleteCustomField($siteId: String!, $paymentScheduleId: String!, $name: String!) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
customField(name: $name) {
delete {
isSuccess
message
}
}
}
}
### variables
variables: {
"siteId": "site Id",
"paymentScheduleId": "",
"name": "custom field name"
}
Dunning Profiles
Create Dunning Profile
- To create a new dunning profile, you need to use the following Mutation:
mutation CreateDunningProfile(
$siteId: String!
$dunningProfile: DunningProfileGQLInputType!
) {
dunningProfiles(siteId: $siteId) {
create(dunningProfile: $dunningProfile) {
isSuccess
message
value{
id
#All properties are found in the DunningProfileGQLType
}
}
}
### variables
{
"siteId": "site Id",
"dunningProfile": {
"name": "dunning_profile_reminder",
"dunningFailAction": "Cancel",
"trials": [
{
"trialDelayInDays": 1,
"trialPercentage": 0.5,
"template": "reminder",
"index": 0
}
],
"siteId": "site Id"
}
}
- You can specify any of the fields detailed in the Dunning Profile.
Update Dunning Profile
- This operation updates the infofields of an existing dunning profile.
- To update an existing dunning profile, you need to use the following Mutation. It is advisable to use
variables
in this case since the input types are more complex than just strings:
mutation UpdateDunningProfile(
$siteId: String!
$dunningProfileId: String!
$dunningProfile: DunningProfileGQLInputType!
) {
dunningProfile(siteId: $siteId, dunningProfileId: $dunningProfileId) {
update(dunningProfile: $dunningProfile) {
isSuccess
message
value{
id
#All properties are found in the DunningProfileGQLType
}
}
}
### variables
{
"siteId": "site Id",
"dunningProfile": {
"name": "dunning_profile_reminder",
"dunningFailAction": "Cancel",
"trials": [
{
"index": 0,
"trialDelayInDays": 1,
"trialPercentage": 0.8,
"template": "reminder"
}
],
"id": "aa187339-246c-4896-a685-55fb7f483168",
"siteId": "site Id"
},
"dunningProfileId": "aa187339-246c-4896-a685-55fb7f483168"
}
- You can specify any of the fields detailed in the Dunning Profile.
Remove Dunning Profile
mutation RemoveDunningProfile(
$siteId: String!
$paymentScheduleId: String!
$dunningProfileId: String
) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
dunningProfile(dunningProfileId: $dunningProfileId) {
remove {
isSuccess
}
}
}
}
### variables
{
"siteId": "site Id",
"paymentScheduleId": "d6c1d09b-c27b-4d2b-8ea1-1afed93038a3",
"dunningProfileId": "b6288d74-f84c-4413-8431-6c097ffeab5e"
}
- You can specify any of the fields detailed in the Dunning Profile.