Web3 Sandpit API

Appearance

Subscription Routes ​

This page provides routes for managing subscriptions. The following routes are available:

POST /subscriptions ​

Description:

This route creates a new subscription.

Authentication:

This route requires authentication with the ADMIN role and the subscription_management, create and write permission.

Request Body:

json
{
  "credits": 0,
  "endDate": "2025-01-01",
  "startDate": "2024-01-01",
  "plan": "basic",
  "orgId": "6546576514654"
}
  • credits (number, required) - The number of credits to allocate.
  • endDate (date, required) - The end date of the subscription.
  • startDate (date, required) - The start date of the subscription.
  • plan (string, required) - The plan for the subscription. Options: 'basic', 'standard', 'premium'.
  • orgId (ObjectId, required) - The ID of the organization.

Response:

On success, it returns the created subscription object.

json
{
  "credits": {
    "total": 100,
    "unallocated": 100,
    "used": 0,
    "remaining": 100,
    "allocated": 0
  },
  "deleted": false,
  "endDate": "2025-12-31T00:00:00.000Z",
  "orgId": "667557920a25f2695e6c5b1c",
  "plan": "basic",
  "startDate": "2024-07-29T00:00:00.000Z",
  "status": "active",
  "id": "66829ea7262b9c216f2a7f38"
}
  • 200 - OK - If the subscription is created successfully.

Errors:

If there is an error creating the subscription, it will return an appropriate error message.

  • 401 - UNAUTHORIZED - If the user is not authenticated.
  • 400 - BAD_REQUEST - If the request body is missing required fields.
  • 500 - INTERNAL_SERVER_ERROR - If there is an error creating the subscription.

Usage:

To create a new subscription, send a POST request to /subscriptions with the subscription details in the request body. Ensure that you are authenticated with the ADMIN role and have the write permission.

Demo:

Try it out on Swagger UI

GET /subscriptions ​

Description:

This route retrieves the subscription history for the authenticated user's organization.

Authentication:

This route requires authentication with OWNER role and the read permission.

Response:

On success, it returns an array of subscription objects representing the subscription history for the authenticated user's organization.

json
[
  {
    "credits": {
      "total": 100,
      "unallocated": 85,
      "remaining": 100,
      "used": 0,
      "allocated": 15
    },
    "status": "active",
    "deleted": false,
    "endDate": "2024-06-20T00:20:00.000Z",
    "plan": "basic",
    "startDate": "2024-06-12T00:00:00.000Z",
    "orgId": "666141dbfe2a0781e76f6549",
    "id": "6667fedf99c95d011386167f"
  }
]
  • 200 - OK - If the subscription history is retrieved successfully.

Errors:

If there is an error retrieving the subscription history, it will return an appropriate error message.

  • 401 - UNAUTHORIZED - If the user is not authenticated.
  • 404 - NOT_FOUND - If the user is not found.
  • 500 - INTERNAL_SERVER_ERROR - If there is an error retrieving the subscription history.

Usage:

To retrieve the subscription history for the authenticated user's organization, send a GET request to /subscriptions. Ensure that you are authenticated with OWNER role and have the read permission.

POST /subscriptions/query ​

Description:

This route queries for subscriptions based on specific criteria.

Authentication:

This route requires authentication with the ADMIN role and the subscription_management and read permission.

Request Body:

To query for subscriptions, In the request body, you can include the necessary fields for filtering and sorting the results. The filter field allows you to specify which subscriptions to include in the query, and the options field can be used to specify pagination and sorting parameters.

json
{
  "filter": {
    "orgId": "6fc6f0e3f0e3f0e3f0e3f0e3" // (ObjectId) ID of the organization,
  },
  "options": {
    "page": 1, // (number) page number,
    "limit": 10, // (number) number of results per page,
    "sort": "createdAt:desc", // (string) sort order
    "fields": "createdAt" // (string) comma-separated list of fields to include in the response
  }
}
  • filter (object, required) - The filter criteria for the query.
  • options (object, required) - The options for the query.

Response:

On success, it returns an array of subscription objects matching the query criteria.

