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

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

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

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

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

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

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

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

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

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

Get Dunning Profile

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

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

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

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

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"
}
Table of Contents