Skip to main content

​
POST /api/subscription/create-checkout

Creates a Stripe Checkout session to upgrade or subscribe to a paid plan (BASIC or PRO). Returns a session ID and URL to redirect the user to complete payment.

​
Authentication

This endpoint requires authentication. Include your access token in the request cookies.

​
Request Body

​
plan
string
required
Plan to subscribe to. Options: BASIC, PRO
​
promotionCode
string
Promotional code for discounts (3-50 characters). Will be converted to uppercase
​
billing
string
default:"monthly"
Billing period. Options: monthly, annual

​
Response

​
sessionId
string
required
Stripe Checkout session ID
​
url
string
required
URL to redirect the user to complete the checkout process
​
message
string
required
Success message

​
Example Request

curl -X POST "https://api.contafy.com/api/subscription/create-checkout" \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=your_access_token" \
  -d '{
    "plan": "PRO",
    "promotionCode": "PROMO2024",
    "billing": "annual"
  }'

​
Example Response

{
  "sessionId": "cs_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "url": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "message": "Checkout session created successfully"
}

​
Usage Flow

  1. Call this endpoint to create a checkout session
  2. Redirect the user to the returned url
  3. User completes payment on Stripe’s hosted checkout page
  4. User is redirected back to your success URL
  5. Stripe webhook updates the subscription status

​
Error Responses

​
401 Unauthorized
error
Authentication required or token expired
{
  "error": "Unauthorized",
  "message": "Authentication required"
}
​
400 Bad Request
error
Invalid request parameters
{
  "error": "Bad Request",
  "message": "Invalid plan. Must be BASIC or PRO"
}
​
409 Conflict
error
User already has an active subscription to the requested plan
{
  "error": "Conflict",
  "message": "You are already subscribed to this plan"
}
​
500 Internal Server Error
error
Server or Stripe error occurred
{
  "error": "Internal Server Error",
  "message": "Failed to create checkout session"
}
The checkout session expires after 24 hours. Users must complete payment within this timeframe.
For annual billing, consider displaying the discount percentage to encourage upgrades.