Saltar al contenido principal

Create Subscription

POST 
/subscriptions

Creates a new subscription with the specified parameters.

Subscription Lifecycle:

  1. When first created, the subscription has a PENDING status
  2. To initiate billing, you must call the activate endpoint with payment details
  3. Once activated, the subscription will automatically bill according to the configured interval

Create from a price:

Send priceId instead of the billing settings. The subscription copies the price's amount, currency, interval, interval count and trial days, and stores priceId and productId. With priceId, the billing and trial fields are rejected. A later change to the price never changes the subscription.

{
  "priceId": "3c5a1f8e-2b7d-4e9a-9c41-7d2e6b0f5a13"
}

Key Configuration Parameters:

  • Billing settings: Amount, currency, interval (daily, weekly, monthly, yearly). Send either these or priceId
  • Schedule customization: Interval count, trial period duration
  • Trial pricing: Offer a free trial with trialPeriodDays/trialPeriodEnd (no charge until the trial ends), or discounted introductory pricing with trialAmount + trialIntervalCount (the trialAmount is charged each billing cycle for that many cycles, then the regular amount applies). trialAmount can also be combined with trialPeriodDays/trialPeriodEnd to charge it once at activation for the whole trial period. trialIntervalCount requires trialAmount and cannot be combined with trialPeriodDays/trialPeriodEnd

Example — 5 EUR for the first 3 months, then 10 EUR/month:

{
  "amount": 1000,
  "currency": "EUR",
  "interval": "month",
  "intervalCount": 1,
  "trialAmount": 500,
  "trialIntervalCount": 3
}

The customer pays 5.00 EUR at activation and for the next two monthly cycles (3 discounted cycles in total), then 10.00 EUR every month.

  • Allowed payment methods: An array of strings specifying which payment methods are allowed for this subscription (e.g., card, bizum)
  • Customer information: Contact details, billing and shipping addresses
  • Communication: Callback URLs for webhook notifications about subscription events

Best Practices:

  • Set clear, descriptive names for subscriptions to help with identification
  • Configure appropriate webhook notifications to monitor subscription status changes
  • Consider offering trial periods to increase customer conversion rates
  • Use metadata to store additional information relevant to your business logic

Request​

Responses​

A subscription object

Última actualización en