Start the monthly subscription, its first payment on Mollie's checkout

Starts the subscription: EUR 20 a month at list prices, which include 17% Luxembourg VAT, with EUR 25 of usage included each month. It returns the subscription, pending, with checkout_url, where the first month is paid on mollie.com. That payment also lets Mollie charge the same card or account each month from then on (a mandate). Once Mollie confirms it, the subscription is active until period_end, the org gets the month’s credit (credit_eur, a subscription credit lot on /v1/balance that lasts that month and the next), and the payment gets its invoice. Mollie then charges the subscription on the same day each month, each paid month granting its credit and invoice once. What each month charges (charged_eur) follows tax_treatment, from the org’s billing details as they are when it is charged, as for a top-up. Usage beyond the subscription’s credit is taken from prepaid credit (createTopUp). Owners’ and admins’ keys only (403 forbidden otherwise).

409 subscription_exists: the org has a subscription that has not ended. 409 billing_details_required and subscription_not_available as for top-ups (createTopUp). More than 10 subscription payments started in an hour is 429 rate_limited. 502 payment_provider_error: Mollie could not be reached or refused the payment; nothing is charged. 503 unavailable: the deployment takes no payments. While test is true, payments go through Mollie’s test mode and no money moves, and their invoices are drafts.

POST/v1/billing/subscription

Authorization

AuthorizationBearer token · headerrequired

Org-scoped API key, pols_....

Responses

201

The subscription, its first payment open at checkout_url.

idstringrequired

statusSubscriptionStatusrequired

pending: its first payment is not paid yet. active: paid until period_end, and charged again then unless cancel_at_period_end. past_due: the last monthly charge failed; it is charged again 3 and 7 days later, and owners may pay it on the billing page meanwhile; a paid one makes it active. ended: canceled and past its period, its first payment not paid, or both retries of a failed charge failed too; final.

Allowed:pendingactivepast_dueended

testbooleanrequired

Paid in Mollie's test mode, which moves no money.

price_eurstringrequired

What a month costs at list prices, VAT included.

charged_eurstringrequired

What Mollie charges each month; price_eur unless the org buys without VAT (tax_treatment).

credit_eurstringrequired

The usage each paid month includes, at list prices.

tax_treatmentTaxTreatmentrequired

How VAT applies to what the org buys, from its billing details and VIES's answer on its VAT ID. lu_vat: 17% Luxembourg VAT, included in the price, for a customer in Luxembourg, a consumer elsewhere in the EU, and an EU business without a VAT ID VIES confirmed. reverse_charge: an EU business outside Luxembourg whose VAT ID VIES confirmed pays the price less VAT and accounts for the VAT itself. outside_eu: a business outside the EU with a tax ID pays the price less VAT, out of scope of EU VAT.

Allowed:lu_vatreverse_chargeoutside_eu

payment_methodstring | nullrequired

What Mollie charges each month, like "Mastercard •••• 6787"; null until the first payment is paid.

period_startstring<date-time> | nullrequired

When the month paid for last started; null until the first payment is paid.

period_endstring<date-time> | nullrequired

When the month paid for last ends, and the next is charged (or the subscription ends, if cancel_at_period_end).

cancel_at_period_endbooleanrequired

Canceled; nothing more is charged and it ends at period_end.

canceled_atstring<date-time> | nullrequired

ended_atstring<date-time> | nullrequired

checkout_urlstring | nullrequired

Where the first payment is paid, on mollie.com, while the subscription is pending and it is open; null otherwise.

paymentsSubscriptionPayment[]required

The 24 latest payments, newest first.

Show properties

Array of SubscriptionPayment

idstringrequired

kindSubscriptionPaymentKindrequired

first: the first month, paid on Mollie's checkout, which also sets up the payment method. renewal: a later month, which Mollie charges on the payment method. payment_method: a payment of EUR 0.00 on the checkout that sets up a new payment method.

Allowed:firstrenewalpayment_method

statusobjectrequired

Where the payment stands at Mollie, as for a top-up; a paid month added its credit.

