Customer Management

Manage customer data by creating, updating, or removing customer profiles. These endpoints provide essential functionality for handling customer information across Gameball.

Available APIs

• Create Customer

• Get Customer

• Get Customer Details

• Get Customer Coupons

• Delete Customer

• Get Customer Hash

POST - Create or Update Customer

https://api.gameball.co/api/v4.0/integrations/customers

This API enables you to create or update a customer profile in Gameball using a unique customerId. Serving as a consistent identity, this customerId allows you to track a customer’s entire journey, linking them to all associated events, purchases, and loyalty activities across their lifetime. This ensures comprehensive customer management within the Gameball platform.

Security: Requires apiKey header.

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

application/json

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.

Its recommended not to use sequence for customerId

---

email string Optional Customer's email address.

Note: This is required if your account uses email-based channel merging.

---

mobile string Optional Customer's mobile number.

Note: This is required if your account uses mobile-based channel merging.

---

deviceToken string Optional Token used to identify the device.

---

osType string Optional Operating system type of the device.

---

customerAttributes Object Optional Additional customer-specific attributes. Includes attributes such as the customer’s name, contact details, and purchase history.

customerAttributes object

displayName string Optional Display name for the customer.

---

firstName string Optional Customer's first name.

---

lastName string Optional Customer's last name.

---

email string Optional Customer's email address.

---

gender string Optional Customer's gender.

---

mobile string Optional Customer's mobile number.

---

dateOfBirth string Optional Customer's date of birth.

---

joinDate string Optional Date the customer joined.

---

country string Optional Customer's country.

---

city string Optional Customer's city.

---

zip string Optional Customer's postal code.

---

preferredLanguage string Optional The customer's preferred language for communication and interactions. This is typically used to personalize notifications, messages, and other system interactions based on the customer's language preference.

---

tags string Optional A list of tags or labels associated with the customer. These tags are used to categorize customers for personalized marketing campaigns, rewards, and tailored communications. Tags can represent customer preferences, behaviors, or any other custom categories relevant to your business.

Example: A customer could have tags like "VIP", "High Spender", or "Frequent Shopper" to indicate their status or behavior patterns, allowing for more targeted engagement.

---

source string Optional Source of the customer registration.

---

utms array Optional List of UTM attributes associated with the customer.

---

devices array Optional List of devices associated with the customer.

---

paymentMethods array Optional List of payment methods used by the customer.This array may include various forms of payment, such as credit cards, PayPal, or other payment providers.Each payment method is represented as a string.

Example:[ "Credit Card", "PayPal", "Apple Pay" ]

---

totalSpent float Optional Total amount spent by the customer.

---

lastOrderDate string Optional Date of the last order placed by the customer.

---

totalOrders integer Optional Total number of orders placed by the customer.

---

avgOrderAmount float Optional Average amount spent per order by this customer.

---

channel string Optional Indicates the channel through which the customer was acquired or engaged. This is especially useful for systems that support multiple channels to track customer origin and interactions. Understanding the acquisition or engagement channel helps in tailoring marketing strategies, optimizing communication, and analyzing customer preferences.

Possible values:

• mobile: The customer was acquired or engaged through your mobile application.

• pos: The customer was acquired or interacted in person using a Point of Sale (POS) system, such as at a physical store or outlet.

• web: The customer was acquired or engaged through your website.

• callcenter: The customer was acquired or engaged over the phone by contacting a customer service representative or a call center.

---

Custom Object Optional Key-value pairs that allow you to store additional attributes for the customer. This can include any extra information specific to your needs, enabling more personalized interactions and offerings.

referrerCode string Optional The referral code of an existing customer who is referring the customer being created. This is required in the create customer request to process the referral.

---

guest boolean Optional A flag indicating if the individual interacting with your system is a guest (not signed up). Set this to true for guest users; otherwise, they are treated as registered customers by default.

---

Sample request

