Coupons API

Create and manage discount codes with validation rules, usage limits, and category restrictions.

The Coupons API manages discount codes with flexible rules — percentage or fixed discounts, date ranges, usage limits, and category/item restrictions.

List Coupons

GET /v1/coupons

Query Parameters:

Parameter	Type	Description
`active`	boolean	Filter by active status
`cursor`	string	Pagination cursor
`limit`	integer	Results per page (1–100, default 20)

const coupons = await renta.coupons.list({ active: true });

curl "https://api.getrenta.io/v1/coupons?active=true" \
  -H "Authorization: Bearer renta_sk_live_..."

Response:

{
  "data": [
    {
      "id": "cp_summer20",
      "code": "SUMMER20",
      "discount_type": "percent",
      "discount_value": 20,
      "valid_from": "2026-06-01T00:00:00Z",
      "valid_to": "2026-08-31T23:59:59Z",
      "max_uses": 100,
      "uses_count": 23,
      "per_customer_limit": 1,
      "restrict_categories": [],
      "restrict_items": [],
      "active": true
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Get Coupon

GET /v1/coupons/:id

const coupon = await renta.coupons.get('cp_summer20');

curl https://api.getrenta.io/v1/coupons/cp_summer20 \
  -H "Authorization: Bearer renta_sk_live_..."

Create Coupon

POST /v1/coupons

Body Parameters:

Parameter	Type	Required	Description
`code`	string	✅	Coupon code (unique, uppercase recommended)
`discount_type`	string	✅	`percent` or `fixed`
`discount_value`	number	✅	Discount amount (percentage or cents)
`valid_from`	string	—	Start date (ISO 8601)
`valid_to`	string	—	End date (ISO 8601)
`max_uses`	integer	—	Maximum total uses (null = unlimited)
`per_customer_limit`	integer	—	Uses per customer (null = unlimited)
`restrict_categories`	string[]	—	Limit to specific category IDs
`restrict_items`	string[]	—	Limit to specific item IDs
`active`	boolean	—	Active status (default `true`)

const coupon = await renta.coupons.create({
  code: 'SUMMER20',
  discount_type: 'percent',
  discount_value: 20,
  valid_from: '2026-06-01T00:00:00Z',
  valid_to: '2026-08-31T23:59:59Z',
  max_uses: 100,
  per_customer_limit: 1,
});

curl -X POST https://api.getrenta.io/v1/coupons \
  -H "Authorization: Bearer renta_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER20",
    "discount_type": "percent",
    "discount_value": 20,
    "valid_from": "2026-06-01T00:00:00Z",
    "valid_to": "2026-08-31T23:59:59Z",
    "max_uses": 100,
    "per_customer_limit": 1
  }'

Update Coupon

PATCH /v1/coupons/:id

await renta.coupons.update('cp_summer20', { active: false });

curl -X PATCH https://api.getrenta.io/v1/coupons/cp_summer20 \
  -H "Authorization: Bearer renta_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

Delete Coupon

DELETE /v1/coupons/:id

await renta.coupons.del('cp_summer20');

curl -X DELETE https://api.getrenta.io/v1/coupons/cp_summer20 \
  -H "Authorization: Bearer renta_sk_live_..."

Validate Coupon

POST /v1/coupons/validate

Check if a coupon code is valid before applying it to a booking.

Body Parameters:

Parameter	Type	Required	Description
`code`	string	✅	Coupon code to validate

const validation = await renta.coupons.validate({ code: 'SUMMER20' });

if (validation.valid) {
  console.log(`Discount: ${validation.coupon!.discount_value}%`);
} else {
  console.log('Coupon is invalid or expired');
}

curl -X POST https://api.getrenta.io/v1/coupons/validate \
  -H "Authorization: Bearer renta_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"code": "SUMMER20"}'

Response (valid):

{
  "valid": true,
  "coupon": {
    "id": "cp_summer20",
    "code": "SUMMER20",
    "discount_type": "percent",
    "discount_value": 20
  }
}

Response (invalid):

{
  "valid": false,
  "coupon": null
}

Coupons are automatically validated when passed as coupon_code in booking creation. The validate endpoint is for previewing discounts before checkout.