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.

POSThttps://intrio.co/api/v1/conversions

Record 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.
typestringrequired
signup, payment, order or refund.
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 signup and payment. For an order without it, Intrio uses order:<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 payment and order. For refund, 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: the id of 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_attr cookie's at). Optional. Applies the attribution window when there's no click_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 ref or click_id), moves the referral to won on the first payment, and creates a reward.
ordertype
Like payment, for shop orders. customer is 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).

Response
{
  "status": "recorded",
  "message": "Payment 1 recorded: reward £980.00",
  "referral_id": "cmi8x2k0w0001qk08z9f3h1a2"
}

200Duplicate: this id was already processed.

Response
{
  "status": "duplicate",
  "message": "Event in_1QxY2z was already processed (recorded)",
  "referral_id": "cmi8x2k0w0001qk08z9f3h1a2"
}

422Rejected by business rules, or invalid fields.

Response
{
  "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.

Response
{ "error": "invalid_api_key", "message": "Missing or invalid API key" }

400Body isn't JSON.

Response
{ "error": "invalid_json", "message": "Body must be JSON" }

429Rate limited.

Response
{ "error": "rate_limited", "message": "Too many requests; slow down and retry" }

500Server error. Nothing was saved; retry with the same id.

Response
{ "error": "internal", "message": "Couldn't record that conversion. It's safe to retry with the same id." }

Statuses#

statusHTTPMeaning
recorded201Saved. For payments and orders, a reward was created (it may be £0 if your rules give nothing).
unattributed201No valid partner: no ref or click_id, an unknown code, an inactive partner, or a first touch outside the attribution window.
no_reward201Saved, but no reward: the payment is beyond the programme's rewarded payments, or a refund had nothing to reverse.
duplicate200This id was already processed. The original outcome is in message.
rejected422Not accepted. message says why (see below).

Rejection messages#

  • No active programme "<slug>"
  • Introductions programmes take referrals from partners, not the conversions API
  • Currency <X> doesn't match the workspace currency <Y>
  • customer.id is required for sign-ups and payments
  • amount is required for payments and orders
  • refunds must be the id of the payment or order being refunded
  • No 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 ref or click_id for 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.