Vatly
Api Reference

Subscriptions

On this page, we'll dive into the different subscription endpoints you can use to manage subscriptions programmatically.

The Subscription API Resource

The subscription model contains all the information about recurring billing relationships with customers.

Properties

NameTypeDescription
idstringUnique identifier for the subscription (starts with subscription_).
resourcestringThe resource type. Always subscription.
customerIdstringID of the customer who owns this subscription.
subscriptionPlanIdstringID of the subscription plan this subscription is based on (starts with subscription_plan_).
testmodebooleanWhether this resource is in test mode.
namestringThe name for the subscription (from the plan).
descriptionstringThe description for the subscription.
billingAddressobjectThe customer billing address for the subscription. Includes fullName, companyName, taxId, streetAndNumber, streetAdditional, city, region, postalCode, and country.
basePriceMoneyThe base price per billing cycle before taxes. A Money object with value (decimal string) and currency (ISO 4217 code).
quantityintegerThe quantity for the subscription (e.g., number of seats).
intervalstringThe billing interval. Can be day, week, month, or year.
intervalCountintegerThe interval count, e.g., "3" for charging every 3 months.
statusstringThe status for the subscription. Can be created, trial, active, canceled, on_grace_period, or paused.
mandateobject | nullThe payment method (mandate) on file. Contains method (e.g. card, sepa_debit, paypal, bacs_debit) and maskedIdentifier (e.g. the last 4 digits). Null if no mandate is set.
startedAtstring | nullWhen the subscription started (ISO 8601 format).
endedAtstring | nullWhen the subscription actually ended (ISO 8601 format). Stays null during a cancellation grace period — it is only set once the subscription has fully ended.
canceledAtstring | nullWhen the subscription was canceled (ISO 8601 format). Set while in on_grace_period, and cleared again if the subscription is resumed. Null if not canceled.
renewedAtstring | nullWhen the subscription was last renewed (ISO 8601 format).
renewedUntilstring | nullCurrent billing period end date (ISO 8601 format).
nextRenewalAtstring | nullWhen the next renewal will be attempted (ISO 8601 format). Null if subscription is canceled or ended.
trialUntilstring | nullWhen the trial period ends (ISO 8601 format). Null if not in trial or trial has ended.
linksobjectHATEOAS links to related resources. Contains self and customer links.

List all subscriptions

GET /v1/subscriptions

This endpoint allows you to retrieve a paginated list of all subscriptions across your account.

Optional attributes

NameTypeDescription
limitintegerThe number of subscriptions to return (default: 10, max: 100).
startingAfterstringA cursor for use in pagination. Returns results after this subscription ID.
endingBeforestringA cursor for use in pagination. Returns results before this subscription ID.
curl -G https://api.vatly.com/v1/subscriptions \
  -H "Authorization: Bearer live_your_api_key_here" \
  -d limit=10

Get a subscription

GET /v1/subscriptions/:id

This endpoint allows you to retrieve a specific subscription by its ID.

Parameters

NameTypeDescription
subscriptionIdstringThe unique identifier of the subscription.
curl https://api.vatly.com/v1/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE \
  -H "Authorization: Bearer live_your_api_key_here"

List customer subscriptions

GET /v1/customers/:customerId/subscriptions

This endpoint allows you to retrieve a paginated list of all subscriptions for a specific customer.

Parameters

NameTypeDescription
customerIdstringThe unique identifier of the customer.
limitintegerThe number of subscriptions to return (default: 10, max: 100).
startingAfterstringA cursor for use in pagination. Returns results after this subscription ID.
endingBeforestringA cursor for use in pagination. Returns results before this subscription ID.
curl -G https://api.vatly.com/v1/customers/customer_Lp3mNvBxKw7RjTgYcZaE/subscriptions \
  -H "Authorization: Bearer live_your_api_key_here" \
  -d limit=10

Get a customer subscription

GET /v1/customers/:customerId/subscriptions/:subscriptionId

This endpoint allows you to retrieve a specific subscription for a specific customer.

Parameters

NameTypeDescription
customerIdstringThe unique identifier of the customer.
subscriptionIdstringThe unique identifier of the subscription.
curl https://api.vatly.com/v1/customers/customer_Lp3mNvBxKw7RjTgYcZaE/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE \
  -H "Authorization: Bearer live_your_api_key_here"

Update a subscription

PATCH /v1/subscriptions/:id

This endpoint allows you to update a subscription. You can change the plan, quantity, or recurring price, and control proration and timing.

Optional attributes

At least one of subscriptionPlanId, quantity, or price must be provided.

