Subscriptions API

The Subscriptions API lets you create and manage customer subscriptions.

Supported subscription flows include:

Creating a subscription: Use the Create a subscription (checkout link) endpoint to create a new subscription. This generates a checkout URL for the customer to complete payment.
Listing subscriptions: The List all subscriptions and List subscription by ID endpoints allow you to retrieve subscriptions for a customer or developer.
Canceling a subscription: Use the Cancel subscription by ID endpoint to cancel an existing subscription.

Create a subscription (checkout link)¶

Endpoint

POST /v1/subscriptions

Creates a local pending subscription record and returns a checkout URL encoded with the customer and developer data. The frontend should redirect the customer to this URL to complete payment. This behavior is implemented by the CreateSubscription view.

Note: The returned checkout URL redirects the customer to the hosted payment flow. Payment and subscription activation are completed asynchronously — the system relies on webhooks to mark the local PlanSubscription as active. Ensure your webhook endpoint is configured and reachable to receive activation events.

Fields

Parameter	Description	Type	Required
`plan_id`	Price/plan id used to locate the local Plan	string	true
`customer_id`	Customer id (existing customer)	string	true

Request

curl -X POST 'https://api.4geeks.io/v1/subscriptions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "plan_id": "price_1AbCdEfG",
    "customer_id": "cus_1234567890",
  }'

Response (201 OK)

{
  "checkout_url": "http://localhost:4200/m/8156f0b9-aabc-43a9-b73b-b615973f2416?data=eyJjdXN0b21lciI6IHsibmFtZSI6ICJ0ZXN0IiwgImVtYWlsIjogInNlYmFzYXJhdkBnbWFpbC5jb20ifSwgImN1c3RvbWVyX2lkIjogImN1c19TeWJkeDhzRklib3d6ayIsICJtZXNzYWdlIjogeyJjb2RlIjogMCwgInRpdGxlIjogIk9LIiwgImNvbnRlbnQiOiAiYWxsIHJlYWR5IGZvciBjaGVja291dCJ9LCAidGVzdCI6IHRydWUsICJkZXZlbG9wZXJfa2V5IjogIktuc0NocVJHbHFyVEduNW1iZEFlZjc1WDhlSVNIOUVSIn0="
}

Errors

Status	Reason	Description
400	Bad Request	Missing required fields (`plan_id`, `customer_id`) or invalid JSON.
401	Unauthorized	Missing or invalid authentication credentials.
404	Not Found	Plan or customer not found in the system.
409	Conflict	Customer already has an active subscription for the plan.
500	Server Error	Unexpected server error.

Example: Bad Request (400)

{
  "code": 400,
  "title": "Invalid custumer_id format",
  "content": "customer_id must be a valid customer ID",
  "type": "danger"
}

Example: Unauthorized (401)

{
  "code": 401,
  "title": "Unauthorized",
  "content": "Authentication credentials were not provided or are invalid.",
  "type": "danger"
}

Example: Not Found (404)

{
  "code": 404,
  "title": "Not Found",
  "content": "Plan with id price_1AbCdEfG not found.",
  "type": "danger"
}

Example: Server Error (500)

{
  "code": 500,
  "title": "Internal Server Error",
  "content": "Invalid_request_error",
  "type": "danger"
}

List subscription by Subscription ID¶

Endpoint

GET /v1/subscriptions/{subscription_id}

Returns the subscriptions associated with the specified subscription_id. If found, the endpoint returns an specific subscription object.

Path parameters

Parameter	Description	Type	Required
`subscription_id`	Public plan key / token identifying the plan	string	true

Request example

curl -X GET 'https://api.4geeks.io/v1/subscriptions/sub_abc21d23' \
  -H 'Authorization: Bearer DEVELOPER_TOKEN'

Response example (200 OK)

{
  "customer": {
    "key": "cust_local_key",
    "name": "Walter Sins",
    "email": "walter@example.com"
  },
  "customer_id": "cus_123sd45",
  "subscription_id": "sub_abc21d23",
  "status": "active",
  "trial_start": "2025-08-01T00:00:00Z",
  "trial_end": "2025-09-01T00:00:00Z",
  "current_period_start": "2025-09-01T00:00:00Z",
  "current_period_end": "2025-10-01T00:00:00Z",
  "start_date": "2025-08-01T00:00:00Z",
}

Errors

