Subscriptions

Create a subscription for a customer with a saved payment method

Create a subscription for a customer with a saved payment method. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.

post/api/v1/subscriptions

Request

Base URL
https://merchant.zahlo.eu
Auth
API key in header x-api-key

Headers

Idempotency-Keystring

Retry-safe key for create operations.

Request body

customerIdstring required

priceIdstring required

An active recurring price.

quantityinteger

couponIdstring

paymentMethodIdstring

Defaults to the customer's default, then the newest saved card. With a trial the customer may have none: the subscription starts with paymentMethodId null and the first charge after the trial goes to failed-payment recovery unless a card is added.

trialDaysinteger

Defaults to the price's trial.

metadataobject

Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.

Response

The subscription

idstring required

object'subscription' required

livemodeboolean

createdAtstring date-time

customerIdstring required

priceIdstring required

quantityinteger

currencystring required

amountMinorinteger required

The current or next period's charge, after discount.

couponIdstring nullable

discountEndsAtstring date-time nullable

paymentMethodIdstring nullable

rail'card' | 'sepa_debit'

trialEndstring date-time nullable

currentPeriodStartstring date-time nullable

currentPeriodEndstring date-time nullable

cancelAtPeriodEndboolean required

cancelledAtstring date-time nullable

cancellationReason'requested' | 'payment_failed' nullable

pastDueSincestring date-time nullable

latestPaymentIdstring nullable

prorationMinorinteger

Proration for an upgrade or seat increase, added to the next period's charge.