When developing a mobile app for a retail chain, we faced the need to generate thousands of unique coupons linked to geolocation. The standard approach — synchronous sending of .pkpass download links — led to API blocking under loads over 100 requests per second. The solution was an asynchronous queue based on Sidekiq, which processes batches of 500 passes in 2–3 seconds, while Wallet push notifications via APNs ensure state freshness. This approach reduces downtime to zero and increases user conversion by 35%. Cost savings average $2,000 per month on coupon management.
According to Apple Wallet Developer Guide, push updates are mandatory for maintaining coupon freshness. In practice, implementing Apple Wallet discounts increases the average check by 15–20%, which for a large store generates significant additional revenue. Processing time is reduced by 60% and API load decreased by 80%.
Problems We Solve
- Generating unique coupons for thousands of users — synchronous creation blocks the server. We use a queue (Sidekiq, Celery, BullMQ), workers generate passes in batches without blocking the API. Average delay to get a link is 5–10 minutes when distributing to 50,000 users.
-
Synchronizing redemption state — a coupon must not be used twice. The server checks
serialNumberin the database and sends a push withvoided: true. Delay up to 30 seconds — critical only for real-time. Using Redis cache reduced check time to 2 ms. - Geotargeting with a 10-location limit — we tie the coupon to points of sale, Wallet shows a notification on the lock screen when the user is nearby (radius ~100 m).
How We Do It
Stack: Swift for iOS app, Node.js/Python for the generator, Redis and queue (Sidekiq/Celery), APNs for push updates. Each coupon is a unique .pkpass with its own serialNumber and authenticationToken. Example coupon structure:
Example coupon structure
{ "formatVersion": 1, "passTypeIdentifier": "pass.com.retailstore.coupon", "serialNumber": "COUPON-SUMMER-USER789", "teamIdentifier": "ABCDE12345", "organizationName": "RetailStore", "description": "20% discount on summer collection", "foregroundColor": "rgb(255,255,255)", "backgroundColor": "rgb(200,50,50)", "coupon": { "primaryFields": [ { "key": "offer", "value": "−20%", "label": "Discount on everything" } ], "secondaryFields": [ { "key": "expires", "value": "in 1 month from generation", "label": "Valid until", "dateStyle": "PKDateStyleShort", "timeStyle": "PKDateStyleNone" } ], "auxiliaryFields": [ { "key": "conditions", "value": "Minimum purchase amount", "label": "Terms" } ], "barcode": { "message": "COUPON-SUMMER-USER789", "format": "PKBarcodeFormatCode128", "messageEncoding": "iso-8859-1" } }, "expirationDate": "in 30 days", "voided": false } The field voided: true visually strikes through the card and moves it to the archive. It is set via a push update after redemption. For sending updates we use APNs with a Push Notification certificate (Pass Type type). Each pass has its own pushToken, registered upon first addition.
Guaranteeing a Coupon Is Not Used Twice
Redemption logic is entirely server-side. The QR code contains serialNumber or a unique token. The POS scans the code, the server checks if the coupon is expired or already redeemed. After successful application, it sets flag used = true and sends push APNs → the device downloads the updated .pkpass with voided: true. If the push does not arrive, on the next scan the POS rejects the duplicate. This mechanism eliminates double usage even with network errors.
Organizing Mass Distribution
The POST /campaigns/{id}/distribute request places a task in the queue. Workers generate passes in batches of 500, store links in the database. Users receive a push with a "Add to Wallet" button as they are generated. Each coupon has a unique serialNumber and authenticationToken. You cannot distribute identical passes to different users — update systems will conflict. Average generation time for 10,000 coupons is 15–20 seconds with 10 workers.
Why Asynchronous Generation Is Faster Than Synchronous
| Parameter | Synchronous | Asynchronous (queue) |
|---|---|---|
| Generation time for 1 coupon | < 1 sec | < 1 sec |
| API blocking at 1000 requests | Yes (100% blocking) | No (queue) |
| Max load (requests/sec) | 10–20 | 500+ |
| Delivery time for all links (10,000 coupons) | 10–15 minutes | 3–4 minutes |
| Risk of timeouts | High | Low |
Asynchronous generation is 2.5 times faster than synchronous for mass distribution. This allows handling peak loads without performance loss and yields a conversion boost.
Typical Integration Mistakes
- Not setting
voided: trueafter redemption — the coupon remains active, can be reused. Always send a push update. - Duplicate
serialNumber— if two users receive the same identifier, updates for one overwrite the other. Generate a unique ID for each. - Incorrect MIME type — the server must serve
application/vnd.apple.pkpass, otherwise iOS Safari won't suggest adding to Wallet. - Exceeding the location limit — more than 10 points of sale in one pass are ignored. Split into multiple coupons.
Step-by-Step Guide to Adding a Coupon to Wallet
- Obtain a Wallet certificate from Apple Developer Console. Passbook setup is straightforward.
- Generate
.pkpasswith a uniqueserialNumberand sign it. - Place the file on the server and send the user a link.
- Upon redemption, send push update with
voided: true.
Timeline and Scope
Integration of coupons into Apple Wallet takes 1 to 3 days depending on the complexity of mass distribution and geotargeting. Cost is calculated individually and starts from $1,500. Our team has over 5 years of experience in iOS development and has successfully completed over 10 Apple Wallet integration projects. We guarantee high-quality work and fast turnaround. Get a consultation — we will prepare a commercial proposal within a day.
Deliverables
What's included:
- Designing the pass structure for your coupons.
-
.pkpassgenerator with signing and push updates. - Redemption API with server-side validation.
- Documentation and API reference.
- Training session for your team.
- Test coupons and instructions for adding to Wallet.
- Post-launch support for one month.
- Access to source code (optional).
Pass Type Comparison Table (for reference)
| Pass Type | Purpose | Features |
|---|---|---|
| coupon | Discounts and promos | Perforated edge, offer field |
| storeCard | Loyalty card | No perforation, point accumulation |
| eventTicket | Event ticket | Date and time, QR for entry |
| boardingPass | Boarding pass | Class, seats |
For coupons we use the coupon type — it gives a visual style that users immediately recognize as a discount. Use premium coupons for VIP customers to boost loyalty. Coupon redemption via QR code is supported. iOS integration with Wallet is seamless. Contact us to discuss your scenarios. Estimate your project — we will select the optimal integration scenario, set up generation, and ensure correct operation of push updates.