Api Reference

Subscription Plans

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

The subscription plan model

The subscription plan model contains all the information about the subscription plans you create, including the name, description, price, and billing interval.

Properties

Name	Type	Description
`id`	`string`	Unique identifier for the subscription plan (always starts with `subscription_plan_`).
`resource`	`string`	The resource type. Always `subscription_plan`.
`testmode`	`boolean`	Whether this plan is in test mode.
`name`	`string`	Display name of the plan.
`description`	`string`	Detailed description of the plan.
`basePrice`	`Money`	Price per billing interval. A Money object with `value` (decimal string) and `currency` (ISO 4217 code).
`interval`	`string`	Billing interval unit. Can be `day`, `week`, `month`, or `year`.
`intervalCount`	`integer`	Number of interval units between billing cycles. For example, `interval: month` with `intervalCount: 3` bills every 3 months.
`status`	`string`	Current status of the plan. Can be `active` (plan is active and can be subscribed to), `pending` (plan is awaiting approval), or `rejected` (plan has been rejected).
`createdAt`	`string`	When this plan was created (ISO 8601 format).
`links`	`object`	HATEOAS links to related resources. Contains `self` link.

List all subscription plans

GET /v1/subscription-plans

This endpoint retrieves a paginated list of all subscription plans. Only plans with active status can be used in checkouts.

Optional query parameters

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

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

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

$plans = $vatly->subscriptionPlans->page();

{
  "data": [
    {
      "id": "subscription_plan_Bm7xNvPwKr3YjTgHcZaE",
      "resource": "subscription_plan",
      "testmode": false,
      "name": "Pro Monthly",
      "description": "Full access to all Pro features, billed monthly",
      "basePrice": {
        "value": "29.00",
        "currency": "EUR"
      },
      "interval": "month",
      "intervalCount": 1,
      "status": "active",
      "createdAt": "2024-01-15T10:30:00Z",
      "links": {
        "self": {
          "href": "https://api.vatly.com/v1/subscription-plans/subscription_plan_Bm7xNvPwKr3YjTgHcZaE",
          "type": "application/json"
        }
      }
    },
    {
      "id": "subscription_plan_Wt5mNvBxKw7YcZaEjLhR",
      "resource": "subscription_plan",
      "testmode": false,
      "name": "Pro Yearly",
      "description": "Full access to all Pro features, billed yearly",
      "basePrice": {
        "value": "290.00",
        "currency": "EUR"
      },
      "interval": "year",
      "intervalCount": 1,
      "status": "active",
      "createdAt": "2024-01-15T10:30:00Z",
      "links": {
        "self": {
          "href": "https://api.vatly.com/v1/subscription-plans/subscription_plan_Wt5mNvBxKw7YcZaEjLhR",
          "type": "application/json"
        }
      }
    }
  ],
  "count": 2,
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/subscription-plans",
      "type": "application/json"
    },
    "next": null,
    "prev": null
  }
}

Create a subscription plan

POST /v1/subscription-plans

Creates a new subscription plan for the authenticated merchant, in the testmode determined from the API token.

A plan created with a live_ token starts in pending status and must be approved by Vatly before it can be used in checkouts — the same review that applies to plans created in the dashboard. A plan created with a test_ token is auto-approved (active) so you can trial checkout immediately.

Constraints:

productType must be saas — e-books are one-off purchases and cannot be sold on a recurring basis.
The day interval is sandbox-only; live plans support week, month, and year.
intervalCount is bounded per unit: up to 365 days, 52 weeks, or 12 months. year always bills once per year (intervalCount is ignored).

Required attributes

Name	Type	Description
`name`	`string`	Display name of the plan (3–255 characters).
`description`	`string`	Detailed description of the plan.
`basePrice`	`Money`	Price per billing interval. A Money object with `value` (decimal string) and `currency` (ISO 4217 code).
`productType`	`string`	Tax product classification. Must be `saas`.
`interval`	`string`	Billing interval unit. One of `day` (sandbox-only), `week`, `month`, or `year`.
`intervalCount`	`integer`	Number of interval units between billing cycles (at least 1).

curl https://api.vatly.com/v1/subscription-plans \
  -H "Authorization: Bearer live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Monthly",
    "description": "Full access to all Pro features, billed monthly",
    "basePrice": { "value": "29.00", "currency": "EUR" },
    "productType": "saas",
    "interval": "month",
    "intervalCount": 1
  }'

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

$plan = $vatly->subscriptionPlans->create([
  'name' => 'Pro Monthly',
  'description' => 'Full access to all Pro features, billed monthly',
  'basePrice' => ['value' => '29.00', 'currency' => 'EUR'],
  'productType' => 'saas',
  'interval' => 'month',
  'intervalCount' => 1,
]);

{
  "id": "subscription_plan_Bm7xNvPwKr3YjTgHcZaE",
  "resource": "subscription_plan",
  "testmode": false,
  "name": "Pro Monthly",
  "description": "Full access to all Pro features, billed monthly",
  "basePrice": {
    "value": "29.00",
    "currency": "EUR"
  },
  "interval": "month",
  "intervalCount": 1,
  "status": "pending",
  "createdAt": "2024-01-15T10:30:00Z",
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/subscription-plans/subscription_plan_Bm7xNvPwKr3YjTgHcZaE",
      "type": "application/json"
    }
  }
}

Retrieve a subscription plan

GET /v1/subscription-plans/:id

This endpoint retrieves a specific subscription plan by its ID.

URL parameters

Name	Type	Description
`id`	`string`	The ID of the subscription plan to retrieve.

curl https://api.vatly.com/v1/subscription-plans/subscription_plan_Bm7xNvPwKr3YjTgHcZaE \
  -H "Authorization: Bearer live_your_api_key_here"

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

$plan = $vatly->subscriptionPlans->get('subscription_plan_Bm7xNvPwKr3YjTgHcZaE');

{
  "id": "subscription_plan_Bm7xNvPwKr3YjTgHcZaE",
  "resource": "subscription_plan",
  "testmode": false,
  "name": "Pro Monthly",
  "description": "Full access to all Pro features, billed monthly",
  "basePrice": {
    "value": "29.00",
    "currency": "EUR"
  },
  "interval": "month",
  "intervalCount": 1,
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z",
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/subscription-plans/subscription_plan_Bm7xNvPwKr3YjTgHcZaE",
      "type": "application/json"
    }
  }
}

Edit this pageorReport an issue

Subscriptions

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

Orders

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