Coupon API

Create, manage, and track promotional coupons for your products on the Hubble platform.

Overview

The Coupon API allows you to create, manage, and track promotional coupons for your products on the Hubble platform.

Base URL

Environment	Base URL
Development	`https://api.dev.myhubble.money`
Production	`https://api.myhubble.money`

Authentication

All API requests require authentication using a Bearer token obtained from the login API.

Required Headers:

Header	Description	Required
`Authorization`	Bearer token obtained from login API	Yes
`Content-Type`	`application/json`	For PUT/POST only
`X-Request-id`	Unique request identifier for tracking	Recommended

Example Headers:

Authorization: Bearer your-access-token
Content-Type: application/json
X-Request-id: unique-request-id-123

See the API Reference overview for details on obtaining your access token.

Endpoints

1. Create Coupon

Create a new promotional coupon for your products.

HTTP Method: POST

Endpoint: /v1/partners/coupons

Request Body:

{
  "code": "SAVE20",
  "conditions": {
    "startDate": "2025-01-01",
    "expiryDate": "2025-12-31",
    "minimumRedemptionAmount": 500.00,
    "applicableVoucherProductIds": ["product-id-1", "product-id-2"],
    "excludeVoucherProductIds": ["product-id-3"],
    "totalUsageLimit": 1000,
    "perUserLimit": 1,
    "applyOnlyForFirstTimeCoupon": false,
    "applyOnlyForFirstRedemption": false
  },
  "discountType": "PERC",
  "discountValue": 20.0,
  "maxDiscountAmount": 100.0,
  "display": {
    "visibility": "LISTED",
    "displayTitle": "Save 20% on Gift Cards",
    "displaySubtitle": "Valid on selected brands",
    "displayImageUrl": "https://your-cdn.com/coupon-banner.png"
  }
}

Request Fields:

Field	Type	Required	Description
`code`	string	Yes	Unique coupon code (will be converted to uppercase)
`conditions`	object	Yes	Coupon conditions and restrictions
`conditions.startDate`	date	Yes	Coupon validity start date (YYYY-MM-DD)
`conditions.expiryDate`	date	Yes	Coupon expiry date (YYYY-MM-DD)
`conditions.minimumRedemptionAmount`	decimal	No	Minimum transaction amount to apply coupon
`conditions.applicableVoucherProductIds`	array	No	List of product IDs where coupon is valid
`conditions.excludeVoucherProductIds`	array	No	List of product IDs where coupon should NOT apply
`conditions.totalUsageLimit`	integer	No	Total number of times coupon can be used (default: 1000)
`conditions.perUserLimit`	integer	No	Number of times a user can use the coupon (default: 1)
`conditions.applyOnlyForFirstTimeCoupon`	boolean	No	Apply only for first-time coupon users (default: false)
`conditions.applyOnlyForFirstRedemption`	boolean	No	Apply only on user’s first redemption (default: false)
`discountType`	enum	Yes	`PERC` (percentage) or `ABS` (absolute amount)
`discountValue`	decimal	Yes	Discount value (percentage or amount)
`maxDiscountAmount`	decimal	Yes	Maximum discount cap
`display`	object	Yes	Coupon display configuration
`display.visibility`	enum	No	`LISTED` or `NOT_LISTED` (default: LISTED)
`display.displayTitle`	string	No	Coupon display title for users
`display.displaySubtitle`	string	No	Coupon subtitle/description
`display.displayImageUrl`	string	No	Banner image URL for coupon display

Response:

Status Code: 201 Created

{
  "id": "01HQZX123456789ABC",
  "code": "SAVE20",
  "conditions": {
    "startDate": "2025-01-01",
    "expiryDate": "2025-12-31",
    "minimumRedemptionAmount": 500.00,
    "applicableVoucherProductIds": ["product-id-1", "product-id-2"],
    "excludeVoucherProductIds": ["product-id-3"],
    "totalUsageLimit": 1000,
    "perUserLimit": 1,
    "applyOnlyForFirstTimeCoupon": false,
    "applyOnlyForFirstRedemption": false
  },
  "discountType": "PERC",
  "discountValue": 20.0,
  "maxDiscountAmount": 100.0,
  "display": {
    "visibility": "LISTED",
    "displayTitle": "Save 20% on Gift Cards",
    "displaySubtitle": "Valid on selected brands",
    "displayImageUrl": "https://your-cdn.com/coupon-banner.png"
  }
}

2. Get Coupon Details

Retrieve details of a specific coupon you created.

HTTP Method: GET

