Skip to content
Ridley Docs

Create a recurring payment schedule.

POST
/v1/recurring-payments
curl --request POST \
  --url https://api.ridleypay.com/v1/recurring-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "payment_reference": "WOO-123", "reference": "WOO-SUB-456", "amount": 29.99, "currency": "JMD", "frequency": "daily", "interval_count": 1, "start_date": "2026-04-06", "end_date": "2027-04-06", "customer_email": "jane@example.com", "customer_name": "Jane Doe", "metadata": { "subscription_id": "sub_abc123" }, "apply_tax": true }'

Creates a new recurring billing schedule linked to a previously successful payment. The initial payment’s card token is stored and used for all future charges.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
payment_reference
required

The reference of the initial successful payment to use as the card token source. Must not be greater than 255 characters.

string
Example
WOO-123
reference
required

A unique reference for this recurring schedule (e.g. your subscription ID). Must not be greater than 255 characters.

string
Example
WOO-SUB-456
amount
required

The amount to charge on each billing cycle. Must be at least 0.01.

number
Example
29.99
currency

ISO 4217 currency code. Defaults to the source’s configured currency. Must be 3 characters.

string
nullable
Example
JMD
frequency
required

Billing frequency: daily, weekly, monthly, or yearly.

string
Allowed values: daily weekly monthly yearly
Example
monthly
interval_count

Number of frequency units between charges. Default 1. E.g. interval_count=2 + frequency=monthly = every 2 months. Must be at least 1. Must not be greater than 365.

integer
nullable
Example
1
start_date

When to start billing. Defaults to one interval from today. Must be a valid date. Must be a date after or equal to today.

string
nullable
Example
2026-04-06
end_date

When to stop billing. Null for indefinite. Must be a valid date. Must be a date after start_date.

string
nullable
Example
2027-04-06
customer_email

Customer’s email address. Must be a valid email address. Must not be greater than 255 characters.

string
nullable
Example
jane@example.com
customer_name

Customer’s full name. Must not be greater than 255 characters.

string
nullable
Example
Jane Doe
metadata

Arbitrary key-value data. Included in webhooks.

object
Example
{
  "subscription_id": "sub_abc123"
}
apply_tax

Apply your team tax settings to every charge. With exclusive tax, amount is the subtotal and tax is added; with inclusive tax, tax is extracted from amount. Recalculated on each charge.

boolean
nullable
Example
true

Responses

Section titled “ Responses ”

201

Section titled “201”

Schedule created

Media typeapplication/json
object
data
object
id
string
type
string
attributes
object
reference
string
amount
string
currency
string
frequency
string
interval_count
integer
status
string
next_billing_date
string
manage_url
string
links
object
self
string
Example
{
  "data": {
    "id": "1",
    "type": "recurring-payments",
    "attributes": {
      "reference": "WOO-SUB-456",
      "amount": "29.99",
      "currency": "JMD",
      "frequency": "monthly",
      "interval_count": 1,
      "status": "active",
      "next_billing_date": "2026-04-06",
      "manage_url": "https://pay.example.com/billing/mgt_abc123"
    },
    "links": {
      "self": "https://pay.example.com/api/v1/recurring-payments/WOO-SUB-456"
    }
  }
}

404

Section titled “404”

Initial payment not found

Media typeapplication/json
object
errors
Array<object>
object
status
string
title
string
detail
string
Example
{
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "Payment not found or not successful. A paid initial payment is required."
    }
  ]
}

422

Section titled “422”

Validation error

Media typeapplication/json
object
errors
Array<object>
object
status
string
title
string
detail
string
meta
object
errors
object
payment_reference
Array<string>
Example
{
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Entity",
      "detail": "The payment reference field is required.",
      "meta": {
        "errors": {
          "payment_reference": [
            "The payment reference field is required."
          ]
        }
      }
    }
  ]
}