Payment & Order Flow
The complete order lifecycle — from browsing the shop to Stripe checkout, webhook processing, shipping, delivery, and tag activation.
What this page covers
This page walks through the entire payment and order flow, from the moment a user adds an item to their cart to when they activate the tags they receive.
Flow Overview
Browse Shop → Add to Cart → Create Order (PENDING)
→ Stripe Checkout → Payment
→ Webhook → Order CONFIRMED
→ Admin Ships → SHIPPED
→ Delivered → DELIVERED
→ User Activates TagsStep 1: Browse the Shop
The user visits the QrioTag shop at /shop and browses available products. Products are loaded from the API.
Step 2: Create an Order
The user selects a product, chooses a variant (color, NFC option), sets a quantity, and proceeds to checkout. The web app creates an order.
The order is now in PENDING status.
Step 3: Stripe Checkout
The user is redirected to Stripe's hosted checkout page to enter payment details.
The web app redirects the user to checkoutUrl. On Stripe's page, the user enters:
- Card number
- Expiration date
- CVC
- Billing address (if different from shipping)
After the user completes payment, Stripe redirects them back to the QrioTag website (the success URL).
Stripe handles all card data
QrioTag never sees or stores credit card numbers. All payment processing happens on Stripe's servers. This means QrioTag does not need PCI compliance for card handling.
Step 4: Webhook Processing
After payment succeeds, Stripe sends a webhook event to the QrioTag API. This happens in the background — the user does not see it.
Step 5: Confirmation Email
The BullMQ worker picks up the email job and sends the order confirmation.
What the user receives:
Subject: Order Confirmed - QRIO-20260408-A3K9M
Hi Jane,
Your QrioTag order has been confirmed!
Order: QRIO-20260408-A3K9M
Date: April 8, 2026
Items:
2x QrioTag Pet (Blue, NFC) — $19.99 each
Subtotal: $39.98
Shipping: $4.99
Tax: $4.00
Total: $48.97
We will notify you when your order ships.
— The QrioTag TeamStep 6: Admin Ships the Order
An admin opens the QrioTag admin panel, goes to Orders, finds the order, and marks it as shipped. They enter a tracking number.
Step 7: Shipping Notification
What the user receives:
Subject: Your QrioTag Order Has Shipped!
Hi Jane,
Your order QRIO-20260408-A3K9M is on its way!
Tracking: 1Z999AA10123456784 (UPS)
Track your package: https://ups.com/track?num=1Z999AA10123456784
Estimated delivery: April 12, 2026
When your tags arrive, scan them or enter the QrioTag ID
to activate them.
— The QrioTag TeamStep 8: Order Delivered
When the package is delivered, the order status is updated to DELIVERED (either automatically via tracking integration or manually by admin).
Step 9: User Activates Tags
The user receives the physical tags. Each tag has a QrioTag ID printed on it (e.g., QRIO-A3K9M2X7). The user scans each tag or enters the ID to activate it.
See Tag Lifecycle for the activation process.
Order Status Flow
PENDING → CONFIRMED → PROCESSING → SHIPPED → DELIVERED
↓
CANCELLED
↓
REFUNDED| Status | Description |
|---|---|
| PENDING | Order created, awaiting payment |
| CONFIRMED | Payment received, order confirmed |
| PROCESSING | Order is being prepared for shipment |
| SHIPPED | Order has been shipped with tracking number |
| DELIVERED | Order has been delivered |
| CANCELLED | Order was cancelled before shipping |
| REFUNDED | Payment was refunded after cancellation or return |
Payment Status Flow
| Status | Description |
|---|---|
| PENDING | Awaiting payment |
| PROCESSING | Payment is being processed by Stripe |
| COMPLETED | Payment successful |
| FAILED | Payment declined or errored |
| REFUNDED | Full refund issued |
| PARTIALLY_REFUNDED | Partial refund issued |
Cancelling an Order
Users can cancel an order before it ships.
POST /api/v1/orders/ord_uuid_1/cancel
Authorization: Bearer <token>If the order has already been paid, the system initiates a refund through Stripe.
Cannot cancel after shipping
Once an order has been marked as SHIPPED, it cannot be cancelled through the API. Contact support for returns and refunds on shipped orders.
Viewing Order History
Users can view all their orders:
GET /api/v1/orders
Authorization: Bearer <token>And view a printable invoice for any order:
GET /api/v1/orders/ord_uuid_1/invoice
Authorization: Bearer <token>
# Returns HTML invoice pageSubscriptions
QrioTag also supports recurring subscriptions for higher tag limits. The subscription flow uses Stripe as well.
Create a subscription:
POST /api/v1/orders/subscribe
Authorization: Bearer <token>
{
"tier": "PREMIUM"
}Cancel a subscription:
DELETE /api/v1/orders/subscribe
Authorization: Bearer <token>View billing info and payment history:
GET /api/v1/orders/billing
Authorization: Bearer <token>See What is QrioTag? for subscription tier details.
Was this page helpful?