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.
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.
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": "test-site",
"customerId": "test-site_c5f19dd38d4840ce831d85e0326e58dd",
"paymentSchedule": {
"siteId": "test-site",
"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": "test-site",
"status": "NotPaid"
},
{
"name": "3 #2",
"date": "2023-11-08T22:00:00.000Z",
"amount": 3,
"siteId": "test-site",
"status": "NotPaid"
},
{
"name": "3 #3",
"date": "2024-05-08T21:00:00.000Z",
"amount": 3,
"siteId": "test-site",
"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": "test-site",
"paymentScheduleId": "42d2032e-9946-4fa0-9e4b-7d0e536cde0c",
"paymentSchedule": {
"siteId": "test-site",
"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": "test-site_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": "test-site",
"name": "Payment #1",
"reference": null,
"date": "2023-06-30T21:00:00",
"amount": 0.834,
"status": "NotPaid"
},
{
"id": "9fc8b01d-c4bc-4e3e-9ef6-a6659247049a",
"siteId": "test-site",
"name": "Payment #2",
"reference": null,
"date": "2023-07-31T21:00:00",
"amount": 0.833,
"status": "NotPaid"
},
{
"id": "13e1f17e-87db-481e-b3c9-3bef782129a0",
"siteId": "test-site",
"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": "test-site",
"customerId": "test-site_341f7f56d2304428a19c85b6d6274322",
"paymentScheduleFromTemplate": {
"paymentScheduleTemplateId": "b54b9110-2627-45fd-a6d8-fa9374cb4578",
"customerId": "test-site_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 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
- Returns a specific 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": "test-site",
"paymentScheduleTemplateId": ""
}
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": "test-site",
"paymentScheduleTemplate": {
"siteId": "test-site",
"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": "test-site",
"PaymentScheduleTemplateId": "ec33559c-fd36-410b-ae63-b7b47b02e216",
"paymentScheduleTemplate": {
"siteId": "test-site",
"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": "test-site",
"paymentScheduleId": "42d2032e-9946-4fa0-9e4b-7d0e536cde0c",
"scheduledPayment": {
"name": "test2",
"date": "2023-06-06T21:00:00.000Z",
"amount": 12,
"siteId": "test-site",
"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": "test-site",
"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": "test-site",
"status": "NotPaid"
}
}
- You can specify any of the fields detailed in the Payment Schedules.
Delete Scheduled Payment
- You can choose to delete a specific payment or a batch/list of payments.
Single Payment Deletion
mutation DeleteScheduledPayment(
$siteId: String!
$scheduledPaymentId: [String!]!
$paymentScheduleId: String!
) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
scheduledPayment(scheduledPaymentId: $scheduledPaymentId) {
delete {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "test-site",
"paymentScheduleId": "ec33559c-fd36-410b-ae63-b7b47b02e216",
"scheduledPaymentId": "ec33559c-fd36-410b-ae63-b7b47b02e216"
}
Batch Payments Deletion
mutation DeleteScheduledPayments(
$siteId: String!
$ids: [String!]!
$paymentScheduleId: String!
) {
paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
scheduledPaymentList(ids: $ids) {
delete {
isSuccess
message
}
}
}
}
### variables
{
"siteId": "test-site",
"paymentScheduleId": "ec33559c-fd36-410b-ae63-b7b47b02e216",
"ids": [
"ec33559c-fd36-410b-ae63-b7b47b02e216",
"ecdjk559c-fd36-410b-ae23-b7sd4das234"
]
}
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": "test-site",
"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": "test-site",
"paymentScheduleId": "adsbd-dlskfj-23-sdfklj204fj"
"ids": ["1123-2343-2343-2334-23423", "1324-1324-1324-2343"]
}
Payment Methods
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": "" }
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": "test-site",
"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"
}
}
Dunning Profiles
Get 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.
Get 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.
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": "test-site",
"dunningProfile": {
"name": "dunning_profile_reminder",
"dunningFailAction": "Cancel",
"trials": [
{
"trialDelayInDays": 1,
"trialPercentage": 0.5,
"template": "reminder",
"index": 0
}
],
"siteId": "test-site"
}
}
- 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": "test-site",
"dunningProfile": {
"name": "dunning_profile_reminder",
"dunningFailAction": "Cancel",
"trials": [
{
"index": 0,
"trialDelayInDays": 1,
"trialPercentage": 0.8,
"template": "reminder"
}
],
"id": "aa187339-246c-4896-a685-55fb7f483168",
"siteId": "test-site"
},
"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": "test-site",
"paymentScheduleId": "d6c1d09b-c27b-4d2b-8ea1-1afed93038a3",
"dunningProfileId": "b6288d74-f84c-4413-8431-6c097ffeab5e"
}
- You can specify any of the fields detailed in the Dunning Profile.