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

Name	Type	Description
`id`	`string`	Unique identifier for the subscription (starts with `sub_`).
`resource`	`string`	The resource type. Always `subscription`.
`customerId`	`string`	ID of the customer who owns this subscription.
`testmode`	`boolean`	Whether this resource is in test mode.
`name`	`string`	The name for the subscription (from the plan).
`description`	`string`	The description for the subscription.
`billingAddress`	`object`	The customer billing address for the subscription. Includes `fullName`, `companyName`, `vatNumber`, `streetAndNumber`, `streetAdditional`, `city`, `region`, `postalCode`, and `country`.
`basePrice`	`Money`	The base price per billing cycle before taxes. A Money object with `value` (decimal string) and `currency` (ISO 4217 code).
`quantity`	`integer`	The quantity for the subscription (e.g., number of seats).
`interval`	`string`	The billing interval. Can be `day`, `week`, `month`, or `year`.
`intervalCount`	`integer`	The interval count, e.g., "3" for charging every 3 months.
`status`	`string`	The status for the subscription. Can be `created`, `trial`, `active`, `canceled`, `on_grace_period`, or `paused`.
`startedAt`	`string \| null`	When the subscription started (ISO 8601 format).
`endedAt`	`string \| null`	When the subscription ended (ISO 8601 format). Null if the subscription is still active.
`cancelledAt`	`string \| null`	When the subscription was cancelled (ISO 8601 format). Null if not cancelled.
`renewedAt`	`string \| null`	When the subscription was last renewed (ISO 8601 format).
`renewedUntil`	`string \| null`	Current billing period end date (ISO 8601 format).
`nextRenewalAt`	`string \| null`	When the next renewal will be attempted (ISO 8601 format). Null if subscription is canceled or ended.
`trialUntil`	`string \| null`	When the trial period ends (ISO 8601 format). Null if not in trial or trial has ended.
`links`	`object`	HATEOAS 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

Name	Type	Description
`limit`	`integer`	The number of subscriptions to return (default: 10, max: 100).
`startingAfter`	`string`	A cursor for use in pagination. Returns results after this subscription ID.
`endingBefore`	`string`	A 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

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$subscriptions = $vatly->subscriptions->page();

{
  "data": [
    {
      "id": "sub_abc123def456",
      "resource": "subscription",
      "customerId": "cus_xyz789",
      "testmode": false,
      "name": "Premium Plan",
      "description": "Access to all premium features",
      "billingAddress": {
        "fullName": "John Doe",
        "companyName": null,
        "vatNumber": null,
        "streetAndNumber": "123 Main St",
        "streetAdditional": "Suite 123",
        "city": "Anytown",
        "region": "CA",
        "postalCode": "12345",
        "country": "US"
      },
      "basePrice": {
        "value": "99.99",
        "currency": "EUR"
      },
      "quantity": 1,
      "interval": "month",
      "intervalCount": 1,
      "status": "active",
      "startedAt": "2023-01-01T00:00:00Z",
      "endedAt": null,
      "cancelledAt": null,
      "renewedAt": "2023-06-01T00:00:00Z",
      "renewedUntil": "2023-07-01T00:00:00Z",
      "nextRenewalAt": "2023-07-01T00:00:00Z",
      "trialUntil": null,
      "links": {
        "self": {
          "href": "https://api.vatly.com/v1/subscriptions/sub_abc123def456",
          "type": "application/json"
        },
        "customer": {
          "href": "https://api.vatly.com/v1/customers/cus_xyz789",
          "type": "application/json"
        }
      }
    }
  ],
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/subscriptions?limit=10",
      "type": "application/json"
    },
    "next": {
      "href": "https://api.vatly.com/v1/subscriptions?startingAfter=sub_abc123def456&limit=10",
      "type": "application/json"
    },
    "prev": null
  },
  "count": 1
}

Get a subscription

GET /v1/subscriptions/:id

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

Parameters

Name	Type	Description
`subscriptionId`	`string`	The unique identifier of the subscription.

curl https://api.vatly.com/v1/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer live_your_api_key_here"

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$subscription = $vatly->subscriptions->get('sub_abc123def456');

