Manage Plans

Response Status Codes

Responses include one of these HTTP status codes:

200: successful.
201: successful.
202: accepted.
400: invalid request.
404: not found.
502: unexpected system error or system timeout.

Create a Plan

Creates a new Recurring Billing plan. The request requires plan information, including billing period, billing amount, and currency. The system returns a plan ID for use in subsequent requests.

Endpoint

POST /rbs/v1/plans

Example

{    "planInformation": {        "billingPeriod": {            "unit": "w",            "length": "1"        },        "billingCycles":        {            "total": "4"        },        "code":"1619310018",        "name": "Test plan",        "description": "Description",        "status":"active"    },    "orderInformation": {        "amountDetails": {            "billingAmount": "7",            "currency": "USD",            "setupFee": "0"        }    }}

{    "_links": {        "self": {            "href": "/rbs/v1/plans/1619212820",            "method": "GET"        },        "update": {            "href": "/rbs/v1/plans/1619212820",            "method": "PATCH"        },        "deactivate": {            "href": "/rbs/v1/plans/1619212820/deactivate",            "method": "POST"        }    },    "id": "1619212820",    "status": "COMPLETED",    "planInformation": {        "code": "1619310018",        "status": "ACTIVE"    }}

{   "status": "INVALID_REQUEST",   "reason": "INVALID_DATA",   "message": "One or more fields in the request contains invalid data.",   "details": [       {          "field": "planInformation.code",          "reason": "DUPLICATE"       }    ] }

These fields are required to create a plan:

Field	Type	Description
`orderInformation.amountDetails.billingAmount`	string
`orderInformation.amountDetails.currency`	string
`planInformation.billingCycles.total`	string	Required for a plan with a defined plan period.
`planInformation.billingPeriod.length`	string
`planInformation.billingPeriod.unit`	string
`planInformation.name`	string

Optional Fields

Field	Type	Description
`orderInformation.amountDetails.setupFee`	string
`planInformation.code`	string
`planInformation.description`	string
`planInformation.status`	string

For more details, see the Create a Plan section of the interactive API Reference.

Activate a Plan

Activates a Recurring Billing plan. An active plan is available for use with subscriptions.

The plan ID is required in the request path.

A 200-level response code indicates success.

For information about response codes, see Transaction Response Codes.

For more details, see the Activate a Plan section of the interactive API Reference.

Endpoint

POST /rbs/v1/plans/{id}/activate

Example

{    "_links": {        "self": {            "href": "/rbs/v1/plans/1619212820",            "method": "GET"        },        "update": {            "href": "/rbs/v1/plans/1619212820",            "method": "PATCH"        },        "deactivate": {            "href": "/rbs/v1/plans/1619212820/deactivate",            "method": "POST"        }    },    "id": "1619212820",    "status": "COMPLETED",    "planInformation": {        "status": "ACTIVE"    }}

{    "status": "INVALID_REQUEST",    "reason": "INVALID_DATA",    "message": "One or more fields in the request contains invalid data."}

Deactivate a Plan

Deactivates a Recurring Billing plan. Only active plans can be deactivated. Deactivating a plan changes its status to inactive.

The plan ID is required in the request path.

For more details, see the Deactivate a Plan section of the interactive API Reference.

Endpoint

POST /rbs/v1/plans/{id}/deactivate

Example

{    "_links": {        "self": {            "href": "/rbs/v1/plans/1619212820",            "method": "GET"        },        "update": {            "href": "/rbs/v1/plans/1619212820",            "method": "PATCH"        },        "activate": {            "href": "/rbs/v1/plans/1619212820/activate",            "method": "POST"        }    },    "id": "1619212820",    "status": "COMPLETED",    "planInformation": {        "status": "INACTIVE"    }}

{    "status": "INVALID_REQUEST",    "reason": "INVALID_DATA",    "message": "One or more fields in the request contains invalid data."}

Delete a Plan

Deletes a Recurring Billing plan.

Plans with draft status can be deleted. Plans with active or inactive status can be deleted only if they have never been assigned to any subscriptions.

The plan ID is required in the request path.

For more details, see the Delete a Plan section of the interactive API Reference.

Endpoint

DELETE /rbs/v1/plans/{id}

Example

{    "status": "COMPLETED"}

{    "status": "INVALID_REQUEST",    "reason": "INVALID_DATA",    "message": "One or more fields in the request contains invalid data."}

Amend a Plan

Updates an existing Recurring Billing plan. The fields available for amendment depend on the plan's current status.

The processingInformation.subscriptionBillingOptions.applyTo field controls whether billing amount changes apply to all existing subscriptions or only to new subscriptions:

ALL: applies changes to all existing subscriptions assigned to the plan
NEW: applies changes only to new subscriptions (default)

Amendment restrictions by plan status

Draft plans: all plan fields can be amended.
Active plans: only planInformation.billingPeriod, planInformation.billingCycles, and orderInformation.amountDetails.currency can be amended.
Inactive plans: cannot be amended. Move to active or draft status first.

Endpoint

PATCH /rbs/v1/plans/{id}

Example

{    "planInformation": {        "billingPeriod": {            "unit": "m",            "length": "1"        },        "billingCycles": {            "total": "12"        },        "name": "Updated plan name",        "description": "Updated description"    },    "orderInformation": {        "amountDetails": {            "billingAmount": "10",            "currency": "USD"        }    },    "processingInformation": {        "subscriptionBillingOptions": {            "applyTo": "NEW"        }    }}

