Home/ Utilities

Utilities

Configuration APIs for home page banners and the ONDC Issue & Grievance Management (IGM) system.

# Get Hero Sections by City

Fetch promotional hero banner carousel data for a specific city's home page.

GET{{base_url}}/hero-sections/city/:cityId

Bearer Token Required

Path Parameters

Field	Type	Required	Description
cityId	string	REQUIRED	MongoDB ObjectId from GET /city: `data.cities[n].id` or GET /nearest-city: `data.id`. Example: `690db16605e92e251850de53`

Response — 200 OK

[   // Direct array (NOT wrapped in "data")
  {
    "id": "6960997240205579cb54b614",
    "cityId": "690db16605e92e251850de53",
    "title": "Welcome to Delhi",
    "description": "Capital of India",
    "images": [
      { "downloadUrl": "https://s3.amazonaws.com/...pre-signed-url..." }
    ],
    "animationStyle": "FADE",
    "animationTime": 5,      // Seconds between auto-advance
    "displayOrder": 0,       // Sort ascending for correct order
    "isActive": true
  }
]

Response Format: Returns a direct array — NOT wrapped in "data". Image URLs are pre-signed S3 URLs valid for 24 hours only. Do not cache them. Sort banners by displayOrder ascending.

# Register Issue

Raise a customer complaint for a booking through the ONDC Issue & Grievance Management (IGM) system. Use when the QR code doesn't work, experience wasn't delivered, wrong item, payment issues, etc.

POST{{base_url}}/register-issue

Bearer Token Required

Request Body — application/json

Field	Type	Required	Source / Description
cityCode	string	REQUIRED	Use `*` for non-city-specific, or valid ONDC city code
transactionId	string	REQUIRED	GET /user/tickets: `transactionId`
bppId	string	REQUIRED	From booking's `onConfirmPayload.context.bpp_id`
bppUri	string	REQUIRED	From booking's `onConfirmPayload.context.bpp_uri`
category	string	REQUIRED	ONDC values: `FULFILLMENT` \| `PAYMENT` \| `ITEM`
subCategory	string	REQUIRED	`FLM101` (not received) \| `FLM102` (quality) \| `ITM01` (wrong item)
name	string	REQUIRED	Complainant's full name
phone	string	REQUIRED	Complainant's phone number
email	string	REQUIRED	Complainant's email
orderId	string	REQUIRED	GET /user/tickets: `orderId`. Example: `HDBAP0000001163`
orderState	string	REQUIRED	`ACTIVE` \| `COMPLETED` \| `CANCELLED`
providerId	string	REQUIRED	GET /item/slug: `provider.id`
itemId	string	REQUIRED	Item UUID
itemQuantity	number	REQUIRED	Quantity of items in the order
fulfillmentId	string	REQUIRED	From booking's `fulfillments[0].id`
shortDesc	string	REQUIRED	1-sentence issue summary. Example: `"QR code not working at venue"`
longDesc	string	REQUIRED	Detailed issue description
sourceType	string	REQUIRED	Always `CONSUMER` for buyer-side issues
status	string	REQUIRED	Always `OPEN` for new issues
issueType	string	REQUIRED	`ISSUE` or `GRIEVANCE` (escalate to GRIEVANCE if unresolved after 3+ days)
images	array	OPTIONAL	Evidence image URLs. Can be empty `[]`
userId	string	OPTIONAL	User UUID from JWT token

Response — 201 Created

{
  "data": {
    "message": "successfully registered the issue",
    "issueId": "ce32896e-d57e-4c24-b9fb-651a574d75fa"   // Save for tracking
  }
}

Save the returned issueId and display it to the user as a reference number. Users can view their issues in GET /user/ticket/:transactionId → issues[] array.

# Common Error Responses

HTTP Status	Meaning	Action
400	Bad Request — invalid payload	Check all required fields and data types
401	Unauthorized — token expired or missing	Re-call GET /auth/token for a fresh token
403	Forbidden — insufficient permissions	Check client role with the HD team
404	Resource not found	Verify slugs, IDs, and path parameters
422	Validation error	Check field formats, types, and allowed enum values
503	BPP service unavailable	Retry after 5–10 seconds with same `transactionId`

ONDC NACK Errors: Even on HTTP 200/201, check onSelect.message.ack.status. If it returns "NACK", the BPP rejected the request. Error details are in message.error. If the BPP times out (30s window), retry the SELECT/INIT call with the same transactionId.

← PreviousUser APIs ↩ Back toComplete Booking Flow