{
  "id": "sub_abc123def456",
  "resource": "subscription",
  "customerId": "cus_xyz789",
  "testmode": false,
  "name": "Premium Plan",
  "description": "Access to all premium features",
  "billingAddress": {
    "fullName": "John Doe",
    "companyName": null,
    "vatNumber": null,
    "streetAndNumber": "123 Main St",
    "streetAdditional": "Suite 123",
    "city": "Anytown",
    "region": "CA",
    "postalCode": "12345",
    "country": "US"
  },
  "basePrice": {
    "value": "99.99",
    "currency": "EUR"
  },
  "quantity": 1,
  "interval": "month",
  "intervalCount": 1,
  "status": "active",
  "startedAt": "2023-01-01T00:00:00Z",
  "endedAt": null,
  "cancelledAt": null,
  "renewedAt": "2023-06-01T00:00:00Z",
  "renewedUntil": "2023-07-01T00:00:00Z",
  "nextRenewalAt": "2023-07-01T00:00:00Z",
  "trialUntil": null,
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/subscriptions/sub_abc123def456",
      "type": "application/json"
    },
    "customer": {
      "href": "https://api.vatly.com/v1/customers/cus_xyz789",
      "type": "application/json"
    }
  }
}

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

Name	Type	Description
`customerId`	`string`	The unique identifier of the customer.
`limit`	`integer`	The number of subscriptions to return (default: 10, max: 100).
`startingAfter`	`string`	A cursor for use in pagination. Returns results after this subscription ID.
`endingBefore`	`string`	A cursor for use in pagination. Returns results before this subscription ID.

curl -G https://api.vatly.com/v1/customers/cus_xyz789/subscriptions \
  -H "Authorization: Bearer live_your_api_key_here" \
  -d limit=10

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$subscriptions = $vatly->customers->subscriptions('cus_xyz789')->page();

{
  "data": [
    {
      "id": "sub_abc123def456",
      "resource": "subscription",
      "customerId": "cus_xyz789",
      "testmode": false,
      "name": "Premium Plan",
      "description": "Access to all premium features",
      "status": "active",
      "startedAt": "2023-01-01T00:00:00Z",
      "nextRenewalAt": "2023-07-01T00:00:00Z"
    }
  ],
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/customers/cus_xyz789/subscriptions?limit=10",
      "type": "application/json"
    },
    "next": {
      "href": "https://api.vatly.com/v1/customers/cus_xyz789/subscriptions?startingAfter=sub_abc123def456&limit=10",
      "type": "application/json"
    },
    "prev": null
  },
  "count": 1
}

Get a customer subscription

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

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

Parameters

Name	Type	Description
`customerId`	`string`	The unique identifier of the customer.
`subscriptionId`	`string`	The unique identifier of the subscription.

curl https://api.vatly.com/v1/customers/cus_xyz789/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer live_your_api_key_here"

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$subscription = $vatly->customers->subscriptions('cus_xyz789')->get('sub_abc123def456');

{
  "id": "sub_abc123def456",
  "resource": "subscription",
  "customerId": "cus_xyz789",
  "testmode": false,
  "name": "Premium Plan",
  "description": "Access to all premium features",
  "billingAddress": {
    "fullName": "John Doe",
    "companyName": null,
    "vatNumber": null,
    "streetAndNumber": "123 Main St",
    "streetAdditional": "Suite 123",
    "city": "Anytown",
    "region": "CA",
    "postalCode": "12345",
    "country": "US"
  },
  "basePrice": {
    "value": "99.99",
    "currency": "EUR"
  },
  "quantity": 1,
  "interval": "month",
  "intervalCount": 1,
  "status": "active",
  "startedAt": "2023-01-01T00:00:00Z",
  "endedAt": null,
  "cancelledAt": null,
  "renewedAt": "2023-06-01T00:00:00Z",
  "renewedUntil": "2023-07-01T00:00:00Z",
  "nextRenewalAt": "2023-07-01T00:00:00Z",
  "trialUntil": null,
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/subscriptions/sub_abc123def456",
      "type": "application/json"
    },
    "customer": {
      "href": "https://api.vatly.com/v1/customers/cus_xyz789",
      "type": "application/json"
    }
  }
}

Update a subscription

PATCH /v1/subscriptions/:id

This endpoint allows you to update a subscription. You can change the plan, quantity, or apply proration settings.

Optional attributes

At least one of subscriptionPlanId or quantity must be provided.

