PortfolioAbout 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
Input UI, result display, copy function
Process control, authentication verification, transactions
Shopify coupon creation API, POS point operation API
Processing Steps in Detail
Receive conversion request from customer, verify authentication
Get real-time balance via POS API, verify conversion eligibility
Create customer-specific coupon via Shopify Admin API
Deduct specified points from balance via POS API
Record issued coupon info in customer's metafield
Return coupon code and details to frontend
Step Details
Steps 1-2: Request Reception and Balance Check
Customer ID: 12345, Requested points: 500pt, Auth token: xxx
Token validity check → OK / Customer ID ownership check → OK
API call: GET /customers/12345/points → Balance 1250pt
Balance(1250) >= Requested(500) → OK / Minimum unit: 100pt → OK / Daily limit: 10000pt → OK
All checks passed
Step 3: Shopify Coupon Generation
| PriceRule Field | Setting |
|---|---|
| Discount type | Fixed amount |
| Discount amount | -500 yen |
| Usage count | Once only |
| Customer restriction | Specific customer only |
| Validity period | 1 year |
| Minimum purchase | None |
Shopify Admin API call: Endpoint priceRules + discountCodes
Generated code example: 70934-AB12CD-500
Response: priceRuleId, discountCodeId, code
Step 4: POS Point Deduction
| Field | Value |
|---|---|
| Endpoint | POST /customers/12345/points/deduct |
| Request amount | 500 |
| Request reason | Coupon conversion |
| Request reference | COUPON-70934-AB12CD-500 |
| Response success | true |
| Response previous_balance | 1250 |
| Response deducted | 500 |
| Response new_balance | 750 |
Important: Record reference information to track conversions
Step 5: Metafield Storage
Storage location: Customer's Shopify metafield (namespace: loyalty, key: coupons)
| Stored Field | Example |
|---|---|
| code | 70934-AB12CD-500 |
| amount | 500 |
| points_used | 500 |
| created_at | 2024-01-15T10:30:00Z |
| expires_at | 2025-01-15T23:59:59Z |
| status | active |
| shopify_price_rule_id | 12345678 |
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
| Order | Process | Reason |
|---|---|---|
| 1st | Coupon creation | Reversible. Don't deduct points if creation fails |
| 2nd | Point deduction | Deduct after coupon exists. Delete coupon if deduction fails |
| 3rd | Record storage | Record after all success. Actuals are complete even if recording fails |
Rollback on Error
| Error Case | Response | Result |
|---|---|---|
| Coupon creation fails | Do nothing (nothing changed yet) | Display error message |
| Point deduction fails | Delete created coupon | Display error message |
| Metafield save fails | Log warning (don't rollback) | Treat as success, notify admin |
Note: Metafield save is "nice to have." If actuals (coupon and points) are correct, operations can cover it
API Call Implementation Points
Retry Strategy
| API | Retry | Reason |
|---|---|---|
| Shopify coupon creation | Up to 3 times | Possible temporary error |
| POS point deduction | No retry | Prevent double deduction |
| Metafield save | Up to 3 times | Low impact if fails |
Timeout Settings
| API | Timeout | Reason |
|---|---|---|
| Shopify coupon creation | 10 seconds | Shopify API is stable |
| POS point deduction | 15 seconds | Some POS systems can be slow |
| Metafield save | 5 seconds | Shopify API is stable |
Performance Considerations
Processing Time Breakdown
| Processing Step | Duration |
|---|---|
| Authentication verification | ~100ms |
| POS balance query | ~500ms |
| Shopify coupon creation | ~800ms |
| POS point deduction | ~600ms |
| Metafield save | ~300ms |
| Total | ~2.3 seconds |
UX response: Show "Processing..." to customer with loading animation to improve perceived speed
Benefits of This Design
Reliability
- Optimized processing order minimizes error impact
- Rollback strategy prevents inconsistencies
- All processes logged for traceability
Maintainability
- Each step is independent and testable
- Easy to identify error causes
- Easily accommodates future features (point rate changes, etc.)