> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xem.email/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Subscription
> Create a new subscription and redirect to payment
# Create Subscription
Create a pending subscription and redirect the user to the payment page. This endpoint integrates with Dodo Payments to handle the payment process.
## 📝 Endpoint
```http theme={"dark"}
POST /subscriptions
```
## 📋 Request Body
The email address for the subscription. This will be used to link the subscription to the user's account.
The ID of the product/plan to subscribe to.
## 📤 Request Example
```bash theme={"dark"}
curl -X POST https://api.posthoot.com/subscriptions \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"product_id": "pro_monthly"
}'
```
```javascript theme={"dark"}
const response = await fetch('https://api.posthoot.com/subscriptions', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'user@example.com',
product_id: 'pro_monthly'
})
});
const data = await response.json();
```
```python theme={"dark"}
import requests
response = requests.post(
'https://api.posthoot.com/subscriptions',
json={
'email': 'user@example.com',
'product_id': 'pro_monthly'
}
)
data = response.json()
```
## 📥 Response
### Success (200 OK)
```json theme={"dark"}
{
"payment_url": "https://pay.dodo.com/checkout/session_abc123",
"subscription_id": "sub_456",
"customer_id": "cus_789",
"status": "pending",
"expires_at": "2024-01-01T11:00:00Z"
}
```
### Error Responses
#### Invalid Product (400 Bad Request)
```json theme={"dark"}
{
"error": "validation_error",
"message": "Invalid product ID",
"code": "INVALID_PRODUCT"
}
```
#### Invalid Email (400 Bad Request)
```json theme={"dark"}
{
"error": "validation_error",
"message": "Invalid email format",
"code": "INVALID_EMAIL"
}
```
#### Payment Error (500 Internal Server Error)
```json theme={"dark"}
{
"error": "payment_error",
"message": "Failed to create payment session",
"code": "PAYMENT_ERROR"
}
```
## 🔄 Subscription Flow
### 1. Create Subscription
```javascript theme={"dark"}
// Step 1: Create subscription
const subscriptionResponse = await fetch('/subscriptions', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: 'user@example.com',
product_id: 'pro_monthly'
})
});
const subscription = await subscriptionResponse.json();
```
### 2. Redirect to Payment
```javascript theme={"dark"}
// Step 2: Redirect user to payment page
window.location.href = subscription.payment_url;
```
### 3. Handle Payment Completion
```javascript theme={"dark"}
// Step 3: User completes payment and returns
// The subscription will be automatically activated via webhook
```
### 4. Link to Account
```javascript theme={"dark"}
// Step 4: When user registers/logs in, subscription is linked
const loginResponse = await fetch('/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: 'user@example.com',
password: 'password123'
})
});
const loginData = await loginResponse.json();
// Subscription is automatically linked to the user's team
```
## 💳 Available Products
### Pro Monthly
```json theme={"dark"}
{
"id": "pro_monthly",
"name": "Pro Plan",
"price": 29.99,
"interval": "monthly",
"features": [
"email_campaigns",
"template_library",
"basic_analytics",
"contact_management"
]
}
```
### Pro Yearly
```json theme={"dark"}
{
"id": "pro_yearly",
"name": "Pro Plan (Yearly)",
"price": 299.99,
"interval": "yearly",
"features": [
"email_campaigns",
"template_library",
"basic_analytics",
"contact_management"
],
"discount": "17%"
}
```
### Enterprise
```json theme={"dark"}
{
"id": "enterprise",
"name": "Enterprise Plan",
"price": 99.99,
"interval": "monthly",
"features": [
"email_campaigns",
"template_library",
"advanced_analytics",
"contact_management",
"automation",
"api_access",
"priority_support"
]
}
```
## 🔐 Security Features
### Payment Security
* **PCI Compliance**: All payments processed through Dodo Payments
* **Encryption**: Payment data encrypted in transit and at rest
* **Tokenization**: Sensitive data tokenized for security
### Subscription Security
* **Email Verification**: Subscription linked to verified email
* **Session Expiration**: Payment sessions expire after 1 hour
* **Fraud Protection**: Advanced fraud detection systems
## 📊 Subscription States
### Pending
* Payment session created
* Waiting for user to complete payment
* Expires after 1 hour
### Active
* Payment completed successfully
* Features enabled for the team
* Billing cycle started
### Canceled
* Subscription canceled by user
* Features disabled at end of billing period
* No further charges
### Paused
* Payment failed or paused
* Features temporarily disabled
* Retry payment to reactivate
## 🛠️ Implementation Examples
### React Component
```jsx theme={"dark"}
import React, { useState } from 'react';
function SubscriptionForm() {
const [email, setEmail] = useState('');
const [productId, setProductId] = useState('pro_monthly');
const [loading, setLoading] = useState(false);
const handleSubmit = async (e) => {
e.preventDefault();
setLoading(true);
try {
const response = await fetch('/subscriptions', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, product_id: productId })
});
if (response.ok) {
const data = await response.json();
window.location.href = data.payment_url;
} else {
const error = await response.json();
alert(error.message);
}
} catch (error) {
alert('Failed to create subscription');
} finally {
setLoading(false);
}
};
return (
);
}
```
### Node.js Server
```javascript theme={"dark"}
const express = require('express');
const app = express();
app.post('/subscriptions', async (req, res) => {
try {
const { email, product_id } = req.body;
// Validate input
if (!email || !product_id) {
return res.status(400).json({
error: 'validation_error',
message: 'Email and product_id are required'
});
}
// Create subscription via Posthoot API
const response = await fetch('https://api.posthoot.com/subscriptions', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, product_id })
});
const data = await response.json();
if (response.ok) {
res.json(data);
} else {
res.status(response.status).json(data);
}
} catch (error) {
res.status(500).json({
error: 'server_error',
message: 'Failed to create subscription'
});
}
});
```
## 🔄 Webhook Integration
### Payment Success Webhook
```javascript theme={"dark"}
app.post('/webhook/payment-success', (req, res) => {
const { subscription_id, customer_id, status } = req.body;
if (status === 'active') {
// Update subscription status in your database
updateSubscriptionStatus(subscription_id, 'active');
// Send welcome email
sendWelcomeEmail(customer_id);
}
res.status(200).send('OK');
});
```
## 📚 Related Endpoints
* [Subscription Features](/subscriptions/features) - Get enabled features
* [Subscription Portal](/subscriptions/portal) - Manage subscription
* [Subscription Webhook](/subscriptions/webhook) - Handle webhooks
* [Authentication](/auth/login) - Link subscription to account