Promotions (automatic coupons) are discounts that apply automatically based on cart contents, order value, or customer eligibility—without requiring customers to enter a code.
| Type | Description | Example |
|---|
percentage | Percentage discount | 20% off |
fixed | Fixed amount off | $50 off |
shipping | Free shipping | Waive shipping |
product | Discount specific products | 30% off sale items |
buyXgetY | Bundle deals | Buy 2, Get 1 Free |
| Aspect | Promotions | Coupons |
|---|
| Activation | Automatic | Customer enters code |
| User Action | None required | Must input code |
| Use Case | Cart-based offers, flash sales | Targeted rewards, campaigns |
| Distribution | System applies | Earned or shared |
{
"isApplied": true,
"couponName": "Summer Sale - 20% Off",
"discountType": "percentage",
"discountAmount": 24.00,
"discountedItems": [
{
"productId": "PROD_123",
"quantity": 1,
"price": 120.00,
"discount": 24.00
}
]
}
POST /api/v4.0/integrations/coupons/automatic
{
"customerId": "customer_123",
"cartId": "cart_456",
"totalPrice": 150.00,
"totalShipping": 10.00,
"lineItems": [
{
"productId": "PROD_789",
"title": "Summer Dress",
"price": 50.00,
"quantity": 3,
"collection": ["summer_2024"]
}
]
}
Call this API whenever cart contents change to check if promotions apply.
Configured in Gameball dashboard:
Cart-Based
- Minimum cart value
- Product collections
- Product categories
- Quantity requirements
Customer-Based
- Customer segments (VIP, first-time)
- Location
- Loyalty tier
- Purchase history
Time-Based
- Date range
- Flash sales
- Recurring (weekly, monthly)
- Event-based (holidays)
Common Scenarios
| Scenario | Description |
|---|
| Flash Sale | ”20% Off Everything - Today Only” |
| Free Shipping | ”Free Shipping on Orders Over $50” |
| Collection Promo | ”Summer Collection - Buy 2 Get 1 Free” |
| First Order | ”15% Off Your First Purchase” |
| VIP Exclusive | ”VIP Members: Extra 10% Off Sale Items” |
Configuration
Promotions are configured in the Gameball Dashboard under Campaigns → Promotions. Once active, the Automatic Coupons API evaluates all eligible promotions against cart data.
