> For the complete documentation index, see [llms.txt](https://docs.shipwithdjango.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shipwithdjango.com/payments-and-billing/billing.md).

# Billing

The billing configuration in ShipWithDjango is highly flexible, allowing you to tailor the payment models to fit your specific needs. This configuration is managed through the `CONFIG/billing.py` file, where you can define how your application handles subscriptions, credits, or both. Below is an overview of the key settings and how to configure them.

### Billing Model

The `BILLING_MODEL` setting determines the payment model your application will use. It can be set to one of the following options:

* **`subscriptions`**: The application uses a subscription model. You need to define subscription plans in the `SUBSCRIPTIONS` list.
* **`credits`**: The application uses a credits model. You need to define credit packages in the `CREDIT_PACKAGES` list.
* **`both`**: The application uses both subscriptions and credits. You need to define both subscription plans and credit packages.
* **`none`**: The application does not use any billing model. Choose this option if you want to provide the service for free.

### Subscription Plans

If your `BILLING_MODEL` is set to `subscriptions` or `both`, you need to define the available subscription plans in the `SUBSCRIPTIONS` list. Each subscription plan is a dictionary with the following keys:

* **`key`**: A unique identifier for the subscription plan.
* **`name`**: The name of the subscription plan displayed to users.
* **`icon`**: The name of a Feather icon associated with the plan.
* **`description`**: A brief description of what the plan offers.
* **`price`**: A dictionary that includes:
  * **`value`**: The monetary value of the subscription.
  * **`currency_symbol`**: The currency symbol for the price (e.g., €, $, £).
* **`stripe_price_id`**: The ID of the Stripe price object, used to create the subscription in Stripe.
* **`show`**: A boolean value indicating whether to display this plan on the pricing page.
* **`lifetime`**: A boolean value indicating if this is a lifetime subscription.
* **`included`**: A list of features included in the plan.
* **`not_included`**: A list of features not included in the plan.

#### Example Subscription Plans

Here are examples of how you might configure different subscription plans:

1. **Free Tier**

   ```python
   {
       'key' : 'default',
       'name' : _('Free tier'),
       'icon' : 'smile',
       'description' : _('For those who want to try out the service before committing'),
       'price' : {
           'value' : 0.00,
           'currency_symbol' : '€',
       },
       'show' : False,
   }
   ```
2. **Lifetime License**

   ```python
   {
       'key' : 'lifetime',
       'name' : _('Lifetime license'),
       'description' : _('Enjoy all the features of the service forever'),
       'icon' : 'thumbs-up',
       'price' : {
           'value' : 299.00,
           'currency_symbol' : '€',
       },
       'stripe_price_id' : 'price_1PKewlRq8MH1iNLlqTtsRHrL',
       'show' : True,
       'lifetime' : True,
       'included': [_('One good thing'), _('One other good thing'), _('And one more good thing')],
       'not_included': [_('One bad thing'), _('One other bad thing'), _('And one more bad thing')],
   }
   ```
3. **Monthly Subscription**

   ```python
   {
       'key' : 'monthly',
       'name' : _('Monthly subscription'),
       'description' : _('Enjoy all the features of the service for a month'),
       'icon' : 'calendar',
       'price' : {
           'value' : 20.00,
           'currency_symbol' : '€',
       },
       'stripe_price_id' : 'price_1PKexCRq8MH1iNLl6Bub67Op',
       'show' : True,
       'lifetime' : False,
       'included': [_('One good thing'), _('One other good thing'), _('And one more good thing')],
       'not_included': [_('One bad thing'), _('One other bad thing'), _('And one more bad thing')],
   }
   ```

### Credit Packages

If your `BILLING_MODEL` is set to `credits` or `both`, you will define credit packages in the `CREDIT_PACKAGES` list. Each credit package is a dictionary with the following keys:

* **`key`**: A unique identifier for the credit package.
* **`name`**: The name of the credit package displayed to users.
* **`icon`**: The name of a Feather icon associated with the package.
* **`description`**: A brief description of what the package offers.
* **`price`**: A dictionary that includes:
  * **`value`**: The monetary value of the credit package.
  * **`currency_symbol`**: The currency symbol for the price.
* **`stripe_price_id`**: The ID of the Stripe price object, used to create the checkout session in Stripe.
* **`show`**: A boolean value indicating whether to display this package on the pricing page.
* **`credits`**: The number of credits provided by the package.

#### Example Credit Packages

Here is an example of how you might configure a credit package:

**10 Credits**

```python
{
    'key' : 'ten_credits',
    'name' : _('10 credits'),
    'description' : _('Get 10 credits to use on the service'),
    'icon' : 'thumbs-up',
    'price' : {
        'value' : 10.00,
        'currency_symbol' : '€',
    },
    'stripe_price_id' : 'price_1PNE60Rq8MH1iNLlO6gf9B55',
    'show' : True,
    'credits' : 10,
}
```

### Configuring Stripe

For both subscription plans and credit packages, the `stripe_price_id` is crucial as it links your plans and packages to Stripe’s payment processing. Make sure to configure these correctly by creating the corresponding prices in your Stripe dashboard.

#### Setting Up Subscription Plans in Stripe

* **Monthly or Annual Subscriptions**: In Stripe, create a "recurring" price and use the generated price ID in the `stripe_price_id` field.
* **Lifetime Subscriptions**: Create a "one-time" price in Stripe and use the generated price ID.

#### Setting Up Credit Packages in Stripe

* For credit packages, create a "one-time" price in Stripe for each package and use the corresponding price IDs.

###