Skip to content

Plans API

🤖 Explain with AI

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 Amount in cents
currency string Yes Currency code (e.g., USD, EUR)
interval string Yes Billing interval (e.g., “month”, “year”)

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 Number of results per page
offset integer No 0 Number of results to skip

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
limit integer Requested page size
offset integer Requested offset

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
}

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 questions? Ask the community or explore tutorials