Endpoint: /v1/partners/coupons/{couponId}

Path Parameters:

Parameter	Type	Required	Description
`couponId`	string	Yes	The ID of the coupon to retrieve

Response:

Status Code: 200 OK

{
  "id": "01HQZX123456789ABC",
  "code": "SAVE20",
  "conditions": {
    "startDate": "2025-01-01",
    "expiryDate": "2025-12-31",
    "minimumRedemptionAmount": 500.00,
    "applicableVoucherProductIds": ["product-id-1", "product-id-2"],
    "excludeVoucherProductIds": ["product-id-3"],
    "totalUsageLimit": 1000,
    "perUserLimit": 1,
    "applyOnlyForFirstTimeCoupon": false,
    "applyOnlyForFirstRedemption": false
  },
  "discountType": "PERC",
  "discountValue": 20.0,
  "maxDiscountAmount": 100.0,
  "display": {
    "visibility": "LISTED",
    "displayTitle": "Save 20% on Gift Cards",
    "displaySubtitle": "Valid on selected brands",
    "displayImageUrl": "https://your-cdn.com/coupon-banner.png"
  }
}

3. Update Coupon

Update an existing coupon. All fields are optional - only provide fields you want to update.

HTTP Method: PUT

Endpoint: /v1/partners/coupons/{couponId}

Path Parameters:

Parameter	Type	Required	Description
`couponId`	string	Yes	The ID of the coupon to update

Request Body:

{
  "conditions": {
    "expiryDate": "2025-12-31",
    "minimumRedemptionAmount": 600.00,
    "applicableVoucherProductIds": ["product-id-1"],
    "excludeVoucherProductIds": ["product-id-4"],
    "totalUsageLimit": 500,
    "perUserLimit": 2,
    "applyOnlyForFirstTimeCoupon": true,
    "applyOnlyForFirstRedemption": false
  },
  "discountValue": 25.0,
  "maxDiscountAmount": 150.0,
  "display": {
    "visibility": "NOT_LISTED",
    "displayTitle": "Updated Title",
    "displaySubtitle": "Updated Subtitle",
    "displayImageUrl": "https://your-cdn.com/new-banner.png"
  }
}

Request Fields (All Optional):

Field	Type	Description
`conditions`	object	Updated coupon conditions (all nested fields optional)
`conditions.expiryDate`	date	New expiry date
`conditions.minimumRedemptionAmount`	decimal	Updated minimum amount
`conditions.applicableVoucherProductIds`	array	Updated product inclusion list
`conditions.excludeVoucherProductIds`	array	Updated product exclusion list
`conditions.totalUsageLimit`	integer	Updated total usage limit
`conditions.perUserLimit`	integer	Updated per-user limit
`conditions.applyOnlyForFirstTimeCoupon`	boolean	Updated first-time coupon user restriction
`conditions.applyOnlyForFirstRedemption`	boolean	Updated first redemption restriction
`discountValue`	decimal	Updated discount value
`maxDiscountAmount`	decimal	Updated discount cap
`display`	object	Updated display configuration (all nested fields optional)
`display.visibility`	enum	Updated visibility (LISTED or NOT_LISTED)
`display.displayTitle`	string	Updated display title
`display.displaySubtitle`	string	Updated subtitle
`display.displayImageUrl`	string	Updated image URL

Response:

Status Code: 200 OK

{
  "id": "01HQZX123456789ABC",
  "code": "SAVE20",
  "conditions": {
    "startDate": "2025-01-01",
    "expiryDate": "2025-12-31",
    "minimumRedemptionAmount": 600.00,
    "applicableVoucherProductIds": ["product-id-1"],
    "excludeVoucherProductIds": ["product-id-4"],
    "totalUsageLimit": 500,
    "perUserLimit": 2,
    "applyOnlyForFirstTimeCoupon": true,
    "applyOnlyForFirstRedemption": false
  },
  "discountType": "PERC",
  "discountValue": 25.0,
  "maxDiscountAmount": 150.0,
  "display": {
    "visibility": "NOT_LISTED",
    "displayTitle": "Updated Title",
    "displaySubtitle": "Updated Subtitle",
    "displayImageUrl": "https://your-cdn.com/new-banner.png"
  }
}

4. Delete Coupon

Delete a coupon you created.

HTTP Method: DELETE

Endpoint: /v1/partners/coupons/{couponId}

Path Parameters:

Parameter	Type	Required	Description
`couponId`	string	Yes	The ID of the coupon to delete

Response:

Status Code: 204 No Content

Discount Types

Percentage Discount (PERC)

