DELETE /api/v1/apps/:appUuid/tenants/:tenantUuid/payment-providers/:paymentProvider/subscriptions

Cancels future renewals for a tenant's current paid subscription with Stripe or Mollie. The tenant keeps access through the end of the already-paid period.

This endpoint is intended for server-side app integrations. Do not expose a write API key in browser code.

Source route file: src/api/routes/external/private/apiKey/app/tenants/paymentProviders/subscriptions/delete.ts

Request Method

DELETE

Base URL

https://api.userdocks.local:5000

Endpoint

/api/v1/apps/:appUuid/tenants/:tenantUuid/payment-providers/:paymentProvider/subscriptions

Path Variables

Variable	Type	Required	Description
appUuid	string	true	App UUID. Must match the x-client-id.
tenantUuid	string	true	Tenant whose current subscription is canceled.
paymentProvider	string	true	Use stripe or mollie.

Query Parameters

No query parameters.

HTTP Headers

Variable	Type	Required	Description
x-api-key	string	true	Write API key value for the app.
x-client-id	string	true	Must match :appUuid path variable.
x-api-key-type	string	true	Use write.

Request Body

No request body.

Successful Response

Success status code: 200.

The response returns the current local subscription record plus cancelAtPeriodEnd and cancelsAt, which describe the cancellation requested from the provider.

{
  "kind": "subscriptions",
  "totalItems": 1,
  "itemsLength": 1,
  "items": [
    {
      "uuid": "11111111-1111-4111-8111-111111111111",
      "tenantUuid": "22222222-2222-4222-8222-222222222222",
      "paymentProviderUuid": "33333333-3333-4333-8333-333333333333",
      "subscriptionId": "sub_12345",
      "paidFrom": "2026-09-01T00:00:00.000Z",
      "paidUntil": "2026-10-01T00:00:00.000Z",
      "status": "active",
      "isPromotion": false,
      "cancelAtPeriodEnd": true,
      "cancelsAt": "2026-10-01T00:00:00.000Z"
    }
  ]
}

The local status remains active during the paid period. Entitlement checks continue to honor paidUntil, so cancellation does not remove access that has already been paid for.

Provider Notes

• Stripe: sets cancel_at_period_end on the connected account's subscription. Stripe's subscription deletion webhook closes the local plan period when the cancellation becomes effective.
• Mollie: cancels future recurring charges immediately. Userdocks continues to honor the locally recorded paid period through paidUntil.
• Repeating a Mollie cancellation after the provider subscription is already missing is treated as a successful cancellation.
• Promotional subscriptions are local records and are not canceled by this provider endpoint.

Error Responses

HTTP Status	Description
400	Invalid path data, or the requested provider is not connected to the app.
401	Missing/invalid API-key headers, or a non-write key was used.
403	The app is disabled.
404	The tenant is outside the app, or no current paid subscription/customer exists.
500	An unexpected provider or server error occurred.

Example

const url =
  'https://api.userdocks.local:5000/api/v1/apps/11111111-1111-4111-8111-111111111111/tenants/22222222-2222-4222-8222-222222222222/payment-providers/stripe/subscriptions';

const response = await fetch(url, {
  method: 'DELETE',
  headers: {
    'x-api-key': '<api-key>',
    'x-client-id': '11111111-1111-4111-8111-111111111111',
    'x-api-key-type': 'write',
  },
});

const data = await response.json();
console.log(response.status, data);