Orders API

Bring your own checkout — take the payment yourself and send the order to Snowcone for fulfillment.

When to use it

The hosted buy button and Shopify cover most stores with no integration. Reach for the Orders API when you already run your own checkout — Stripe or otherwise — and want to own the entire buying experience. You charge the customer, then POST the order; Snowcone prints and ships behind it.

Authenticate

Orders use a server-side API key — an sk_-prefixed secret, never the public Shop ID. Pass it in the x-api-key header (an Authorization: Bearer token works too). Writing orders needs the orders:add scope; reading them needs orders:read.

This key is a secret — keep it on your server. Anyone holding an orders:add key can place orders against your account.

Create an order

POST to /orders with the order under a top-level json field. Each line item names a product code, the variant and artworkUrl you rendered, and a quantity — the same values you used to build the mockup.

curl https://api.snowcone.app/orders \
  -X POST \
  -H "x-api-key: sk_your_orders_add_key" \
  -H "Content-Type: application/json" \
  -d '{
    "json": {
      "reference": "your-internal-order-123",
      "items": [
        {
          "productCode": "BEEB77",
          "variant": "L_BLK",
          "quantity": 1,
          "artworkUrl": "https://cdn.example.com/art.png"
        }
      ],
      "shipTo": {
        "name": "Ada Lovelace",
        "address1": "5 Bell Yard",
        "city": "London",
        "postalCode": "WC2A",
        "country": "GB"
      }
    }
  }'

// Server-side only — the sk_ key never reaches the browser.
const res = await fetch("https://api.snowcone.app/orders", {
  method: "POST",
  headers: {
    "x-api-key": process.env.SNOWCONE_ORDERS_KEY, // sk_… scoped orders:add
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    json: {
      reference: "your-internal-order-123",
      items: [
        { productCode: "BEEB77", variant: "L_BLK", quantity: 1, artworkUrl: "https://cdn.example.com/art.png" },
      ],
      shipTo: { name: "Ada Lovelace", address1: "5 Bell Yard", city: "London", postalCode: "WC2A", country: "GB" },
    },
  }),
});

const order = await res.json(); // { id, orderNumber, json, created_at, updated_at }

The order body is a flexible JSON blob — we store exactly what you send and return it on the order, alongside a generated id and orderNumber. Include your own reference so you can reconcile against your checkout.

Read it back

Fetch an order by id with an orders:read key to reconcile and track fulfillment.

bash

# Read an order back (orders:read scope).
curl https://api.snowcone.app/orders/<id> \
  -H "x-api-key: sk_your_orders_read_key"