json
[
  {
    "_id": "6667f86a11fc9ba506d598e6",
    "credits": {
      "total": 100,
      "allocated": 0,
      "remaining": 0,
      "used": 0
    },
    "endDate": "2024-06-18T00:00:00.000Z",
    "plan": "premium",
    "startDate": "2024-05-12T00:00:00.000Z",
    "createdAt": "2024-06-11T07:10:34.682Z",
    "updatedAt": "2024-06-18T07:35:00.016Z",
    "status": "inactive"
  },
  {
    "_id": "666c17201e99fb0aede5379e",
    "credits": {
      "total": 124,
      "unallocated": 124,
      "used": 0
    },
    "endDate": "2025-06-20T00:00:00.000Z",
    "orgId": "66614457aeca9967422b018e",
    "plan": "premium",
    "startDate": "2024-06-15T00:00:00.000Z",
    "status": "active",
    "createdAt": "2024-06-14T10:10:40.112Z",
    "updatedAt": "2024-06-14T11:49:28.205Z"
  }
]
  • 200 - OK - If the subscriptions are retrieved successfully.

Errors:

If there is an error querying subscriptions, it will return an appropriate error message.

  • 401 - UNAUTHORIZED - If the user is not authenticated.
  • 500 - INTERNAL_SERVER_ERROR - If there is an error querying subscriptions.

Usage:

To query for subscriptions, send a POST request to /subscriptions/query with the query criteria in the request body. Ensure that you are authenticated with the ADMIN role and have the read permission.

GET /subscriptions/my ​

Description:

This route retrieves all subscriptions for the authenticated user.

Authentication:

This route requires authentication with the USER role and the read permission.

Response:

On success, it returns an array of subscription objects for the authenticated user.

json
[
  {
    "credits": [],
    "creditsRemaining": 0,
    "creditsTotal": 0,
    "creditsUsed": 0,
    "id": "667e52015767249ca5838bfa"
  }
]
  • 200 - OK - If the subscriptions are retrieved successfully.

Errors:

If there is an error retrieving the subscriptions, it will return an appropriate error message.

  • 401 - UNAUTHORIZED - If the user is not authenticated.
  • 404 - NOT_FOUND - If the user is not found.
  • 500 - INTERNAL_SERVER_ERROR - If there is an error retrieving the subscriptions.

Usage:

To retrieve all subscriptions for the authenticated user, send a GET request to /subscriptions/my. Ensure that you are authenticated with the USER role and have the read permission.

GET /subscriptions/active/my ​

Description: This route retrieves the active subscription for the authenticated user.

Authentication:

This route requires authentication with the USER role and the read permission.

Response:

On success, it returns the active subscription object for the authenticated user.

json
[
  {
    "credits": [],
    "creditsRemaining": 0,
    "creditsTotal": 0,
    "creditsUsed": 0,
    "id": "667e52015767249ca5838bfa"
  }
]
  • 200 - OK - If the active subscription is retrieved successfully.

Errors:

If there is an error retrieving the active subscription, it will return an appropriate error message.

  • 401 - UNAUTHORIZED - If the user is not authenticated.
  • 404 - NOT_FOUND - If the user is not found.
  • 500 - INTERNAL_SERVER_ERROR - If there is an error retrieving the active subscription.

Usage:

To retrieve the active subscription for the authenticated user, send a GET request to /subscriptions/active/my. Ensure that you are authenticated with the USER role and have the read permission.

GET /subscriptions/active/user/:userId ​

Description:

This route retrieves the active subscription for a specific user.

Parameters:

  • userId (string, required): The ID of the user.

Authentication:

This route requires authentication with the OWNER role and the read permission.

Response:

On success, it returns the active subscription object for the specified user.

json
[
  {
    "from": "66756e07ac43d0f30402ae6f",
    "remaining": 10,
    "total": 10,
    "used": 0
  }
]
  • 200 - OK - If the active subscription is retrieved successfully.

Errors:

If there is an error retrieving the active subscription, it will return an appropriate error message.

  • 401 - UNAUTHORIZED - If the user is not authenticated.
  • 404 - NOT_FOUND - If the user is not found.
  • 500 - INTERNAL_SERVER_ERROR - If there is an error retrieving the active subscription.

Usage:

