Coupon Management API

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

Base URLs

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

---

Endpoints

1. Create Coupon

Create a new promotional coupon for your products.

POST/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 (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.

GET/v1/partners/coupons/{couponId}

Path Parameters:

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

Response (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.

PUT/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"
  }
}

Response (200 OK):

Returns the updated coupon object.

---

4. Delete Coupon

Delete a coupon you created.

DELETE/v1/partners/coupons/{couponId}

Path Parameters:

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

Response (204 No Content):

Body: Empty

---

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

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

---

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: First-Time User Discount

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 4: 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"
  }
}

---

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"

---

Important Notes

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

1. Unique Codes: Use unique coupon codes to avoid conflicts
2. Expiry Dates: Set reasonable expiry dates; expired coupons cannot be used
3. Usage Limits: Set appropriate totalUsageLimit and perUserLimit to control budget
4. Product Filtering: Use applicableVoucherProductIds and excludeVoucherProductIds for fine-grained control
5. Testing: Always test in development environment before deploying to production

Coupon Validation in Staging

Coupons are environment-specific - a coupon created in staging will not exist in production and vice versa. Always test your coupons in staging first.