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/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

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

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: $siteId
    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
      }
    ]
  }
}

Scheduled Payments

  • Creates a scheduled payment under a specific payment schedule. Mutation
mutation CreateScheduledPayment(
  $siteId: String!
  $scheduledPayment: ScheduledPaymentGQLInputType!
  $paymentScheduleId: String!
) {
  paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
    scheduledPayments {
      create(scheduledPayment: $scheduledPayment) {
        isSuccess
        message
      }
    }
  }
}

GraphQL Variables

{
  "siteId": "test-site",
  "paymentScheduleId": "",
  "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"
  }
}

Update

  • To update a scheduled payment, you need to use the following: Mutation
mutation UpdateScheduledPayment(
  $siteId: String!
  $paymentScheduleId: String!
  $scheduledPayment: ScheduledPaymentGQLInputType!
) {
  paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
    scheduledPayment(scheduledPayment: $scheduledPayment) {
      update {
        isSuccess
        message
      }
    }
  }
}

GraphQL 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

  • You can choose to delete a specific payment or a batch/list of payments. Mutation

Single Payment Deletion

mutation DeleteScheduledPayment(
  $siteId: String!
  $scheduledPaymentId: [String!]!
  $paymentScheduleId: String!
) {
  paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
    scheduledPayment(scheduledPaymentId: $scheduledPaymentId) {
      delete {
        isSuccess
        message
      }
    }
  }
}

GraphQL Variables

{
  "siteId": "test-site",
  "paymentScheduleId": "ec33559c-fd36-410b-ae63-b7b47b02e216",
  "scheduledPaymentId": "ec33559c-fd36-410b-ae63-b7b47b02e216"
}

Batch Payments Deletion

mutation DeleteScheduledPayment(
  $siteId: String!
  $ids: [String!]!
  $paymentScheduleId: String!
) {
  paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
    scheduledPaymentList(ids: $ids) {
      delete {
        isSuccess
        message
      }
    }
  }
}

GraphQL 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. Mutation

Single Payment Mark as Paid

mutation MarkScheduledPaymentAsPaid(
  $siteId: String!
  $paymentScheduledId: String!
  $scheduledPaymentId: String!
) {
  paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
    scheduledPayment(scheduledPaymentId: $scheduledPaymentId) {
      markAsPaid {
        isSuccess
        message
      }
    }
  }
}

GraphQL 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 MarkScheduledPaymentAsPaid(
  $siteId: String!
  $ids: [String!]!
  $paymentScheduledId: String!
) {
  paymentSchedule(siteId: $siteId, paymentScheduleId: $paymentScheduleId) {
    scheduledPaymentList(ids: $ids) {
      markAsPaid {
        isSuccess
        message
      }
    }
  }
}

GraphQL 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

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