Introduction

​

Patterns

​

Catalog Access

• Real-Time Catalog Access — Serve Snappy’s V3 catalog on demand with live API calls (and optional edge caching). No local mirror, no sync jobs.
• Bulk Catalog Export — Export the full catalog asynchronously and maintain a local copy. Queue a job, poll for completion, download the result.
• Swag Products Access — Access Snappy’s swag catalog. Requires the Snappy-Account-Id header and swag-specific filters.

​

Orders

• Place Orders — Place direct-fulfillment orders via POST /v3/orders. Covers address validation, idempotency, bulk placement, and the Swag variant.
• Track Order Fulfillment — Subscribe to order webhooks and respond to fulfillment lifecycle events. Covers all four event types and delivery status transitions.

​

Triggered Gifting

• Send Triggered Gifts — Create gifts programmatically with POST /v2/gifts. Covers bulk chunking, idempotency keys, and partial failure handling.
• Auto-claim Gifts as Fallback — Auto-claim a gift on the recipient’s behalf when they don’t claim it themselves. Covers the fallback flow, webhook cancellation, and 409 handling.

​

Recipes

• Build a Rewards Experience — An embedded marketplace: fetch the catalog, personalize a “For You” page, present products with variant selection, validate addresses, place orders, and track fulfillment.
• Triggered Gifting — Send gifts at scale programmatically: create gifts in bulk, handle idempotency, and manage the recipient experience through webhooks.

​

Migration

• Migrating V2 to V3 — Key differences between the V2 and V3 APIs: endpoint changes, pagination, authentication, and entity model updates.