Api Reference
One-off Products
On this page, we'll dive into the different one-off product endpoints you can use to query your products programmatically.
A one-off product is a digital product that can be bought once. Products can be created via the API or in the Vatly dashboard, and added to checkouts.
Looking for subscription plans? See the Subscription Plans API instead.
The one-off product model
Below you'll find all properties for the Vatly One-off Product API resource.
Properties
| Name | Type | Description |
|---|---|---|
id | string | Unique identifier for the product (starts with one_off_product_). |
resource | string | The resource type. Always one_off_product. |
testmode | boolean | Whether this product is in test mode. |
name | string | Display name of the product. |
description | string | Detailed description of the product. |
basePrice | Money | Default price of the product. A Money object with value (decimal string) and currency (ISO 4217 code). Can be overridden in checkout. |
status | string | Current status of the product. Can be active (product is active and can be purchased), pending (awaiting approval), or rejected (has been rejected). |
createdAt | string | When this product was created (ISO 8601 format). |
links | object | HATEOAS links to related resources. Contains self link. |
List all one-off products
GET /v1/one-off-products
This endpoint retrieves a paginated list of all one-off products.
Only products with active status can be used in checkouts.
Optional parameters
| Name | Type | Description |
|---|---|---|
limit | integer | The number of products to return (default: 10, max: 100). |
startingAfter | string | A cursor for use in pagination. Returns results after this product ID. |
endingBefore | string | A cursor for use in pagination. Returns results before this product ID. |
curl -G https://api.vatly.com/v1/one-off-products \
-H "Authorization: Bearer live_your_api_key_here" \
-d limit=10
$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');
$products = $vatly->oneOffProducts->page();
{
"data": [
{
"id": "one_off_product_Vr8kQdFhSrG4Y3DnfsdqH",
"resource": "one_off_product",
"testmode": false,
"name": "Premium License",
"description": "Lifetime access to all premium features",
"basePrice": {
"value": "299.00",
"currency": "EUR"
},
"status": "active",
"createdAt": "2024-01-15T10:30:00Z",
"links": {
"self": {
"href": "https://api.vatly.com/v1/one-off-products/one_off_product_Vr8kQdFhSrG4Y3DnfsdqH",
"type": "application/json"
}
}
}
],
"count": 1,
"links": {
"self": {
"href": "https://api.vatly.com/v1/one-off-products",
"type": "application/json"
},
"next": null,
"prev": null
}
}
Create a one-off product
POST /v1/one-off-products
Creates a new one-off product for the authenticated merchant, in the testmode determined from the API token.
A product 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 products created in the dashboard. A product created with a test_ token is auto-approved (active) so you can trial checkout immediately.
Required attributes
| Name | Type | Description |
|---|---|---|
name | string | Display name of the product (3–255 characters). |
description | string | Detailed description of the product. |
basePrice | Money | Price of the product. A Money object with value (decimal string) and currency (ISO 4217 code). |
productType | string | Tax product classification. One of saas (Software as a Service) or ebook (electronic book). |
curl https://api.vatly.com/v1/one-off-products \
-H "Authorization: Bearer live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Premium License",
"description": "Lifetime access to all premium features",
"basePrice": { "value": "299.00", "currency": "EUR" },
"productType": "saas"
}'
$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');
$product = $vatly->oneOffProducts->create([
'name' => 'Premium License',
'description' => 'Lifetime access to all premium features',
'basePrice' => ['value' => '299.00', 'currency' => 'EUR'],
'productType' => 'saas',
]);
{
"id": "one_off_product_Vr8kQdFhSrG4Y3DnfsdqH",
"resource": "one_off_product",
"testmode": false,
"name": "Premium License",
"description": "Lifetime access to all premium features",
"basePrice": {
"value": "299.00",
"currency": "EUR"
},
"status": "pending",
"createdAt": "2024-01-15T10:30:00Z",
"links": {
"self": {
"href": "https://api.vatly.com/v1/one-off-products/one_off_product_Vr8kQdFhSrG4Y3DnfsdqH",
"type": "application/json"
}
}
}
Get a specific one-off product
GET /v1/one-off-products/:oneOffProductId
This endpoint retrieves a specific one-off product by its ID.
Parameters
| Name | Type | Description |
|---|---|---|
oneOffProductId | string | The ID of the one-off product to retrieve. |
curl https://api.vatly.com/v1/one-off-products/one_off_product_Vr8kQdFhSrG4Y3DnfsdqH \
-H "Authorization: Bearer live_your_api_key_here"
$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');
$product = $vatly->oneOffProducts->get('one_off_product_Vr8kQdFhSrG4Y3DnfsdqH');
{
"id": "one_off_product_Vr8kQdFhSrG4Y3DnfsdqH",
"resource": "one_off_product",
"testmode": false,
"name": "Premium License",
"description": "Lifetime access to all premium features",
"basePrice": {
"value": "299.00",
"currency": "EUR"
},
"status": "active",
"createdAt": "2024-01-15T10:30:00Z",
"links": {
"self": {
"href": "https://api.vatly.com/v1/one-off-products/one_off_product_Vr8kQdFhSrG4Y3DnfsdqH",
"type": "application/json"
}
}
}