QrioTagQrioTag Docs
API Reference

Orders API

Browse products, place orders, manage Stripe checkout, subscriptions, billing, invoices, and refunds.

The Orders API handles the QrioTag shop — browsing products, placing orders, processing payments through Stripe, and managing subscriptions.

List Products

GET /api/v1/orders/products — Public

List Orders

GET /api/v1/orders — Required

Create Order

POST /api/v1/orders — Required

Checkout

POST /api/v1/orders/:id/checkout — Required

Subscribe

POST /api/v1/orders/subscribe — Required

Billing

GET /api/v1/orders/billing — Required

List Orders

Retrieve all orders for the authenticated user.

GET /api/v1/orders — Auth: Required

Query parameters

ParameterTypeDefaultDescription
pageinteger1Page number
limitinteger10Items per page
  curl "https://api.qriotag.global/api/v1/orders?page=1&limit=10" \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": [
    {
      "id": "ord_abc123",
      "status": "COMPLETED",
      "total": 29.99,
      "currency": "USD",
      "items": [
        {
          "productId": "prod_001",
          "name": "QrioTag Keychain (3-Pack)",
          "quantity": 1,
          "price": 29.99
        }
      ],
      "createdAt": "2025-05-20T10:00:00.000Z"
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "totalPages": 1
  }
}

Get Order

Retrieve a single order by ID.

GET /api/v1/orders/:id — Auth: Required

  curl https://api.qriotag.global/api/v1/orders/ord_abc123 \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "id": "ord_abc123",
    "status": "COMPLETED",
    "total": 29.99,
    "currency": "USD",
    "items": [
      {
        "productId": "prod_001",
        "name": "QrioTag Keychain (3-Pack)",
        "quantity": 1,
        "price": 29.99,
        "variant": "Blue"
      }
    ],
    "shippingAddress": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "stripeSessionId": "cs_live_abc123...",
    "createdAt": "2025-05-20T10:00:00.000Z",
    "updatedAt": "2025-05-21T14:00:00.000Z"
  }
}

Create Order

Create a new order with selected products.

POST /api/v1/orders — Auth: Required

Request body

FieldTypeRequiredDescription
itemsarrayYesArray of order items
items[].productIdstringYesProduct ID
items[].quantityintegerYesQuantity
items[].variantIdstringNoProduct variant ID
  curl -X POST https://api.qriotag.global/api/v1/orders \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "items": [
        { "productId": "prod_001", "quantity": 2 },
        { "productId": "prod_003", "quantity": 1, "variantId": "var_blue" }
      ]
    }'

Response

{
  "success": true,
  "data": {
    "id": "ord_def456",
    "status": "PENDING",
    "total": 74.97,
    "currency": "USD",
    "items": [
      { "productId": "prod_001", "name": "QrioTag Keychain (3-Pack)", "quantity": 2, "price": 29.99 },
      { "productId": "prod_003", "name": "QrioTag Pet Tag", "quantity": 1, "price": 14.99 }
    ]
  }
}

Checkout Order

Generate a Stripe checkout session URL for payment.

POST /api/v1/orders/:id/checkout — Auth: Required

  curl -X POST https://api.qriotag.global/api/v1/orders/ord_def456/checkout \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_live_abc123...",
    "sessionId": "cs_live_abc123..."
  }
}

Payment flow

Redirect the user to checkoutUrl. After payment, Stripe sends a webhook to confirm the order. The order status updates to COMPLETED automatically.

Get Invoice

Download the HTML invoice for a completed order.

GET /api/v1/orders/:id/invoice — Auth: Required

  curl https://api.qriotag.global/api/v1/orders/ord_abc123/invoice \
    -H "Authorization: Bearer <token>" \
    -o invoice.html

Response

Returns text/html content.

Cancel Order

Cancel a pending order before payment.

POST /api/v1/orders/:id/cancel — Auth: Required

  curl -X POST https://api.qriotag.global/api/v1/orders/ord_def456/cancel \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "id": "ord_def456",
    "status": "CANCELLED",
    "message": "Order cancelled successfully"
  }
}