Name	Type	Description
`subscriptionPlanId`	`string`	The ID of the subscription plan to update to (starts with `plan_`). Must match the testmode of the current subscription.
`quantity`	`integer`	The new quantity for the subscription. Must be at least 1.
`prorate`	`boolean`	Whether 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`.
`applyImmediately`	`boolean`	Whether to apply changes immediately or at the end of the current billing period. Default: `false`.
`invoiceImmediately`	`boolean`	Whether to generate an invoice immediately for proration. Only applies when `applyImmediately` and `prorate` are both true. Default: `false`.
`anchor`	`date`	Reset the billing anchor to this date. Cannot be combined with `trialUntil`.
`trialUntil`	`string`	Extend 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/sub_abc123def456 \
  -H "Authorization: Bearer live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionPlanId": "plan_yearly123",
    "quantity": 3,
    "prorate": true,
    "applyImmediately": true
  }'

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$subscription = $vatly->subscriptions->update('sub_abc123def456', [
    'subscriptionPlanId' => 'plan_yearly123',
    'quantity' => 3,
    'prorate' => true,
    'applyImmediately' => true,
]);

{
  "id": "sub_abc123def456",
  "resource": "subscription",
  "customerId": "cus_xyz789",
  "testmode": false,
  "name": "Premium Yearly",
  "description": "Access to all premium features, billed annually",
  "billingAddress": {
    "fullName": "John Doe",
    "companyName": null,
    "vatNumber": null,
    "streetAndNumber": "123 Main St",
    "streetAdditional": "Suite 123",
    "city": "Anytown",
    "region": "CA",
    "postalCode": "12345",
    "country": "US"
  },
  "basePrice": {
    "value": "999.00",
    "currency": "EUR"
  },
  "quantity": 3,
  "interval": "year",
  "intervalCount": 1,
  "status": "active",
  "startedAt": "2023-01-01T00:00:00Z",
  "endedAt": null,
  "cancelledAt": null,
  "renewedAt": "2023-06-01T00:00:00Z",
  "renewedUntil": "2024-06-01T00:00:00Z",
  "nextRenewalAt": "2024-06-01T00:00:00Z",
  "trialUntil": null,
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/subscriptions/sub_abc123def456",
      "type": "application/json"
    },
    "customer": {
      "href": "https://api.vatly.com/v1/customers/cus_xyz789",
      "type": "application/json"
    }
  }
}

Update subscription billing details

PATCH /v1/subscriptions/:id/update-billing

This endpoint initiates a hosted flow for updating subscription billing details. It returns a URL where the customer can update their billing address, VAT number, and other invoice details.

Required attributes

Name	Type	Description
`redirectUrlSuccess`	`string`	URL to redirect after successful billing update.
`redirectUrlCanceled`	`string`	URL to redirect if customer cancels the update.

Optional attributes

Name	Type	Description
`billingAddress`	`object`	Pre-fill billing address fields. Customer can modify these values in the hosted form.

curl -X PATCH https://api.vatly.com/v1/subscriptions/sub_abc123def456/update-billing \
  -H "Authorization: Bearer live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectUrlSuccess": "https://example.com/billing-updated",
    "redirectUrlCanceled": "https://example.com/billing-canceled",
    "billingAddress": {
      "country": "NL",
      "streetAndNumber": "456 New St",
      "city": "Amsterdam",
      "postalCode": "1012AB"
    }
  }'

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$response = $vatly->subscriptions->updateBilling('sub_abc123def456', [
    'redirectUrlSuccess' => 'https://example.com/billing-updated',
    'redirectUrlCanceled' => 'https://example.com/billing-canceled',
    'billingAddress' => [
        'country' => 'NL',
        'streetAndNumber' => '456 New St',
        'city' => 'Amsterdam',
        'postalCode' => '1012AB',
    ],
]);

// Redirect the customer to the hosted billing update page
header('Location: ' . $response->href, true, 303);

{
  "href": "https://vatly.com/subscriptions/sub_abc123def456/billing?token=xyz...",
  "type": "text/html"
}

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.

Optional query parameters

Name	Type	Description
`immediately`	`boolean`	Cancel immediately instead of at period end. Default: `false`.

curl -X DELETE https://api.vatly.com/v1/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer live_your_api_key_here"

curl -X DELETE "https://api.vatly.com/v1/subscriptions/sub_abc123def456?immediately=true" \
  -H "Authorization: Bearer live_your_api_key_here"

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$vatly->subscriptions->cancel('sub_abc123def456');

Returns 204 No Content on success.

Edit this pageorReport an issue

Checkouts

On this page, we'll dive into the different checkout endpoints you can use to manage your checkouts programmatically.

Subscription Plans

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