{
    "customerId": "cust_abc12345xyz67890",
    "customerAttributes": {
        "country": "USA",
        "city": "Los Angeles",
        "zip": "90001",
        "dateOfBirth": "1985-10-25",
        "joinDate": "2023-05-01",
        "custom": {
        "membershipLevel": "Gold",
        },
        "tags": [
            "loyal",
            "VIP"
        ],
        "source": "website",
        "utMs": [],
        "devices": [],
        "paymentMethods": [],
        "totalSpent": 1500,
        "lastOrderDate": "2024-09-15T00:00:00",
        "totalOrders": 25
    }
}

Response

application/json

gameballId number The customer’s unique ID within the Gameball system. This ID is used to store the customer in our database and is different from the customerId used in the dashboard.

---

Sample Response

{
    "gameballId": 417984
}

---

GET - Customer

https://api.gameball.co/api/v4/integrations/customers/{customerId}

This API allows you to retrieve essential customer information from Gameball using a unique customerId. While focused on providing key profile details, the response excludes personally identifiable information (PII), ensuring secure access to customer data for seamless integration and personalized engagement.

This endpoint returns general customer info (no personal data) with the public key. To access PII, use Get Customer Details with the secret key.

Security: Requires apiKey header.

Request

Path Parameters

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.

---

Response

application/json

gameballId number The customer’s unique ID within the Gameball system. This ID is used to store the customer in our database and is different from the customerId used in the dashboard.

---

customerId string 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.

---

customerAttributes Object Optional Additional customer-specific attributes. Includes attributes such as the customer’s name, contact details, and purchase history.

This is a minimized customerAttributes object, excluding all personally identifiable information (PII) for privacy protection.

customerAttributes object

custom Object Key-value pairs that allow you to store additional attributes for the customer. This can include any extra information specific to your needs, enabling more personalized interactions and offerings.

---

gender string Customer's gender.

---

country string Customer's country.

---

city string Customer's city.

---

tags array Tags associated with the customer.

---

source string Source of the customer registration.

---

utMs array List of UTM attributes associated with the customer.

---

devices array List of devices associated with the customer.

---

paymentMethods array List of payment methods used by the customer.

---

totalSpent number Total amount spent by the customer.

---

lastOrderDate string Date of the last order placed by the customer.

---

totalOrders number Total number of orders placed by the customer.

---

manualDate string Custom date for manual entries.

referralCode string The referral code of the customer. Used to refer other customers.

---

referralLink string The referral link generated for the customer.

---

dynamicReferralLink string A dynamic referral link for mobile apps, enabling users to share a unique URL with others for referral purposes.

---

Sample Response

{
    "gameballId": 417384,
    "customerId": "cust_abc12345xyz67890",
    "customerAttributes": {
        "gender": "Male",
        "community": "Gaming",
        "country": "USA",
        "city": "Los Angeles",
        "zip": "90001",
        "custom": {},
        "tags": [
            "loyal",
            "VIP"
        ],
        "source": "website",
        "utMs": [],
        "devices": [],
        "paymentMethods": [],
        "totalSpent": 1500,
        "lastOrderDate": "2024-09-15T00:00:00",
        "totalOrders": 25,
         "manualDate": null
    },
    "referralCode": "n13jACFC400AYZ",
    "referralLink": "https://myapp.com/register?ReferralCode=n13jACFC400AYZ",
    "dynamicReferralLink": null
}

---

GET - Customer Details

https://api.gameball.co/api/v4/integrations/customers/{customerId}/details

This API provides access to comprehensive customer information in Gameball, including personally identifiable information (PII), using a unique customerId. Secured by a secret key, this endpoint ensures that sensitive customer data remains protected, offering a complete view of the customer profile for more personalized and secure interactions.

Security: Requires apikey and secretkey headers.

Request

Path Parameters

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.

---

Response

application/json

customerId string 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.

---

gameballId number The customer’s unique ID within the Gameball system. This ID is used to store the customer in our database and is different from the customerId used in the dashboard.

---

customerAttributes Object Additional customer-specific attributes. Includes attributes such as the customer’s name, contact details, and purchase history.

customerAttributes object

displayName string

Display name for the customer.