To retrieve the active subscription for a user, send a GET request to /subscriptions/active/user/:userId with the user ID in the URL. Ensure that you are authenticated with the OWNER role and have the read permission.

GET /subscriptions/active/organization/:orgId ​

Description:

This route retrieves the active subscription for a specific organization.

Parameters:

  • orgId (string, required): The ID of the organization.

Authentication:

This route requires authentication with the ADMIN role and the subscription_management and read permission.

Response:

On success, it returns the active subscription object for the specified organization.

json
[
  {
    "credits": {
      "total": 100,
      "unallocated": 80,
      "used": 0,
      "remaining": 100,
      "allocated": 20
    },
    "deleted": false,
    "endDate": "2025-12-31T00:00:00.000Z",
    "orgId": "666141dbfe2a0781e76f6549",
    "plan": "basic",
    "startDate": "2024-06-19T00:00:00.000Z",
    "status": "active",
    "id": "667167d5c655e8810245c41a"
  },
  {
    "credits": {
      "total": 100,
      "unallocated": 100,
      "used": 0,
      "remaining": 100,
      "allocated": 0
    },
    "deleted": false,
    "endDate": "2025-12-31T00:00:00.000Z",
    "orgId": "666141dbfe2a0781e76f6549",
    "plan": "basic",
    "startDate": "2024-06-19T00:00:00.000Z",
    "status": "active",
    "id": "667175a4665a2e5178b736a1"
  }
]
  • 200 - OK - If the active subscription is retrieved successfully.

Errors:

If there is an error retrieving the active subscription, it will return an appropriate error message.

  • 401 - UNAUTHORIZED - If the user is not authenticated.
  • 404 - NOT_FOUND - If the organization is not found.
  • 500 - INTERNAL_SERVER_ERROR - If there is an error retrieving the active subscription.

Usage:

To retrieve the active subscription for an organization, send a GET request to /subscriptions/active/organization/:orgId with the organization ID in the URL. Ensure that you are authenticated with the ADMIN role and have the read permission.

GET /subscriptions/organization/:orgId ​

Description:

This route retrieves the subscription history for a specific organization.

Parameters:

  • orgId (string, required): The ID of the organization.

Authentication:

This route requires authentication with the ADMIN role and the subscription_management and read permission.

Response:

On success, it returns an array of subscription objects representing the subscription history for the specified organization.

json
[
  {
    "credits": {
      "total": 100,
      "unallocated": 100,
      "used": 0,
      "remaining": 100,
      "allocated": 0
    },
    "deleted": false,
    "endDate": "2025-12-31T00:00:00.000Z",
    "orgId": "666143fb41d61aaed0bbfbdb",
    "plan": "basic",
    "startDate": "2024-06-13T00:00:00.000Z",
    "status": "active",
    "id": "666c2b741e4220d147f2c073"
  },
  {
    "credits": {
      "total": 100,
      "unallocated": 100,
      "used": 0,
      "remaining": 100,
      "allocated": 0
    },
    "deleted": false,
    "endDate": "2024-12-31T00:00:00.000Z",
    "orgId": "666143fb41d61aaed0bbfbdb",
    "plan": "basic",
    "startDate": "2024-06-15T00:00:00.000Z",
    "status": "active",
    "id": "666c2c361e4220d147f2c078"
  },
  {
    "credits": {
      "total": 136,
      "unallocated": 290,
      "used": 0,
      "remaining": 136,
      "allocated": -154
    },
    "deleted": false,
    "endDate": "2024-06-17T00:00:00.000Z",
    "orgId": "666143fb41d61aaed0bbfbdb",
    "plan": "basic",
    "startDate": "2024-06-15T00:00:00.000Z",
    "status": "inactive",
    "id": "666c2c3d1e4220d147f2c07a"
  }
]
  • 200 - OK - If the subscription history is retrieved successfully.

Errors:

If there is an error retrieving the subscription history, it will return an appropriate error message.

  • 401 - UNAUTHORIZED - If the user is not authenticated.
  • 404 - NOT_FOUND - If the organization is not found.
  • 500 - INTERNAL_SERVER_ERROR - If there is an error retrieving the subscription history.

Usage:

To retrieve the subscription history for an organization, send a GET request to /subscriptions/organization/:orgId with the organization ID in the URL. Ensure that you are authenticated with the ADMIN role and have the read permission.

