Skip to main content
POST
/
api
/
v4.0
/
integrations
/
coupons
/
automatic
cURL
curl --request POST \
  --url https://api.gameball.co/api/v4.0/integrations/coupons/automatic \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "customerId": "<string>",
  "cartId": "<string>",
  "email": "<string>",
  "mobile": "<string>",
  "totalPrice": 123,
  "totalShipping": 123,
  "lineItems": [
    {
      "productId": "<string>",
      "quantity": 123,
      "price": 123,
      "sku": "<string>",
      "tags": [
        "<string>"
      ],
      "category": [
        "<string>"
      ],
      "weight": 123,
      "vendor": "<string>",
      "collection": [
        "<string>"
      ],
      "title": "<string>",
      "taxes": 123,
      "discount": 123,
      "extra": {}
    }
  ],
  "merchant": {
    "uniqueId": "<string>",
    "name": "<string>",
    "branch": {
      "uniqueId": "<string>",
      "name": "<string>"
    }
  }
}
'
{
  "isApplied": true,
  "couponName": "<string>",
  "discountAmount": 123,
  "discountType": "shipping",
  "discountedItems": [
    {
      "productId": "<string>",
      "quantity": 123,
      "discount": 123,
      "price": 123
    }
  ]
}

Automatic Coupons

The API call applies a predefined automatic coupon that aligns with specific promotional criteria and reward structures. It enables seamless integration with promotional campaigns, ensuring coupons are issued based on predefined eligibility conditions, enhancing customer engagement and marketing efforts.
Channel Merging Available
If your system uses different customer IDs across multiple channels (e.g., online and offline), Gameball’s channel merging feature helps unify customer profiles. By including the customer’s mobile number or email (based on your merging configuration) with each request, Gameball will combine activities into a single profile.
For more information, head to the Channel Merging Guide.

Request Body

customerId
string
required
Unique identifier for the customer that you can reference across the customer’s whole lifetime. Could be a database ID, random string, email, or anything that uniquely identifies the customer.
email
string
Customer’s email address.
This is required if your account uses email-based channel merging.
mobile
string
Customer’s mobile number.
This is required if your account uses mobile-based channel merging.
cartId
string
required
Identifier for the shopping cart associated with the order.
totalPrice
float
The total cost of the order, including all item prices, shipping, taxes, and tips. This value does not account for any discounts or coupons applied and is not used for calculations in Gameball; it is solely saved as historical data linked to the order. Must be a positive value.Example: A customer purchases items worth 120,includingtaxesandshipping.Evenifa120, including taxes and shipping. Even if a 20 coupon is applied, the totalPrice remains $120 as it represents the original cost of the order before any discounts are applied.
totalShipping
float
The total shipping cost associated with the order. This should be included when a Free Shipping promotion is configured in your account, enabling the system to calculate and apply the appropriate discount to the cart.
lineItems
array
An array containing details about each product in the order. If not provided, the calculation will only consider the total order values.
lineItems[].productId
string
Unique identifier for the product or service being purchased.
lineItems[].quantity
float
Number of units purchased for this product or service.
lineItems[].price
float
The original price of a single product before any tax or discount is applied. This reflects the cost of one unit of the item, not the total for multiple quantities in an order.Example: If the original price of a product is 50andacustomerbuystwounits,thepriceforeachitemwouldstillberecordedas50 and a customer buys two units, the **price** for each item would still be recorded as 50, regardless of quantity.
lineItems[].sku
string
Stock Keeping Unit (SKU) for the product.
lineItems[].tags
array
Tags associated with the product for categorization or promotional purposes.
lineItems[].category
array
Product category, such as fashion or electronics. It can include one or multiple categories. Example: ["natural", "cosmetics"]
lineItems[].weight
float
Weight of the product.
lineItems[].vendor
string
Vendor or manufacturer of the product.
lineItems[].collection
array
Collection ID(s) to which the product belongs. It can include one or multiple collections. Example: ["14313", "4343"]
lineItems[].title
string
Product title or name.
lineItems[].taxes
float
The total amount of taxes applied to the line item, expressed in the shop’s currency. This amount must be positive and reflects the total taxes based on the quantity of the item.
lineItems[].discount
float
The total discount applied to this line item, expressed as a positive value. This amount should reflect the total discounts based on the quantity of the item.
lineItems[].extra
object
Key-value pairs containing any extra information about the product, such as size, color, or other custom attributes. The values must be of type string or number.
merchant
object
This object contains details about the specific merchant involved in the transaction, which is particularly important for businesses managing multiple merchants or branches under the same Gameball account. This object can provide identifying information about both the main merchant and any associated branch where the transaction took place.
merchant.uniqueId
string
Unique identifier for the merchant.
merchant.name
string
Name of the merchant.
merchant.branch.uniqueId
string
required
Unique identifier for the branch where the order took place.
merchant.branch.name
string
Name of the branch where the order took place.

Response

isApplied
boolean
A boolean indicating whether a coupon was successfully applied to the order (true if applied, false otherwise).
couponName
string
The name of the applied coupon.
discountAmount
number
The total discount value applied to the order.
discountType
string
Type of the coupon, such as fixed amount, percentage discount, free shipping, or product-specific coupon.Possible Values:
  • shipping
  • fixed
  • percentage
  • product
  • buyXgetY
discountedItems
array
A list of affected items, detailing their price, quantity, and applied discount.
discountedItems[].productId
string
Unique identifier for the product or service.
discountedItems[].quantity
number
Number of units purchased for this product or service.
discountedItems[].discount
float
The total discount applied to this line item.
discountedItems[].price
float
The original price of a single product.

Authorizations

apikey
string
header
required

Body

application/json
customerId
string
required
cartId
string
required
email
string
mobile
string
totalPrice
number
totalShipping
number
lineItems
object[]
merchant
object

Response

200 - application/json

Automatic coupon applied successfully

isApplied
boolean
couponName
string
discountAmount
number
discountType
enum<string>
Available options:
shipping,
fixed,
percentage,
product,
buyXgetY
discountedItems
object[]