Applies a percentage-based discount with a maximum cap.

discountValue: Percentage value (e.g., 20 for 20%)
maxDiscountAmount: Maximum discount cap in currency

Example: 20% off, max ₹100

{
  "discountType": "PERC",
  "discountValue": 20.0,
  "maxDiscountAmount": 100.0
}

Absolute Discount (ABS)

Applies a fixed amount discount.

discountValue: Fixed amount discount
maxDiscountAmount: Same as discountValue

Example: Flat ₹50 off

{
  "discountType": "ABS",
  "discountValue": 50.0,
  "maxDiscountAmount": 50.0
}

Error Responses

400 Bad Request

Invalid request data or validation failure.

{
  "code": "INVALID_REQUEST",
  "message": "Expiry date must be after start date",
  "requestId": "req-123",
  "debugMessage": "Validation failed for field: expiryDate"
}

401 Unauthorized

Missing or invalid authentication credentials.

{
  "code": "UNAUTHORIZED",
  "message": "Invalid authentication credentials",
  "requestId": "req-123"
}

403 Forbidden

Attempting to access/modify a coupon created by another partner.

{
  "code": "ACCESS_DENIED",
  "message": "You can only access your own coupons",
  "requestId": "req-123"
}

404 Not Found

Coupon not found.

{
  "code": "NOT_FOUND",
  "message": "Coupon not found with id: 01HQZX123456789ABC",
  "requestId": "req-123"
}

Important Notes

Coupon Structure

The API uses nested objects for better organization:

conditions: All coupon conditions, restrictions, and usage limits
display: All display-related configuration for the user interface

New Condition Fields

Product Filtering:

applicableVoucherProductIds: Whitelist of product IDs where coupon can be applied
excludeVoucherProductIds: Blacklist of product IDs where coupon cannot be applied
These can be used together: apply to specific products but exclude certain ones

User Targeting:

applyOnlyForFirstTimeCoupon: If true, only users who have never used any coupon before can use this coupon
applyOnlyForFirstRedemption: If true, only users making their first redemption transaction can use this coupon
These restrictions help target new users or first-time customers

Display Visibility

LISTED (default): Coupon appears in the user’s coupon listing/discovery page
NOT_LISTED: Coupon is hidden from listings but can still be applied if user knows the code (useful for private/targeted promotions)

Coupon Behavior

Automatic Application: Coupons are automatically applied on redemption transactions (not deposits)
Validation: System validates 16+ conditions before applying coupon (expiry, limits, amounts, product eligibility, etc.)
Usage Tracking: Each coupon application is tracked and counted against usage limits
Ownership: Partners can only manage coupons they created

Best Practices

Unique Codes: Use unique coupon codes to avoid conflicts
Expiry Dates: Set reasonable expiry dates; expired coupons cannot be used
Usage Limits: Set appropriate totalUsageLimit and perUserLimit to control budget
Product Filtering:
- Use applicableVoucherProductIds to restrict coupons to specific products
- Use excludeVoucherProductIds to exclude specific products from coupon eligibility
- Combine both for fine-grained control (e.g., “all products except sale items”)
User Targeting:
- Use applyOnlyForFirstTimeCoupon to target users who have never used coupons
- Use applyOnlyForFirstRedemption to target first-time purchasers
Display Information: Provide clear displayTitle and displaySubtitle for better user experience
Visibility Control: Use NOT_LISTED for private promotions or targeted campaigns
Testing: Always test in development environment before deploying to production

Restrictions

Partners can only create coupons for their own products
Maximum totalUsageLimit may be capped at system level
Maximum perUserLimit may be capped at system level
Discount values are validated against sanity check rules
Coupon codes must be unique across the platform

Usage Examples

Example 1: Basic Percentage Discount

20% off on all products, max ₹100 discount:

{
  "code": "SAVE20",
  "conditions": {
    "startDate": "2025-01-01",
    "expiryDate": "2025-12-31"
  },
  "discountType": "PERC",
  "discountValue": 20.0,
  "maxDiscountAmount": 100.0,
  "display": {
    "displayTitle": "Save 20% on all products"
  }
}

Example 2: Product-Specific Discount

Flat ₹50 off on specific products only:

{
  "code": "GIFTCARD50",
  "conditions": {
    "startDate": "2025-01-01",
    "expiryDate": "2025-03-31",
    "applicableVoucherProductIds": ["amazon-gift-card", "flipkart-gift-card"],
    "minimumRedemptionAmount": 500.00
  },
  "discountType": "ABS",
  "discountValue": 50.0,
  "maxDiscountAmount": 50.0,
  "display": {
    "displayTitle": "₹50 off on Gift Cards",
    "displaySubtitle": "Min transaction ₹500"
  }
}

