Place Orders

The Place Orders pattern creates direct-fulfillment orders through the V3 orders API. A single POST /v3/orders call creates an order that Snappy fulfills and ships to the recipient — no two-step gift/claim flow required.

Prerequisites

API key with orders:create scope
A configured billing method under the ordering account
accountId, billingMethodId, and variantId ready

Physical vs digital variants

The shipping address requirement depends on the variant type:

Physical variants (variant.shippingRequired: true) — physical merchandise, apparel, experiences. Require the full shipping address: address1, city, provinceCode, postalCode, and countryCode. address2 is optional.
Digital variants (variant.shippingRequired: false) — gift cards, e-vouchers, and other card-based rewards. Require only countryCode, used for pricing and localization. No street/city/postal fields needed since there’s no physical delivery.

Snappy validates the address at runtime against the variant’s shippingRequired value — if you send only countryCode for a physical variant, the request is rejected.

Pre-flight: validate the address

For physical variants, run the recipient’s address through Snappy’s validation endpoint before placing the order. This catches undeliverable addresses before the order is created.

POST /v3/orders/addresses/validate

JavaScript

async function validateAddress(address) {
  const res = await fetch(`${SNAPPY}/v3/orders/addresses/validate`, {
    method: "POST",
    headers,
    body: JSON.stringify({ address }),
  });
  const result = await res.json();
  if (!result.valid) throw new Error(`Invalid address: ${result.message}`);
  return result.normalizedAddress;
}

For address autocomplete as the user types, use GET /v3/orders/addresses/autocomplete?filter[address]=...&filter[country]=US.

Skip address validation for digital variants — there’s no physical address to validate. countryCode alone is sufficient.

Place the order

POST /v3/orders

The account is scoped via header, not body:

JavaScript

async function placeOrder({ variantId, recipient, shippingAddress, idempotencyKey, tags, metadata }) {
  const res = await fetch(`${SNAPPY}/v3/orders`, {
    method: "POST",
    headers: {
      ...headers,
      "Snappy-Account-Id": process.env.SNAPPY_ACCOUNT_ID,
    },
    body: JSON.stringify({
      billingMethodId: process.env.SNAPPY_BILLING_METHOD_ID,
      variantId,
      recipient: {
        firstName: recipient.firstName,
        lastName: recipient.lastName,
        email: recipient.email,
        phone: recipient.phone,           // E.164, required
      },
      shippingAddress: {
        // For physical variants, include the full address:
        address1: shippingAddress.address1,
        address2: shippingAddress.address2,   // optional
        city: shippingAddress.city,
        provinceCode: shippingAddress.provinceCode,
        postalCode: shippingAddress.postalCode,
        countryCode: shippingAddress.countryCode,
        // For digital variants, `countryCode` alone is enough.
      },
      idempotencyKey,    // top-level, 1–120 chars, stable per order attempt
      tags,              // optional string[]: for your reporting and filtering
      metadata,          // optional object: roundtrips on status-changed webhooks
    }),
  });
  if (!res.ok) throw new Error(`Order failed ${res.status}: ${await res.text()}`);
  const { data } = await res.json();
  return data; // { id, status: "active", trackingLink }
}

Python

def place_order(variant_id, recipient, shipping_address, idempotency_key, tags=None, metadata=None):
    payload = {
        "billingMethodId": os.environ["SNAPPY_BILLING_METHOD_ID"],
        "variantId": variant_id,
        "recipient": {
            "firstName": recipient["first_name"],
            "lastName": recipient["last_name"],
            "email": recipient["email"],
            "phone": recipient["phone"],
        },
        # For physical variants, include the full address.
        # For digital variants (e.g. gift cards), send just {"countryCode": ...}.
        "shippingAddress": {
            "address1": shipping_address["address1"],
            "address2": shipping_address.get("address2"),
            "city": shipping_address["city"],
            "provinceCode": shipping_address["province_code"],
            "postalCode": shipping_address["postal_code"],
            "countryCode": shipping_address["country_code"],
        },
        "idempotencyKey": idempotency_key,
    }
    if tags:     payload["tags"] = tags
    if metadata: payload["metadata"] = metadata
    order_headers = {**headers, "Snappy-Account-Id": os.environ["SNAPPY_ACCOUNT_ID"]}
    res = requests.post(f"{SNAPPY}/v3/orders", headers=order_headers, json=payload)
    res.raise_for_status()
    return res.json()["data"]

Idempotency

The idempotencyKey (top-level field, 1–120 chars) makes retries safe. Sending the same key twice returns the original order — no duplicate, no double charge. Derive from stable identifiers:

JavaScript

// Good: stable per user per redemption event
const key = `user-${userId}-redemption-${redemptionId}`;
// Bad: changes on retry
const key = crypto.randomUUID();

Reuse the same key on all retry attempts for the same order.

Cancel an order

DELETE /v3/orders/{orderId}

Orders can only be canceled before fulfillment begins. Check status on the order before attempting cancellation.

Bulk placement

For placing multiple orders (e.g., a batch send), use bounded concurrency to stay within rate limits:

JavaScript

async function placeOrdersBatch(orderRequests, { concurrency = 5 } = {}) {
  const results = [];
  for (let i = 0; i < orderRequests.length; i += concurrency) {
    const batch = orderRequests.slice(i, i + concurrency);
    const batchResults = await Promise.all(batch.map(req => placeOrder(req)));
    results.push(...batchResults);
  }
  return results;
}

Swag orders

Swag orders use the same POST /v3/orders endpoint but require:

Snappy-Account-Id header (same as standard orders)
A variantId from a swag product (fetched with filter[catalog]=swag)

Swag variants are always physical, so send the full shipping address.

Failure table

HTTP	Meaning	Action
`422`	Insufficient funds	Alert your ops team; this is a billing issue
`422`	Variant not available in country	Offer alternatives via recommendations endpoint
`404`	Variant, billing method, or account not found	Config bug on your side — log and fix
`400`	Physical variant missing required address fields	Ensure the full address is sent when `variant.shippingRequired` is true
`400`	Invalid body (bad phone, malformed address)	Validate at form entry; catch before reaching this call
`409`	Duplicate order (same idempotency key, different body)	Check your key derivation — keys must be stable

Real-Time Catalog Access — fetching the variant ID and its shippingRequired before placing the order
Track Order Fulfillment — subscribe to webhooks after placing
Build a Rewards Experience — end-to-end recipe using this pattern

Introduction

Patterns

Recipes

Migration

Prerequisites

Physical vs digital variants

Pre-flight: validate the address

Place the order

Idempotency

Cancel an order

Bulk placement

Swag orders

Failure table

​Prerequisites

​Physical vs digital variants

​Pre-flight: validate the address

​Place the order

​Idempotency

​Cancel an order

​Bulk placement

​Swag orders

​Failure table

​Related

Prerequisites

Physical vs digital variants

Pre-flight: validate the address

Place the order

Idempotency

Cancel an order

Bulk placement

Swag orders

Failure table

Related