Build against anyshop

1. 1. Create an API key: Dashboard → API keys. It is shown once. Keys carry full access or a picked set of scopes; a call outside a key’s scopes returns 403 missing_scope.
2. 2. Add a webhook endpoint: Dashboard → Webhooks. The signing secret is also shown once.
3. 3. Watch an order arrive: open one of your payment links, complete a purchase, and watch order.paid land on your endpoint.

curl https://anyshop.io/api/v1/products \
  -H "Authorization: Bearer ask_live_…"

const crypto = require('node:crypto');

// secret: the whsec_… value shown once when you created the endpoint
function verify(secret, headers, rawBody) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatureHeader = headers['webhook-signature'];
  if (!id || !timestamp || !signatureHeader) return false;

  // Reject replays: more than five minutes of clock skew is not skew.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64url');
  const expected =
    'v1,' + crypto.createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest('base64');

  // Several signatures arrive during a secret rotation — any match is valid.
  return signatureHeader.split(' ').some((candidate) => {
    const a = Buffer.from(candidate);
    const b = Buffer.from(expected);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

Sign over the raw request body, byte for byte: parsing and re-serializing JSON changes it and the signature will not match. During a secret rotation the header carries several signatures for 24 hours; accept the delivery if any of them verifies.

Payloads are snapshots taken when the event was created, and deliveries are not ordered. Treat the event as a signal, and read the resource back through the API when you need authoritative state.

Envelope

The order object

Line items

{
  "id": "evt_01kzsfzevmet5t2x52tdmrkths",
  "type": "order.paid",
  "created_at": "2026-08-12T09:15:22.000Z",
  "data": {
    "order": {
      "object": "order",
      "id": "ord_01kzsfzevnenhvmje0gaq3t9kr",
      "mode": "live",
      "status": "paid",
      "origin": "checkout",
      "checkout_session_id": "cs_01kzsfzevnecdrxee8gpjptt3a",
      "subscription_id": null,
      "currency": "EUR",
      "amount_subtotal": 4900,
      "amount_discount": 490,
      "amount_tax": 0,
      "amount_total": 4410,
      "amount_refunded": 0,
      "coupon": {
        "id": "cpn_01kzsfzevnejkb0dcgxc4e0ypd",
        "code": "LAUNCH10"
      },
      "buyer_country": "DE",
      "customer": {
        "id": "cust_01kzsfzevne699t1xd2gd4qh0k",
        "email": "buyer@example.com"
      },
      "metadata": {
        "your_user_id": "84213",
        "plan": "pro"
      },
      "items": [
        {
          "object": "order_item",
          "id": "oli_01kzsfzevnfzbve1kvyders7dj",
          "product_id": "prod_01kzsfzevnfh18rfjejnr4w3dy",
          "product_name": "Pro plan — 1 year",
          "pricing_type": "one_time",
          "quantity": 1,
          "unit_amount": 4900,
          "subtotal": 4900,
          "currency": "EUR"
        }
      ],
      "paid_at": "2026-08-12T09:15:22.000Z",
      "created_at": "2026-08-12T09:15:20.000Z"
    }
  }
}

• Delivery stops at 16 attempts or 72 hours after the event was created, whichever comes first.
• The clock is anchored to the EVENT, not to the delivery: redriving an old event does not restart it.
• Delays are lower bounds. A retry may land later than the schedule, never earlier.
• Respond 2xx within 20 seconds. Do the work asynchronously — a slow 200 counts as a timeout.
• An endpoint that exhausts a delivery having had zero successes since that event was created is disabled automatically, and we email the support address on your business profile.
• A manual redrive from the dashboard makes exactly one attempt and never retries.

• Buyers collect files and license keys from their receipt page in the portal. Entitlement is the order itself: while an order is paid (or partially refunded) and not disputed, its deliverables are reachable; a full refund or a dispute revokes access automatically, with no separate event.
• License keys are claimed atomically when the order is paid: one buyer per key, guaranteed at the database. A product whose key pool is empty refuses new checkouts (buyers see “product not available”), so a paid order without a key is a rare race the merchant is alerted to.
• Dynamic delivery: a product can carry a fulfillment URL. On every paid checkout, anyshop POSTs a signed JSON request there ({fulfillment_id, order_id, product_id, product_name, buyer_email, amount, currency, mode, metadata}), signed with the product’s own secret using the exact Standard Webhooks scheme described above. Whatever your endpoint returns with a 2xx (text, up to 64 KB) becomes the buyer’s deliverable, shown in their portal like a license key. Non-2xx and timeouts retry on the same published ladder; the buyer sees “being prepared” until then, and the merchant can retry a failed one from the order page.
• For YOUR system’s entitlements, nothing changes: act on order.paid and order.refunded exactly as before. anyshop’s built-in delivery is additive: use it, ignore it, or do both.

• Authenticate with `Authorization: Bearer ask_live_…` (or `ask_test_…`). The key determines both the store and the mode — there is no store parameter.
• A resource that belongs to another store returns 404, never 403. "That exists but is not yours" is an existence oracle, so we do not say it.
• Money is always an integer in minor units next to its currency. Never a float.
• Timestamps are ISO-8601 UTC. Ids carry their prefix (ord_, prod_, cust_…).
• Fields are added, never removed or retyped. A breaking change would come with a new version.
• 120 requests per minute per store; failed authentications are limited separately, by IP.

Endpoints

Errors

{
  "error": {
    "type": "invalid_request",
    "message": "Check the fields and try again.",
    "fields": [{ "path": "price_amount", "message": "Expected number" }]
  }
}

Orders are identical on the wire

order.paid, order.refunded, and every /v1 read look the same whichever processor charged. Keep keying on customer.id and deduplicating on the event id — nothing in your handler needs a processor branch.

Refund and dispute payloads carry both id families

Refunds and disputes on PayPal orders carry paypal_refund_id / paypal_dispute_id, and stripe_refund_id / stripe_dispute_id are null (and vice versa). Treat the ids as opaque evidence — the amounts and statuses are the contract.

PayPal subscriptions are billed by PayPal

The subscription wire object says source: "paypal". Renewals still arrive as subscription.renewed with an embedded order; payment failures arrive as subscription.past_due with a payment_error instead of a retry timeline (the retry cadence is PayPal’s); subscription.renewal_upcoming is not emitted for these.

Buyer consent is collected on the product page

For PayPal checkouts the EU withdrawal waiver is a checkbox on the storefront (PayPal’s hosted page collects no consent). The accepted text still lands on the order as withdrawal_waiver_text.