Skip to main content

​
Recurring Billing Schemas

API endpoints for managing subscription and recurring payment schedules.

​
Endpoints

MethodEndpointDescription
POST/v1/billing/recurring/createCreate recurring billing schedule
POST/v1/recurring/:scheduleId/pausePause recurring schedule
POST/v1/recurring/:scheduleId/resumeResume paused schedule
GET/v1/recurringGet recurring schedules with filters
GET/v1/recurring/:scheduleIdGet specific schedule by ID
DELETE/v1/recurring/:scheduleIdCancel recurring schedule

​
POST /v1/billing/recurring/create

Create a new recurring billing schedule for automated payments.

​
Request Body

{
  "customerId": "string",
  "agreementPhrase": "string",
  "amount": 9.99,
  "currency": "string",
  "frequency": "daily | weekly | monthly | yearly",
  "interval": 1,
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-12-31T23:59:59Z",
  "maxBillings": 12,
  "description": "string",
  "metadata": {}
}

​
Request Schema

FieldTypeRequiredDescription
customerIdstringYesCustomer identifier
agreementPhrasestringYesCustomer agreement phrase
amountnumberYesBilling amount
currencystringYesCurrency code
frequencystringYesBilling frequency
intervalnumberNoInterval between billings (default: 1)
startDatestringYesSchedule start date
endDatestringNoSchedule end date
maxBillingsnumberNoMaximum number of billings
descriptionstringNoSchedule description
metadataobjectNoAdditional metadata

​
Response Schema

{
  "statusCode": 201,
  "success": true,
  "message": "Recurring schedule created successfully",
  "data": {
    "scheduleId": "string",
    "customerId": "string",
    "amount": 9.99,
    "frequency": "monthly",
    "status": "active",
    "nextBillingDate": "2024-02-01T00:00:00Z"
  }
}

​
POST /v1/recurring/:scheduleId/pause

Pause an active recurring billing schedule.

​
Request Body

{
  "reason": "string"
}

​
Response Schema

{
  "statusCode": 200,
  "success": true,
  "message": "Recurring schedule paused successfully",
  "data": {
    "scheduleId": "string",
    "status": "paused",
    "pausedAt": "2024-01-01T00:00:00Z"
  }
}

​
POST /v1/recurring/:scheduleId/resume

Resume a paused recurring billing schedule.

​
Request Body

{
  "reason": "string"
}

​
Response Schema

{
  "statusCode": 200,
  "success": true,
  "message": "Recurring schedule resumed successfully",
  "data": {
    "scheduleId": "string",
    "status": "active",
    "resumedAt": "2024-01-01T00:00:00Z",
    "nextBillingDate": "2024-02-01T00:00:00Z"
  }
}

​
GET /v1/recurring

Get multiple recurring billing schedules with optional filters.

​
Query Parameters

ParameterTypeRequiredDescription
customerIdstringNoFilter by customer ID
statusstringNoFilter by status (active, paused, cancelled)
limitnumberNoNumber of results to return
skipnumberNoNumber of results to skip

​
Response Schema

{
  "statusCode": 200,
  "success": true,
  "data": {
    "schedules": [
      {
        "scheduleId": "string",
        "customerId": "string",
        "amount": 9.99,
        "currency": "string",
        "frequency": "monthly",
        "status": "active",
        "nextBillingDate": "2024-02-01T00:00:00Z",
        "totalBillings": 5,
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1
  }
}

​
Recurring Schedule Schema

FieldTypeDescription
scheduleIdstringUnique schedule identifier
customerIdstringCustomer identifier
agreementPhrasestringAgreement Phrase for billing
amountnumberBilling amount
currencystringCurrency code
frequencystringBilling frequency
intervalnumberInterval between billings
statusstringSchedule status
startDatestringSchedule start date
endDatestringSchedule end date
nextBillingDatestringNext billing date
totalBillingsnumberTotal billings processed
maxBillingsnumberMaximum billings allowed
failedAttemptsnumberFailed billing attempts
descriptionstringSchedule description
createdAtstringCreation timestamp

​
Status Types

StatusDescription
activeSchedule is active and processing
pausedSchedule is temporarily paused
cancelledSchedule has been cancelled
completedSchedule has completed all billings
processingSchedule is currently processing

​
Error Responses

​
400 Bad Request

{
  "statusCode": 400,
  "success": false,
  "message": "Customer must have approve_recurring permission"
}

​
404 Not Found

{
  "statusCode": 404,
  "success": false,
  "message": "Recurring schedule not found"
}