Subscriptions#

Subscription management

Get subscription#

GET/organizations/{org_id}/subscription

Get organization subscription details

Security#

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`org_id`	string	path	Yes	Organization ID

Code Examples#

curl -X GET "https://searchaf.antfly.io/api/v1/organizations/{org_id}/subscription" \\
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "stripe_customer_id": "string",
  "stripe_subscription_id": "string",
  "status": "active",
  "plan_type": "free",
  "billing_cycle_start": "2025-10-02",
  "billing_cycle_end": "2025-10-02",
  "created_at": "2025-10-02T15:30:00Z",
  "updated_at": "2025-10-02T15:30:00Z"
}

Create subscription#

POST/organizations/{org_id}/subscription

Create Stripe subscription for organization (requires admin+ role)

Security#

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`org_id`	string	path	Yes	Organization ID

Request Body#

Example:

{
    "plan_type": "free",
    "payment_method_id": "pm_1234567890"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/organizations/{org_id}/subscription" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "plan_type": "free",
    "payment_method_id": "pm_1234567890"
}'

Responses#

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "stripe_customer_id": "string",
  "stripe_subscription_id": "string",
  "status": "active",
  "plan_type": "free",
  "billing_cycle_start": "2025-10-02",
  "billing_cycle_end": "2025-10-02",
  "created_at": "2025-10-02T15:30:00Z",
  "updated_at": "2025-10-02T15:30:00Z"
}

Update subscription#

PATCH/organizations/{org_id}/subscription

Update subscription plan (requires admin+ role)

Security#

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`org_id`	string	path	Yes	Organization ID

Request Body#

Example:

{
    "plan_type": "free",
    "payment_method_id": "string"
}

Code Examples#

curl -X PATCH "https://searchaf.antfly.io/api/v1/organizations/{org_id}/subscription" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "plan_type": "free",
    "payment_method_id": "string"
}'

Responses#

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "stripe_customer_id": "string",
  "stripe_subscription_id": "string",
  "status": "active",
  "plan_type": "free",
  "billing_cycle_start": "2025-10-02",
  "billing_cycle_end": "2025-10-02",
  "created_at": "2025-10-02T15:30:00Z",
  "updated_at": "2025-10-02T15:30:00Z"
}

Cancel subscription#

DELETE/organizations/{org_id}/subscription

Cancel subscription (requires admin+ role, downgrades to free)

Security#

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`org_id`	string	path	Yes	Organization ID

Code Examples#

curl -X DELETE "https://searchaf.antfly.io/api/v1/organizations/{org_id}/subscription" \\
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

No response body

Create billing/checkout session#

POST/organizations/{org_id}/subscription/portal

Smart billing endpoint that automatically routes users based on their subscription status:

Paid plan users → Redirected to Stripe Billing Portal (manage payment, view invoices, cancel)
Free plan users → Redirected to Stripe Checkout (upgrade to paid plan)

The response includes a type field indicating which flow was used.

Security#

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

Name	Type	Location	Required	Description
`org_id`	string	path	Yes	Organization ID

Request Body#

Example:

{
    "return_url": "https://searchaf.antfly.io/settings/billing",
    "plan": "growth"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/organizations/{org_id}/subscription/portal" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "return_url": "https://searchaf.antfly.io/settings/billing",
    "plan": "growth"
}'

Responses#

{
  "url": "https://checkout.stripe.com/c/pay/cs_test_...",
  "type": "checkout"
}