Example 3: Exclude Specific Products

15% off on all products except already discounted items:

{
  "code": "SPECIAL15",
  "conditions": {
    "startDate": "2025-01-01",
    "expiryDate": "2025-12-31",
    "excludeVoucherProductIds": ["sale-item-1", "sale-item-2"]
  },
  "discountType": "PERC",
  "discountValue": 15.0,
  "maxDiscountAmount": 200.0,
  "display": {
    "displayTitle": "15% off (excludes sale items)"
  }
}

Example 4: First-Time Coupon User

Welcome offer for users who have never used any coupon:

{
  "code": "WELCOME100",
  "conditions": {
    "startDate": "2025-01-01",
    "expiryDate": "2025-12-31",
    "applyOnlyForFirstTimeCoupon": true,
    "minimumRedemptionAmount": 1000.00
  },
  "discountType": "ABS",
  "discountValue": 100.0,
  "maxDiscountAmount": 100.0,
  "display": {
    "displayTitle": "₹100 off on your first coupon",
    "displaySubtitle": "For new coupon users only"
  }
}

Example 5: First Purchase Discount

Discount for users making their first redemption:

{
  "code": "FIRST200",
  "conditions": {
    "startDate": "2025-01-01",
    "expiryDate": "2025-12-31",
    "applyOnlyForFirstRedemption": true,
    "minimumRedemptionAmount": 2000.00
  },
  "discountType": "ABS",
  "discountValue": 200.0,
  "maxDiscountAmount": 200.0,
  "display": {
    "displayTitle": "₹200 off on first purchase",
    "displaySubtitle": "Min order ₹2000"
  }
}

Example 6: Hidden/Private Coupon

Coupon not listed publicly, only usable if user knows the code:

{
  "code": "VIP500",
  "conditions": {
    "startDate": "2025-01-01",
    "expiryDate": "2025-03-31",
    "perUserLimit": 1,
    "totalUsageLimit": 100
  },
  "discountType": "ABS",
  "discountValue": 500.0,
  "maxDiscountAmount": 500.0,
  "display": {
    "visibility": "NOT_LISTED",
    "displayTitle": "VIP Exclusive - ₹500 off",
    "displaySubtitle": "Limited to 100 uses"
  }
}

Example 7: Combined Restrictions

Apply to specific products, exclude some, and target first-time users:

{
  "code": "NEWYEAR2025",
  "conditions": {
    "startDate": "2025-01-01",
    "expiryDate": "2025-01-31",
    "applicableVoucherProductIds": ["premium-1", "premium-2", "premium-3"],
    "excludeVoucherProductIds": ["premium-1-sale"],
    "applyOnlyForFirstTimeCoupon": true,
    "minimumRedemptionAmount": 1500.00,
    "perUserLimit": 1,
    "totalUsageLimit": 500
  },
  "discountType": "PERC",
  "discountValue": 25.0,
  "maxDiscountAmount": 300.0,
  "display": {
    "displayTitle": "New Year Special - 25% off",
    "displaySubtitle": "For first-time users on premium products"
  }
}

Code Examples

cURL

Create Coupon

curl -X POST https://api.myhubble.money/v1/partners/coupons \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "X-Request-id: req-$(date +%s)" \
  -d '{
    "code": "SAVE20",
    "conditions": {
      "startDate": "2025-01-01",
      "expiryDate": "2025-12-31",
      "totalUsageLimit": 1000,
      "perUserLimit": 1
    },
    "discountType": "PERC",
    "discountValue": 20.0,
    "maxDiscountAmount": 100.0,
    "display": {
      "displayTitle": "Save 20%"
    }
  }'

Get Coupon

curl -X GET https://api.myhubble.money/v1/partners/coupons/01HQZX123456789ABC \
  -H "Authorization: Bearer your-access-token"

Update Coupon

curl -X PUT https://api.myhubble.money/v1/partners/coupons/01HQZX123456789ABC \
  -H "Authorization: Bearer your-access-token" \
  -H "Content-Type: application/json" \
  -H "X-Request-id: req-$(date +%s)" \
  -d '{
    "conditions": {
      "expiryDate": "2025-12-31",
      "totalUsageLimit": 500
    }
  }'

Delete Coupon

curl -X DELETE https://api.myhubble.money/v1/partners/coupons/01HQZX123456789ABC \
  -H "Authorization: Bearer your-access-token"