Audience: Mobile/web frontend developers Scope: Coupon apply, validation endpoints

Promotion Module - API & Integration Guide

1. How to Read / Quick Metadata

• Module: Promotion
• Primary base URLs:
  • Admin: /api/admin/promotions
  • Customer: /api/promotions
  • Mobile-composed customer: /api/mobile/promotions
• Auth model:
  • Admin routes: JwtAuthGuard + RoleGuard + @Permissions(...)
  • Customer routes: JwtAuthGuard
• Response envelope: ResponseDto<T> with paginated responses for list endpoints

2. High-Level Overview

Promotion API covers:

• admin coupon lifecycle management (CRUD + disable)
• customer coupon operations (apply/remove)
• customer read paths (active promotions and personal usage history)

POST /promotions/apply supports two behaviors:

• cart mutation mode when productId is omitted
• product-only validation mode when productId is provided

3. Core Concepts and Terminology

• promotion: coupon contract (promotion table)
• promotion scope: target filter rows (promotion_scope) tied to product/category/tag
• promotion usage: redemption history (promotion_usage) linked to customer + cart/order
• eligibility model: digital-cart + online-payment only
• code normalization: trim + uppercase before evaluation

Schema integrity contracts behind API behavior:

• promotion_usage_target_check: at least one of cart_id/order_id
• promotion_scope_target_check: exactly one of product_id/category_id/tag_id
• non-negative checks for discount/cart-value fields

4. Route Summary

4.1 Admin

4.2 Customer / Mobile

Mobile-composed routes are available under /api/mobile/promotions/....

Route Details

Apply Coupon

Remove Coupon

5. Query Parameters

Common list fields from QueryDto:

• pagination (default true)
• page (default 1)
• size (default 20)
• search (optional)
• order (asc/desc, default desc unless endpoint override)

Endpoint-specific parameters:

• admin list (GET /api/admin/promotions): status, sort
• customer active list (GET /api/promotions): discountType, sort, order (default asc)
• customer usage list (GET /api/promotions/my-usage): sort (discountApplied|createdAt)

6. Response Shape Examples

Active promotion list item example:

"
  "id": 12,
  "code": "SUMMER2026",
  "description": "Summer sale discount",
  "discountType": "percentage",
  "discountValue": 10,
  "maxDiscountCap": 5000,
  "minCartValue": 1000,
  "cartTypeEligibility": "digital",
  "startDate": "2026-04-01T00:00:00.000Z",
  "endDate": "2026-04-30T23:59:59.000Z"
"

Product validation mode response (POST /api/promotions/apply with productId):

"
  "message": "Coupon validated for product",
  "data": "
    "valid": true,
    "discount": 1000,
    "promotionId": 42,
    "promotionCode": "SUMMER2026"
  "",
  "errorCode": null
"

7. Enums

Promotion enums in active contracts:

• promotion_status: active, disabled, expired
• discount_type: flat, percentage
• cart_type_eligibility: digital
• payment_method_eligibility: online
• scope_type: product, category, tag

8. Integration Diagram

9. Caching

TTL envs:

• PROMOTION_ADMIN_CACHE_TTL_SECONDS
• PROMOTION_CUSTOMER_CACHE_TTL_SECONDS

10. Error Handling

All promotion API errors return the standard error envelope with errorCode.

"
  "statusCode": 400,
  "errorCode": "PROMOTION_NOT_APPLICABLE",
  "message": "Coupon is no longer active.",
  "timestamp": "2026-03-20T10:00:00.000Z",
  "path": "/api/promotions/apply"
"

Time fields in this module are stored as timezone-aware values and should be handled as ISO-8601 instants by API consumers.

11. Endpoint Reference + Payload Cheatsheet

11.1 Payload Cheatsheet Table (Every Endpoint)

11.1.1 Admin Promotions Endpoint Query Variations

11.1.2 Customer Active Promotions Query Variations

11.1.3 Customer Usage History Query Variations

11.1.4 Apply Coupon Request Variations

11.1.5 Admin Create Promotion Request Variations

11.1.6 Promotion Scope Variations

11.1.7 Promotion Response Field Variations

11.1.8 Coupon Validation Response Variations

11.1.9 Error Response Variations

11.1.10 Cache Invalidation Variations

11.1.11 Enums Reference

12. Testing Scenarios

12.1 Suggested Test Scenarios

• Admin creates promotion with valid date range, publishes it, and promotion appears in customer active list (GET /api/promotions).
• Admin creates promotion with product scope (scopes["" scopeType: "product", scopeId: N ""]), applies coupon, and discount applies only to that product.
• User applies valid coupon code to cart without productId, and cart discount is applied successfully via cart mutation.
• User applies coupon code with productId (validation-only mode), receives "" valid: true/false "" without modifying cart.
• User applies expired/inactive coupon and receives 400 PROMOTION_NOT_APPLICABLE with detailed reason.
• User applies coupon without meeting minimum cart value and receives 400 PROMOTION_NOT_APPLICABLE for minCartValue.
• User removes applied coupon from cart and cart reverts to original pricing.
• Admin deletes promotion with usage history and receives 400 PROMOTION_USAGE_CONFLICT; disable succeeds.

See Also

• Feature Guide: See Promotion - Feature List Section 6 (State Models) for promotion lifecycle and scope diagrams.
• Backend Reference: See Promotion - Backend Documentation Section 11 for system architecture diagram.
• Apply endpoint returns 429 RATE_LIMIT_EXCEEDED after sliding window threshold exceeded.