Subscriptions#

Subscription management

Get subscription#

GET/organizations/{org_id}/subscription

Get organization subscription details

Parameters#

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

Code Examples#

curl -X GET "https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/subscription" \
-H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/subscription", {
method: "GET",
headers: {
  Authorization: "Bearer YOUR_TOKEN"
}
});

const data = await response.json();

Responses#

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

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

Create subscription#

POST/organizations/{org_id}/subscription

Create Stripe subscription for organization (requires admin+ role)

Parameters#

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

Request Body#

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

Code Examples#

curl -X POST "https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/subscription" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"plan_type": "free",
"payment_method_id": "pm_1234567890"
}'

const response = await fetch("https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/subscription", {
method: "POST",
headers: {
  Authorization: "Bearer YOUR_TOKEN",
  "Content-Type": "application/json"
},
body: JSON.stringify({
  "plan_type": "free",
  "payment_method_id": "pm_1234567890"
})
});

const data = await response.json();

Responses#

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

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

Update subscription#

PATCH/organizations/{org_id}/subscription

Update subscription plan (requires admin+ role)

Parameters#

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

Request Body#

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

Code Examples#

curl -X PATCH "https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/subscription" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"plan_type": "free",
"payment_method_id": "string"
}'

const response = await fetch("https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/subscription", {
method: "PATCH",
headers: {
  Authorization: "Bearer YOUR_TOKEN",
  "Content-Type": "application/json"
},
body: JSON.stringify({
  "plan_type": "free",
  "payment_method_id": "string"
})
});

const data = await response.json();

Responses#

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

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

Cancel subscription#

DELETE/organizations/{org_id}/subscription

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

Parameters#

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

Code Examples#

curl -X DELETE "https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/subscription" \
-H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/subscription", {
method: "DELETE",
headers: {
  Authorization: "Bearer YOUR_TOKEN"
}
});

const data = await response.json();

Responses#

No response body

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

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.

Parameters#

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

Request Body#

{
  "return_url": "https://platform.antfly.io/settings/billing",
  "plan": "growth",
  "intent": "setup_payment_method"
}

Code Examples#

curl -X POST "https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/subscription/portal" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"return_url": "https://platform.antfly.io/settings/billing",
"plan": "growth",
"intent": "setup_payment_method"
}'

const response = await fetch("https://platform.antfly.io/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/subscription/portal", {
method: "POST",
headers: {
  Authorization: "Bearer YOUR_TOKEN",
  "Content-Type": "application/json"
},
body: JSON.stringify({
  "return_url": "https://platform.antfly.io/settings/billing",
  "plan": "growth",
  "intent": "setup_payment_method"
})
});

const data = await response.json();

Responses#

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

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

{
  "type": "https://platform.antfly.io/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email address is required",
  "instance": "https://platform.antfly.io/api/v1/users/550e8400-e29b-41d4-a716-446655440000",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}