Coupons API

The Coupons API allows you to create and manage discount codes for your payments.

The Coupon Object

{
  "id": "cpn_abc123def456",
  "object": "coupon",
  "code": "SAVE20",
  "percent_off": 20,
  "amount_off": null,
  "currency": "GHS",
  "duration": "once",
  "duration_in_months": null,
  "max_redemptions": 100,
  "max_redemptions_per_customer": 1,
  "times_redeemed": 5,
  "minimum_amount": null,
  "maximum_discount": null,
  "valid_from": "2024-01-01T00:00:00Z",
  "valid_until": "2024-12-31T23:59:59Z",
  "applies_to": "all",
  "first_time_only": false,
  "active": true,
  "metadata": {},
  "livemode": true,
  "created": "2024-01-01T10:00:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier
`object`	string	Always `"coupon"`
`code`	string	Coupon code (uppercase)
`percent_off`	number	Percentage discount (0-100)
`amount_off`	number	Fixed amount discount in GHS
`currency`	string	Currency code
`duration`	string	`once`, `repeating`, `forever`
`duration_in_months`	integer	Duration for repeating coupons
`max_redemptions`	integer	Maximum total redemptions
`max_redemptions_per_customer`	integer	Per-customer redemption limit
`times_redeemed`	integer	Number of times redeemed
`minimum_amount`	number	Minimum order amount in GHS
`maximum_discount`	number	Maximum discount cap in GHS
`valid_from`	string	Start date
`valid_until`	string	Expiration date
`applies_to`	string	What the coupon applies to
`first_time_only`	boolean	Only for first-time customers
`active`	boolean	Whether coupon is active
`metadata`	object	Custom metadata
`created`	string	Creation timestamp

Create a Coupon

POST /v1/coupons

Request Body

Parameter	Type	Required	Description
`code`	string	Yes	Coupon code (auto-uppercased)
`percent_off`	number	No*	Percentage discount (0-100)
`amount_off`	number	No*	Fixed amount discount in GHS
`currency`	string	No	Currency (default: `GHS`)
`duration`	string	No	`once` (default), `repeating`, `forever`
`duration_in_months`	number	No	Duration for repeating coupons
`max_redemptions`	number	No	Maximum total redemptions
`max_redemptions_per_customer`	number	No	Per-customer limit
`minimum_amount`	number	No	Minimum order amount in GHS
`maximum_discount`	number	No	Maximum discount cap in GHS
`valid_from`	string	No	Start date (ISO 8601)
`valid_until`	string	No	Expiration date (ISO 8601)
`applies_to`	string	No	Default: `all`
`applicable_ids`	array	No	Array of applicable product/invoice IDs
`first_time_only`	boolean	No	Only for first-time customers (default: `false`)
`metadata`	object	No	Custom metadata

*Either percent_off or amount_off is required (not both).

curl -X POST https://api.shikacreators.com/v1/coupons \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SAVE20",
    "percent_off": 20,
    "duration": "once",
    "max_redemptions": 100,
    "valid_until": "2024-12-31T23:59:59Z"
  }'

const coupon = await shikacreators.coupons.create({
  code: 'SAVE20',
  percent_off: 20,
  duration: 'once',
  max_redemptions: 100,
  valid_until: '2024-12-31T23:59:59Z'
})

coupon = client.coupons.create(
    code='SAVE20',
    percent_off=20,
    duration='once',
    max_redemptions=100,
    valid_until='2024-12-31T23:59:59Z'
)

Retrieve a Coupon

GET /v1/coupons/:id

Get by Code

GET /v1/coupons/code/:code

Update a Coupon

POST /v1/coupons/:id

Request Body

Parameter	Type	Description
`active`	boolean	Enable/disable coupon
`max_redemptions`	number	Update redemption limit
`valid_until`	string	Update expiration date
`metadata`	object	Update metadata

Delete a Coupon

DELETE /v1/coupons/:id

Validate a Coupon

Validates a coupon code and calculates the discount.

POST /v1/coupons/validate

Request Body

Parameter	Type	Required	Description
`code`	string	Yes	Coupon code to validate
`customer`	string	No	Customer ID (for per-customer checks)
`amount`	number	No	Order amount in GHS (for minimum amount checks)

Response

{
  "valid": true,
  "coupon": { ... },
  "discount": 20,
  "currency": "GHS"
}

If invalid:

{
  "valid": false,
  "reason": "Coupon has expired"
}

List Coupons

GET /v1/coupons

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100, default 10)
`starting_after`	string	Cursor for pagination

Coupons

On this page