Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gameball.co/llms.txt

Use this file to discover all available pages before exploring further.

Promotions (automatic coupons) are discounts that apply automatically based on cart contents, order value, or customer eligibility—without requiring customers to enter a code.

​
Promotion Types

TypeDescriptionExample
percentagePercentage discount20% off
fixedFixed amount off$50 off
shippingFree shippingWaive shipping
productDiscount specific products30% off sale items
buyXgetYBundle dealsBuy 2, Get 1 Free

​
Promotions vs Coupons

AspectPromotionsCoupons
ActivationAutomaticCustomer enters code
User ActionNone requiredMust input code
Use CaseCart-based offers, flash salesTargeted rewards, campaigns
DistributionSystem appliesEarned or shared

​
Promotion Response

{
  "isApplied": true,
  "couponName": "Summer Sale - 20% Off",
  "discountType": "percentage",
  "discountAmount": 24.00,
  "discountedItems": [
    {
      "productId": "PROD_123",
      "quantity": 1,
      "price": 120.00,
      "discount": 24.00
    }
  ]
}

​
Checking for Promotions

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.

​
Promotion Conditions

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

ScenarioDescription
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.

Automatic Coupons API

API endpoint documentation

Promotions Tutorial

Implementation guide