Skip to content

🤖 Explain with AI

Plans API

The Plans API allows you to create and manage subscription plans that define pricing and billing intervals for recurring payments.

Base URL

https://api.4geeks.io

Authentication

All endpoints require the X-Api-Key header:

X-Api-Key: sk_test_your_api_key_here

See Authentication for details.

Create Plan

Creates a new plan.

POST /v1/plans

Request Body

Field Type Required Description
product_id string Yes The associated product ID
amount integer Yes Recurring price in the currency’s minor unit (e.g. cents), greater than 0
currency string Yes Currency code (e.g., USD, EUR)
interval string Yes day, week, month or year (default: month)

Request Example

curl -X POST 'https://api.4geeks.io/v1/plans' \
  -H 'X-Api-Key: sk_test_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "product_id": "prod_a1b2c3d4e5f6",
    "amount": 9999,
    "currency": "USD",
    "interval": "month"
  }'

import requests

response = requests.post(
    'https://api.4geeks.io/v1/plans',
    headers={'X-Api-Key': 'sk_test_your_api_key_here'},
    json={
        'product_id': 'prod_a1b2c3d4e5f6',
        'amount': 9999,
        'currency': 'USD',
        'interval': 'month'
    }
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/plans', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'sk_test_your_api_key_here',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        product_id: 'prod_a1b2c3d4e5f6',
        amount: 9999,
        currency: 'USD',
        interval: 'month'
    })
});
const data = await response.json();
console.log(data);

Response (200 OK)

Field Type Description
id string Plan ID
object string Object type (default: “plan”)
product_id string Associated product ID
amount integer Amount in cents
currency string Currency code
interval string Billing interval
active boolean Whether the plan is active

Response Example

{
    "id": "plan_x1y2z3a4b5c6",
    "object": "plan",
    "product_id": "prod_a1b2c3d4e5f6",
    "amount": 9999,
    "currency": "USD",
    "interval": "month",
    "active": true
}

List Plans

Lists plans with pagination.

GET /v1/plans

Query Parameters

Parameter Type Required Default Description
limit integer No 10 Page size, 1–100
offset integer No 0 Number of results to skip (up to 1000)

Request Example

curl -X GET 'https://api.4geeks.io/v1/plans?limit=5&offset=0' \
  -H 'X-Api-Key: sk_test_your_api_key_here'

import requests

response = requests.get(
    'https://api.4geeks.io/v1/plans',
    headers={'X-Api-Key': 'sk_test_your_api_key_here'},
    params={'limit': 5, 'offset': 0}
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/plans?limit=5&offset=0', {
    headers: {'X-Api-Key': 'sk_test_your_api_key_here'}
});
const data = await response.json();
console.log(data);

Response (200 OK)

Field Type Description
items array[PlanResponse] Array of plan objects
total_items integer Total number of plans. Lower bound: the gateway does not expose counts
limit integer Requested page size
offset integer Requested offset
has_more boolean Whether another page exists

Response Example

{
    "items": [
        {
            "id": "plan_x1y2z3a4b5c6",
            "object": "plan",
            "product_id": "prod_a1b2c3d4e5f6",
            "amount": 9999,
            "currency": "USD",
            "interval": "month",
            "active": true
        },
        {
            "id": "plan_w9x8y7z6a5b4",
            "object": "plan",
            "product_id": "prod_g7h8i9j0k1l2",
            "amount": 4999,
            "currency": "USD",
            "interval": "year",
            "active": true
        }
    ],
    "total_items": 2,
    "limit": 5,
    "offset": 0,
    "has_more": false
}

Error Response (422 Validation Error)

All endpoints may return a 422 status when validation fails.

{
    "detail": [
        {
            "loc": ["body", "product_id"],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}

Still have questions? Ask on Discord or explore the tutorials.