---

firstName string

Customer's first name.

---

lastName string

Customer's last name.

---

email string

Customer's email address.

---

gender string

Customer's gender.

---

mobile string

Customer's mobile number.

---

dateOfBirth string

Customer's date of birth.

---

joinDate string

Date the customer joined.

---

country string

Customer's country.

---

city string

Customer's city.

---

zip string

Customer's postal code.

---

preferredLanguage string

The customer's preferred language for communication and interactions. This is typically used to personalize notifications, messages, and other system interactions based on the customer's language preference.

---

tags string

A list of tags or labels associated with the customer. These tags are used to categorize customers for personalized marketing campaigns, rewards, and tailored communications. Tags can represent customer preferences, behaviors, or any other custom categories relevant to your business.

Example:

• "VIP"

• "High Spender"

• "Frequent Shopper"

These tags allow for more targeted engagement based on customer status or behavior patterns.

---

source string

Source of the customer registration.

---

utms array

List of UTM attributes associated with the customer.

---

devices array

List of devices associated with the customer.

---

paymentMethods array

List of payment methods used by the customer. This array may include various forms of payment, such as credit cards, PayPal, or other payment providers. Each payment method is represented as a string.

Example:

• ["Credit Card", "PayPal", "Apple Pay"]

---

totalSpent number

Total amount spent by the customer.

---

lastOrderDate string

Date of the last order placed by the customer.

---

totalOrders number

Total number of orders placed by the customer.

---

avgOrderAmount number

Average amount spent per order by this customer.

---

channel string Indicates the channel through which the customer was acquired or engaged. This is especially useful for systems that support multiple channels to track customer origin and interactions. Understanding the acquisition or engagement channel helps in tailoring marketing strategies, optimizing communication, and analyzing customer preferences.

Possible values:

• mobile: The customer was acquired or engaged through your mobile application.

• pos: The customer was acquired or interacted in person using a Point of Sale (POS) system, such as at a physical store or outlet.

• web: The customer was acquired or engaged through your website.

• callcenter: The customer was acquired or engaged over the phone by contacting a customer service representative or a call center.

referralCode string The referral code of the customer. Used to refer other customers.

---

referralLink string The referral link generated for the customer.

---

dynamicReferralLink string A dynamic referral link for mobile apps, enabling users to share a unique URL with others for referral purposes.

---

Sample Response

{
    "customerId": "cust_abc12345xyz67890",
    "gameballId": 418384,
    "customerAttributes": {
        "displayName": "John Doe",
        "firstName": "John",
        "lastName": "Doe",
        "email": "[e-mail]",
        "manualDate": null,
        "gender": "Male",
        "mobile": "[phone]",
        "dateOfBirth": "1985-10-25T00:00:00",
        "joinDate": "2023-05-01T00:00:00",
        "country": "USA",
        "city": "Los Angeles",
        "zip": "90001",
        "custom": {
            "favoriteCategory": "Electronics",
            "purchaseIntent": "High"
        },
        "tags": [
            "loyal",
            "VIP"
        ],
        "source": "website",
        "utMs": [],
        "devices": [],
        "paymentMethods": [],
        "totalSpent": 1024,
        "lastOrderDate": "2024-09-15T00:00:00",
        "totalOrders": 20
    },
    "referralCode": "n13jACFC400AYZ",
    "referralLink": "https://myapp.com/account/register?ReferralCode=n13jACFC400AYZ",
    "dynamicReferralLink": "https://myapp.page.link/xyz123?d=1"
}

---

GET - Customer Coupons

https://api.gameball.co/api/v4/integrations/customers/{customerId}/coupons

This API retrieves a customer’s available coupons in Gameball, offering detailed information on each coupon's type, status, and usage. Use this endpoint to access current coupon data associated with the customer for better engagement.

Security: Requires apikey and secretkey headers.

Request

Path Parameters

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.

---

Response

application/json

coupons array

List of coupon objects associated with the customer.

coupons object

name string

Name of the coupon.

---

code string

