Managing Discounts

Create a discount

Two discount categories are currently supported. The required fields differ slightly between them.

Apply to all orders

curl --request POST \
  --url https://api.chowdeck.com/merchant/discount \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "reference": "disc-summer-001",
    "title": "Summer Sale",
    "description": "10% off all orders this weekend",
    "type": "percentage_off",
    "value": 10,
    "category": "price_slash_off_all_orders",
    "vendor_references": ["vendor-ref-001"],
    "expiry_date": "2025-08-31T23:59:59Z",
    "maximum_usage_times": 500,
    "minimum_order_amount": 200000,
    "capped_amount": 100000
  }'

Apply to specific menu items

curl --request POST \
  --url https://api.chowdeck.com/merchant/discount \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "reference": "disc-coke-001",
    "title": "Coke Promo",
    "description": "₦200 off Chilled Coke",
    "type": "flat_fee",
    "value": 20000,
    "category": "price_slash_off_menu",
    "vendor_references": ["vendor-ref-001"],
    "menu_references": ["item-chilled-coke-001"],
    "expiry_date": "2025-08-31T23:59:59Z",
    "maximum_usage_times": 200,
    "minimum_order_amount": 100000
  }'

Request body:

Field	Type	Required	Description
`reference`	string	Yes	A unique identifier you define for this discount
`title`	string	Yes	Display name of the discount
`description`	string	Yes	Short description shown to customers
`type`	string	Yes	`"flat_fee"` or `"percentage_off"`
`value`	number	Yes	Discount value. For `flat_fee`, in the smallest currency unit. For `percentage_off`, a number between 1–100.
`category`	string	Yes	`"price_slash_off_all_orders"` or `"price_slash_off_menu"`
`vendor_references`	array	Yes	References of the vendors this discount applies to
`expiry_date`	string	Yes	ISO 8601 date when the discount expires
`maximum_usage_times`	integer	Yes	Total number of times this discount can be used across all customers
`minimum_order_amount`	integer	Yes	Minimum order value required to apply the discount, in the smallest currency unit
`capped_amount`	integer	Required for `price_slash_off_all_orders`	Maximum discount value to apply, in the smallest currency unit
`menu_references`	array	Required for `price_slash_off_menu`	References of the menu items this discount applies to
`is_auto_applied`	boolean	No	Whether to apply this discount automatically without a customer action

For flat_fee, value is in the smallest currency unit. ₦500 off → 50000.

capped_amount prevents large discounts on high-value orders. A 20% discount capped at ₦1,000 means customers never get more than ₦1,000 off regardless of order size.

Update a discount

curl --request PUT \
  --url https://api.chowdeck.com/merchant/discount/{reference} \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Extended Summer Sale",
    "expiry_date": "2025-09-15T23:59:59Z",
    "maximum_usage_times": 1000,
    "minimum_order_amount": 150000
  }'

Request body:

Field	Type	Required	Description
`title`	string	No	Updated title
`description`	string	No	Updated description
`value`	number	No	Updated discount value
`minimum_order_amount`	integer	No	Updated minimum order amount
`expiry_date`	string	No	Updated expiry date (ISO 8601)
`maximum_usage_times`	integer	No	Updated usage limit
`is_auto_applied`	boolean	No	Updated auto-apply setting

Activate and deactivate discounts

Discounts are inactive by default when created. You must explicitly activate them before customers can use them.

Activate

curl --request PATCH \
  --url https://api.chowdeck.com/merchant/discount/activate \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "references": ["disc-summer-001", "disc-summer-002"]
  }'

Deactivate

curl --request DELETE \
  --url https://api.chowdeck.com/merchant/discount/deactivate \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "references": ["disc-summer-001"]
  }'

Deactivating a discount prevents it from being applied to new orders immediately. It does not affect orders where the discount has already been applied.

Get a discount

curl --request GET \
  --url https://api.chowdeck.com/merchant/discount/{reference} \
  --header 'Authorization: Bearer YOUR_API_KEY'

List discounts

curl --request GET \
  --url 'https://api.chowdeck.com/merchant/discount?page=1&per_page=50' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Supported query parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`per_page`	integer	`50`	Results per page
`references`	string	—	Comma-separated discount references to filter by
`is_active`	boolean	—	Filter by active or inactive status
`only_unexpired`	boolean	—	Return only discounts that have not yet expired
`only_auto_applied`	boolean	—	Return only auto-applied discounts
`menu_references`	string	—	Comma-separated menu references to filter by

Error responses

All failed requests return this shape:

{
  "status": "failed",
  "message": "..."
}