> ## Documentation Index
> Fetch the complete documentation index at: https://devkit4ai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Subscription Plan
> Change the user's subscription to a different plan (upgrade or downgrade)
Change the authenticated user's subscription to a different plan. Proration is applied by default, adjusting the billing amount based on time remaining in the current period.
## Authentication
This endpoint requires end user authentication via HTTP Bearer Token with project scope.
## Query Parameters
Use test mode credentials. Set to `false` for production.
## Request Body
Stripe Price ID for the new plan (e.g., `price_1ABC123def456`)
How to handle proration:
* `create_prorations` - Apply credit/charge for prorated amount
* `none` - No proration; new price applies next billing cycle
* `always_invoice` - Invoice immediately for prorated amount
## Response
Stripe subscription ID
Subscription status after update
New active Price ID
Human-readable confirmation message
## Example Request
```bash theme={null}
curl -X POST "https://api.devkit4ai.com/api/v1/payments/stripe/update-subscription?test_mode=true" \
-H "Authorization: Bearer {end_user_jwt}" \
-H "Content-Type: application/json" \
-d '{
"new_price_id": "price_1XYZ789abc123",
"proration_behavior": "create_prorations"
}'
```
## Example Response
```json theme={null}
{
"subscription_id": "sub_1ABC123def456",
"status": "active",
"price_id": "price_1XYZ789abc123",
"message": "Subscription updated to new plan successfully."
}
```
## Proration Behaviors
```mermaid theme={null}
flowchart TD
A[Update Subscription] --> B{proration_behavior}
B -->|create_prorations| C[Calculate credit/charge]
C --> D[Apply at next invoice]
B -->|always_invoice| E[Calculate credit/charge]
E --> F[Invoice immediately]
B -->|none| G[No price adjustment]
G --> H[New price next cycle]
```
### Proration Examples
| Scenario | Current | New | Proration |
| -------------- | ------- | ------- | ------------------------------ |
| **Upgrade** | \$10/mo | \$20/mo | Charge difference prorated |
| **Downgrade** | \$20/mo | \$10/mo | Credit applied to next invoice |
| **Same price** | \$10/mo | \$10/mo | No change in billing |
## Integration Example
```typescript theme={null}
// Plan upgrade/downgrade component
function ChangePlanModal({ currentPriceId, plans }) {
const [selectedPlan, setSelectedPlan] = useState(currentPriceId);
const [loading, setLoading] = useState(false);
const handleChangePlan = async () => {
if (selectedPlan === currentPriceId) return;
setLoading(true);
try {
const response = await fetch('/api/update-subscription', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
new_price_id: selectedPlan,
proration_behavior: 'create_prorations'
})
});
const result = await response.json();
showToast(result.message);
closeModal();
refreshSubscriptionStatus();
} catch (error) {
showError('Failed to update plan');
} finally {
setLoading(false);
}
};
return (