SpicePay

Subscriptions

Recurring billing with smart retries on the orchestration rails.

SpicePay subscriptions run recurring charges on the same payment and connector infrastructure as one-off payments — one place to watch renewals, retries, and dunning across your whole customer base.

Concepts

Object Description
Plan A product being sold on a recurring basis
Item price A concrete price + interval for a plan (e.g. €29 / month)
Subscription A customer attached to an item price, with a billing anchor date
Invoice One billing period's charge attempt(s)

Creating a subscription

curl https://api.spicepay.net/subscriptions \
  -H "api-key: prd_****************" \
  -H "Content-Type: application/json" \
  -d @body.json

{
  "customer_id": "cus_ada",
  "plan_id": "plan_pro",
  "item_price_id": "price_pro_monthly_eur",
  "payment_details": {
    "return_url": "https://your-shop.example/billing",
    "setup_future_usage": "off_session"
  }
}

The first charge authenticates the customer and saves the payment method as an off-session mandate; renewals then charge it without customer interaction.

A subscription moves through these statuses (and sits in pending while the very first payment is in flight):

Subscription lifecycle A subscription is created, may enter a trial, then becomes active. From active it can move to paused, unpaid after failed renewals, or cancelled. created trial active paused unpaid cancelled

Smart retries and dunning

When a renewal charge fails, SpicePay:

  1. Classifies the decline — hard declines (stolen card) stop immediately; soft declines (insufficient funds, do-not-honor) enter the retry schedule.
  2. Retries at issuer-friendly times over a configurable window (default: 4 attempts over 14 days).
  3. Sends dunning emails to the customer with a secure link to update their payment method.
  4. Applies your configured final action: cancel, mark unpaid, or keep past-due.

Account-updater support on capable connectors refreshes expired or reissued cards automatically before renewal.

Lifecycle changes

  • Upgrades/downgrades — switch plans with proration (charge or credit the difference).
  • Pause/resume — suspend billing without losing the subscription record.
  • Cancellation — immediate or at period end.

Billing activity emits webhooks — invoice_paid on successful renewals, payment_failed on failed charge attempts, mandate_revoked when the saved method is withdrawn — so your entitlement system stays in sync. See Webhooks.