Embedded Marketplace (Direct fulfillment)

“Your platform displays the catalog and collects the order, Snappy handles the fulfillment.” Use this recipe when you want to embed Snappy’s product catalog inside your own platform and let your users select items directly. Your system handles the UI, collects the shipping address, and places the order. Snappy handles fulfillment. Common use cases include:

Swag stores
Procurement portals
Rewards redemption platforms

Overview

In this model, your system handles catalog display, product selection, and address collection. Once your user has made their selection, you pass all the required information to Snappy in two sequential API calls and Snappy processes the order immediately. Your integration only needs to handle three things: retrieving products, placing orders, and listening for status updates via Webhooks.

Setting Up Your API Client

Before making any API calls, initialize your HTTP client with your API key. This setup is used throughout all steps below.

const axios = require('axios');

const snappyClient = axios.create({
  baseURL: 'https://api.snappy.com/public-api/v2',
  headers: {
    'X-Api-Key': process.env.SNAPPY_API_KEY,
    'Content-Type': 'application/json'
  }
});

import requests
import os

session = requests.Session()
session.headers.update({
  'X-Api-Key': os.environ.get('SNAPPY_API_KEY'),
  'Content-Type': 'application/json'
})

BASE_URL = 'https://api.snappy.com/public-api/v2'

Store your API key as an environment variable - never hardcode it in your source code.

Step 1: Identify your Campaign

Every gift is created within a Campaign. Before making any API calls, you need the id of the Campaign you want to send under. If you haven’t created a Campaign yet, you can do so either through the Snappy Dashboard or via the API using POST /campaigns. When created via the API, the Campaign is automatically assigned the Account’s default Billing Method.

Every Campaign requires a default Collection or Product to be configured. In the Embedded Marketplace model, this is not used - you will specify the exact product and variant when placing the order.

Endpoint: GET /campaigns - use this to retrieve your Campaign list and confirm the correct id.

async function getCampaigns() {
  const response = await snappyClient.get('/campaigns');
  const campaigns = response.data.results;
  console.log('Available campaigns:', campaigns);
  return campaigns;
}

def get_campaigns():
    response = session.get(f'{BASE_URL}/campaigns')
    response.raise_for_status()
    campaigns = response.json()['results']
    print('Available campaigns:', campaigns)
    return campaigns

→ For the full list of Campaign configuration options, see the API Reference.

Step 2: Retrieve and Display the Product Catalog

Retrieve the available products and display them in your own platform UI. Call GET /products to return the full product catalog available to your account. Each Product object contains a variants array representing the available options (e.g. size, color). Your UI should present these variants to the user so they can make their selection. The response includes full product details. The fields most relevant to your UI are id, name, and the variants array. For example:

{
  "id": "prd_12345",
  "name": "Premium Hoodie",
  "variants": [
    { "id": "var_001", "size": "M", "color": "Navy" },
    { "id": "var_002", "size": "L", "color": "Navy" },
    { "id": "var_003", "size": "M", "color": "Black" }
  ]
}

Use Field Projection to optimize performance and reduce payload size. See Request & Response Standards.

→ For the full product object schema, see the API Reference.

Step 3: User Selects an Item

This step happens within your platform - no API calls required yet. Your user browses the catalog you’ve displayed, selects their preferred item and variant, and provides their shipping address if you don’t already have it on file. Once you have all three pieces of information - Campaign ID, Variant ID, and shipping address - you’re ready to place the order.

We recommend validating the shipping address before placing the order to reduce fulfillment failures. See Validate Order Address.

Step 4: Create the Gift

Call POST /gifts with your Campaign ID and recipient details. This creates the Gift object and returns a giftId which you’ll need in the next step.

async function createGift(campaignId, recipient) {
  const response = await snappyClient.post('/gifts', {
    campaignId: campaignId,
    recipients: [
      {
        firstname: recipient.firstname,
        lastname: recipient.lastname,
        email: recipient.email,
        key: recipient.key
      }
    ]
  });

  const gift = response.data.results[0];
  console.log('Gift created:', gift.id);
  return gift.id; // Store this - needed for the claim step
}

// Example usage
const giftId = await createGift('cmp_12345', {
  firstname: 'John',
  lastname: 'Smith',
  email: 'john@example.com',
  key: 'john-smith-onboarding-swag'
});

def create_gift(campaign_id, recipient):
    response = session.post(f'{BASE_URL}/gifts', json={
        'campaignId': campaign_id,
        'recipients': [
            {
                'firstname': recipient['firstname'],
                'lastname': recipient['lastname'],
                'email': recipient['email'],
                'key': recipient['key']
            }
        ]
    })
    response.raise_for_status()
    gift = response.json()['results'][0]
    print(f"Gift created: {gift['id']}")
    return gift['id']  # Store this - needed for the claim step

# Example usage
gift_id = create_gift('cmp_12345', {
    'firstname': 'John',
    'lastname': 'Smith',
    'email': 'john@example.com',
    'key': 'john-smith-onboarding-swag'
})

{
  "campaignId": "cmp_12345",
  "recipients": [
    {
      "firstname": "John",
      "lastname": "Smith",
      "email": "john@example.com",
      "key": "john-smith-onboarding-swag"
    }
  ]
}

A successful response returns the Gift object including the giftId. Note the giftId - you will need it in the next step.

In this approach the Gift is created without a variant or shipping address. The recipient will not receive a notification - the Claim step immediately completes the order.

