Skip to content
Raidboxes

Subscriptions API

Introduction

The Subscriptions API provides endpoints for managing user subscriptions, including listing subscriptions, canceling, revoking cancellations, and updating subscription details. All endpoints require JWT authentication.

Subscriptions list

Retrieve a paginated list of subscriptions for the authenticated user.

Endpoint

GET /v1/subscriptions

Request Parameters

Parameter Location Type Required Default Description
Authorization Header string Yes - Bearer token (JWT)
filter Query array No - Array of filters (e.g., filter[service]=server)
page Query integer No 1 Page number for pagination
per_page Query integer No 20 Number of items per page
sort Query string No - Sorting criteria (e.g., -created_at for descending)

Example Query

GET /v1/subscriptions?filter[service]=server&page=1&per_page=10&sort=-created_at

Responses

Success Response

  • Status Code: 200 OK
  • Description: List of subscriptions retrieved successfully
  • Body:
[
  {
    "id": "BF67DO",
    "status": "active",
    "service": "server",
    "type": "standard",
    "started_at": "2023-01-15T10:00:00+00:00",
    "renews_at": "2024-01-15T10:00:00+00:00",
    "meta": { ...
      "provider_reference": "BTM7UyUgke08O1tyU",
      "details": {
        "title": "Test Box"
      }
    }, 
    "items": [ ...
      {
        "id": "AJ6EJQCF",
        "name": "Starter",
        "cancellation_date": null,
        "quantity": 1,
        "type": "product",
        "status": "active"
      }
    ] 
  }
]

Error Responses

401 Unauthorized
{
    "timestamp": "2025-12-01T16:37:11+00:00",
    "message": "Authentication credentials are required.",
    "path": "/v1/subscriptions",
    "request_id": "req_5450b035"
}

Cancel subscription

Cancel a specific subscription by its ID. The subscription will remain active until the end of the current billing period.

Endpoint

POST /v1/subscriptions/{id}/cancel

Request Parameters

Parameter Location Type Required Description
id Path string Yes The ID of the subscription to cancel
Authorization Header string Yes Bearer token (JWT)

Responses

Success Response

  • Status Code: 200 OK
  • Description: Subscription canceled successfully
  • Body:
{
  "data": {
    "id": "f32054fd-9bd4-3932-bec8-9c4969495b77",
    "cancellation_date": "2025-12-01T16:15:01+00:00",
    "next_renewal_date": "2026-01-01T16:15:01+00:00",
    "items": [],
    "status": "terminated"
  }
}

Error Responses

401 Unauthorized
{
    "timestamp": "timestamp",
    "path": "/v1/subscriptions/{id}/cancel",
    "request_id": "request-id",
    "message": "Unauthenticated."
}
404 Not Found
{
    "timestamp": "timestamp",
    "path": "/v1/subscriptions/{id}/cancel",
    "request_id": "request-id",
    "message": "Request not found."
}
500 Internal Server Error
{
    "timestamp": "timestamp",
    "path": "/v1/subscriptions/{id}/cancel",
    "request_id": "request-id",
    "message": "Request could not be processed."
}

Cancel specific items of the subscription

Cancel specific items (Add Ons) of a subscription by its ID.

Endpoint

POST /v1/subscriptions/{id}/items/cancel

Request Parameters

Parameter Location Type Required Description
id Path string Yes The ID of the subscription
Authorization Header string Yes Bearer token (JWT)

Request Body

Field Type Required Description
items array Yes Array of item IDs to cancel

Example Request Body

{
  "items": ["AJ6EJQCF", "BK7FKRDG"]
}

Responses

Success Response

  • Status Code: 200 OK
  • Description: Subscription items canceled successfully
  • Body:
{
  "items": [
    {
      "id": "AJ6EJQCF",
      "type": "product",
      "internal_name": "Fully Managed Standard",
      "name": "Fully Managed",
      "cancellation_date": null,
      "status": "active",
      "quantity": 1
    }
  ]
}

Error Responses

401 Unauthorized
{
    "timestamp": "timestamp",
    "path": "/v1/subscriptions/{id}/items/cancel",
    "request_id": "request-id",
    "message": "Unauthenticated."
}
404 Not Found
{
    "timestamp": "timestamp",
    "path": "/v1/subscriptions/{id}/items/cancel",
    "request_id": "request-id",
    "message": "Request not found."
}
500 Internal Server Error
{
    "timestamp": "timestamp",
    "path": "/v1/subscriptions/{id}/items/cancel",
    "request_id": "request-id",
    "message": "Request could not be processed."
}

Revoke cancelled subscription

Revoke a previously canceled subscription by its ID. This will reactivate the subscription.

Endpoint

DELETE /v1/subscriptions/{id}/cancel

Request Parameters

Parameter Location Type Required Description
id Path string Yes The ID of the subscription to revoke cancellation
Authorization Header string Yes Bearer token (JWT)

Responses

Success Response

  • Status Code: 200 OK
  • Description: Subscription cancellation revoked successfully
  • Body:
{
  "data": {
    "id": "f32054fd-9bd4-3932-bec8-9c4969495b77",
    "cancellation_date": null,
    "next_renewal_date": "2026-01-01T16:15:01+00:00",
    "items": [],
    "status": "active"
  }
}

Error Responses

401 Unauthorized
{
    "timestamp": "timestamp",
    "path": "/v1/subscriptions/{id}/cancel",
    "request_id": "request-id",
    "message": "Unauthenticated."
}
404 Not Found
{
    "timestamp": "timestamp",
    "path": "/v1/subscriptions/{id}/cancel",
    "request_id": "request-id",
    "message": "Request not found."
}
500 Internal Server Error
{
    "timestamp": "timestamp",
    "path": "/v1/subscriptions/{id}/cancel",
    "request_id": "request-id",
    "message": "Request could not be processed."
}

Revoke cancellation specific items of the subscription

Revoke cancellation of specific items (Add Ons) of a subscription by its ID.

Endpoint

DELETE /v1/subscriptions/{id}/items/revoke

Request Parameters

Parameter Location Type Required Description
id Path string Yes The ID of the subscription
Authorization Header string Yes Bearer token (JWT)

Request Body

Field Type Required Description
items array Yes Array of item IDs to revoke cancellation

Example Request Body

{
  "items": ["AJ6EJQCF", "BK7FKRDG"]
}

Responses

Success Response

  • Status Code: 200 OK
  • Description: Subscription cancellation items revoked successfully
  • Body:
{
  "items": [
    {
      "id": "AJ6EJQCF",
      "type": "product",
      "internal_name": "Fully Managed Standard",
      "name": "Fully Managed",
      "cancellation_date": null,
      "status": "active",
      "quantity": 1
    }
  ]
}

Error Responses

401 Unauthorized
{
    "timestamp": "timestamp",
    "path": "/v1/subscriptions/{id}/items/revoke",
    "request_id": "request-id",
    "message": "Unauthenticated."
}
404 Not Found
{
    "timestamp": "timestamp",
    "path": "/v1/subscriptions/{id}/items/revoke",
    "request_id": "request-id",
    "message": "Request not found."
}
500 Internal Server Error
{
    "timestamp": "timestamp",
    "path": "/v1/subscriptions/{id}/items/revoke",
    "request_id": "request-id",
    "message": "Request could not be processed."
}