Server-side
Conversions API
POST /api/v1/conversions: record sign-ups, payments, orders and refunds from your server. Every field, status and error.
Available on Growth and above. On Free and Starter, use the tracking script, Stripe, Shopify or WooCommerce, which work on every plan. Keys created on Growth keep working after a downgrade.
https://intrio.co/api/v1/conversionsRecord one sign-up, payment, order or refund.
curl https://intrio.co/api/v1/conversions \
-H "Authorization: Bearer $INTRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"id": "in_1QxY2z",
"type": "payment",
"programme": "app",
"customer": { "id": "user_42", "email": "sam@acme.com" },
"amount": 4900,
"currency": "GBP"
}'Body#
idstringrequired- Your unique id for this event, 1 to 200 characters. Use the invoice, order, charge or user id. See idempotency.
typestringrequiredsignup,payment,orderorrefund.programmestringrequired- The programme slug, up to 60 characters. Must be an active Sign-ups or Sales programme.
refstring- The partner code (
pp_ref/via), up to 60 characters. click_idstring- The click id (
pp_click), up to 80 characters. Applies the attribution window. customer.idstring- Your stable id for the customer, 1 to 200 characters. Required for
signupandpayment. For anorderwithout it, Intrio usesorder:<id>. customer.emailstring- Valid email, up to 254 characters. Shown to you and used as the referral's label.
customer.namestring- Up to 120 characters.
amountinteger- Minor units, 0 to 1,000,000,000. Required for
paymentandorder. Forrefund, the amount refunded (defaults to the full original amount). currencystring- 3-letter code. If given, it must match the workspace currency (any case).
refundsstring- For
refund: theidof the payment or order being refunded. Required for refunds. attributed_atstring- ISO 8601 date-time: when the visitor first followed the partner link (the
pp_attrcookie'sat). Optional. Applies the attribution window when there's noclick_id; without either, the event is accepted. occurred_atstring- ISO 8601 date-time with offset, for example
2026-11-20T09:30:00Z. Defaults to now. Used for the attribution window, hold days and the referral date.
How each type is handled#
signuptype- Credits the partner for the customer. Creates the referral if it's new.
paymenttype- A recurring or one-off payment. Credits the partner (if the customer is new and the event carries a
reforclick_id), moves the referral to won on the first payment, and creates a reward. ordertype- Like
payment, for shop orders.customeris optional. refundtype- Reduces or claws back the reward on the payment named in
refunds.
Attribution happens once per customer and programme. When the first event for a customer.id carries a valid ref or click_id, a referral is created for that partner. Later payments for the same customer.id are credited to that partner without needing ref. If the first event has no partner, it's recorded as unattributed and nothing is created.
When both ref and click_id are given and the click belongs to this programme, the click's partner is used. A click_id, or for ref-only events an attributed_at, older than the programme's attribution window gives unattributed.
Responses#
201Recorded, or accepted with no credit (unattributed, no_reward).
{
"status": "recorded",
"message": "Payment 1 recorded: reward £980.00",
"referral_id": "cmi8x2k0w0001qk08z9f3h1a2"
}200Duplicate: this id was already processed.
{
"status": "duplicate",
"message": "Event in_1QxY2z was already processed (recorded)",
"referral_id": "cmi8x2k0w0001qk08z9f3h1a2"
}422Rejected by business rules, or invalid fields.
{
"status": "rejected",
"message": "No active programme \"ap\"",
"referral_id": null
}
{
"error": "invalid_request",
"message": "Check the fields",
"fields": { "amount": ["amount must be integer minor units"] }
}401Missing or invalid key.
{ "error": "invalid_api_key", "message": "Missing or invalid API key" }400Body isn't JSON.
{ "error": "invalid_json", "message": "Body must be JSON" }429Rate limited.
{ "error": "rate_limited", "message": "Too many requests; slow down and retry" }500Server error. Nothing was saved; retry with the same id.
{ "error": "internal", "message": "Couldn't record that conversion. It's safe to retry with the same id." }Statuses#
| status | HTTP | Meaning |
|---|---|---|
recorded | 201 | Saved. For payments and orders, a reward was created (it may be £0 if your rules give nothing). |
unattributed | 201 | No valid partner: no ref or click_id, an unknown code, an inactive partner, or a first touch outside the attribution window. |
no_reward | 201 | Saved, but no reward: the payment is beyond the programme's rewarded payments, or a refund had nothing to reverse. |
duplicate | 200 | This id was already processed. The original outcome is in message. |
rejected | 422 | Not accepted. message says why (see below). |
Rejection messages#
No active programme "<slug>"Introductions programmes take referrals from partners, not the conversions APICurrency <X> doesn't match the workspace currency <Y>customer.id is required for sign-ups and paymentsamount is required for payments and ordersrefunds must be the id of the payment or order being refundedNo recorded payment "<id>"
Idempotency#
Every event is processed once per id, whatever the retries. Each request runs in a single transaction, so after a 500 or a timeout nothing was saved and you can safely retry with the same id.
Use ids that are unique per event within your workspace: prefix them if two systems report to the same workspace, for example signup_<user id> and <stripe invoice id>.
Rate limits#
1,200 requests per minute per workspace, counted in fixed one-minute windows. Over the limit you get 429; wait and retry with the same id. The Node SDK retries 429s and 5xx for you.
Testing#
There's no separate test mode. To test safely:
- Create a separate test programme (for example slug
app-test) and switch it off when you're done; events for an inactive programme are rejected. - Invite yourself as a partner and use your own code as
ref. - Use clearly fake ids such as
test_001. - Events without a
reforclick_idfor a new customer create nothing, so you can check authentication and validation without side effects.
Last updated 20 November 2026. Building with an AI assistant? Point it at /docs/llms-full.txt.