Subscriptions

Subscriptions let you charge customers on a recurring schedule. Start by creating a plan that defines what is being sold, how much it costs and how often it should be charged. A subscription then connects a customer to that plan and manages the recurring billing relationship.

Each billing cycle creates a charge associated with the subscription. You can track successful charges, failed payments and subscription state through the API and webhook events.

Plans

A plan defines the recurring product or service. It contains the amount, currency and billing interval that subscriptions created from it will use.

For example, the following plan charges $49 every month for a Pro subscription.

curl --request POST \
  --url https://api.mitu.ai/v1/subscription-plans \
  --header "x-api-key: $MITU_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Pro",
    "description": "Unlimited lookups and priority support",
    "amount": 49.00,
    "currency": "USD",
    "billingInterval": "month",
    "features": [
      "Unlimited lookups",
      "Priority support"
    ]
  }'

Plan parameters

Plan status

A plan can be active, paused or archived. Use the plan status to control whether the plan should continue being offered without changing the subscriptions and billing history already associated with it.

Keep plans stable once customers are using them. If you are introducing materially different pricing or terms, creating another plan can make the resulting subscription history easier to understand than changing the meaning of an existing plan.

Create a subscription

A subscription connects a subscriber to a plan and starts the recurring billing relationship.

curl --request POST \
  --url https://api.mitu.ai/v1/subscriptions \
  --header "x-api-key: $MITU_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "subscriptionPlanId": "plan_7h2kq9xz",
    "paymentMethod": "mpp_crypto",
    "subscriberId": "cus_ds9hazr8jd3l",
    "subscriberType": "user"
  }'

Subscription parameters

See Agent payments for more information about supported payment methods.

Subscription lifecycle

A subscription moves through states as recurring charges are attempted and the billing relationship changes.

Use subscription state together with webhook events to determine whether access to your own product or service should continue. For example, your application may respond differently to a past_due subscription than to one that has been explicitly cancelled.

Your own application remains responsible for the product behaviour associated with these states, such as restricting access, notifying a customer or allowing a grace period.

Cancel a subscription

Cancel a subscription when recurring billing should stop.

POST /v1/subscriptions/{id}/cancel

Cancellation changes the billing relationship for that subscription. Keep the subscription record rather than treating cancellation as deletion so your application retains its billing history.

Subscription invoices

Each recurring charge produces an invoice associated with the subscription. These invoices give you a record of individual billing periods while the subscription represents the overall recurring relationship.

Retrieve the invoices generated for a subscription with:

GET /v1/subscriptions/{id}/invoices

Use the generated invoices when you need to inspect individual charges or reconcile a particular billing period. The subscription itself should remain the source for understanding the overall recurring relationship and its current state.

See Invoices for invoice lifecycle and payment behaviour.

Let the payer choose a plan

You can also offer subscriptions through a payment experience instead of creating the subscription directly for a specific subscriber.

Create a payment experience with type set to subscription and associate it with the plan you want to offer. If the payer should be able to choose between several plans, provide the available plans and enable customer choice.

The amount and currency come from the selected plan rather than being configured separately on the payment experience. This keeps the plan as the source of truth for the recurring price.

A subscription payment experience can be completed through the appropriate payer flow, allowing you to offer recurring plans without building a separate subscription checkout.

See Payment experiences for creating subscription payment experiences.

Track subscription events

Use webhook events to keep subscription state in your application up to date.

plan.created
subscription.created
subscription.charged
subscription.past_due
subscription.cancelled

subscription.created tells you that the recurring relationship has been established, while subscription.charged represents a successful recurring charge. A subscription.past_due event tells your application that a scheduled charge was not completed successfully.

Use these events to update your own billing records and trigger the appropriate product behaviour. Process webhook events idempotently so a repeated delivery does not apply the same billing change twice.

See Events for event payloads and Webhooks for delivery and verification.

Plans and subscriptions serve different purposes

A plan describes what you sell repeatedly. A subscription describes who is subscribed to it and the state of that recurring relationship.

Several subscribers can use the same plan without creating duplicate definitions of the product and its price. Their subscription states and generated invoices remain independent, so one subscriber becoming past due does not affect anyone else using the same plan.

Keeping those concepts separate also makes it easier to introduce new plans while preserving the billing history of existing subscriptions.

Related