Create a recurring schedule

For full-service accounts (accounts where Debitsuccess has a recurring schedule for a customer and a total amount to collect - e.g. $1,200 to collect over 12 monthly payments). Normally a customer will be debited on the same day or date each week/fortnight/month (e.g. 1^st of the month or every Wednesday), so to avoid accidentally starting a new schedule on a different day/date we will, by default, align a new schedule with the customer’s existing schedule, if they have one.

For example,

01/01/2021 $200

01/02/2021 $200

01/03/2021 $200

A request to create a new schedule is received with an instalment amount of $190 and a MinimumEffectiveDate of 28/03/2021.

SOAP API

Using CreateSchedule call you can set a recurring schedule as follows:

Assuming the OverrideBillingCycleAlignment option is not set, the billing will continue as follows:

01/04/2021 $190

01/05/2021 $190

01/06/2021 $190

If OverrideBillingCycleAlignment is set to true then the new schedule would start on 28/03/2021.

REST API

Use the Create Recurring Schedule endpoint of Customer Services API to create a new recurring schedule for a customer.

POST https://<ServerURL>/CustomerServices/v1.0/accounts/{accountId}/recurringSchedules

The newly created schedule will be created as an open-ended schedule, hence there is no EndDate parameter.
Accepted values for Frequency are Weekly, Fortnightly, Four-weekly, Monthly, Bi-monthly and Quarterly.
If OverrideBillingCycleAlignment is set to true will overrides default behaviour and sets the start date of the new payment schedule to be the recurringScheduleStartDate as described in the example above.

Tiered Schedule

REST API

When an account is loaded using the Create Account it allows a maximum of three recurring schedules to be assigned to an account. These schedules can be configured as tiered schedules with different start dates, instalment amounts, and frequencies.

POST https://<ServerURL>/CustomerServices/v1.0/accounts

However, the Create Recurring Schedule endpoint only creates an open-ended schedule until the account reaches the end of term or it is closed down. See the below example for a tiered schedule.

SOAP API

The below request is an example is where an account with a recurring schedule has already been loaded using PostCustomerAccount.

Assuming the initial schedule is for $10 weekly starting on 6th of Jan 2021, the following request using CreateSchedule will cause the payments from the 20th of Jan onwards to be $50 weekly, so the structure of the account would be:

6th Jan - $10
13th Jan - $10
20th Jan - $50

Payments will continue at $50 weekly until the account reaches the end of term or it is closed down.

Note: If an account is fixed term, the contract value will be set when the account is initially loaded (based on the initial schedule), so in this case, the contract value would need to be adjusted as well using the AdjustAccountTotalValue message.

Sample request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:deb="Debitsuccess.WebServices.WCF" xmlns:deb1="http://schemas.datacontract.org/2004/07/Debitsuccess.WebServices.Core">
   <soapenv:Header/>
   <soapenv:Body>
      <deb:CreateSchedule>
         <deb:request>
            <deb1:DateCreated>2020-09-22</deb1:DateCreated>
            <deb1:Id>333</deb1:Id>
            <deb1:RequestInitiator>ReqInit333</deb1:RequestInitiator>
            <deb1:User>
               <deb1:Id>33333</deb1:Id>
               <deb1:Password>#Password</deb1:Password>
               <deb1:Username>Username</deb1:Username>
            </deb1:User>
            <deb1:AccountReferenceNo>Abc12345</deb1:AccountReferenceNo>
            <deb1:ExternalAccountReferenceNo></deb1:ExternalAccountReferenceNo>
            <deb1:NewPaySchedule>
               <deb1:Id></deb1:Id>
               <deb1:Description>test schedule 1</deb1:Description>
               <deb1:Installment>10</deb1:Installment>
               <deb1:PaymentFrequency>Weekly</deb1:PaymentFrequency>
               <deb1:ScheduleId>123457</deb1:ScheduleId>
               <deb1:MinimumEffectiveDate>2020-12-16</deb1:MinimumEffectiveDate>
               <deb1:ExternalScheduleIdentifier>ext123457</deb1:ExternalScheduleIdentifier>
            </deb1:NewPaySchedule>
         </deb:request>
      </deb:CreateSchedule>
   </soapenv:Body>
</soapenv:Envelope>

Sample response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Header>
      <ActivityId CorrelationId="7c8b6ca0-aa02-4b97-81dc-e93c3df0a9e3" xmlns="http://schemas.microsoft.com/2004/09/ServiceModel/Diagnostics">00000000-0000-0000-0000-000000000000</ActivityId>
   </s:Header>
   <s:Body>
      <CreateScheduleResponse xmlns="Debitsuccess.WebServices.WCF">
         <CreateScheduleResult xmlns:a="http://schemas.datacontract.org/2004/07/Debitsuccess.WebServices.Core" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <a:DateCreated>2020-12-01T16:06:48.3423919+13:00</a:DateCreated>
            <a:Id>50dc3dbf-f4ec-4e75-8e3e-8dc4e2bedfd6</a:Id>
            <a:ResponseNotes>
               <a:ResponseMessageNote>
                  <a:Code>00</a:Code>
                  <a:Note>Success</a:Note>
                  <a:NoteType>Info</a:NoteType>
               </a:ResponseMessageNote>
            </a:ResponseNotes>
            <a:Status>Succeed</a:Status>
            <a:NewScheduleId>66522251</a:NewScheduleId>
         </CreateScheduleResult>
      </CreateScheduleResponse>
   </s:Body>
</s:Envelope>

Price increase for customers

A price increase is similar to the tiered schedule example above, but the account must be outside minimum term (unless the customer signs a variation form) and the customer must be notified about the price increase.

Creating a Payment Break

If you want to create a gap in payments for a customer (to give the customer free time), for example:

01-Feb $100

01-Mar $100

01-Apr $100

01-May $100

You would load the first schedule (usually along with the account using PostCustomerAccount) and then create the 2nd schedule using CreateSchedule with a MinimumEffectiveDate of 01-May and a previousScheduleEndDate of 31-Mar, this way the customer will not have a payment due in April. You could achieve a similar outcome using a suspension, but this would add on the suspension period to the end of the contract.

If you are using REST APIs, the Create Recurring Schedule endpoint can be used with the MinimumEffectiveDate and previousScheduleEndDate parameters set as explained above.

Changing the Instalment Amount for a Future Schedule

If you have a schedule starting on a future date and you want to change the amount, date, or frequency of the payment, the easiest way to do this is to replace the schedule with a new one.

For example,

Schedule 1 - $100 Monthly from 01-Jan

Schedule 2 - $150 Monthly from 01-May

If the customer has the above schedules configured and would like to change schedule 2 to be $30 Weekly from 01-May. To do this, you can use CreateSchedule including an instalment of $30, frequency weekly, and deleteFutureSchedules set to true. The deleteFutureSchedules flag will cause the schedule starting on the same day or future to be removed.

If you are using REST APIs, the Create Recurring Schedule endpoint can be used with the same parameters as explained above.

Page:

Create a recurring schedule
Page:

Create a one-off schedule
Page:

Change the payment date
Page:

CreateSchedule — Creates a new recurring or one-off payment schedule for a customer.

On this page:

1 Create a recurring schedule
- 1.1 SOAP API
- 1.2 REST API
2 Tiered Schedule
- 2.1 REST API
- 2.2 SOAP API
  - 2.2.1 Sample request
  - 2.2.2 Sample response
3 Price increase for customers
4 Creating a Payment Break
5 Changing the Instalment Amount for a Future Schedule
6 Related Articles