Points to Coupon Conversion Architecture

About This Article

We replaced the act of "using points" with a mechanism that "consumes points to issue a coupon, then receives a discount with that coupon." This article explains the technical architecture in detail.

Conversion Process Overview

System Integration

Systems Involved in Conversion Process

Frontend (Next.js)

Input UI, result display, copy function

Own Server (API Routes)

Process control, authentication verification, transactions

External APIs

Shopify coupon creation API, POS point operation API

Processing Steps in Detail

Receive Conversion Request

Receive conversion request from customer, verify authentication

Check Point Balance

Get real-time balance via POS API, verify conversion eligibility

Generate Coupon

Create customer-specific coupon via Shopify Admin API

Deduct Points

Deduct specified points from balance via POS API

Save to Metafield

Record issued coupon info in customer's metafield

Return Result

Return coupon code and details to frontend

Step Details

Steps 1-2: Request Reception and Balance Check

Balance Check Flow

Request Received

Customer ID: 12345, Requested points: 500pt, Auth token: xxx

Authentication Verification

Token validity check → OK / Customer ID ownership check → OK

POS Balance Query

API call: GET /customers/12345/points → Balance 1250pt

Conversion Eligibility Check

Balance(1250) >= Requested(500) → OK / Minimum unit: 100pt → OK / Daily limit: 10000pt → OK

Proceed to Step 3

All checks passed

Step 3: Shopify Coupon Generation

Shopify Admin API call: Endpoint priceRules + discountCodes

Generated code example: 70934-AB12CD-500

Response: priceRuleId, discountCodeId, code

Step 4: POS Point Deduction

Important: Record reference information to track conversions

Step 5: Metafield Storage

Storage location: Customer's Shopify metafield (namespace: loyalty, key: coupons)

Uses: My page list display, usage tracking, cancellation reference

Transaction Design

Why Order Matters

Ideal order: 1. Create coupon → 2. Deduct points → 3. Save record

Rollback on Error

Note: Metafield save is "nice to have." If actuals (coupon and points) are correct, operations can cover it

API Call Implementation Points

Retry Strategy

Timeout Settings

Performance Considerations

Processing Time Breakdown

UX response: Show "Processing..." to customer with loading animation to improve perceived speed