Subscription Plans¶

List subscription plans¶

GET /subscription-plans

Code samples

curl -X GET https://localhost:9543/api/v0.9/subscription-plans \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Lists subscription plans for an organization. When name is supplied, only the matching plan (if any) is returned. Plan names are unique within an organization.

Authentication¶

Parameters

Name	In	Type	Required	Description
name	query	string	false	Filter by exact plan name. Returns an array of zero or one items.

Example responses

200 Response

{
  "list": [
    {
      "id": "string",
      "displayName": "string",
      "description": "string",
      "limits": [
        {
          "limitType": "REQUEST_COUNT",
          "limitCount": 10000,
          "timeUnit": "MONTH",
          "timeAmount": 1
        }
      ],
      "refId": "string",
      "orgId": "string",
      "createdBy": "[email protected]",
      "createdAt": "2026-05-07T08:30:00Z",
      "updatedAt": "2026-05-07T08:30:00Z"
    }
  ],
  "count": 1,
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	List of subscription plan DTOs. Empty array when no plans match.	Inline
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» list	[SubscriptionPlanResponse]	false	none	none
»» id	string	false	none	The plan's handle (unique per org). Not the internal database uuid.
»» displayName	string	false	none	none
»» description	string	false	none	none
»» limits	[object]	false	none	Rate/quota limits enforced for this plan. Empty when the plan is unlimited.
»»» limitType	string	false	none	none
»»» limitCount	any	false	none	Returned as a string when the stored count exceeds the safe integer range, otherwise a number. Unlimited plans have no limit entries — the `limits` array is empty.

oneOf

Name	Type	Required	Restrictions	Description
»»»» anonymous	integer	false	none	none

xor

Name	Type	Required	Restrictions	Description
»»»» anonymous	string	false	none	none

continued

Name	Type	Required	Restrictions	Description
»»» timeUnit	string¦null	false	none	none
»»» timeAmount	integer	false	none	none
»» refId	string¦null	false	none	Platform API subscription plan UUID associated with this plan.
»» orgId	string	false	none	none
»» createdBy	string	false	none	Identity of the user who created this subscription plan, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses and list items.
»» updatedBy	string	false	none	Identity of the user who last updated this subscription plan, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses only, omitted on list items.
»» createdAt	string(date-time)	false	none	none
»» updatedAt	string(date-time)	false	none	none
» count	integer	false	none	Number of items returned in this page.
» pagination	Pagination	false	none	Standard pagination metadata returned with collection responses.
»» total	integer	true	none	Total number of records matching the query.
»» limit	integer	true	none	Maximum number of records returned in this response.
»» offset	integer	true	none	Number of records skipped before this page.

Enumerated Values

Property	Value
limitType	REQUEST_COUNT
limitType	EVENT_COUNT
limitType	BANDWIDTH
limitType	TOTAL_TOKEN_COUNT
timeUnit	MINUTE
timeUnit	HOUR
timeUnit	DAY
timeUnit	MONTH
timeUnit	null

Enumerated Values

Property	Value
status	error

Create subscription plans¶

POST /subscription-plans

Code samples

curl -X POST https://localhost:9543/api/v0.9/subscription-plans \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Creates one subscription plan when the request body is an object, or multiple subscription plans when the body is an array. Bulk creation returns a message instead of creating plans when generateDefaultSubPlans is enabled.

Payload

{
  "id": "Gold",
  "refId": "string",
  "displayName": "string",
  "description": "string",
  "limits": [
    {
      "limitType": "REQUEST_COUNT",
      "limitCount": 10000,
      "timeUnit": "MINUTE",
      "timeAmount": 1
    }
  ]
}

id: Gold
refId: string
displayName: string
description: string
limits:
  - limitType: REQUEST_COUNT
    limitCount: 10000
    timeUnit: MINUTE
    timeAmount: 1

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	any	true	Subscription plan payload. Send a single object for single create/upsert, or a non-empty array for bulk create/upsert; each object carries its rate/quota rules in `limits`. Alternatively, upload a YAML file in the `subscriptionPlan` multipart field; use `kind: SubscriptionPlan` for a single plan or `kind: SubscriptionPlanList` with an `items` array for bulk operations. YAML uploads may use the legacy `type: requestcount` or `type: eventcount` shorthand, which is converted into `limits` before storage.

Example responses

200 Response

{
  "message": "string"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	JSON message response.	MessageResponse
201	Created	Subscription plan create/update response for single or bulk operations.	Inline
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
limitType	REQUEST_COUNT
limitType	EVENT_COUNT
limitType	BANDWIDTH
limitType	TOTAL_TOKEN_COUNT
timeUnit	MINUTE
timeUnit	HOUR
timeUnit	DAY
timeUnit	MONTH
timeUnit	null

Enumerated Values

Property	Value
status	error

Upsert subscription plans¶

PUT /subscription-plans

Code samples

curl -X PUT https://localhost:9543/api/v0.9/subscription-plans \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Upserts one subscription plan when the request body is an object, or multiple plans when the body is an array. A single plan update returns 200 when an existing plan is updated and 201 when a new plan is created. Bulk updates return a message when generateDefaultSubPlans is enabled.

Payload

{
  "id": "Gold",
  "refId": "string",
  "displayName": "string",
  "description": "string",
  "limits": [
    {
      "limitType": "REQUEST_COUNT",
      "limitCount": 10000,
      "timeUnit": "MINUTE",
      "timeAmount": 1
    }
  ]
}

id: Gold
refId: string
displayName: string
description: string
limits:
  - limitType: REQUEST_COUNT
    limitCount: 10000
    timeUnit: MINUTE
    timeAmount: 1

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	any	true	Subscription plan payload. Send a single object for single create/upsert, or a non-empty array for bulk create/upsert; each object carries its rate/quota rules in `limits`. Alternatively, upload a YAML file in the `subscriptionPlan` multipart field; use `kind: SubscriptionPlan` for a single plan or `kind: SubscriptionPlanList` with an `items` array for bulk operations. YAML uploads may use the legacy `type: requestcount` or `type: eventcount` shorthand, which is converted into `limits` before storage.

Example responses

200 Response

{
  "id": "string",
  "displayName": "string",
  "description": "string",
  "limits": [
    {
      "limitType": "REQUEST_COUNT",
      "limitCount": 10000,
      "timeUnit": "MINUTE",
      "timeAmount": 1
    }
  ],
  "refId": "string",
  "orgId": "string",
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Subscription plan update response. Bulk updates may return a list, and some configurations return a message.	Inline
201	Created	Subscription plan create/update response for single or bulk operations.	Inline
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
limitType	REQUEST_COUNT
limitType	EVENT_COUNT
limitType	BANDWIDTH
limitType	TOTAL_TOKEN_COUNT
timeUnit	MINUTE
timeUnit	HOUR
timeUnit	DAY
timeUnit	MONTH
timeUnit	null

Enumerated Values

Property	Value
limitType	REQUEST_COUNT
limitType	EVENT_COUNT
limitType	BANDWIDTH
limitType	TOTAL_TOKEN_COUNT
timeUnit	MINUTE
timeUnit	HOUR
timeUnit	DAY
timeUnit	MONTH
timeUnit	null

Enumerated Values

Property	Value
status	error

Get a subscription plan¶

GET /subscription-plans/{planId}

Code samples

curl -X GET https://localhost:9543/api/v0.9/subscription-plans/{planId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Retrieves a single subscription plan by planId.

Authentication¶

Parameters

Name	In	Type	Required	Description
planId	path	string	true	The subscription plan's handle (unique per org).

Example responses

200 Response

{
  "id": "string",
  "displayName": "string",
  "description": "string",
  "limits": [
    {
      "limitType": "REQUEST_COUNT",
      "limitCount": 10000,
      "timeUnit": "MINUTE",
      "timeAmount": 1
    }
  ],
  "refId": "string",
  "orgId": "string",
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Subscription plan DTO.	SubscriptionPlanResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Delete a subscription plan¶

DELETE /subscription-plans/{planId}

Code samples

curl -X DELETE https://localhost:9543/api/v0.9/subscription-plans/{planId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Deletes a subscription plan by planId.

Authentication¶

Parameters

Name	In	Type	Required	Description
planId	path	string	true	The subscription plan's handle (unique per org).

Example responses

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
204	No Content	Subscription plan deleted successfully.	None
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error