Skip to main content

Frequently Asked Questions

Common questions about integrating with the Hubble API.

Orders​

1. What are the possible scenarios for a response when placing an order?​

StatusDescriptionYour Action
SUCCESSVouchers will be returned instantlyDisplay vouchers to user
FAILEDThe order has failedShow error, retry with new referenceId
PROCESSINGGeneration in progressListen for webhook or poll the Get Orders API

2. What should be done in case of a timeout?​

In the event of a timeout, use the endpoint /v1/partners/orders/by-reference/{referenceId} to verify if the order was successfully created.

  • 404 response = Order was NOT created. You may safely retry with the same referenceId.
  • Any other response = Order exists. Process based on the returned status.

3. How can you ensure that an order is idempotent?​

The referenceId passed with the order acts as an idempotency key. Using this reference ID ensures that there is only one order in the system for that ID, preventing duplicate orders.

note

The referenceId is consumed even if the order fails. Always generate a new referenceId for retry attempts.

Brands​

4. How will product changes be communicated?​

Clients can subscribe to the Brand Updated Webhook to receive notifications about product updates. Only changes to the following fields are communicated through webhooks:

{
  "id": "brand_id",
  "denominationType": "FIXED/FLEXIBLE",
  "status": "ACTIVE/INACTIVE",
  "denominations": [100, 1000, 5000],
  "amountRestrictions": {
    "minOrderAmount": 100,
    "maxOrderAmount": 5000,
    "minVoucherAmount": 100,
    "maxVoucherAmount": 5000,
    "maxVouchersPerOrder": 5,
    "maxVouchersPerDenomination": 1,
    "maxDenominationsPerOrder": 1
  }
}

For other updates such as new brand additions, asset changes, or other metadata updates, implement a regular synchronization process (e.g., once per day) with the Get Brands API.

See the Webhooks documentation for more details.

5. What's the difference between tags and categories for brands?​

TypePurposeExample Use
CategoriesStrict classification system for grouping brandsDisplay brands in specific app sections (e.g., "Popular Brands", "Food & Beverage")
TagsFlexible, descriptive keywords for searchabilityEnable granular filtering based on user queries (e.g., "Pizza", "FastFood", "Online Shopping")

In short: Use categories for structured grouping and tags for flexible searching.

6. What are the available brand categories?​

The following categories are available as of July 2025:

PHARMACY, ENTERTAINMENT, QUICK_COMMERCE, DIWALI_SPECIAL, OFFLINE_BRANDS,
TRAVEL_AND_TRANSPORT, FURNISHING, ACCESSORIES, GROCERY, WATCHES,
EMERGING_BRANDS, NEW_BRANDS, LUXURY, ONE_STOP_SHOPS, APPLE, BEAUTY,
HOTELS, MUSIC, SOFTWARE, HAND_BAGS, HOME_DECOR, GAMING, OTT, JEWELLERY,
ELECTRONICS, BILL_PAYMENTS, FITNESS, FOOD, FASHION, RAKHI_SPECIAL,
HOT_DEALS, KIDS, FOOTWARE
note

This list is subject to change as categories are added or removed over time. Use the Get Brands API to fetch current categories.

Discounts​

7. Why doesn't the API return discount percentage information?​

Discount percentages are managed outside of the API system. These are determined by business arrangements and may vary based on specific partnerships.

For discount-related inquiries, please contact the Hubble business team for details.

Brand Discount Webhook

Subscribe to the Brand Discount Update webhook to receive notifications when subvention/discount percentages change for brands.

Authentication​

8. How long is the access token valid?​

The token validity is returned in the expiresInSecs field (typically 3600 seconds / 1 hour). Implement token refresh logic to re-authenticate before expiry.

9. What happens if I use staging credentials on production?​

You will receive authentication errors. Staging and production credentials are completely separate and cannot be interchanged.

Webhooks​

10. Why doesn't the Order Terminal State webhook include my referenceId?​

The webhook payload includes orderId and status, but not referenceId. Use the orderId to fetch the full order details via GET /v1/partners/orders/{orderId}, which includes your referenceId.

11. Are webhook endpoints different for staging and production?​

Yes. Webhook endpoints are configured per environment. You must configure staging and production webhook endpoints separately.

Wallet​

12. How do I top up my wallet?​

Wallet loading is an offline process. Contact your Hubble account manager to request a top-up.

13. What happens when my wallet balance is insufficient?​

You will receive error code E300 (Insufficient wallet balance). Orders will fail until the wallet is topped up. Set up the Wallet Low Balance webhook to receive alerts before this happens.