Sweepsy API v1

Authentication

Send the public key as a Bearer token, plus the timestamp and signature headers. The signed string is the timestamp, a single dot, and the exact raw JSON body. Rotate a key from API keys if it becomes public.

Manage API keys

Quickstart

1. Create or copy an API key.
2. Connect a development store.
3. Send a signed test entry from your server.
4. Check the result on Entries.

Endpoints

Track is the browser call from a thank-you page. It is not the trusted path. Brands that need a hard guarantee use the signed entries route. Widget configuration and events carry no participant data. Lookup returns that person’s counts only, and does not reveal a winner before the draw is published.

Entries

Create an entry only after the related order is final. Required fields are orderId and email. campaign is optional and selects the live campaign by slug. Optional fields are firstName, lastName, phone, country, region, customerId, amount, netAmount, currency, marketingOptIn, and items.

netAmount is product revenue after discounts, excluding tax and shipping. Omit it and the order is recorded but left out of billing. A gift-card line item sets giftCard so that amount does not earn tickets.

A successful response includes ok, created, entryId, tickets, ticketRange, totalTickets, and campaign. A duplicate order id returns 409.

Rate limits

Limits are requests per IP for the window below. They are not a priced tier. A limited request returns 429 with error rate_limited.

Campaigns

A campaign defines its dates, markets, prize, entry rules, and draw schedule. Use the campaign slug in server requests.

Winners and draw

Sweepsy runs the verified draw from valid entries. Read winner status in the workspace. Do not infer a winner before the draw completes.

Audience

Audience data belongs to the connected brand. Use consented customer fields only. Do not send payment data.

Webhooks and signatures

Shopify, Stripe, and WooCommerce each have a webhook path under /api/webhooks. Use the endpoint shown on Webhooks. Verify every signature. Return success only after your server stores the event.

View webhook endpoints

Shopify connection

Connect Shopify from Store connection. Connected stores open the embedded Shopify app from the workspace.

Errors

Retry temporary server errors with backoff. Fix authentication and validation errors before retrying. Delivery logs are not available in this workspace yet.

Features

Agents

Use the Sweepsy MCP guide to connect Codex, Claude, Cursor, or another MCP client. Grant only the access required for the task.

Available tools cover brand identity, campaigns, entry rules, prize tiers, entry simulation, analytics, widgets, draws, and winners.

Workflow prompts help an agent plan a sweepstake, build a custom pop-up, report on a campaign, and check launch readiness.

Reference resources describe ticket rules, storefront widget requirements, territory rules, and product limits.

Examples

cURL

TIMESTAMP=$(date +%s)
BODY='{"campaign":"your-campaign","orderId":"ORDER-1234","email":"buyer@example.com"}'
SIGNATURE=$(printf '%s.%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$SWEEPSY_API_SECRET" | awk '{print $2}')
curl -X POST https://trysweepsy.com/api/v1/entries \
  -H "Authorization: Bearer $SWEEPSY_PUBLIC_KEY" \
  -H "X-Sweepy-Timestamp: $TIMESTAMP" \
  -H "X-Sweepy-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d "$BODY"

TypeScript

import { createHmac } from "node:crypto";

const body = JSON.stringify({
  campaign: "your-campaign",
  orderId: "ORDER-1234",
  email: "buyer@example.com",
});
const timestamp = Math.floor(Date.now() / 1000).toString();
// Your server's own settings. Never ship the secret key to a browser.
const { SWEEPSY_API_SECRET, SWEEPSY_PUBLIC_KEY } = process.env;
const signature = createHmac("sha256", SWEEPSY_API_SECRET ?? "")
  .update(timestamp + "." + body)
  .digest("hex");

const response = await fetch("https://trysweepsy.com/api/v1/entries", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + SWEEPSY_PUBLIC_KEY,
    "X-Sweepy-Timestamp": timestamp,
    "X-Sweepy-Signature": signature,
    "Content-Type": "application/json",
  },
  body,
});

if (!response.ok) throw new Error("Sweepsy entry request failed");