Skip to content

Plans API

🤖 Explain with AI

The Plans API is designed to manage subscription plans efficiently. It supports plan creation, listing all plans, retrieval by ID, modification, and deletion, allowing seamless management of memberships.

The API ensures clear and consistent responses, including detailed error handling, to provide a smooth experience for developers.

Create a plan

Endpoint

POST /v1/plans/

This endpoint allows creating a new recurring plan in the system by sending a POST request with the plan details — such as name, description, amount, currency, interval (frequency of charge), trialPeriodDays, and an optional image. If the operation is successful, it confirms the plan’s creation and provides its unique id.

Request:

curl -X POST 'https://api.4geeks.io/v1/plans/' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Plan Premium",
           "description": "This is a sample plan",
           "currency": "USD",
           "amount": 9.99,
           "interval": "Monthly",
           "trialPeriodDays": 7,
           "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
         }'

Response:

{
    "code": 201,
    "title": "Complete registration",
    "content": "The registration was successfully completed.",
    "type": "success",
    "data": {
        "id": "d36a4a5c-9fa9-4d55-b47f-4f1d50f2a180"
    }
}

Get all plans

Endpoint

GET /v1/plans/

This endpoint retrieves a list of all plans with pagination support. You can specify the page number and the number of plans per page using the page and page_size parameters.

Fields:

Parameter Description Type Required
page The page number to retrieve integer true
page_size The number of plans per page integer true
test Indicates if it is in test mode (true for testing, false for production). boolean false

Request:

curl -X GET 'https://api.4geeks.io/v1/plans/?page_size=1&page=1' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response:

{
  "count": 2,
  "current_page": 1,
  "total_pages": 1,
  "results": [
    {
      "id": "f1a2b3c4-5678-90ab-cdef-1234567890ab",
      "name": "Premium Plan",
      "description": "Unlimited access to all features with premium support.",
      "amount": 9.99,
      "currency": "USD",
      "interval": "Monthly",
      "trialPeriodDays": 7,
      "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...", 
      "created_on": "2025-08-17T20:00:00Z"
    },
    {
      "id": "a1b2c3d4-5678-90ef-ghij-1234567890cd",
      "name": "Basic Plan",
      "description": "Limited access to basic features with standard support.",
      "amount": 4.99,
      "currency": "USD",
      "interval": "Monthly",
      "trialPeriodDays": 0,
      "image": null,
      "created_on": "2025-08-17T20:05:00Z"
    }
  ]
}

Get a specific plan

Endpoint

GET /v1/plans/{id}/

This endpoint get a specific plan.

Fields:

Parameter Description Type Required
test Indicates of the is in test mode (true for testing, false for production). boolean false

Request:

curl -X GET 'https://api.4geeks.io/v1/plans/f9b77185-a62e-4da9-a056-3c7b812ca334/' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response 200 OK:

{
  "id": "f9b77185-a62e-4da9-a056-3c7b812ca334",
  "name": "Standard Plan",
  "description": "This plan offers access to standard features with basic support.",
  "amount": 19.99,
  "currency": "USD",
  "interval": "Monthly",
  "trialPeriodDays": 0,
  "images": {
    "default": "",
    "additional_images": []
  },
  "created_on": "2025-03-25T08:50:15.732299Z",
  "test": true
}

Response 404 Not Found:

{
  "error": {
    "code": 404,
    "message": "Plan not found"
  }
}

Update a plan

Endpoint

PUT /v1/plans/{id}/

This endpoint update a plan.

Fields:

Parameter Description Type Required
test Indicates of the is in test mode (true for testing, false for production). boolean false

Request:

curl -X PUT 'https://api.4geeks.io/v1/plans/f9b77185-a62e-4da9-a056-3c7b812ca334/' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Updated Premium Plan",
           "description": "Updated description with full access to features",
           "amount": 19.99,
           "currency": "USD",
           "interval": "Monthly",
           "trialPeriodDays": 7,
           "images": {
             "default": "",
             "additional_images": []
           },
           "test": false
         }'

Response:

{
    "code": 200,
    "title": "Updated plan",
    "content": "The plan was successfully updated.",
    "type": "success"
}

Delete a plan

Endpoint

DELETE /v1/plans/{id}/

This endpoint removes permanently a plan.

Request:

curl -X DELETE 'https://api.4geeks.io/v1/plans/{id}/' \
     -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response:

{
    "code": 200,
    "title": "plan deleted",
    "content": "The plan was successfully deleted.",
    "type": "success"
}

Error Handling

The API returns standard HTTP status codes to indicate the success or failure of a request. Below are some common errors:

Status Code Error Message Description
400 Bad Request The request is malformed or missing required parameters.
401 Unauthorized The request lacks valid authentication credentials.
404 Not Found The requested resource (e.g., plans ID) does not exist.
500 Internal Server Error An unexpected error occurred on the server. Contact support for assistance.

Example error response:

{
    "error": "Unauthorized",
    "message": "Authentication credentials were not provided."
}