Status	Reason	Description
401	Unauthorized	Missing or invalid auth credentials.
404	Not Found	Plan not found.
500	Server Error	Internal error.

List subscription by Key plan¶

Endpoint

GET /v1/subscriptions/{key_plan}

Returns the subscriptions associated with the specified key_plan (public plan key). If found, the endpoint returns an array of subscription objects.

Path parameters

Parameter	Description	Type	Required
`key_plan`	Public plan key / token identifying the plan	string	true

Request example

curl -X GET 'https://api.4geeks.io/v1/subscriptions/plan_abcdef' \
  -H 'Authorization: Bearer DEVELOPER_TOKEN'

Response example (200 OK)

{
  "customer": {
    "key": "cust_local_key",
    "name": "Jane Example",
    "email": "jane@example.com"
  },
  "customer_id": "cus_12345",
  "subscription_id": "sub_abc123",
  "status": "active",
  "trial_start": "2025-08-01T00:00:00Z",
  "trial_end": "2025-09-01T00:00:00Z",
  "current_period_start": "2025-09-01T00:00:00Z",
  "current_period_end": "2025-10-01T00:00:00Z",
  "start_date": "2025-08-01T00:00:00Z",
}

Errors

Status	Reason	Description
401	Unauthorized	Missing or invalid auth credentials.
404	Not Found	Plan not found.
500	Server Error	Internal error.

List all subscriptions¶

Endpoint

GET /v1/subscriptions

Returns a list of subscriptions associated with the caller. When called with a user/customer token the endpoint returns that user’s subscriptions; when called with a developer token it returns subscriptions for the developer’s plans. Implemented by SubscribeListView and protected by authentication.

Request example (user)

curl -X GET 'https://api.4geeks.io/v1/subscriptions' \
  -H 'Authorization: Bearer USER_ACCESS_TOKEN'

Response example (200 OK)

[
  {
    "customer": {
      "key": "cust_local_key",
      "name": "Jane Example",
      "email": "jane@example.com"
    },
    "customer_id": "cus_12345",
    "subscription_id": "sub_abc123",
    "status": "active",
    "trial_start": "2025-08-01T00:00:00Z",
    "trial_end": "2025-09-01T00:00:00Z",
    "current_period_start": "2025-09-01T00:00:00Z",
    "current_period_end": "2025-10-01T00:00:00Z",
    "start_date": "2025-08-01T00:00:00Z",
  }
  {
    "customer": {
      "key": "cust_local_key",
      "name": "Bob Example",
      "email": "bob@example.com"
    },
    "customer_id": "cus_124522",
    "subscription_id": "sub_abc13223",
    "status": "active",
    "trial_start": "2025-08-01T00:00:00Z",
    "trial_end": "2025-09-01T00:00:00Z",
    "current_period_start": "2025-09-01T00:00:00Z",
    "current_period_end": "2025-10-01T00:00:00Z",
    "start_date": "2025-08-01T00:00:00Z",
  } 
]

Errors

Status	Reason	Description
401	Unauthorized	Missing or invalid auth credentials.
403	Forbidden	Token does not have permission to list developer subscriptions.
500	Server Error	Internal error.

Cancel subscription by ID¶

Endpoint

DELETE /v1/subscriptions/{subscription_id}

Cancels a subscription by id. The endpoint receives a subscription_id , sets the local PlanSubscription.active field from true to false, and returns the updated subscription record. Authentication as a developer or an authorized admin is required.

Path parameters

Parameter	Description	Type	Required
`subscription_id`	Subscription id (sub_…) or local id	string	true

Request example

curl -X DELETE 'https://api.4geeks.io/v1/subscriptions/sub_abc123' \
  -H 'Authorization: Bearer DEVELOPER_TOKEN'

Response example (200 OK)

{
  "code": 200,
  "title": "Subscription cancelled",
  "content": "The subscription has been successfully cancelled.",
  "type": "success"
}

Errors

Status	Reason	Description
401	Unauthorized	Missing or invalid auth credentials.
404	Not Found	Subscription not found.
400	Bad Request	Invalid subscription id.
500	Server Error	Internal error.

Notes

This endpoint updates the local PlanSubscription record (active -> false) and attempts to cancel the subscription when available; Errors are logged and surfaced as 500 if critical.
After cancellation the system triggers emails and webhooks to notify plan owners and subscribers when configured.

Ask questions in the community forums.
Check out changelog.