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
  }
}

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.