NameTypeDescription
subscriptionPlanIdstringThe ID of the subscription plan to update to (starts with subscription_plan_). Must match the testmode of the current subscription.
quantityintegerThe new total quantity for the subscription (e.g. number of seats). This sets the quantity to the given value — it is not added to the current quantity. Must be at least 1.
priceobjectSet a new recurring price while keeping the current plan. A Money object with value (decimal string) and currency (EUR or USD); the currency must match the subscription's own currency. Sent alongside subscriptionPlanId, it overrides the new plan's default price.
proratebooleanWhether to prorate charges for the partial billing period. If true, the customer is credited for unused time on the old plan and charged for remaining time on the new plan. Default: true.
applyImmediatelybooleanWhether to apply changes immediately or at the end of the current billing period. Default: false.
invoiceImmediatelybooleanWhether to generate an invoice immediately for proration. Only applies when applyImmediately and prorate are both true. Default: false.
anchordateSet the billing anchor to a specific calendar date (YYYY-MM-DD, interpreted in UTC); the billing cycle is recalculated around it. Cannot be combined with resetAnchor.
resetAnchorbooleanReset the billing anchor to "now" — the moment the update is processed becomes the new cycle anchor and future renewals align to it. Cannot be combined with anchor. Default: false.
trialUntilstringExtend or set a trial period until this date (ISO 8601 format). Cannot be combined with anchor.
curl -X PATCH https://api.vatly.com/v1/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE \
  -H "Authorization: Bearer live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionPlanId": "subscription_plan_Wt5mNvBxKw7YcZaEjLhR",
    "prorate": true,
    "applyImmediately": true
  }'

Create billing update link

POST /v1/subscriptions/:id/billing-update-link

Creates a signed link that the customer can use to update the billing details for this subscription — billing address, VAT number, and company name — via a hosted flow.

Required attributes

NameTypeDescription
redirectUrlSuccessstringURL to redirect after successful billing update.
redirectUrlCanceledstringURL to redirect if customer cancels the update.

Optional attributes

NameTypeDescription
billingAddressobjectPre-fill billing address fields. Customer can modify these values in the hosted form.
curl -X POST https://api.vatly.com/v1/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE/billing-update-link \
  -H "Authorization: Bearer live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectUrlSuccess": "https://example.com/billing-updated",
    "redirectUrlCanceled": "https://example.com/account/billing",
    "billingAddress": {
      "companyName": "Acme Corp",
      "taxId": "DE123456789"
    }
  }'

Cancel a subscription

DELETE /v1/subscriptions/:id

This endpoint allows you to cancel a subscription. By default, the subscription will remain active until the end of the current billing period (grace period), after which it will be fully canceled. Set immediately=true to cancel immediately.

During the grace period the subscription's status is on_grace_period and canceledAt is set, while endedAt stays null. A grace-period cancellation can still be reversed with Resume a subscription until the period lapses. A subscription canceled with immediately=true (status canceled) cannot be reactivated — create a new subscription instead.

Optional query parameters

NameTypeDescription
immediatelybooleanCancel immediately instead of at period end. Default: false.
curl -X DELETE https://api.vatly.com/v1/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE \
  -H "Authorization: Bearer live_your_api_key_here"

Returns 204 No Content on success.

Resume a subscription

POST /v1/subscriptions/:id/resume

Resumes a subscription that was canceled with a grace period, while it is still within that period.

When this works:

  • The subscription's status is on_grace_period.
  • endedAt stays null throughout the grace period — resumability is keyed off status, not endedAt.

Result:

  • Status returns to active.
  • The existing billing cycle and renewal schedule are preserved (no new charge fires immediately) and the original payment mandate remains in effect.
  • canceledAt is cleared and a subscription.resumed webhook is delivered.
  • The refreshed subscription is returned in the response body.

When this does not work (returns 422):

  • The subscription was canceled immediately (status is canceled).
  • The grace period has already lapsed (status is now canceled and endedAt is set).
  • The subscription is already active (the no-op is rejected for clarity, not silently ignored).

In all of those cases, create a new subscription instead.

Parameters

NameTypeDescription
idstringThe unique identifier of the subscription.
curl -X POST https://api.vatly.com/v1/subscriptions/subscription_Lp3mNvBxKw7RjTgYcZaE/resume \
  -H "Authorization: Bearer live_your_api_key_here"

One-off Products

On this page, we'll dive into the different one-off product endpoints you can use to query your products programmatically.

Subscription Plans

On this page, we'll dive into the different subscription plan endpoints you can use to query your plans programmatically.

Copyright © 2026