Payment Schedules APIs

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 How to create a payment schedule.

Payment Schedules API

The Payment Schedules API is part of the core service and thus all requests should go to https://api.subsbase.io/core/graphql.

The core service expects 2 headers, the X-SITE-ID and authorization so the request would be:

POST https://api.subsbase.io/core/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

Returns an array of payment schedules.

Query

query GetPaymentSchedules($siteId: String!,$filter: FilterGQLInputType,$pagination: PaginationGQLInputType,$sorting: [SortingGQLInputType]) { 
    paymentSchedules (siteId: $siteId,filter: $filter,pagination: $pagination,sorting: $sorting) {
        isSuccess
        pagination
        data
        message
    } 
}

GraphQL Variables

{"siteId":"","filter":"","pagination":"","sorting":""}

For details about Filter, Sorting and Pagination Input Types, please check out FilterGQLInputType, SortingGQLInputType, and PaginationGQLInputType.

Payment Schedule

Returns a specific payment schedule.

Query

query GetPaymentSchedule($siteId: String!,$paymentScheduleId: String!) { 
    paymentSchedule (siteId: $siteId,paymentScheduleId: $paymentScheduleId) {
        siteId
        id
        name
        product
        currency
        paymentMethod
        customer
        data
        scheduledPayments
        invoiceId
        invoice
        dunningProfile
    } 
}

GraphQL Variables

{
    "siteId":"",
    "paymentScheduleId":""
}

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

mutation CreateCustomerPaymentSchedules(
    $siteId: String!
    $customerId: String!
    $paymentSchedule: PaymentScheduleGQLInputType!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        paymentSchedules {
            create(paymentSchedule: $paymentSchedule) {
                isSuccess
                message
            }
        }
    }
}

GraphQL Variables

{
  "siteId": "test-site",
  "customerId": "test-site_341f7f56d2304428a19c85b6d6274322",
  "paymentSchedule": {
    "siteId": "test-site",
    "name": "test-schedule-payment",
    "product": "test-schedule-payment",
    "currencyCode": "egp",
    "paymentMethod": {
      "id": "9392e570-f006-41c0-bbba-8705ce0030b8",
      "displayText": "8769",
      "isDefault": false,
      "type": "Visa Card",
      "metaData": "",
      "identifier": "",
      "providerReference": null,
      "sitePaymentMethodId": "182687d0-7ce2-4312-b589-ec911cb10cdc",
      "billingInfo": {
        "address": {
          "countryCode": "",
          "city": "",
          "province": "",
          "postalCode": "",
          "line1": "",
          "line2": ""
        }
      }
    },
    "data": "{\"invoicing\":\"NoInvoice\"}",
    "scheduledPayments": [
      {
        "name": "test-schedule-payment",
        "date": "2023-02-28T22:00:00.000Z",
        "amount": 20,
        "siteId": "test-site",
        "status": "NotPaid"
      }
    ]
  }
}

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

mutation CreateCustomerPaymentSchedulesFromTemplate(
    $siteId: String!
    $customerId: String!
    $paymentScheduleFromTemplate: PaymentScheduleFromTemplateGQLInputType!
) {
    customer(siteId: $siteId, customerId: $customerId) {
        paymentSchedules {
            createFromTemplate(
                paymentScheduleFromTemplate: $paymentScheduleFromTemplate
            ) {
                isSuccess
                message
            }
        }
    }
}

GraphQL 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

Returns an array of payment schedule templates.

Query

query PaymentScheduleTemplates($siteId: String!,$filter: FilterGQLInputType,$pagination: PaginationGQLInputType,$sorting: [SortingGQLInputType]) { 
    paymentScheduleTemplates (siteId: $siteId,filter: $filter,pagination: $pagination,sorting: $sorting) {
        isSuccess
        pagination
        data
        message
    } 
}

GraphQL Variables

{"siteId":"","filter":"","pagination":"","sorting":""}

