Trial API
Start a 7-day free trial of any paid agent plan — no credit card required. One trial is allowed per organization.
Trial lifecycle
Each trial follows a state machine. Once started, a trial can transition through the following states:
ACTIVE ──► EXPIRED (automatic after 7 days)
ACTIVE ──► CONVERTED (Stripe checkout completed)
ACTIVE ──► CANCELED (user cancels trial)
EXPIRED ─► CONVERTED (3-day grace period allows late conversion)After a trial expires, there is a 3-day grace period during which the organization can still convert to a paid plan without data loss. After the grace period, trial resources are permanently deleted.
Start a trial
Start a 7-day free trial of a paid agent plan. No credit card is required. Each organization may only start one trial.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
plan | string | Yes | Plan to trial: starter, growth, or pro |
curl
curl -X POST https://api.aidenid.com/v1/trials/start \
-H "Authorization: Bearer aid_your_api_key" \
-H "X-Org-Id: org_abc123" \
-H "X-Project-Id: proj_def456" \
-H "Idempotency-Key: <GENERATED_UNIQUE_KEY>" \
-H "Content-Type: application/json" \
-d '{ "plan": "growth" }'Python
import requests
resp = requests.post(
"https://api.aidenid.com/v1/trials/start",
headers={
"Authorization": "Bearer aid_your_api_key",
"X-Org-Id": "org_abc123",
"X-Project-Id": "proj_def456",
"Idempotency-Key": "trial-start-001",
},
json={"plan": "growth"},
)
trial = resp.json()
print(f"Trial {trial['id']} active until {trial['expires_at']}")Response 201 Created
{
"id": "trial_g1h2i3j4",
"plan": "growth",
"status": "ACTIVE",
"started_at": "2026-04-06T10:00:00Z",
"expires_at": "2026-04-13T10:00:00Z",
"org_id": "org_abc123"
}Check trial status
Retrieve the current state of a trial. Possible statuses are ACTIVE, EXPIRED, CONVERTED, and CANCELED.
curl
curl "https://api.aidenid.com/v1/trials/trial_g1h2i3j4" \
-H "Authorization: Bearer aid_your_api_key" \
-H "X-Org-Id: org_abc123" \
-H "X-Project-Id: proj_def456"Response 200 OK
{
"id": "trial_g1h2i3j4",
"plan": "growth",
"status": "ACTIVE",
"started_at": "2026-04-06T10:00:00Z",
"expires_at": "2026-04-13T10:00:00Z",
"days_remaining": 7,
"org_id": "org_abc123"
}Convert trial to paid
Convert an active (or recently expired) trial to a paid subscription. Returns a Stripe checkout URL. Once checkout is completed, the trial status transitions to CONVERTED.
curl
curl -X POST https://api.aidenid.com/v1/trials/trial_g1h2i3j4/convert \
-H "Authorization: Bearer aid_your_api_key" \
-H "X-Org-Id: org_abc123" \
-H "X-Project-Id: proj_def456" \
-H "Idempotency-Key: <GENERATED_UNIQUE_KEY>"TypeScript
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 10_000);
const res = await fetch(
"https://api.aidenid.com/v1/trials/trial_g1h2i3j4/convert",
{
method: "POST",
headers: {
"Authorization": "Bearer aid_your_api_key",
"X-Org-Id": "org_abc123",
"X-Project-Id": "proj_def456",
"Idempotency-Key": "convert-001",
},
signal: controller.signal,
}
);
clearTimeout(timeout);
const { checkout_url } = await res.json();
// Redirect user to Stripe checkout
window.location.href = checkout_url;Response 200 OK
{
"checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
"trial_id": "trial_g1h2i3j4",
"plan": "growth"
}Error codes
| Code | Status | Description |
|---|---|---|
trial_already_exists | 409 | This organization has already used its trial |
trial_not_found | 404 | Trial does not exist |
trial_expired | 410 | Trial has expired beyond the grace period |
trial_already_converted | 409 | Trial has already been converted to a paid plan |
trial_canceled | 409 | Trial was canceled and cannot be converted |
invalid_plan | 400 | Plan must be one of: starter, growth, pro |
missing_idempotency_key | 400 | Mutation request missing Idempotency-Key header |
Related
- Billing API — manage subscriptions after conversion
- Pricing — compare plan features and limits
- Free Tier API — zero-auth alternative for single-use flows