The coupon code that the customer will use. Example: If a coupon code like "7wagbk72a4" is generated for a customer, it can be used during checkout to apply the relevant discount or offer.

---

value number

The monetary value or percentage value of the coupon, depending on its type. Example: If a coupon provides a $100 discount, the value will be 100.

---

type string

Type of the coupon, such as fixed amount, percentage discount, free shipping, or product-specific coupon. Possible Values :

• shipping

• fixed

• percentage

• product

• custom

---

target string

It defines how the coupon is associated with the customer based on its origin or creation method. The possible values are:

• Online:The coupon is created through the redemption process, which can occur when a customer redeems points according to the general redemption rules, or when they redeem a different type of coupon based on extra redemption rules.

• POS: The coupon is created through a physical point of sale (POS), typically in-store.

• Permanent : The coupon is awarded to the customer as a lifetime reward upon reaching a certain tier.

• Reward: The coupon is part of a reward campaign, where the coupon is issued as a reward to the customer. This is typically given when the customer achieve a reward campaign.

• Automation: The coupon is generated automatically through an automation workflow, triggered by predefined system actions or customer behaviors.

---

currency string

Currency code if the coupon has a fixed monetary value.

---

startDate datetime

The date and time when the coupon becomes valid and can be used. Example: If the coupon becomes valid on October 17, 2024, the startDate will be "2024-10-17T08:22:00.0000Z".

---

expiryDate datetime

The date and time when the coupon will expire and no longer be valid. Example: If the coupon expires on October 17, 2027, the expiryDate will be "2027-10-17T08:22:00.0000Z".piry date of the coupon.

---

isExpired boolean

Indicates if the coupon has expired.

---

isActive boolean

Status of the coupon, whether it is active or not.

---

usageLimit number

The total number of times the coupon can be used across all customers. Example: If a coupon can only be used once, the usageLimit will be set to 1, indicating that it cannot be reused after the first use.

---

limitPerCustomer number

The number of times a single customer can use the coupon. Example: If each customer can only use the coupon one time, the limitPerCustomer will be set to 1, ensuring the coupon can only be redeemed once per customer.

---

usedCount number

Number of times the coupon has been used.

---

customerUsedCount number

Number of times the coupon has been used by the customer.

---

capping number

The maximum discount or value cap that the coupon can offer, even if the discount calculation exceeds this value. Example: If the maximum discount for the coupon is capped at $400, the capping will be set to "400", meaning the discount will not exceed that amount.

---

minOrderValue number

The minimum order value required for the coupon to be applied. Example: If the coupon requires a minimum purchase of $1,000 to apply, the minOrderValue will be 1000.

---

entitledProductIds array

A list of product IDs that are eligible for the coupon. If provided, only these products can benefit from the coupon.

Example: If the coupon is only valid for a specific product, the entitledProductIds array may contain IDs like ["productId123"] to indicate that only this product is eligible for the discount. coupon.

---

entitledVariantIds array

A list of product variant IDs that are eligible for the coupon. If provided, only these product variants can benefit from the coupon.

Example: If the coupon is valid for specific product variants, the entitledVariantIds array might include IDs like ["variantId456"], limiting the coupon to these variants.

---

entitledCollectionIds array

A list of collection IDs that are eligible for the coupon. If provided, only these collections can benefit from the coupon.

Example: If the coupon applies to an collection of products, the entitledCollectionIds array could include ["collectionId789"], indicating which collections the coupon can be used on.

---

entitledMerchantIdsarray

A list of merchant external IDs that are eligible to redeem the coupon. When provided, only the merchants with IDs in this list can benefit from or apply the coupon. This allows the coupon to be restricted to specific merchants, ensuring that it is valid only for certain merchants. If the array is empty or not provided, the coupon will be available to all merchants.

---

entitledPlatforms array

Platforms where the coupon can be applied.

---

combinesWith.orderDiscounts boolean

Indicates if the coupon can be combined with order discounts. Example: If the coupon cannot be combined with order discounts, this field will be set to false, ensuring that the coupon and other discounts will not apply together.

---

