Implementation notes

Worked examples

Sign in and use the customer token

Request:

POST /api/v1/login
Origin: your-registered-site.example
api-key: <BRAND_API_KEY>
Content-Type: application/json

{"payload":{"email":"alex@example.com","otp":"123456","recaptcha_token":"<TOKEN_IF_REQUIRED>"}}

Illustrative successful response:

{"success":true,"result":{"message":"Login successfully","token":"<CUSTOMER_TOKEN>","userId":123,"isVerified":"<VERIFICATION_STATUS>"}}

Use the returned token, while retaining the brand context:

curl "$BASE_URL/api/v1/user/detail" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN"

Add an address

Illustrative request body:

{"payload":{"address1":"123 Example Street","city":"New York","state":"New York","zip":"10001","country":"US","addressString":"123 Example Street, New York, NY 10001, US","isPrimary":true}}

Illustrative successful response:

{"success":true,"result":{"message":"User address successfully added with id: 456","addressId":456}}

A customer validation error can still have HTTP 200:

{"success": false, "error": "\"address1\" is required"}

Registration notes and implementation gaps

These observations describe the customer backend as of 22 October 2026. They are not additional API features.

Case	What the code currently does
Repeated cancellation	PUT /api/v1/user/order/cancel/:orderId is declared twice with the same handler. It has one documentation entry.
Misleading comments	verify-OTP claims to return a login token. Controller/service behavior is documented above.
Swagger coverage	/doc derives schemas from validator files and omits direct app.ts endpoints. A Swagger schema can lag behind inline controller validation.
Service-owned schemas	v2 loyalty and mini-games, NFT/web3 operations, payment providers, and some search/catalogue responses depend on external services. Their complete downstream response schemas are not defined here; service source links identify the integration boundary.

Commented-out routes

The following declarations are inside comments and do not register routes. The commented duplicate verify-otp declaration has a separate active declaration documented above. The other entries should not be treated as callable APIs.

Method	Commented path	Route source
GET	/api/v1/blog/:blogId	routes/v1/blog_route.js
GET	/api/v1/blogs/:slug	routes/v1/blog_route.js
GET	/api/v1/blogs	routes/v1/blog_route.js
GET	/api/v1/verify-user/:userToken	routes/v1/customer_route.js
POST	/api/v1/verify-otp	routes/v1/customer_route.js

Exported controllers without a live route declaration are not callable merely because the function exists. In particular, several older loyalty/reward and catalogue helpers remain in the code but are not registered by the current route arrays.

Keeping these pages current

These pages were split from API_DOCUMENTATION.md in the customer backend, which is kept in step with the routes by python3 scripts/verify-api-documentation.py (a static check: it compares documented endpoints with active route declarations and does not call the API). When an endpoint changes, update its entry here, then run npm run api:console so the Try it blocks pick up the new paths, access labels, query names and example bodies.

Related pages

• Batch Commerce API overview
• Sign-up and login