REST API
The AdvocateLoop API lets you record claims, conversions, refunds, and visits with a simple HTTP POST — from your own backend, or from any tool that can send an HTTP request.
Prefer a no-code tool? See Zapier or Make; both send events through this same API.
What you’ll need
Before configuring anything, gather two values from your AdvocateLoop dashboard:
- API Key — found under Admin → Developers. Keep this secret; treat it like a password.
- Brand ID — found alongside the API key on the same page.
You’ll send both as HTTP headers on every request.
Plan tiers
Some event types are available on all plans; others require Premier:
| Event | Starter | Growth | Premier |
|---|---|---|---|
Conversions (/track/conversion) | ✓ | ✓ | ✓ |
Refunds (/track/refund) | ✓ | ✓ | ✓ |
Claims (/track/claim) | — | — | ✓ |
Visits (/track/visit) | — | — | ✓ |
If you send a Premier-only event type on a lower-tier plan, the API returns a 403 response with a clear message.
The basics
Every request follows the same shape:
- URL:
https://api.advocateloop.com/api/v1/track/<event>(e.g./api/v1/track/conversion) - Method:
POST - Headers:
Content-Type: application/jsonX-API-Key: <your API key>X-Brand-ID: <your brand ID>
- Body: JSON payload (shape depends on the event type — see below)
If the request succeeds, you’ll get a 200 response with a JSON body like:
{ "success": true, "data": { /* event-specific details */ } }If something goes wrong, you’ll get a 4xx response with an explanation:
{ "success": false, "error": "what went wrong" }Some outcomes aren’t errors in your request: AdvocateLoop understood it, and the answer is “no”. For example, a claim from a customer who isn’t eligible for the referral comes back as 200 with "success": false and an error code saying why. Those codes are listed under each event below.
Rate limits
Requests are rate limited per brand, per minute, across everything that uses your API key. The limits are set well above normal store and automation traffic.
Over the limit, you get a 429 with a Retry-After header and a retryAfter value (in seconds) in the body. Wait that long and send the request again:
{ "success": false, "error": "Too many requests", "message": "Rate limit exceeded. Please try again later.", "retryAfter": 12 }Your plan also includes a monthly number of API calls. Past it, requests return 429 with "error": "API call limit exceeded for this billing period" and a resets_at date. That one won’t clear by retrying; it resets with your billing period.
Recording a conversion
Use this when someone completes a purchase or other tracked outcome that should count against a referral.
Request
POST https://api.advocateloop.com/api/v1/track/conversionContent-Type: application/jsonX-API-Key: <your API key>X-Brand-ID: <your brand ID>
{ "customer_email": "buyer@example.com", "customer_name": "Jane Doe", "order_id": "ORD-12345", "order_total": 108.00, "tax": 8.00, "shipping": 10.00, "discount": 5.00, "referral_code": "JOHN123", "items": [ { "name": "Vitamin C Serum", "quantity": 2, "unit_price": 32.00, "sku": "VITC-30", "category_path": ["Skincare", "Serums"] }, { "name": "Gift Wrapping", "quantity": 1, "unit_price": 4.00 } ]}Fields
| Field | Required | Notes |
|---|---|---|
customer_email | yes | Customer’s email address |
order_total | yes | What the customer actually paid — items + tax + shipping, after discounts |
tax, shipping, discount | yes | Use 0 if not applicable |
customer_name | no | Customer’s name |
order_id | no | Your internal order identifier, for cross-referencing |
referral_code | no | Include if you know it |
items | no | Line items in the order. Fields below. |
Each entry in items:
| Field | Required | Notes |
|---|---|---|
name | yes | Item or service name |
quantity | no | Units. Defaults to 1 |
unit_price | no | Price per unit. Or send line_total for the line’s total |
sku | no | SKU, plan code, or service code |
category_path | no | Ordered category path, top level first — e.g. ["Skincare", "Serums"] |
image_url | no | Image URL for the item |
Responses
| Response | Meaning |
|---|---|
200, data.status: "attributed" | Recorded and credited to the advocate |
200, data.status: "already_tracked" | This order_id was already recorded; nothing was counted twice |
200, data.status: "not_attributed" | Acknowledged but not stored: the customer has no open referral claim. If the sale was referred, it appears under Rewards → Activity → Unattributed rewards, where you can credit it to the right advocate. |
400, error: "visitor_id_not_found" | AdvocateLoop has no record of this customer (no referral visit or claim for this email). |
A conversion always belongs to a claim: the customer’s claim, made in the widget, at a checkout we integrate with, or through Recording a claim.
Available on all plans.
Recording a refund
Use this when an order is refunded (in full or in part) so the conversion is updated accordingly.
Request
POST https://api.advocateloop.com/api/v1/track/refundContent-Type: application/jsonX-API-Key: <your API key>X-Brand-ID: <your brand ID>
{ "order_id": "ORD-12345", "refund_amount": 50.00, "refund_reason": "Customer changed mind on one item"}Fields
| Field | Required | Notes |
|---|---|---|
order_id | one of¹ | The order_id from the original conversion |
conversion_id | one of¹ | AdvocateLoop conversion ID — an alternative way to identify the conversion |
claim_id | one of¹ | Associated claim ID — another alternative identifier |
refund_amount | no | The amount refunded in this transaction. Omit for a full refund of the remaining amount. |
refund_id | no | Your refund identifier. Recommended: sending the same refund_id again returns the existing refund instead of refunding twice. |
refund_reason | no | Free-text reason for the refund |
¹ Provide at least one of order_id, conversion_id, or claim_id to identify the conversion.
Refunds don’t include an items array. A refund that brings the order to zero reverses the advocate’s reward for it.
Responses
| Response | Meaning |
|---|---|
200 | Refund recorded (or, for a repeated refund_id, the existing one returned) |
404, error: "conversion_not_found" | No AdvocateLoop conversion matches. Usually the order wasn’t a referral; if it was only just placed, retry shortly. |
400, error: "already_refunded" | The conversion is already fully refunded, or there’s nothing left to refund |
Available on all plans.
Closing a claim when an order is cancelled
When an order is cancelled or its payment fails, tell AdvocateLoop so the customer’s claim doesn’t stay open. If the order had already been paid and recorded as a conversion, it’s treated as a full refund: the advocate’s reward is reversed.
POST https://api.advocateloop.com/api/v1/track/claim-statusContent-Type: application/jsonX-API-Key: <your API key>X-Brand-ID: <your brand ID>
{ "claim_id": 5567, "status": "cancelled"}| Field | Required | Notes |
|---|---|---|
status | yes | cancelled or failed |
claim_id | one of | The claim_id returned when the claim was recorded. Needed for an order that was never paid. |
order_id | one of | For a paid order: the order_id you sent with the conversion |
Sending it again is safe: a claim that’s already closed or refunded is left as it is.
Available on all plans.
Recording a claim — Premier only
Use this when a customer first claims a referral (signs up, requests a discount code, starts a booking) from a system that captures it outside the widget. Most integrations won’t need it.
The customer must have arrived through a referral link: AdvocateLoop checks the same referral rules as the widget and our checkout integrations (see Responses below). It finds the customer’s referral visit from the visitor_id, or from an earlier visit or claim under the same email.
Request
POST https://api.advocateloop.com/api/v1/track/claimContent-Type: application/jsonX-API-Key: <your API key>X-Brand-ID: <your brand ID>
{ "referral_code": "JOHN123", "customer_email": "newuser@example.com", "customer_name": "Sam Smith", "customer_phone": "+1-555-0100"}Fields
| Field | Required | Notes |
|---|---|---|
referral_code | yes | The code being claimed |
customer_email | yes | The customer’s email |
customer_name | no | Display name |
customer_phone | no | Contact phone |
visitor_id | no | The AdvocateLoop visitor ID from the customer’s browser (the __alvid cookie), if you have it |
coupon_code | no | The coupon the customer used, if any |
items | no | Line items, same fields as the conversion items above |
Responses
A recorded claim returns 200 with "success": true and the claim in data (including claim_id). If the customer already has an open claim, that one is returned instead of a second being made.
A customer who doesn’t qualify returns 200 with "success": false, an error code and a customer-friendly message:
error | Meaning |
|---|---|
invalid_code | No advocate has this referral code |
advocate_inactive | The advocate has been switched off or flagged |
no_attribution | The customer has no referral visit on record (for example, they typed the code without using the link) |
attribution_expired | Their referral visit is older than your attribution window |
self_referral | The customer is the advocate |
already_claimed | First-purchase-only is on and this customer has already used a referral |
advocate_email_mismatch | An advocate reward can only be redeemed with the advocate’s own email |
no_redemptions_available | The advocate has no reward available to redeem yet |
fraud_blocked | This customer or advocate is flagged for fraud |
A 400 with error: "visitor_id_not_found" means AdvocateLoop has no visit or claim on record for this customer, so there’s nothing to attribute.
Premier plan only.
Recording a visit — Premier only
Track a click on a referral link from an external system — e.g. logging clicks from a custom email tool. Most integrations won’t need it.
Request
POST https://api.advocateloop.com/api/v1/track/visitContent-Type: application/jsonX-API-Key: <your API key>X-Brand-ID: <your brand ID>
{ "referral_code": "JOHN123", "landing_page": "https://example.com/products/widget", "utm_source": "newsletter", "utm_medium": "email", "utm_campaign": "spring-sale"}Premier plan only.
Sending from your backend
If you’re sending from your own server (Node, Python, PHP, Ruby, anything that can do HTTP), it’s just a POST with the headers and body above. There’s no SDK — the API is small enough that direct HTTP is the simplest path.
Node.js example
const response = await fetch('https://api.advocateloop.com/api/v1/track/conversion', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-API-Key': process.env.ADVOCATELOOP_API_KEY, 'X-Brand-ID': process.env.ADVOCATELOOP_BRAND_ID }, body: JSON.stringify({ customer_email: 'buyer@example.com', order_id: 'ORD-12345', order_total: 108.00, tax: 8.00, shipping: 10.00, discount: 5.00, referral_code: 'JOHN123' })});
const result = await response.json();if (!result.success) { console.error('Failed to record conversion:', result.error);}Python example
import requestsimport os
response = requests.post( 'https://api.advocateloop.com/api/v1/track/conversion', headers={ 'Content-Type': 'application/json', 'X-API-Key': os.environ['ADVOCATELOOP_API_KEY'], 'X-Brand-ID': os.environ['ADVOCATELOOP_BRAND_ID'] }, json={ 'customer_email': 'buyer@example.com', 'order_id': 'ORD-12345', 'order_total': 108.00, 'tax': 8.00, 'shipping': 10.00, 'discount': 5.00, 'referral_code': 'JOHN123' })
result = response.json()if not result.get('success'): print(f"Failed: {result.get('error')}")Common issues
“401 Unauthorized” / “Invalid API key” — double-check the X-API-Key header value. Make sure there’s no leading/trailing whitespace and that you’re using the key from the right environment (production vs sandbox if you have separate keys).
“429 Too many requests” — you’ve hit the per-minute limit. Wait for the Retry-After seconds and send again. If the error says the API call limit is exceeded for the billing period, that’s your plan’s monthly allowance.
“403 Feature not available” on claim/visit — these event types require Premier. Either upgrade your plan, or restructure your integration to use conversions/refunds (which are available on all plans).
“400 Bad Request” with field-specific error — the API tells you which field is missing or invalid. Read the error field of the response.
Numbers arriving as strings — common with some no-code HTTP tools. JSON numbers must not be quoted. If order_total: "108.00" shows up in your request body, your tool is escaping the number. Check your tool’s settings for “data pass-through” or “raw JSON” options.
Webhook fires multiple times — most automation tools retry failed deliveries. Use the order_id field for conversions: if you send the same order_id twice, AdvocateLoop won’t double-count it.
Security best practices
- Treat your API key like a password. Don’t commit it to source control. Don’t share it in support tickets unless explicitly asked (and rotate it after).
- Use HTTPS. All AdvocateLoop endpoints require it; HTTP requests are rejected.
- Rotate keys if you suspect a leak or when a team member with access leaves.
- Limit access. Give each integration its own API key if you can, so you can revoke one without breaking others.