Skip to content

Subscriptions API

🤖 Explain with AI

The Subscriptions API allows you to create and manage recurring subscriptions for your customers.

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 Subscription

Creates a new subscription.

POST /v1/subscriptions

Request Body

Field Type Required Description
customer_id string Yes The customer ID
plan_id string Yes The plan ID to subscribe to

Request Example

curl -X POST 'https://api.4geeks.io/v1/subscriptions' \
  -H 'X-Api-Key: sk_test_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "cus_9a8b7c6d5e4f",
    "plan_id": "plan_x1y2z3a4b5c6"
  }'

import requests

response = requests.post(
    'https://api.4geeks.io/v1/subscriptions',
    headers={'X-Api-Key': 'sk_test_your_api_key_here'},
    json={
        'customer_id': 'cus_9a8b7c6d5e4f',
        'plan_id': 'plan_x1y2z3a4b5c6'
    }
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/subscriptions', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'sk_test_your_api_key_here',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        customer_id: 'cus_9a8b7c6d5e4f',
        plan_id: 'plan_x1y2z3a4b5c6'
    })
});
const data = await response.json();
console.log(data);

Response (200 OK)

Field Type Description
id string Subscription ID
object string Object type (default: “subscription”)
customer_id string Associated customer ID
plan_id string Associated plan ID
status string Subscription status
current_period_end integer End of current billing period (Unix timestamp)

Response Example

{
    "id": "sub_k7l8m9n0o1p2",
    "object": "subscription",
    "customer_id": "cus_9a8b7c6d5e4f",
    "plan_id": "plan_x1y2z3a4b5c6",
    "status": "active",
    "current_period_end": 1746057600
}

List Subscriptions

Lists subscriptions with pagination.

GET /v1/subscriptions

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/subscriptions?limit=5&offset=0' \
  -H 'X-Api-Key: sk_test_your_api_key_here'

import requests

response = requests.get(
    'https://api.4geeks.io/v1/subscriptions',
    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/subscriptions?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[SubscriptionResponse] Array of subscription objects
total_items integer Total number of subscriptions
limit integer Requested page size
offset integer Requested offset

Response Example

{
    "items": [
        {
            "id": "sub_k7l8m9n0o1p2",
            "object": "subscription",
            "customer_id": "cus_9a8b7c6d5e4f",
            "plan_id": "plan_x1y2z3a4b5c6",
            "status": "active",
            "current_period_end": 1746057600
        },
        {
            "id": "sub_q3r4s5t6u7v8",
            "object": "subscription",
            "customer_id": "cus_1f2g3h4i5j6k",
            "plan_id": "plan_w9x8y7z6a5b4",
            "status": "canceled",
            "current_period_end": null
        }
    ],
    "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", "customer_id"],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}

Still questions? Ask the community or explore tutorials