Payment Schedule Template

Returns a specific payment schedule template.

Query

query PaymentScheduleTemplate($siteId: String!,$paymentScheduleTemplateId: String!) { 
    paymentScheduleTemplate (siteId: $siteId,paymentScheduleTemplateId: $paymentScheduleTemplateId) {
        id
        siteId
        name
        description
        data
        payments
    } 
}

GraphQL 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

mutation CreatePaymentScheduleTemplate(
    $siteId: String!
    $paymentScheduleTemplate: PaymentScheduleTemplateGQLInputType!
) {
    paymentScheduleTemplates(siteId: $siteId) {
        create(paymentScheduleTemplate: $paymentScheduleTemplate) {
            isSuccess
            message
        }
    }
}

GraphQL 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

mutation UpdatePaymentScheduleTemplate(
    $siteId: String!
    $PaymentScheduleTemplateId: String!
    $paymentScheduleTemplate: PaymentScheduleTemplateGQLInputType!
) {
    paymentScheduleTemplate(
        siteId: $siteeId
        paymentScheduleTemplateId: $PaymentScheduleTemplateId
    ) {
        update(paymentScheduleTemplate: $paymentScheduleTemplate) {
            isSuccess
            message
        }
    }
}

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

Delete Payment Schedule Template

To delete 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

mutation DeletePaymentScheduleTemplate(
    $siteId: String!
    $PaymentScheduleTemplateId: String!
) {
    paymentScheduleTemplate(
        siteId: $siteId
        paymentScheduleTemplateId: $PaymentScheduleTemplateId
    ) {
        delete {
            isSuccess
            message
        }
    }
}

GraphQL Variables

{
    "siteId": "test-site",
    "paymentScheduleTemplateId": "ffa1d184-c35a-4d51-b55c-75b20ed37628"
}

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

query GetSitePaymentMethods($siteId: String!) { 
    getSitePaymentMethods (siteId: $siteId) {
        id
        siteId
        paymentProviderCode
        displayText
        displayImage
        properties
    } 
}

GraphQL 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

query GetSiteManualPaymentMethods($siteId: String!) { 
    getSiteManualPaymentMethods (siteId: $siteId) {
        id
        siteId
        paymentProviderCode
        displayText
        displayImage
        properties
    } 
}

GraphQL 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

mutation ChangePaymentMethod(
    $siteId: String!
    $paymentScheduleId: String!
    $paymentMethod: PaymentMethodGQLInputType!
) {
    paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
        changePaymentMethod(paymentMethod: $paymentMethod) {
            isSuccess
            message
        }
    }
}

GraphQL 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

Returns an array of dunning profiles.

Query

query GetDunningProfiles($siteId: String!,$filter: FilterGQLInputType,$pagination: PaginationGQLInputType,$sorting: [SortingGQLInputType]) { 
    dunningProfiles (siteId: $siteId,filter: $filter,pagination: $pagination,sorting: $sorting) {
        isSuccess
        pagination
        data
        message
    } 
}

GraphQL Variables

{"siteId":"","filter":"","pagination":"","sorting":""}

Get Dunning Profile

Returns a specific dunning profile.

Query

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

GraphQL Variables

{"siteId":"","dunningProfileId":""}

Change Dunning Profile

This operation changes/updates the infofields of an existing dunning profile.
To change/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

mutation ChangeDunningProfile(
    $siteId: String!
    $paymentScheduleId: String!
    $dunningProfileId: String!
) {
    paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
        changeDunningProfile(dunningProfileId: $dunningProfileId) {
            isSuccess
            message
        }
    }
}

GraphQL Variables

{
    "siteId": "test-site",
    "paymentScheduleId": "d6c1d09b-c27b-4d2b-8ea1-1afed93038a3",
    "dunningProfileId": "b6288d74-f84c-4413-8431-6c097ffeab5e"
}