REST API

The DropLink API lets you create and manage checkout links programmatically. Available on the Growth plan.

• Base URL: https://droplink.zerglo.workers.dev/api/v1
• Machine-readable spec: OpenAPI 3.1

Authentication

Generate a token in Settings → API tokens inside the app. The plaintext token is shown once at creation — we store only a SHA-256 hash.

Send it on every request:

Authorization: Bearer <your token>

Tokens carry scopes chosen at creation: links:read, links:write, analytics:read. A request whose scope is missing returns 403.

Response envelope

Every response is JSON:

{ "success": true, "data": { ... }, "pagination": { "total": 42, "limit": 20, "offset": 0 } }

Errors:

{ "success": false, "error": "Link limit reached for your plan" }

Endpoints

List links — GET /links

Query params: limit (default 20, max 100), offset, status (active, paused, archived, or all — default all).

curl -H "Authorization: Bearer $TOKEN" \
  "https://droplink.zerglo.workers.dev/api/v1/links?status=active&limit=10"

Returns an array of link objects, each with its items (products) and config (discount/UTM/note).

Create a link — POST /links

curl -X POST https://droplink.zerglo.workers.dev/api/v1/links \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer drop",
    "items": [{
      "productId": "gid://shopify/Product/123",
      "variantId": "gid://shopify/ProductVariant/456",
      "quantity": 1,
      "sellingPlanId": "gid://shopify/SellingPlan/789"
    }],
    "discountCode": "SAVE10",
    "utmSource": "newsletter"
  }'

Each item requires productId, variantId, and quantity. Optional: productTitle, productImageUrl, sellingPlanId, sellingPlanName — include a sellingPlanId to make it a subscription link. Optional top-level fields: discountCode, utmSource, utmMedium, utmCampaign, customNote.

Plan rules are enforced exactly as in the dashboard: discounts/UTMs/notes and multiple items need Starter+, and the active-link limit applies (409 when exceeded).

Get a link — GET /links/:id

Update a link — PUT /links/:id

Send any subset of the create fields; omitted fields keep their current values. isActive: true|false activates or pauses the link.

Delete a link — DELETE /links/:id

Permanently removes the link and its analytics history. Prefer pausing (isActive: false) if you want to keep the data.

Analytics overview — GET /analytics/overview

{
  "totalClicks": 1240,
  "uniqueClicks": 980,
  "totalConversions": 87,
  "totalRevenue": 4311.5,
  "period": "all_time"
}

totalConversions/totalRevenue are null on plans without conversion tracking.

Per-link analytics — GET /analytics/links/:id

Optional from and to query params (ISO dates) filter the window.

Fair use

There's no hard request quota today; aggressive polling may be throttled. Prefer webhooks over polling for real-time updates.