curl -X POST "${BASE_URL}/api/v2/subscription/createSchedule" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
--data-raw '{
"merchant_id": "48290713",
"plan_id": "DDR73019482",
"type": 6,
"schedule_name": "Usage charge",
"amount": "10.00",
"start_date": "2030-01-15"
}'{
"code": 0,
"message": "ok",
"data": {
"schedule_id": 947281,
"schedule_no": "s1893452400000462",
"status": 2,
"plan_id": "DDR73019482"
}
}Add a payment schedule to a By agreement DDR
Parameters by schedule type
Supply merchant_id, plan_id, type, amount and start_date. The target DDR must be active, have a bound payment method and allow a new schedule.
| type | Schedule type | Additional required fields |
|---|---|---|
| 1 | Successful payment count | day_of_debit, end_terms |
| 2 | Total amount | day_of_debit, total_amount |
| 3 | Until cancelled | day_of_debit |
| 4 | End date | day_of_debit, end_date, with the end date no earlier than start_date |
| 6 | One-off | day_of_debit is not required |
Quarterly, half-yearly and yearly frequencies require day_of_debit_dtstart. Custom frequencies require process_type=12, custom_cycle_type and custom_cycle, consistent with the RRULE. See each field for start dates, first debit dates and full value limits.
Adds a payment schedule only to an activated By agreement DDR with a payment method already attached. The schedule uses that DDR’s payment method. If any schedule is Paused, including a Deposit, resume or cancel it first. If an Active non-Deposit schedule exists, wait until it ends or is cancelled before adding another. Nonstandard RRULE expressions require process_type=12, custom_cycle_type and custom_cycle. start_date cannot precede the DDR start date. The first actual debit must be no earlier than tomorrow in the service business timezone and must comply with the DDR start date and frequency rules. Retain both plan_id and schedule_no from the response.
All examples illustrate request and response formats. Replace customers, orders, cards and accounts with approved test data. BASE_URL is the service root domain without /api/v2. ACCESS_TOKEN is the access_token returned by /oauth/token. Example dates are in 2030; replace them with actual dates that satisfy the current date restrictions.
curl -X POST "${BASE_URL}/api/v2/subscription/createSchedule" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
--data-raw '{
"merchant_id": "48290713",
"plan_id": "DDR73019482",
"type": 6,
"schedule_name": "Usage charge",
"amount": "10.00",
"start_date": "2030-01-15"
}'{
"code": 0,
"message": "ok",
"data": {
"schedule_id": 947281,
"schedule_no": "s1893452400000462",
"status": 2,
"plan_id": "DDR73019482"
}
}Authorizations
OAuth2 client_credentials authorization. Obtain a new access_token when it expires.
Body
Adds a payment schedule to an activated By agreement DDR with a payment method attached, using that DDR's payment method. If any schedule is Paused, including a Deposit, resume or cancel it first. If an Active non-Deposit schedule exists, wait until it ends or is cancelled before adding another. Nonstandard RRULE expressions require process_type=12, custom_cycle_type and custom_cycle together.
Business identifier assigned by BillBuddy.
1 - 20DDR subscription ID.
1 - 50Payment schedule type: 1 after a number of successful payments; 2 at a cumulative amount; 3 until cancelled; 4 on an end date; 6 One-off. Types 5 and 7 are not allowed.
1, 2, 3, 4, 6 One-off or per-payment amount in major currency units, for example 10.50 means AUD 10.50. At most two decimal places. Numbers and numeric strings are accepted, with a minimum of 0.01 and maximum of 9999999.99; the same range applies to both types.
0.01 <= x <= 9999999.99Must be a multiple of 0.01Payment schedule start date in YYYY-MM-DD format. Cannot precede the DDR start date. Past dates are accepted, but the first actual debit must be no earlier than tomorrow in the service business timezone and must comply with the DDR start date and RRULE date rules.
1Payment schedule name. Defaults to the DDR plan_name when omitted.
255Target total amount in major currency units, with at most two decimal places and a minimum of 0.01. Accepts a number or numeric string. Required and non-null when type=2. The number of payments is calculated from the target amount.
x >= 0.01Must be a multiple of 0.01RFC 5545 RRULE debit rule. Required and non-null for type=1/2/3/4; optional for type=6 (one-off). See the integration guide for frequency syntax.
255Provide 12 only for a custom frequency. Other frequencies are inferred from the RRULE; omit this field for them.
12, null Required for process_type=12: 1 days, 2 weeks, 3 months, 4 years. Must correspond to the RRULE FREQ. Non-Custom mode prohibits nonempty custom cycle parameters. Required and non-null when process_type=12.
1, 2, 3, 4, null Required for process_type=12. A positive integer equal to the RRULE INTERVAL. Minimum 5 for days and 1 for other units. Required and non-null when process_type=12.
x >= 1First debit anchor. Required for quarterly, half-yearly and yearly frequencies. YYYY-MM-DD is recommended; the date must be strictly after the corresponding start_date and within one billing cycle (3/6/12 months, clamped to month end). MM-DD is also accepted if it is a valid month/day; the full-date window restriction does not apply to that format.
^(\d{4}-)?\d{2}-\d{2}$End date, preferably YYYY-MM-DD. Required and non-null when type=4. When supplied, cannot precede start_date in the same segment.
Number of successful payments, an integer of at least 1. Required and non-null when type=1.
x >= 1Response
HTTP 200. Distinguish success, business errors, validation errors and business authentication errors using the response body code.