Show properties

object

charged_eurstringrequired

What Mollie charges; "0.00" for payment_method.

credit_eurstringrequired

The usage a paid month includes, at list prices; "0.00" for payment_method.

tax_treatmentTaxTreatment | nullrequired

How VAT applies to the month; null for payment_method.

Show properties

Any of:

TaxTreatment

string

null

null

testbooleanrequired

Made in Mollie's test mode, which moves no money.

checkout_urlstring | nullrequired

Where a first or payment_method payment is paid, on mollie.com, while it is open; null otherwise.

credit_lot_idstring | nullrequired

The subscription credit lot the paid month added (/v1/balance); null otherwise.

invoice_idstring | nullrequired

The paid month's invoice (/v1/invoices/{invoice}); null until it is issued, and for payment_method.

created_atstring<date-time>required

paid_atstring<date-time> | nullrequired

created_atstring<date-time>required

429

Rate limited (rate_limited): too many requests or failed authentications from this address, too many requests or lifecycle calls for this org, or too many of its exec, file, computer and CDP calls in progress at once. Retry after Retry-After seconds.

errorobjectrequired

Show properties

codestringrequired

Stable machine-readable code: bad_request (400), unauthorized (401), insufficient_credit (402, no credit left to start a sandbox), forbidden (403), quota_exceeded (403), trial_limit (403, beyond what a trial org may run), not_found (404), conflict (409), billing_details_required (409, save the billing details before topping up), topup_not_available (409, the org cannot top up as it would be taxed; the message says why), desktop_controlled (409, a person viewing the desktop has taken control of it, see control), rate_limited (429, see Retry-After), trial_capacity (429, all trial capacity in use; retry after Retry-After), host_capacity (429, the host is short of memory right now, so nothing new starts there; retry after Retry-After), internal (500), runtime_error (502, the sandbox host failed), payment_provider_error (502, Mollie could not be reached or refused a payment), unavailable (503, the feature is not configured on this deployment), waking (503, the sandbox is still waking from standby or booting; retry), timeout (504, or 408 when a request body stalls).

messagestringrequired

controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties

heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

default

Error.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

controlDesktopControl

Who has control of a sandbox's desktop. In an error, it is present only with code desktop_controlled.

Show properties

heldbooleanrequired

Someone viewing the desktop has taken control of it.

holderstring

Only when held; their name as the desktop's viewers see it, their user's name or else their API key's.

sincestring<date-time>

Only when held; when they took control.

expires_atstring<date-time>

Only when held; when control lapses unless they use the desktop before.

Request

curl -X POST 'https://api.pols.so/v1/billing/subscription' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch("https://api.pols.so/v1/billing/subscription", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.post(
    "https://api.pols.so/v1/billing/subscription",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

{
  "id": "sbs_4m8x2k9q1z7c",
  "status": "pending",
  "test": true,
  "price_eur": "20.00",
  "charged_eur": "17.09",
  "credit_eur": "25.00",
  "tax_treatment": "lu_vat",
  "payment_method": "string",
  "period_start": "2019-08-24T14:15:22Z",
  "period_end": "2019-08-24T14:15:22Z",
  "cancel_at_period_end": true,
  "canceled_at": "2019-08-24T14:15:22Z",
  "ended_at": "2019-08-24T14:15:22Z",
  "checkout_url": "string",
  "payments": [
    {
      "id": "pay_7h2k9m4q1x8z",
      "kind": "first",
      "status": "open",
      "charged_eur": "20.00",
      "credit_eur": "25.00",
      "tax_treatment": "lu_vat",
      "test": true,
      "checkout_url": "string",
      "credit_lot_id": "string",
      "invoice_id": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "paid_at": "2019-08-24T14:15:22Z"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z"
}

{
  "error": {
    "code": "string",
    "message": "string",
    "control": {
      "held": true,
      "holder": "Ada",
      "since": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z"
    }
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "control": {
      "held": true,
      "holder": "Ada",
      "since": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z"
    }
  }
}