Api Reference

Checkouts

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

The Checkout API Resource

Below you'll find all properties for the Vatly Checkout API resource.

Properties

Name	Type	Description
`id`	`string`	Unique identifier for the checkout (starts with `chk_`).
`resource`	`string`	The resource type. Always `checkout`.
`merchantId`	`string`	Unique identifier for the merchant this checkout belongs to.
`orderId`	`string \| null`	Unique identifier for the order created from this checkout. Only available when the checkout has been paid successfully.
`testmode`	`boolean`	Whether this checkout is in test mode.
`redirectUrlSuccess`	`string`	The URL to which the checkout should redirect the user after the checkout has been paid successfully.
`redirectUrlCanceled`	`string`	The URL to which the user should get redirected when the user cancels the checkout.
`metadata`	`object \| null`	Arbitrary key-value metadata for your application. Up to 50 keys, with key names up to 40 characters and values up to 500 characters.
`status`	`string`	The status of the checkout. Can be `created`, `paid`, `canceled`, `failed`, or `expired`.
`expiresAt`	`string \| null`	When this checkout will expire (ISO 8601 format).
`createdAt`	`string`	The moment the checkout was created, in ISO 8601 format.
`links`	`object`	HATEOAS links to related resources. Contains `checkoutUrl` (the hosted checkout page URL), `self`, and optionally `order` (after completion).

List all checkouts

GET /v1/checkouts

This endpoint allows you to retrieve a paginated list of all your checkouts. By default, a maximum of ten checkouts are shown per page.

Optional attributes

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

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

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

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

{
  "data": [
    {
      "id": "chk_abc123def456",
      "resource": "checkout",
      "merchantId": "mer_abc123",
      "orderId": "ord_xyz789",
      "testmode": false,
      "redirectUrlSuccess": "https://example.com/success",
      "redirectUrlCanceled": "https://example.com/canceled",
      "metadata": null,
      "status": "paid",
      "expiresAt": "2024-01-15T14:30:00Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "links": {
        "checkoutUrl": {
          "href": "https://pay.vatly.com/chk_abc123def456",
          "type": "text/html"
        },
        "self": {
          "href": "https://api.vatly.com/v1/checkouts/chk_abc123def456",
          "type": "application/json"
        },
        "order": {
          "href": "https://api.vatly.com/v1/orders/ord_xyz789",
          "type": "application/json"
        }
      }
    }
  ],
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/checkouts?limit=10",
      "type": "application/json"
    },
    "next": {
      "href": "https://api.vatly.com/v1/checkouts?startingAfter=chk_abc123def456&limit=10",
      "type": "application/json"
    },
    "prev": null
  },
  "count": 1
}

Create a checkout

POST /v1/checkouts

This endpoint allows you to start a new hosted Vatly Checkout. Make sure you have at least one subscription plan or one-off product configured in your Vatly account.

Once paid, any subscription plan product assigned to the checkout will kick off a new subscription for that plan.

Required attributes

Name	Type	Description
`products`	`array`	An array of product objects to include in this checkout. Each product can have: `id` (required, starts with `prod_` or `plan_`), `quantity` (optional, default: 1), `price` (optional, Money object), `trialDays` (optional, for subscription plans), `metadata` (optional).
`redirectUrlSuccess`	`string`	The URL to which the checkout should redirect the user after the checkout has been paid successfully.
`redirectUrlCanceled`	`string`	The URL to which the user should get redirected when the user cancels the checkout.

Optional attributes

Name	Type	Description
`metadata`	`object`	Arbitrary key-value metadata for your application.
`customerId`	`string`	The ID for an existing customer to associate with this checkout. If provided, the customer's email will be pre-filled. Must match the testmode of the API token.

curl https://api.vatly.com/v1/checkouts \
  -H "Authorization: Bearer live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {"id": "prod_abc123", "quantity": 1},
      {"id": "plan_xyz789", "trialDays": 14}
    ],
    "redirectUrlSuccess": "https://example.com/success",
    "redirectUrlCanceled": "https://example.com/canceled"
  }'

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

$checkout = $vatly->checkouts->create([
  'products' => [
    ['id' => 'prod_abc123', 'quantity' => 1],
    ['id' => 'plan_xyz789', 'trialDays' => 14],
  ],
  'redirectUrlSuccess' => 'https://example.com/success',
  'redirectUrlCanceled' => 'https://example.com/canceled',
]);

// Redirect the user to the checkout URL
header('Location: ' . $checkout->links->checkoutUrl->href, true, 303);

{
  "id": "chk_abc123def456",
  "resource": "checkout",
  "merchantId": "mer_abc123",
  "orderId": null,
  "testmode": false,
  "redirectUrlSuccess": "https://example.com/success",
  "redirectUrlCanceled": "https://example.com/canceled",
  "metadata": null,
  "status": "created",
  "expiresAt": "2024-01-15T14:30:00Z",
  "createdAt": "2024-01-15T10:30:00Z",
  "links": {
    "checkoutUrl": {
      "href": "https://pay.vatly.com/chk_abc123def456",
      "type": "text/html"
    },
    "self": {
      "href": "https://api.vatly.com/v1/checkouts/chk_abc123def456",
      "type": "application/json"
    },
    "order": null
  }
}

Retrieve a checkout

GET /v1/checkouts/:id

This endpoint allows you to retrieve a checkout by providing the checkout id. Refer to the list at the top of this page to see which properties are included with checkout objects.

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

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

$checkout = $vatly->checkouts->get('chk_abc123def456');

{
  "id": "chk_abc123def456",
  "resource": "checkout",
  "merchantId": "mer_abc123",
  "orderId": "ord_xyz789",
  "testmode": false,
  "redirectUrlSuccess": "https://example.com/success",
  "redirectUrlCanceled": "https://example.com/canceled",
  "metadata": null,
  "status": "paid",
  "expiresAt": "2024-01-15T14:30:00Z",
  "createdAt": "2024-01-15T10:30:00Z",
  "links": {
    "checkoutUrl": {
      "href": "https://pay.vatly.com/chk_abc123def456",
      "type": "text/html"
    },
    "self": {
      "href": "https://api.vatly.com/v1/checkouts/chk_abc123def456",
      "type": "application/json"
    },
    "order": {
      "href": "https://api.vatly.com/v1/orders/ord_xyz789",
      "type": "application/json"
    }
  }
}

Edit this pageorReport an issue

Customers

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

Subscriptions

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