Skip to main content
POST
/
api
/
v1
/
promotions
Create a new promotion
curl --request POST \
  --url https://api.example.com/api/v1/promotions \
  --header 'Content-Type: application/json' \
  --header 'x-calry-api-key: <api-key>' \
  --data '
{
  "name": "Summer Sale 2023",
  "thumbnailURL": "https://example.com/promotions/summer-sale-2023",
  "startDate": "2025-06-01T00:00:00.000Z",
  "endDate": "2025-08-31T23:59:59.999Z",
  "bookingPeriodStart": "2025-06-01T00:00:00.000Z",
  "bookingPeriodEnd": "2025-09-30T23:59:59.999Z",
  "discountPercentage": 15,
  "description": "Get 15% off on all summer bookings",
  "city": "San Francisco",
  "couponCode": "SUMMER2023"
}
'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Summer Sale 2023",
  "discountPercentage": 15,
  "workspaceID": "123e4567-e89b-12d3-a456-426614174000",
  "startDate": "2025-06-01T00:00:00.000Z",
  "endDate": "2025-08-31T23:59:59.999Z",
  "bookingPeriodStart": "2025-06-01",
  "bookingPeriodEnd": "2025-09-30",
  "thumbnailURL": "https://example.com/promotions/summer-sale-2023",
  "status": "ACTIVE",
  "createdAt": "2025-05-15T10:30:00.000Z",
  "updatedAt": "2025-05-16T14:45:00.000Z",
  "description": "Get 15% off on all summer bookings",
  "city": "San Francisco",
  "couponCode": "SUMMER2023"
}

Authorizations

​
x-calry-api-key
string
header
required

Headers

​
x-calry-tenant-id
string

Optional tenant ID to specify which tenant to operate as. Controls access to promotions and their associated listings. If not provided, the default tenant will be used.

Body

application/json
​
name
string
required

Name of the promotion

Example:

"Summer Sale 2023"

​
thumbnailURL
string
required

Thumbnail URL for the promotion

Example:

"https://example.com/promotions/summer-sale-2023"

​
startDate
string<date-time>
required

Start date of the promotion

Example:

"2025-06-01T00:00:00.000Z"

​
endDate
string<date-time>
required

End date of the promotion

Example:

"2025-08-31T23:59:59.999Z"

​
bookingPeriodStart
string<date-time>
required

Start date of the booking period this promotion applies to

Example:

"2025-06-01T00:00:00.000Z"

​
bookingPeriodEnd
string<date-time>
required

End date of the booking period this promotion applies to

Example:

"2025-09-30T23:59:59.999Z"

​
discountPercentage
number
required

Discount percentage to apply

Required range: 0 <= x <= 100
Example:

15

​
description
string

Description of the promotion

Example:

"Get 15% off on all summer bookings"

​
city
object

City this promotion is valid in

Example:

"San Francisco"

​
couponCode
string

Optional coupon code for the promotion

Example:

"SUMMER2023"

Response

Promotion created successfully

​
id
string
required

Unique identifier for the promotion

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
name
string
required

Name of the promotion

Example:

"Summer Sale 2023"

​
discountPercentage
number
required

Discount percentage to apply

Example:

15

​
workspaceID
string
required

ID of the workspace this promotion belongs to

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
startDate
string<date-time>
required

Start date of the promotion

Example:

"2025-06-01T00:00:00.000Z"

​
endDate
string<date-time>
required

End date of the promotion

Example:

"2025-08-31T23:59:59.999Z"

​
bookingPeriodStart
string
required

Start date of the booking period this promotion applies to

Example:

"2025-06-01"

​
bookingPeriodEnd
string
required

End date of the booking period this promotion applies to

Example:

"2025-09-30"

​
thumbnailURL
string
required

Thumbnail URL for the promotion

Example:

"https://example.com/promotions/summer-sale-2023"

​
status
enum<string>
required

Status of the promotion

Available options:
ACTIVE,
INACTIVE
Example:

"ACTIVE"

​
createdAt
string<date-time>
required

When the promotion was created

Example:

"2025-05-15T10:30:00.000Z"

​
updatedAt
string<date-time>
required

When the promotion was last updated

Example:

"2025-05-16T14:45:00.000Z"

​
description
object

Description of the promotion

Example:

"Get 15% off on all summer bookings"

​
city
object

City this promotion is valid in

Example:

"San Francisco"

​
couponCode
object

Coupon code for the promotion

Example:

"SUMMER2023"