> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions

> Set up recurring billing and subscription management

## Overview

Shoppex handles recurring payments automatically. Create subscription products and let us manage renewals, retries, and cancellations.

<Info>
  This guide is about the subscription flow itself.
  For Developer API endpoints and webhook event names, use the API reference and webhook docs.
</Info>

## Creating a Subscription Product

<Steps>
  <Step title="Create Product">
    Go to **Products → Create Product** and select **Subscription** as the product type.
  </Step>

  <Step title="Configure Billing">
    Set the billing interval:

    * **Daily** - Charged every day
    * **Weekly** - Charged every 7 days
    * **Monthly** - Charged on the same day each month
    * **Yearly** - Charged annually
  </Step>

  <Step title="Set Trial Period (Optional)">
    Offer a free trial before the first charge:

    * 7-day trial
    * 14-day trial
    * 30-day trial
    * Custom duration
  </Step>
</Steps>

## Handling Failed Payments

When a renewal payment fails, Shoppex:

1. **Retries automatically** - 3 attempts over 7 days
2. **Notifies the customer** - Email with payment update link
3. **Marks as past\_due** - Subscription continues during grace period
4. **Cancels** - After all retries fail

Configure retry behavior in **Settings → Subscriptions**.

## Customer Portal

Give customers control over their subscriptions via the Shoppex billing portal. Each customer receives a unique portal link in their confirmation emails where they can:

* View billing history
* Update payment method
* Cancel subscription
* Download invoices

<Tip>
  The customer portal link is included in all subscription-related emails sent to customers.
</Tip>

## Webhooks

Subscribe to these events for subscription updates:

| Event                    | Description              |
| ------------------------ | ------------------------ |
| `subscription:created`   | New subscription started |
| `subscription:cancelled` | Subscription cancelled   |

Shoppex supports more subscription webhook events than the short table above, including `subscription:updated`, `subscription:renewed`, `subscription:upcoming`, and trial events.

See the [Webhooks Guide](/guides/webhooks) for setup instructions.

## Prorating

When customers upgrade or downgrade:

* **Upgrade**: Charged the difference immediately
* **Downgrade**: Credit applied to next invoice

<Info>
  Proration is calculated based on days remaining in the current billing period.
</Info>

***

## Headless / Developer API Checkout

Dashboard checkout and payment links already use Shoppex subscription products. For a custom frontend or backend-driven flow, start checkout with **`POST /dev/v1/orders`**, not `POST /dev/v1/payments`.

| Endpoint                | Subscription support                                               |
| ----------------------- | ------------------------------------------------------------------ |
| `POST /dev/v1/orders`   | Yes — when `items[].product_id` points to a `SUBSCRIPTION` product |
| `POST /dev/v1/payments` | No — one-off developer invoice only; no subscription record        |

```typescript theme={"system"}
const response = await fetch('https://api.shoppex.io/dev/v1/orders', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    customer_email: 'customer@example.com',
    custom_fields: { app_user_id: '154' },
    items: [{ product_id: 'YOUR_SUBSCRIPTION_PRODUCT_UNIQID', quantity: 1 }],
  }),
});

const { data } = await response.json();
// Redirect the buyer to hosted checkout, then listen for subscription:* webhooks.
```

After payment completes, Shoppex creates the subscription record, shows it in **Dashboard → Subscriptions**, and emits events such as `subscription:created` and `subscription:renewed`.

<Info>
  Custom fields such as `plan_type: monthly` do not create subscriptions by themselves. They are opaque metadata on the invoice. Recurring billing requires a real `SUBSCRIPTION` catalog product and the `orders` checkout path.
</Info>

***

## Managing Subscriptions via API

The Dev API exposes full subscription management. Here are the most common operations:

| Action                   | Endpoint                                         |
| ------------------------ | ------------------------------------------------ |
| List all subscriptions   | `GET /dev/v1/subscriptions`                      |
| Get subscription details | `GET /dev/v1/subscriptions/{id}`                 |
| Cancel a subscription    | `POST /dev/v1/subscriptions/{id}/cancel`         |
| Pause billing            | `POST /dev/v1/subscriptions/{id}/pause`          |
| Resume billing           | `POST /dev/v1/subscriptions/{id}/resume`         |
| Change plan              | `POST /dev/v1/subscriptions/{id}/change-plan`    |
| Issue a refund           | `POST /dev/v1/subscriptions/{id}/refund`         |
| List available plans     | `GET /dev/v1/subscriptions/{id}/plan-options`    |
| Update custom fields     | `PATCH /dev/v1/subscriptions/{id}/custom-fields` |
| View billing history     | `GET /dev/v1/subscriptions/{id}/billing-history` |

<Tip>
  Listen for `subscription:upcoming` webhooks to send renewal reminder emails before a charge happens. This is one of the most useful subscription webhooks and often overlooked.
</Tip>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhooks Guide" icon="bell" href="/guides/webhooks">
    Get notified about subscription lifecycle events
  </Card>

  <Card title="Invoice Guide" icon="file-invoice" href="/guides/invoices">
    Understand the invoices generated by subscriptions
  </Card>
</CardGroup>