Events API

POST https://www.referly.so/api/atlas/v1/events

​

Endpoint and authentication

• The store’s Atlas API token, generated in Store settings under Tracking and connection, API token. It starts with atl_ and is shown once. This is the token to use from your own server and from Zapier or Make.
• A Referly REST API key or Zapier API key of the program the store belongs to. Atlas resolves the store from the key.

​

Request body

{
  "events": [
    { "event": "Lead", "id": "lead_7f3a", "email": "jane@example.com" },
    { "event": "Purchase", "id": "1001", "value": 129, "currency": "USD", "email": "jane@example.com" }
  ]
}

​

Responses and errors

{
  "ok": true,
  "results": [
    { "event": "Lead", "id": "lead_7f3a", "status": "recorded", "conversionId": "cnv_8a1f" },
    { "event": "Purchase", "id": "1001", "status": "merged", "orderId": "ord_3c77" }
  ]
}

​

Rate limits

​

Duplicates and merging

• Purchase: the order id (id) is the key. A second Purchase with the same id is merged into the first (merged). A purchase the tracker recorded in the browser waits 60 seconds for your server’s copy and takes its value and time.
• Lead, CompleteRegistration, StartTrial, Subscribe: the key is id, or userId or email when id is missing. On top of that, the same person and the same type within 24 hours merge into one conversion, whatever the ids: the server copy wins the value and the time. A conversion first seen in the browser waits 60 seconds for the server copy.

​

Examples

curl -X POST https://www.referly.so/api/atlas/v1/events \
  -H "Authorization: Bearer atl_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "StartTrial",
    "id": "sub_1Q8xVe",
    "userId": "user_123",
    "email": "jane@example.com",
    "value": 0,
    "currency": "USD",
    "occurredAt": "2026-10-21T09:30:00Z"
  }'

const res = await fetch("https://www.referly.so/api/atlas/v1/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ATLAS_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    events: [
      {
        event: "CompleteRegistration",
        id: user.id,
        email: user.email,
        firstName: user.firstName,
        visitorId: user.referlyVisitorId, // saved from referlyAtlas.getVisitorId() at sign up
        ip: req.ip,
        userAgent: req.headers["user-agent"],
      },
      {
        event: "Purchase",
        id: order.id,
        value: order.total,
        currency: order.currency,
        email: user.email,
        userId: user.id,
      },
    ],
  }),
});

const { ok, results } = await res.json();
for (const r of results) {
  if (r.status === "rejected") console.error(r.event, r.error);
}

import os
import requests

res = requests.post(
    "https://www.referly.so/api/atlas/v1/events",
    headers={"Authorization": f"Bearer {os.environ['ATLAS_API_TOKEN']}"},
    json={"event": "Lead", "id": lead.id, "email": lead.email, "details": {"plan": "Pro"}},
)
for r in res.json()["results"]:
    print(r["status"], r.get("error"))

​

Zapier

• URL: https://www.referly.so/api/atlas/v1/events
• Payload Type: json
• Data: one row per field, for example event set to Lead, id mapped to the record id from your trigger, email mapped to the email from your trigger, then value and currency when you have them.
• Headers: Authorization set to Bearer atl_YOUR_TOKEN, and Content-Type set to application/json.

​

Make

• URL: https://www.referly.so/api/atlas/v1/events
• Method: POST
• Headers: Authorization with the value Bearer atl_YOUR_TOKEN
• Body type: Raw, with Content type JSON (application/json)
• Request content: the JSON event, mapping fields from the previous module, for example the record id into id and the email into email.