Skip to main content
Welcome to the preview portal — This is an early release of the new Doc Hub experience, with more content coming soon.

Manage Plans

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

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:

Required Fields: Create a Plan
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: Create a Plan
orderInformation.amountDetails.setupFee string
planInformation.code string
planInformation.description string
planInformation.status string

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.

Endpoint

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

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

Example

{    "_links": {        "self": {            "href": "/rbs/v1/plans/1619214189",            "method": "GET"        },        "update": {            "href": "/rbs/v1/plans/1619214189",            "method": "PATCH"        },        "deactivate": {            "href": "/rbs/v1/plans/1619214189/deactivate",            "method": "POST"        }    },    "id": "1619214189",    "status": "COMPLETED",    "planInformation": {        "code": "1619214189",        "status": "ACTIVE"    }}
{    "status": "NOT_FOUND",    "reason": "INVALID_DATA",    "message": "One or more fields in the request contains invalid data.",    "details": [        {            "field": "subscriptionInformation.planId",            "reason": "NOT_FOUND"        }    ]}

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.

Endpoint

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

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

Example

{    "_links": {        "self": {            "href": "/rbs/v1/plans/1619214189",            "method": "GET"        },        "activate": {            "href": "/rbs/v1/plans/1619214189/activate",            "method": "POST"        }    },    "id": "1619214189",    "status": "COMPLETED",    "planInformation": {        "code": "1619214189",        "status": "INACTIVE"    }}
{    "status": "INVALID_REQUEST",    "reason": "INVALID_DATA",    "message": "One or more fields in the request contains invalid data.",    "details": [        {            "field": "planInformation.status",            "reason": "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.

Endpoint

DELETE /rbs/v1/plans/{id}

DELETE /rbs/v1/plans/{id}

Example

{    "status": "COMPLETED"}
{    "status": "NOT_FOUND",    "reason": "NOT_FOUND",    "message": "One or more fields in the request contains invalid data.",    "details": [        {            "field": "subscriptionInformation.planId",            "reason": "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}

PATCH /rbs/v1/plans/{id}

Example

{    "planInformation": {        "name": "AmendPlan",        "description": "Amend Plan 1610394600",        "billingPeriod":{            "length": "4",            "unit": "M"        },        "billingCycles":{            "total": "7"        }    },    "orderInformation": {        "amountDetails": {            "billingAmount": "38.00",            "setupFee": "35"        }    },    "processingInformation": {        "subscriptionBillingOptions": {            "applyTo": "all"        }    }}     
{    "_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",    "submitTimeUtc": "2023-04-13T21:39:34.993Z",    "status": "COMPLETED",    "planInformation": {        "code": "1616024773",        "status": "DRAFT"    }}           
{    "status": "NOT_FOUND",    "reason": "INVALID_DATA",    "message": "One or more fields in the request contains invalid data.",    "details": [        {            "field": "subscriptionInformation.planId",            "reason": "NOT_FOUND"        }    ]}
Optional Fields: Amend a Plan
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.

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

Endpoint

GET /rbs/v1/plans/{id}

GET /rbs/v1/plans/{id}

Example

{    "_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": "NOT_FOUND",  "reason": "INVALID_DATA"}

Retrieve a Plan Code

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

Endpoint

GET /rbs/v1/plans/code

GET /rbs/v1/plans/code

Example

{    "code": "1619310019"}
{  "status": "NOT_FOUND",  "reason": "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

Endpoint

GET /rbs/v1/plans

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"    }  ]}

Last published: October 28, 2026

Not available for your audience

This page isn't available for your current audience selection.