Subscribe to Plan

Add prepaid credits to your organization. This endpoint initiates the payment flow and returns a redirect URL where the user should complete payment.

Request

POST /billing/subscribe

Authentication

Requires an Admin Bearer JWT token.

Authorization: Bearer <access_token>

Request Body

{
  "planId": "660e8400-e29b-41d4-a716-446655440001"
}

Request Fields

Field	Type	Required	Description
planId	UUID	Yes	The unique identifier of the plan to subscribe to

Response

Returns a subscription response with a redirect URL for payment completion.

Success Response

Status Code: 200 OK

Response Body:

{
  "redirectUrl": "https://payment.provider.com/checkout/session_abc123",
  "subscription": {
    "planName": "paid",
    "planDisplayName": "Paid",
    "tier": "PAID",
    "priceCents": 0,
    "currency": "EUR",
    "status": "PENDING",
    "currentPeriodStart": null,
    "currentPeriodEnd": null,
    "gracePeriodEnd": null
  },
  "success": true
}

Response Fields

Field	Type	Description
redirectUrl	string	URL where the user should be redirected to complete payment
subscription	object	Subscription details (status will be PENDING until payment completes)
subscription.planName	string	Internal plan identifier
subscription.planDisplayName	string	Human-readable plan name
subscription.tier	string	Plan tier enum: FREE or PAID
subscription.priceCents	integer	Price in cents (usage-based)
subscription.currency	string	Currency code (e.g., EUR, USD)
subscription.status	string	Subscription status (initially PENDING)
subscription.currentPeriodStart	string	ISO timestamp (null until payment completes)
subscription.currentPeriodEnd	string	ISO timestamp (null until payment completes)
subscription.gracePeriodEnd	string	ISO timestamp (null)
success	boolean	Whether the subscription initiation was successful

Errors

Status Code	Error Code	Description
400	BAD_REQUEST	Invalid plan ID or organization already has an active subscription
401	UNAUTHORIZED	Missing or invalid JWT token
403	FORBIDDEN	User does not have admin privileges
404	NOT_FOUND	Plan with the specified ID does not exist
422	UNPROCESSABLE_ENTITY	Cannot subscribe (e.g., insufficient billing details)

Example

Request

curl -X POST https://api.entryguard.io/api/v1/billing/subscribe \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "660e8400-e29b-41d4-a716-446655440001"
  }'

Response

{
  "redirectUrl": "https://payment.provider.com/checkout/session_abc123",
  "subscription": {
    "planName": "paid",
    "planDisplayName": "Paid",
    "tier": "PAID",
    "priceCents": 0,
    "currency": "EUR",
    "status": "PENDING",
    "currentPeriodStart": null,
    "currentPeriodEnd": null,
    "gracePeriodEnd": null
  },
  "success": true
}

Notes

• After receiving the response, redirect the user to the redirectUrl to complete payment.
• Payment methods are automatically captured during the checkout flow.
• Once payment is complete, the user will be redirected back to your application and the subscription status will change to ACTIVE.
• The subscription will be logged in the audit trail with event type SUBSCRIPTION_CREATED.
• Billing details must be configured before subscribing (see Update Billing Details endpoint).