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": "" }

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"
}

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":""}

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"
}

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": "" }

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":""}

Dunning Profile

query GetDunningProfile($siteId: String!, $dunningProfileId: String!) {
  dunningProfile(siteId: $siteId, dunningProfileId: $dunningProfileId) {
    id
    siteId
    name
    dunningFailAction
    trials
  }
}

### variables
{ "siteId": "", "dunningProfileId": "" }

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"
            }
        ]
    }
}

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"
  }
}

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
      }
    ]
  }
}

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
      }
    ]
  }
}

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"
    }
}

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"
  }
}

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"
}
  • 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"
  }
}

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"
}

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"
}