> ## Documentation Index
> Fetch the complete documentation index at: https://docs.credibill.tech/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Plans
> Define how you charge your customers
We strongly advise managing all plan operations (create, read, update, delete)
through the Credibill dashboard instead of using the API. The dashboard
provides a user-friendly interface for defining pricing structures, managing
trials, and configuring complex pricing models. Use the API only when you need
programmatic plan operations in exceptional cases.
**Plans** define the pricing structure, billing interval, and feature set for a subscription.
## Plan Structure
A Plan consists of:
* **Name**: A human-readable name for the plan (e.g., `Pro Plan`, `Basic Plan`).
* **Description**: A brief description of what the plan offers.
* **Interval**: How often the customer is billed (e.g., `month`, `year`).
* **Currency**: The currency for the plan (e.g., `UGX`, `KES`).
* **Prices**: The amount to be charged.
* **Trial Period**: Optional free trial duration before billing starts.
### Pricing Models
Credibill supports flexible pricing models:
1. **Flat Rate**: A fixed amount per interval (e.g., UGX 10,000/month).
2. **Per Unit**: Charged based on the number of units (e.g., UGX 5,000 per seat).
3. **Tiered**: Different prices for different volume ranges (e.g., first 100 free, then UGX 100/unit).
4. **Usage-Based**: Metered billing based on reported usage (e.g., UGX 1 per API call).
Note: **Features** can be defined within your application and not
Credibill.
## How to create a plan
Create a new plan with pricing and billing configuration. This endpoint allows you to define how customers are charged when subscribed to this plan.
* Endpoint: `https://giant-goldfish-922.convex.site/api/v1/plans`
* Method: `POST`
* Authentication: Authorization: `Bearer `
### Request Body Schema
| Field | Type | Required | Description |
| ----------- | ------ | -------- | ---------------------------------------------------------------- |
| name | string | Yes | The name of the plan (e.g., "Pro Plan"). |
| description | string | No | A brief description of what the plan includes. |
| interval | string | Yes | Billing interval - "month" or "year". |
| currency | string | Yes | The currency code (e.g., "UGX", "KES", "USD"). |
| price | number | Yes | The amount to charge per billing interval. |
| trialDays | number | No | Number of free trial days before billing starts (defaults to 0). |
| metadata | object | No | Arbitrary JSON data for storing additional plan information. |
### Examples
```typescript theme={null}
// src/hooks/useCreatePlan.ts
import { useMutation, UseMutationOptions } from "@tanstack/react-query";
export type PlanData = {
name: string,
description?: string,
interval: "month" | "year",
currency: string,
price: number,
trialDays?: number,
metadata?: Record,
};
export type CreatePlanResponse = {
success: boolean,
planId: string,
};
const useApiKey = () => {
// !! REPLACE THIS PLACEHOLDER !!
const apiKey = 'YOUR_CREDIBILL_API_KEY';
return apiKey;
};
const CREDIBILL_URL = 'https://giant-goldfish-922.convex.site';
const ENDPOINT = '/api/v1/plans';
type UseCreatePlanOptions = Omit , 'mutationFn'>;
/\*\*
- Custom React Query hook for creating a plan
- @param options - Optional configuration options for useMutation
- @returns The mutation object provided by TanStack Query
\*/
export const useCreatePlan = (
options?: UseCreatePlanOptions
) => {
const apiKey = useApiKey();
return useMutation({
mutationFn: async (data: PlanData) => {
if (!apiKey) {
throw new Error("API Key is required for authentication.");
}
const response = await fetch(`${CREDIBILL_URL}${ENDPOINT}`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}`,
},
body: JSON.stringify(data),
});
if (!response.ok) {
const errorBody = await response.json();
throw new Error(errorBody.error || `HTTP error! Status: ${response.status}`);
}
return response.json();
},
...options,
});
};
```
#### Usage in a Component
```typescript theme={null}
import React, { useState } from 'react';
import { useCreatePlan } from './hooks/useCreatePlan';
export const CreatePlanForm = () => {
const [name, setName] = useState('');
const [description, setDescription] = useState('');
const [interval, setInterval] = useState<'month' | 'year'>('month');
const [currency, setCurrency] = useState('UGX');
const [price, setPrice] = useState('');
const [trialDays, setTrialDays] = useState('');
const { mutate, isPending, isError, isSuccess, data, error, reset } = useCreatePlan({
onSuccess: (responseData) => {
console.log(`Success! Plan ID: ${responseData.planId}`);
},
});
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
if (isPending) return;
reset();
mutate({
name: name.trim(),
description: description.trim() || undefined,
interval,
currency: currency.trim(),
price: parseFloat(price),
trialDays: trialDays ? parseInt(trialDays) : undefined,
});
};
return (
⚠️ Recommendation: Consider creating plans through the dashboard for a better experience.