Refund Order

Issue a refund for a completed order.

Admin only

This endpoint requires admin privileges.

POST /api/v1/orders/:id/refund — Auth: Required (Admin)

  curl -X POST https://api.qriotag.global/api/v1/orders/ord_abc123/refund \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "id": "ord_abc123",
    "status": "REFUNDED",
    "refundId": "re_stripe_abc123"
  }
}

List Products

Browse available QrioTag products.

GET /api/v1/orders/products — Auth: None (public)

Rate limited to 30 requests per minute per IP.

Query parameters

ParameterTypeDefaultDescription
pageinteger1Page number
limitinteger10Items per page
  curl "https://api.qriotag.global/api/v1/orders/products?page=1&limit=20"

Response

{
  "success": true,
  "data": [
    {
      "id": "prod_001",
      "name": "QrioTag Keychain (3-Pack)",
      "slug": "qriotag-keychain-3pack",
      "description": "Three durable keychain QrioTags",
      "price": 29.99,
      "currency": "USD",
      "images": ["https://cdn.qriotag.com/products/keychain.jpg"],
      "variants": [
        { "id": "var_blue", "name": "Blue", "price": 29.99 },
        { "id": "var_red", "name": "Red", "price": 29.99 }
      ],
      "inStock": true
    }
  ],
  "meta": {
    "total": 8,
    "page": 1,
    "totalPages": 1
  }
}

Get Product by Slug

Retrieve a single product by its URL slug.

GET /api/v1/orders/products/:slug — Auth: None (public)

  curl https://api.qriotag.global/api/v1/orders/products/qriotag-keychain-3pack

Response

{
  "success": true,
  "data": {
    "id": "prod_001",
    "name": "QrioTag Keychain (3-Pack)",
    "slug": "qriotag-keychain-3pack",
    "description": "Three durable keychain QrioTags with NFC capability",
    "price": 29.99,
    "currency": "USD",
    "images": ["https://cdn.qriotag.com/products/keychain.jpg"],
    "variants": [],
    "inStock": true
  }
}

Subscribe

Start a subscription plan.

POST /api/v1/orders/subscribe — Auth: Required

Request body

FieldTypeRequiredDescription
tierstringYesSubscription tier: PRO (only value accepted)
  curl -X POST https://api.qriotag.global/api/v1/orders/subscribe \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{ "tier": "PRO" }'

Response

{
  "success": true,
  "data": {
    "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_live_sub...",
    "sessionId": "cs_live_sub..."
  }
}

Cancel Subscription

Cancel the current subscription.

DELETE /api/v1/orders/subscribe — Auth: Required

  curl -X DELETE https://api.qriotag.global/api/v1/orders/subscribe \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "message": "Subscription cancelled. Access continues until the end of the billing period.",
    "endsAt": "2025-07-15T00:00:00.000Z"
  }
}

Get Billing Info

Retrieve current billing and subscription details.

GET /api/v1/orders/billing — Auth: Required

  curl https://api.qriotag.global/api/v1/orders/billing \
    -H "Authorization: Bearer <token>"

Response

{
  "success": true,
  "data": {
    "subscription": {
      "tier": "PRO",
      "status": "ACTIVE",
      "currentPeriodEnd": "2025-07-15T00:00:00.000Z"
    },
    "paymentMethod": {
      "brand": "visa",
      "last4": "4242"
    },
    "invoices": [
      {
        "id": "inv_001",
        "amount": 9.99,
        "status": "paid",
        "date": "2025-06-15T00:00:00.000Z"
      }
    ]
  }
}

Was this page helpful?

Edit on GitHub

Notifications API

Previous Page

Emergency API

Next Page

On this page

List OrdersQuery parametersResponseGet OrderResponseCreate OrderRequest bodyResponseCheckout OrderResponseGet InvoiceResponseCancel OrderResponseRefund OrderResponseList ProductsQuery parametersResponseGet Product by SlugResponseSubscribeRequest bodyResponseCancel SubscriptionResponseGet Billing InfoResponse
Orders API | QrioTag Docs