PATCH /subscriptions/credits/add ​

Description:

This route adds more credits to a subscription.

Authentication:

This route requires authentication with the ADMIN role and the subscription_management and write permission.

Request Body:

json
{
  "credits": 5,
  "subscriptionId": "65f2d9a9f0d9f0d9a9f0d9a9"
}
  • credits (number, required): The number of credits to add.
  • subscriptionId (objectId, required): The ID of the subscription to add credits to.

Response:

On success, it returns the updated subscription object with the added credits.

  • 200 - OK - If the credits were added successfully.
json
{
  "credits": {
    "total": 112,
    "unallocated": 112,
    "used": 0,
    "remaining": 112,
    "allocated": 0
  },
  "deleted": false,
  "endDate": "2025-12-31T00:00:00.000Z",
  "orgId": "666143fb41d61aaed0bbfbdb",
  "plan": "basic",
  "startDate": "2024-06-13T00:00:00.000Z",
  "status": "active",
  "id": "666c2b741e4220d147f2c073"
}

Errors:

If there is an error adding credits to the subscription, it will return an appropriate error message.

  • 401 - UNAUTHORIZED - If the user is not authenticated.
  • 404 - NOT_FOUND - If the subscription is not found.
  • 500 - INTERNAL_SERVER_ERROR - If there is an error adding credits to the subscription.

Usage:

To add more credits to a subscription, send a PATCH request to /subscriptions/credits/add with the necessary details in the request body. Ensure that you are authenticated with the ADMIN role and have the write permission.

PATCH /subscriptions/credits/allocation ​

Description:

This route allocates credits for a subscription.

Authentication:

This route requires authentication with the OWNER role and the user_management and write permission.

Request Body:

json
{
  "credits": 5,
  "subscriptionId": "65f2d9a9f0d9f0d9a9f0d9a9",
  "userId": "65f2d9a9f0d9f0d9a9f0d9a9"
}
  • credits (number, required): The number of credits to allocate.
  • subscriptionId (objectId, required): The ID of the subscription to allocate credits to.
  • userId (objectId, required): The ID of the user to allocate credits for.

Response:

On success, it returns the updated subscription object with the allocated credits.

json
{
  "updatedSubscription": {
    "credits": {
      "total": 100,
      "unallocated": 85,
      "remaining": 100,
      "used": 0,
      "allocated": 15
    },
    "status": "active",
    "deleted": false,
    "endDate": "2024-06-20T00:20:00.000Z",
    "plan": "basic",
    "startDate": "2024-06-12T00:00:00.000Z",
    "orgId": "666141dbfe2a0781e76f6549",
    "id": "6667fedf99c95d011386167f"
  },
  "updatedUser": {
    "deleted": false,
    "email": "johnDoe@example.com",
    "orgId": "666141dbfe2a0781e76f6549",
    "credits": [
      {
        "from": "6667fedf99c95d011386167f",
        "remaining": 5,
        "total": 5,
        "used": 0
      }
    ],
    "creditsRemaining": 5,
    "creditsTotal": 5,
    "creditsUsed": 0,
    "id": "667508dac02f4472622d33ee"
  }
}
  • 200 - OK - If the credits were allocated successfully.

Errors:

If there is an error allocating credits to the subscription, it will return an appropriate error message.

  • 400 - BAD_REQUEST - If the request body is invalid.
  • 401 - UNAUTHORIZED - If the user is not authenticated.
  • 404 - NOT_FOUND - If the subscription or user is not found.
  • 500 - INTERNAL_SERVER_ERROR - If there is an error allocating credits to the subscription.

Usage:

To allocate credits for a subscription, send a PATCH request to /subscriptions/credits/allocation with the necessary details in the request body. Ensure that you are authenticated with the OWNER role and have the write permission.

GET /subscriptions/:subscriptionId ​

Description:

This route retrieves a specific subscription by its ID.

Parameters:

  • subscriptionId (string, required): The ID of the subscription.

Authentication:

This route requires authentication with either the ADMIN or OWNER role and the read permission.

Response:

On success, it returns the subscription object with the specified ID.

  • 200 - OK - If the subscription is retrieved successfully.