{    "_links": {        "self": {            "href": "/rbs/v1/plans/1619212820",            "method": "GET"        }    },    "id": "1619212820",    "status": "COMPLETED"}

{    "status": "INVALID_REQUEST",    "reason": "INVALID_DATA",    "message": "One or more fields in the request contains invalid data.",    "details": [        {            "field": "planInformation.billingCycles.total",            "reason": "INVALID_VALUE"        }    ]}

Optional Fields

Field	Type	Description
`orderInformation.amountDetails.billingAmount`	string
`orderInformation.amountDetails.setupFee`	string
`planInformation.billingCycles.total`	string	Can only be increased for plans with an existing value.
`planInformation.code`	string
`planInformation.description`	string
`planInformation.name`	string
`processingInformation.subscriptionBillingOptions.applyTo`	string	Default is `NEW`.

For more details, see the Amend a Plan section of the interactive API Reference.

Retrieve a Plan

Retrieves details for a specific Recurring Billing plan.

Response details

The response returns this information:

Plan ID
Plan code
Plan name
Plan description
Plan status
Billing period unit
Billing period length
Number of billing cycles
Currency
Billing amount
Set-up fee

For more details, see the Retrieve a Plan section of the interactive API Reference.

Endpoint

GET /rbs/v1/plans/{id}

Example

{    "_links": {        "self": {            "href": "/rbs/v1/plans/1619212820",            "method": "GET"        },        "update": {            "href": "/rbs/v1/plans/1619212820",            "method": "PATCH"        },        "deactivate": {            "href": "/rbs/v1/plans/1619212820/deactivate",            "method": "POST"        }    },    "id": "1619212820",    "code": "1619310018",    "name": "Test plan",    "description": "Description",    "status": "ACTIVE",    "billingPeriod": {        "unit": "w",        "length": "1"    },    "billingCycles": {        "total": "4"    },    "currency": "USD",    "billingAmount": "7",    "setupFee": "0"}

{    "status": "NOT_FOUND",    "reason": "PLAN_NOT_FOUND",    "message": "The requested plan was not found."}

Retrieve a Plan Code

Retrieves the next consecutive plan code that the system automatically assigns. This retrieves the next code available before plan creation.

For more details, see the Retrieve a Plan Code section of the interactive API Reference.

Endpoint

GET /rbs/v1/plans/code

Example

{    "code": "1619310019"}

{    "status": "INVALID_REQUEST",    "reason": "INVALID_DATA",    "message": "One or more fields in the request contains invalid data."}

Retrieve a List of Plans

Retrieves a list of Recurring Billing plans. Results can be filtered, paginated, and sorted.

Query parameters

filters: a search string in Lucene query syntax used to filter plans.
offset: the number of records before the first record in the result set.
limit: the number of records in the result set. The default is 20. The maximum is 100.

Response details

The response returns this information for each plan:

Plan ID
Plan code
Plan name
Plan description
Plan status
Billing period unit
Billing period length
Number of billing cycles
Currency
Billing amount
Set-up fee
Number of subscribers (total)
Number of active subscribers

For more details, see the Retrieve a List of Plans section of the interactive API Reference.

Endpoint

GET /rbs/v1/plans

Example

{    "_links": {        "self": {            "href": "/rbs/v1/plans?limit=2",            "method": "GET"        },        "next": {            "href": "/rbs/v1/plans?offset=2&limit=2",            "method": "GET"        }    },    "totalCount": 96,    "plans": [        {            "_links": {                "self": {                    "href": "/rbs/v1/plans/1619212820",                    "method": "GET"                },                "update": {                    "href": "/rbs/v1/plans/1619212820",                    "method": "PATCH"                },                "deactivate": {                    "href": "/rbs/v1/plans/1619212820/deactivate",                    "method": "POST"                }            },            "id": "1619212820",            "planInformation": {                "code": "1619310018",                "status": "ACTIVE",                "name": "Test plan",                "description": "Description",                "billingPeriod": {                    "length": "1",                    "unit": "W"                },                "billingCycles": {                    "total": "4"                }            },            "orderInformation": {                "amountDetails": {                    "currency": "USD",                    "billingAmount": "7.00",                    "setupFee": "0.00"                }            }        },        {            "_links": {                "self": {                    "href": "/rbs/v1/plans/6183561970436023701960",                    "method": "GET"                },                "update": {                    "href": "/rbs/v1/plans/6183561970436023701960",                    "method": "PATCH"                },                "activate": {                    "href": "/rbs/v1/plans/6183561970436023701960/activate",                    "method": "POST"                }            },            "id": "6183561970436023701960",            "planInformation": {                "code": "1616024773",                "status": "DRAFT",                "name": "Plan Test",                "description": "12123",                "billingPeriod": {                    "length": "9999",                    "unit": "Y"                },                "billingCycles": {                    "total": "123"                }            },            "orderInformation": {                "amountDetails": {                    "currency": "USD",                    "billingAmount": "1.00",                    "setupFee": "0.00"                }            }        }    ]}

{    "status": "INVALID_REQUEST",    "reason": "VALIDATION_ERROR",    "message": "Field validation errors.",    "details": [        {            "field": "customerInformation.email",            "reason": "Invalid email"        }    ]}

Was this page helpful?

Last published: September 29, 2026