Coupons
Postman Doc: https://documenter.getpostman.com/view/20499442/[merchant-collection-id]

--------------------------------------------------------------------------------
API: Create Coupon
--------------------------------------------------------------------------------
    POST /merchant/api/v1/domains/:domain_id/coupons [Seller Finance & Analytics, Orchestration]

    Description: Create coupon rules and actions. Supports complex `coupon_rule` and `coupon_action` structures including product/collection restrictions, usage limits, time windows, and stackability.

    Request Body (abridged example):
        {
            "code": "SAVE20",
            "title": "Save 20%",
            "active": true,
            "starts_at": "2025-01-01T00:00:00Z",
            "expires_at": "2025-01-31T23:59:59Z",
            "coupon_rule": { "min_cart_value": 100, "applicable_products": ["prod_1"], "exclusive": false },
            "coupon_action": { "type": "percentage", "value": 20 }
        }

    Flow Sequence:
        # Step 1: Validate coupon fields and overlap rules
        # Step 2: Persist coupon in Marketing & Promotions Service
        # Step 3: Propagate to cache and reporting
        # Step 4: Log creation event

    Response: 201 Created with coupon object

--------------------------------------------------------------------------------
API: List / Get / Update / Delete Coupon
--------------------------------------------------------------------------------
    GET /merchant/api/v1/domains/:domain_id/coupons
    GET /merchant/api/v1/domains/:domain_id/coupons/:id
    PATCH /merchant/api/v1/domains/:domain_id/coupons/:id
    DELETE /merchant/api/v1/domains/:domain_id/coupons/:id

    Notes: `PUT /merchant/api/v1/coupons/apply` exists at orchestration level for validating and applying coupons to a cart; see Postman collection examples.

    Flow Sequence (List/Get):
        # Step 1: Validate Token and Domain
        # Step 2: Fetch coupon(s) from Marketing & Promotions Service
        GET /api/promotions/coupons?domain_id=:domain_id [Marketing & Promotions Service]

    Flow Sequence (PATCH/DELETE):
        # Step 1: Validate Token and Permissions
        # Step 2: Update/Delete coupon in Marketing & Promotions Service
        PATCH/DELETE /api/promotions/coupons/:id [Marketing & Promotions Service]
        # Step 3: Invalidate cache and update reporting
        POST /api/cache/invalidate [Caching Service, Shared Services]

    Flow Sequence (Apply Coupon - Orchestration):
        # Step 1: Validate Token and Domain
        # Step 2: Fetch Cart Details
        GET /api/carts/:cart_id [Cart Service, Core Microservices]
        # Step 3: Validate coupon rules via Promotions Service
        POST /api/promotions/coupons/validate [Marketing & Promotions Service]
        # Step 4: Calculate discount and update cart totals
        PATCH /api/carts/:cart_id/apply-discount [Cart Service, Core Microservices]
        # Step 5: Return updated cart with discount breakdown