json
{
  "credits": {
    "unallocated": 0,
    "total": 100,
    "allocated": 100,
    "remaining": 100,
    "used": 0
  },
  "createdBy": "66605ceba6b6a8478a0953ea",
  "deleted": false,
  "endDate": "2024-06-18T00:00:00.000Z",
  "organizationId": "666143fb41d61aaed0bbfbdb",
  "plan": "premium",
  "startDate": "2024-05-12T00:00:00.000Z",
  "deletedBy": "66605ceba6b6a8478a0953ea",
  "status": "inactive",
  "id": "6667f86a11fc9ba506d598e6"
}

Errors:

If there is an error retrieving the subscription, it will return an appropriate error message.

  • 401 - UNAUTHORIZED - If the user is not authenticated.
  • 404 - NOT_FOUND - If the subscription is not found.
  • 500 - INTERNAL_SERVER_ERROR - If there is an error retrieving the subscription.

Usage:

To retrieve a specific subscription, send a GET request to /subscriptions/:subscriptionId with the subscription ID in the URL. Ensure that you are authenticated with either the ADMIN or OWNER role and have the read permission.

PATCH /subscriptions/:subscriptionId ​

Description:

This route updates a specific subscription by its ID.

Parameters:

  • subscriptionId (string, required): The ID of the subscription.

Authentication:

This route requires authentication with the ADMIN role and the subscription_management and update permission.

Response:

On success, it returns the updated subscription object.

json
{
  "credits": {
    "total": 135,
    "unallocated": 125,
    "used": 0,
    "remaining": 135,
    "allocated": 10
  },
  "deleted": false,
  "endDate": "2025-12-31T00:00:00.000Z",
  "orgId": "667557920a25f2695e6c5b1c",
  "plan": "basic",
  "startDate": "2024-07-29T00:00:00.000Z",
  "status": "active",
  "updatedBy": "66740a56d434270f2c248db0",
  "id": "66756e07ac43d0f30402ae6f"
}
  • 200 - OK - If the subscription is updated successfully.

Errors:

If there is an error updating the subscription, it will return an appropriate error message.

  • 401 - UNAUTHORIZED - If the user is not authenticated.
  • 404 - NOT_FOUND - If the subscription is not found.
  • 500 - INTERNAL_SERVER_ERROR - If there is an error updating the subscription.

Usage:

To update a specific subscription, send a PATCH request to /subscriptions/:subscriptionId with the subscription ID in the URL and the updated subscription details in the request body. Ensure that you are authenticated with the ADMIN role and have the write permission.

DELETE /subscriptions/:subscriptionId ​

Description:

This route deletes a specific subscription by its ID.

Parameters:

  • subscriptionId (string, required): The ID of the subscription.

Authentication:

This route requires authentication with the ADMIN role and the delete and subscription_management permission.

Response:

On success, it returns a success message.

json
{
  "credits": {
    "total": 135,
    "unallocated": 125,
    "used": 0,
    "remaining": 135,
    "allocated": 10
  },
  "deleted": true,
  "endDate": "2025-12-31T00:00:00.000Z",
  "orgId": "667557920a25f2695e6c5b1c",
  "plan": "basic",
  "startDate": "2024-07-29T00:00:00.000Z",
  "status": "active",
  "updatedBy": "66740a56d434270f2c248db0",
  "deletedAt": "2024-07-02T06:24:43.457Z",
  "deletedBy": "66740a56d434270f2c248db0",
  "deletedReason": "Subscription deleted",
  "id": "66756e07ac43d0f30402ae6f"
}
  • 200 - OK - If the subscription is deleted successfully.

Errors:

If there is an error deleting the subscription, it will return an appropriate error message.

  • 401 - UNAUTHORIZED - If the user is not authenticated.
  • 404 - NOT_FOUND - If the subscription is not found.
  • 500 - INTERNAL_SERVER_ERROR - If there is an error deleting the subscription.

Usage:

To delete a specific subscription, send a DELETE request to /subscriptions/:subscriptionId with the subscription ID in the URL. Ensure that you are authenticated with the ADMIN role and have the write permission.

CertiCheck

Copyright © 2024 TrackGenesis®