Include a unique key for every recipient to prevent duplicate gifts. See Duplicate Detection.

Step 5: Claim the Gift

Call POST /gifts//claim with the selected Variant ID and the recipient’s shipping address. This finalizes the Gift and places the Order immediately.

async function claimGift(giftId, variantId, shippingAddress) {
  const response = await snappyClient.post(`/gifts/{giftId}/claim`, {
    variantId: variantId,
    shippingAddress: shippingAddress
  });

  const order = response.data;
  console.log('Order placed:', order.id);
  console.log('Order status:', order.status);
  return order;
}

// Example usage
claimGift(giftId, 'var_001', {
  line1: '123 Main Street',
  city: 'New York',
  state: 'NY',
  zip: '10001',
  country: 'US'
});

def claim_gift(gift_id, variant_id, shipping_address):
    response = session.post(f'{BASE_URL}/gifts/{gift_id}/claim', json={
        'variantId': variant_id,
        'shippingAddress': shipping_address
    })
    response.raise_for_status()
    order = response.json()
    print(f"Order placed: {order['id']}")
    print(f"Order status: {order['status']}")
    return order

# Example usage
claim_gift(gift_id, 'var_001', {
    'line1': '123 Main Street',
    'city': 'New York',
    'state': 'NY',
    'zip': '10001',
    'country': 'US'
})

{
  "variantId": "var_001",
  "shippingAddress": {
    "line1": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US"
  }
}

Step 6: Track Fulfillment via Webhooks

Listen for Webhook events to track fulfillment progress. Key events to handle:

Event	Meaning
`gift-delivery-status-changed` (status: `orderReceived`)	Order has been placed with the fulfillment partner
`gift-delivery-status-changed` (status: `inTransit`)	Product has shipped
`gift-delivery-status-changed` (status: `delivered`)	Product has reached its final destination

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/snappy', (req, res) => {
  const { webhookData, eventData } = req.body;

  if (webhookData.eventType === 'gift-delivery-status-changed') {
    const { giftId, deliveryStatus } = eventData;
    console.log(`Delivery update for gift ${giftId}: ${deliveryStatus}`);

    switch (deliveryStatus) {
      case 'orderReceived':
        console.log('Order confirmed with fulfillment partner');
        break;
      case 'inTransit':
        console.log('Order shipped');
        break;
      case 'delivered':
        console.log('Order delivered successfully');
        break;
    }
  }

  if (webhookData.eventType === 'order-canceled') {
    console.log(`Order canceled for gift ${eventData.giftId}`);
    console.log('Reason:', eventData.cancelReason);
    // Handle cancellation - notify sender, offer replacement etc.
  }

  if (webhookData.eventType === 'order-out-of-stock') {
    console.log(`Out of stock for gift ${eventData.giftId}`);
    // Handle out of stock - offer alternative variant etc.
  }

  res.status(200).send('OK');
});

app.listen(3000, () => console.log('Webhook listener running on port 3000'));

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/snappy', methods=['POST'])
def handle_webhook():
    payload = request.json
    webhook_data = payload['webhookData']
    event_data = payload['eventData']
    event_type = webhook_data['eventType']

    if event_type == 'gift-delivery-status-changed':
        gift_id = event_data['giftId']
        delivery_status = event_data['deliveryStatus']
        print(f"Delivery update for gift {gift_id}: {delivery_status}")

        if delivery_status == 'orderReceived':
            print('Order confirmed with fulfillment partner')
        elif delivery_status == 'inTransit':
            print('Order shipped')
        elif delivery_status == 'delivered':
            print('Order delivered successfully')

    elif event_type == 'order-canceled':
        print(f"Order canceled for gift {event_data['giftId']}")
        print(f"Reason: {event_data.get('cancelReason')}")
        # Handle cancellation - notify sender, offer replacement etc.

    elif event_type == 'order-out-of-stock':
        print(f"Out of stock for gift {event_data['giftId']}")
        # Handle out of stock - offer alternative variant etc.

    return jsonify({'status': 'ok'}), 200

if __name__ == '__main__':
    app.run(port=3000)

→ Configure your webhook listener - see Webhooks: Overview & Setup.

Full Flow Summary

GET /campaigns → retrieve your campaign ID
GET /products → retrieve catalog to display in your platform
[User selects item, variant, and provides shipping address]
POST /gifts → create the gift, get back the giftId
POST /gifts/claim → claim the gift with variant and shipping address
Webhooks → track order fulfillment and delivery

Welcome

Start building

Our API Standards

Migrating to V3

Webhooks & Events

Embedded Marketplace (Direct fulfillment)

Overview

Setting Up Your API Client

Step 1: Identify your Campaign

Step 2: Retrieve and Display the Product Catalog

Step 3: User Selects an Item

Step 4: Create the Gift

Step 5: Claim the Gift

Step 6: Track Fulfillment via Webhooks

Full Flow Summary

​Overview

​Setting Up Your API Client

​Step 1: Identify your Campaign

​Step 2: Retrieve and Display the Product Catalog

​Step 3: User Selects an Item

​Step 4: Create the Gift

​Step 5: Claim the Gift

​Step 6: Track Fulfillment via Webhooks

​Full Flow Summary

Overview

Setting Up Your API Client

Step 1: Identify your Campaign

Step 2: Retrieve and Display the Product Catalog

Step 3: User Selects an Item

Step 4: Create the Gift

Step 5: Claim the Gift

Step 6: Track Fulfillment via Webhooks

Full Flow Summary