Coupons

Coupons allow you to offer discounts to customers through promotional codes.

Navigation: Settings > Coupons

Overview

Create discount codes that customers can apply at checkout to take a percentage, a flat amount, the shipping charge, or a fixed cart price off their orders.

Coupon Types

Spark CRM supports four coupon types:

Creating a Coupon

Step 1: Navigate to Coupons

1. Go to Settings in the sidebar
2. Click Coupons in the left menu

The Coupons tab is listed for everyone, but the panel itself only loads for users who pass the coupon permission check — account owners and administrators, or a member of an Account-type team who has been granted coupons:view_any. Anyone else sees an Access Restricted card. Members who are not owners or administrators additionally need coupons:create, coupons:update and coupons:delete. Editing and deleting are possible only on an Account-type team, and only for coupons owned by your current team — that restriction applies to owners and administrators too.

Step 2: Create New Coupon

1. Click Add Coupon button
2. Fill in the coupon details:

Step 3: Save

Click Create Coupon to save the new coupon. When you are editing an existing coupon, the same button reads Update Coupon.

Coupon Configuration Details

Coupon Code

• Must be unique within your team
• Case-insensitive (SAVE20 = save20)
• Recommended: Use memorable, relevant codes

Percentage Off Discount

• Discount Amount represents a percentage (20 = 20% off)
• Applied to the cart subtotal
• Rounded to the nearest cent when applied at checkout (the API validate endpoint returns the unrounded figure)

Fixed Amount Off Discount

• Discount Amount represents a dollar amount
• Applied to the cart subtotal
• Capped at the cart subtotal at checkout, so the customer is never discounted more than the goods are worth

Usage Limits

Total Usage Limit: Total times the coupon can be redeemed

• Leave empty for unlimited (0 is also treated as unlimited)
• Tracks across all customers

Per Customer Limit: Limit per individual

• Leave empty for unlimited
• Identified by the customer record (customer_id), not by the email string. On the checkout page the customer is looked up from the email entered, so a shopper who orders under a different email — or who has no customer record yet — is treated as a new individual.

Date Restrictions

Start Date: Coupon becomes active on this date Expiry Date: Coupon becomes invalid after this date

• Both optional
• Date only — no time of day; a date is stored as midnight UTC
• The API rejects an expiry date that is not after the start date; the settings form does not currently validate the ordering
• Use for time-limited promotions

Minimum Purchase

• The cart subtotal — before shipping and tax — must meet this threshold
• Useful for “Get $10 off orders over $50”

Managing Coupons

Coupon List

The list displays all coupons:

Editing a Coupon

1. Find the coupon in the list
2. Click the ⋯ menu at the end of the row and choose Edit (shown only if you have permission to update coupons)
3. Modify settings in the flyout panel
4. Click Update Coupon

Deactivating a Coupon

Use the row ⋯ menu and choose Deactivate to switch a coupon off without deleting it (the same item reads Activate when it is off). You can also uncheck Active in the edit form.

Deleting a Coupon

1. Open the row ⋯ menu and choose Delete (shown only if you have permission to delete coupons)
2. Confirm in the dialog

Deletion is a soft delete: the coupon disappears from the Coupons list, and its code becomes available for a new, unrelated coupon.

Coupon Validation via API

The API provides a coupon validation endpoint:

POST /v1/coupons/{code}/validate

Request:

{
  "subtotal": 99.99
}

subtotal is required. customer_email, country, product_ids and category_ids are accepted by the validator but are not evaluated by this endpoint — it checks only active status, the date window, the total usage limit and the minimum purchase. Per-customer limits, first-time-customer and allowed-email, country, product and category restrictions are enforced at checkout, so a code this endpoint calls valid can still be rejected on the order.

Response:

{
  "success": true,
  "is_valid": true,
  "discount_amount": 19.998,
  "coupon": { "code": "SAVE20", "type": "percentage", "...": "..." },
  "validation_errors": []
}

discount_amount is returned unrounded; round it for display. discount_amount here is the model-level figure: Free Shipping coupons return 0 (shipping is applied at checkout) and Fixed Amount coupons are not capped at the subtotal. Use the checkout total for the amount the customer actually sees. When the coupon fails validation the call still returns HTTP 200 with is_valid: false and the reasons in validation_errors. An unknown code returns HTTP 404 with {"success": false, "message": "Coupon not found", "is_valid": false}.

Campaign Integration

Coupons are validated during checkout:

1. Customer enters coupon code
2. System validates:
   • Code exists and is active
   • Usage limits not exceeded (total and per customer)
   • Date restrictions met
   • Minimum purchase met (cart subtotal)
   • Product, category, country and email restrictions met
3. Discount applied to order

Only one coupon applies per order — entering a second code replaces the first.

Best Practices

Code Naming

• Descriptive: SUMMER2026, WELCOME10
• Short: Easy to type on mobile
• Unique: Avoid confusion with past codes

Usage Limits

• Set limits to control promotion costs
• Use per-customer limits for acquisition offers
• Monitor high-volume codes closely

Expiration

• Always set expiration for time-limited promos
• Leave open for ongoing referral codes
• Deactivate instead of delete for reporting

Testing

• Test coupons with sandbox orders
• Verify discount calculations
• Check edge cases (minimum purchase, usage limits)

Troubleshooting

Coupon Not Working

Check:

• Coupon is Active
• Within date range
• Usage limits not reached
• Cart subtotal meets the Minimum Purchase

Wrong Discount Applied

Check:

• Coupon type (Percentage Off vs Fixed Amount Off vs Fixed Price)
• Discount Amount is correct
• Which code the order actually carries — only one coupon applies per order, and entering a second code replaces the first (check the order’s cart coupon_code)

Customer Can’t Find Coupon

Check:

• Exact code spelling
• Code isn’t expired
• Per-customer limit not reached

Related Topics

• Campaigns - Campaign configuration
• API Reference - Coupon API endpoints