Promotions PRO
A promotion takes a percentage off for a period, for the whole store or for some products. In the panel, they are called Discounts. When several apply, the biggest one wins.
List promotions
GET
/discountsQuery
| Name | Type | Required | Description |
|---|---|---|---|
cursor | string | No | The next_cursor of the previous page. |
limit | integer | No | Page size (default 50, max 200). |
Example
bash
curl "https://api.fastyvendor.com/api/v1/discounts?limit=1" \
-H "Authorization: Bearer $FASTY_KEY"js
const res = await fetch('https://api.fastyvendor.com/api/v1/discounts?limit=1', {
headers: {
Authorization: `Bearer ${process.env.FASTY_KEY}`,
},
})
const data = await res.json()python
import os, requests
res = requests.get(
"https://api.fastyvendor.com/api/v1/discounts?limit=1",
headers={"Authorization": f"Bearer {os.environ['FASTY_KEY']}"},
)
data = res.json()lsl
llHTTPRequest(API + "/discounts?limit=1",
[HTTP_CUSTOM_HEADER, "Authorization", "Bearer " + KEY,
HTTP_BODY_MAXLENGTH, 16384],
"");Response: 200 OK
json
{
"items": [
{
"id": "dsc_fkwvf2r58mtetr",
"name": "Weekend sale",
"percent": 15,
"scope": {
"mode": "all",
"products": [],
"groups": []
},
"starts_at": "2026-11-04T18:27:04.208Z",
"ends_at": null,
"state": "active",
"products": 98,
"sales": 0,
"revenue": 0,
"given": 0,
"created_at": "2026-11-04T18:27:04.209Z"
}
],
"next_cursor": "1"
}Create a promotion
POST
/discountsA % off with dates. When several apply, the biggest one wins.
Without starts_at, the sale starts now. Without ends_at, it runs until you end it. Vendors change their price by themselves.
Body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | No | The name. Up to 60 characters. |
percent | integer | Yes | Percent off. From 1 to 90. |
scope | object | No | Where it is valid. |
scope.mode | string | Yes | all = everything · except = all but the lists · only = just the lists. One of all, except, only. |
scope.products | array of strings | No | Product ids. |
scope.groups | array of strings | No | Group ids. |
starts_at | string or null | No | null or missing = now. |
ends_at | string or null | No | null = until you end it. |
Example
bash
curl -X POST "https://api.fastyvendor.com/api/v1/discounts" \
-H "Authorization: Bearer $FASTY_KEY" \
-H "Idempotency-Key: my-unique-id-123" \
-H "Content-Type: application/json" \
-d '{"name":"Weekend sale","percent":15}'js
const res = await fetch('https://api.fastyvendor.com/api/v1/discounts', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.FASTY_KEY}`,
'Idempotency-Key': 'my-unique-id-123',
'Content-Type': 'application/json',
},
body: JSON.stringify({"name":"Weekend sale","percent":15}),
})
const data = await res.json()python
import os, requests
res = requests.post(
"https://api.fastyvendor.com/api/v1/discounts",
headers={"Authorization": f"Bearer {os.environ['FASTY_KEY']}", "Idempotency-Key": "my-unique-id-123"},
json={"name":"Weekend sale","percent":15},
)
data = res.json()lsl
llHTTPRequest(API + "/discounts",
[HTTP_METHOD, "POST",
HTTP_MIMETYPE, "application/json",
HTTP_CUSTOM_HEADER, "Authorization", "Bearer " + KEY,
HTTP_CUSTOM_HEADER, "Idempotency-Key", "my-unique-id-123"],
"{\"name\":\"Weekend sale\",\"percent\":15}");Response: 201 Created
json
{
"id": "dsc_fkwvf2r58mtetr",
"name": "Weekend sale",
"percent": 15,
"scope": {
"mode": "all",
"products": [],
"groups": []
},
"starts_at": "2026-11-04T18:27:04.208Z",
"ends_at": null,
"state": "active",
"products": 98,
"sales": 0,
"revenue": 0,
"given": 0,
"created_at": "2026-11-04T18:27:04.209Z"
}End a promotion now
POST
/discounts/{id}/endPath
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The id. |
Example
bash
curl -X POST "https://api.fastyvendor.com/api/v1/discounts/dsc_fkwvf2r58mtetr/end" \
-H "Authorization: Bearer $FASTY_KEY" \
-H "Idempotency-Key: my-unique-id-123"js
const res = await fetch('https://api.fastyvendor.com/api/v1/discounts/dsc_fkwvf2r58mtetr/end', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.FASTY_KEY}`,
'Idempotency-Key': 'my-unique-id-123',
},
})
const data = await res.json()python
import os, requests
res = requests.post(
"https://api.fastyvendor.com/api/v1/discounts/dsc_fkwvf2r58mtetr/end",
headers={"Authorization": f"Bearer {os.environ['FASTY_KEY']}", "Idempotency-Key": "my-unique-id-123"},
)
data = res.json()lsl
llHTTPRequest(API + "/discounts/dsc_fkwvf2r58mtetr/end",
[HTTP_METHOD, "POST",
HTTP_CUSTOM_HEADER, "Authorization", "Bearer " + KEY,
HTTP_CUSTOM_HEADER, "Idempotency-Key", "my-unique-id-123"],
"");Response: 200 OK
json
{
"id": "dsc_fkwvf2r58mtetr",
"name": "Weekend sale",
"percent": 15,
"scope": {
"mode": "all",
"products": [],
"groups": []
},
"starts_at": "2026-11-04T18:27:04.208Z",
"ends_at": "2026-11-04T18:27:04.283Z",
"state": "ended",
"products": 98,
"sales": 0,
"revenue": 0,
"given": 0,
"created_at": "2026-11-04T18:27:04.209Z"
}The promotion object
| Field | Type | Description |
|---|---|---|
id | string | The id. |
name | string | The name. |
percent | integer | Percent off. From -9,007,199,254,740,991 to 9,007,199,254,740,991. |
scope | object | Where it is valid: all products, all except the lists, or only the lists. |
scope.mode | string | all = everything · except = all but the lists · only = just the lists. One of all, except, only. |
scope.products | array of strings | Product ids. |
scope.groups | array of strings | Group ids. |
starts_at | string | ISO 8601 date and time (UTC). |
ends_at | string or null | ISO 8601 date and time (UTC), or null. |
state | string | The current state. One of scheduled, active, ended. |
products | integer | Products whose price it changes right now. From -9,007,199,254,740,991 to 9,007,199,254,740,991. |
sales | integer | How many sales. From -9,007,199,254,740,991 to 9,007,199,254,740,991. |
revenue | integer | L$ sold with it. From -9,007,199,254,740,991 to 9,007,199,254,740,991. |
given | integer | L$ given as discount. From -9,007,199,254,740,991 to 9,007,199,254,740,991. |
created_at | string | ISO 8601 date and time (UTC). |