combinesWith.productDiscounts boolean

Indicates if the coupon can be combined with product discounts. Example: If the coupon cannot be used with existing product discounts, combinesWith.productDiscounts will be false, preventing customers from stacking discounts.

---

combinesWith.shippingDiscounts boolean

Indicates if the coupon can be combined with shipping discounts. Example: If the coupon cannot be combined with free shipping offers, combinesWith.shippingDiscounts will be false.

---

group.handle string

A unique identifier for the coupon group.

---

group.url string

URL of the coupon group.

---

group.iconPath string

Icon path of the coupon group.

---

isManualCouponboolean

Flag specifies whether the coupon is manually created by the user or automatically generated by the system as part of a reward or automation process.

Example: if set to true , this means that this coupon is generated manually .

---

isAvaliableToUse boolean

Flag determines whether a coupon can be used by a specific customer at a given time. This flag considers several key conditions to ensure the coupon is eligible for redemption:

• Expiry Date: The coupon must not have expired. If the current date is after the expiry date, the coupon will not be available.

• Start Date: The coupon must be within its valid usage period. If the current date is before the start date, the coupon cannot be used yet.

• Active Status: The coupon must be active. If isActive is set to false, the coupon is not available for use.

• Usage Limit: The coupon must not have reached its overall usage limit. If the total number of uses has been exhausted, the coupon will no longer be available for use.

• Per-Customer Usage Limit: The coupon must not have been used more than the allowed number of times by the specific customer. If the customer has reached the maximum allowed usage (e.g., limitPerCustomer), they will not be able to use the coupon again.

If all these conditions are met, the coupon will be available for use. Otherwise, it will be marked as unavailable.

---

Sample Response

{
  "coupons": [
    {
      "name": "Welcome Discount",
      "code": "WELCOME2024",
      "value": 10,
      "type": "percentage",
      "target": "Reward",
      "isManualCoupon": false,
      "currency": "USD",
      "startDate": "2024-01-01T00:00:00.000Z",
      "expiryDate": "2024-12-31T23:59:59.999Z",
      "isExpired": false,
      "isActive": true,
      "usageLimit": 999,
      "limitPerCustomer": 1,
      "usedCount": 10,
      "customerUsedCount": 0,
      "capping": 50,
      "minOrderValue": 20,
      "entitledProductIds": ["prod_123", "prod_456"],
      "entitledVariantIds": ["var_789"],
      "entitledCollectionIds": ["col_101112"],
      "entitledMerchantIds": [],
      "entitledPlatforms": ["online", "mobile"],
      "combinesWith": {
        "orderDiscounts": true,
        "productDiscounts": false,
        "shippingDiscounts": true
      },
      "group": {
        "handle": "welcome-offers",
        "url": "https://example.com/coupons/welcome-offers",
        "iconPath": "/images/icons/welcome.png"
      },
     "isAvlaibleToUse": false
    }
  ]
}

---

DELETE - Delete Customer

https://api.gameball.co/api/v4/integrations/customers/{customerId}

The API call removes the customer identified by customerId from the system. This removes the customer profile and associated data.

This API can also be accessed using the POST method for systems that do not support DELETE. In such cases, simply use /customers/{customerId}/delete endpoint to achieve the same functionality.

Security: Requires apikey and secretkey headers.

Request

Path Parameters

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.

---

GET - Customer Hash

https://api.gameball.co/api/v4/integrations/customers/{customerId}/hash

The API call generates a hash for an existing customer based on their unique customerId. This hash is used to securely redeem loyalty points during transactions.

Security: Requires apikey and secretkey headers.

Request

Path Parameters

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.

---

Response

application/json

hash string

A unique, rotating identifier generated for each customer, used as an additional layer of security and verification during redemptions and hold operations. This number is dynamically regenerated with each transaction to ensure secure validation and prevent unauthorized actions. The hash serves as a key to verify the legitimacy of the redemption or hold request. Refer to the Hold Management Section for more details about using the hash generated here.

---

Sample Response

{
    "hash": "039684"
}