Refficks API reference

The organization the key belongs to, and the key's name, purpose (zapier, make, n8n, or null for a key made on the API keys screen) and abilities, each with a label in words. An automation platform shows this as the connection's name. Nothing in it is part of the key, and any secret key may call it (identify).

The server-side ingest endpoint. Authenticated with an API key, not a session.

Idempotent: the Idempotency-Key header is required. Replaying the same key with the same payload returns the original event and "status": "duplicate". Reusing it with a different payload is a 409.

Processing is asynchronous: the response acknowledges receipt, it does not report attribution or commission outcomes.

Oldest first, tie-broken on the key. A server walks the whole list, and a newest-first page shifts under a paginating caller every time a partner is added: page two repeats a row from page one and drops another. Ascending by a key that only grows means a page already read stays read.

Nobody is emailed unless the request says so. No portal invitation is sent by default; pass send_portal_invitation: true for one. A person pressing Add Partner is adding one person and watching; a server is a loop, and a first sync that mails two thousand people (several hundred of whom left years ago) cannot be un-sent.

organization_id is never accepted. The tenant comes from the key, and supplying it is a validation error rather than a silently ignored field.

status is refused. A partner created already archived would have a status nobody set and no audit entry could explain; archiving is its own call.

Exactly one of email or code. Both, or neither, is a 422: "either, and I will guess" is how a lookup quietly answers the wrong question when the two disagree.

A single object or a 404, never a list of length zero or one. An integration should not have to store Refficks' ids to use Refficks, and should not have to unwrap an array to find that out.

code matches any tracking link of theirs, including a retired one: a code out of a year-old newsletter still identifies whose it was.

A genuine partial update: a field sent as null is cleared, a field not sent is untouched.

Details only. status, lifecycle_stage, roles and currency are refused with a message naming the endpoint that does the job: refused rather than ignored, because a silently dropped field returns a 200 and a partner object, and the caller ships. The bug then surfaces months later against the one partner where it mattered.

The scores are refused too. They are computed, and a score a client can set is a score no recommendation built on it means anything.

Separate from PATCH because a stage change is a decision with consequences (it fires automations, it stamps approved_at, it is what lets somebody into the portal), and an edit to a field is not.

The legal moves are the same ones a person gets. An illegal one is a 409, so a server cannot walk a partner around the funnel a screen would refuse to.

Archiving, not deleting. A partner is attached to conversions, ledger entries and payouts; removing the row would make last quarter unreconcilable. It also stops their tracking: an archived partner's links stop earning.

Security review F-25: refused with 403 to a key made for an automation platform, and so is restoring.

A POST to a named path rather than a DELETE, because DELETE promises removal and this keeps everything.

Erasure is deliberately absent from this surface. It takes a typed confirmation from somebody who has read the sentence saying it cannot be undone, and a token cannot read a sentence.

Their programme memberships are deliberately untouched, here as on the screen: restoring must not reinstate a programme the merchant suspended on purpose before archiving them. Two decisions, and only one of them is being undone.

slug is derived from the name and cannot be chosen here: uniqueness is per organization and there is nothing to check against until the programme exists. It is editable afterwards.

Set default_destination_url: without it every link you later mint has to carry the same URL again, and a link with nowhere to go is refused.

module is refused: it decides which half of the product a programme belongs to, so changing it would leave everything already recorded under the old one belonging to nothing.

Rates are not here: a key may set no rate, so commission plans are read only.

A tier may be chosen here and not changed afterwards: a tier sets what somebody earns, and a key may set no rate, so a PATCH naming one is refused.

Two things to know before your first script. A partner created while the merchant has exactly one programme is already in it, so enrolling them again is a 409; enrolment is deliberately not idempotent, because a second call that meant to change something and silently did nothing is worse than a conflict you can read. And enrolling somebody mints their first tracking link.

status only. tier_id and custom_commission_plan_id are refused with a message naming where they are set. Both decide what somebody earns, and a key may set no rate.

There is no POST here, and the absence is the decision. A plan sets what everybody earns, and nobody has said a token may set a rate. A write is a 405: the address is real and the method is not.

Ordered by priority, which is the order that decides which plan pays: a merchant reading this list is almost always asking which one applies.

The partner must already be in the programme: a link's terms come from the membership, so a link without one is a link nobody could state the rate for. Enrolling a partner also mints their first link, so this is for the second and after.

With no destination_url, the programme's default_destination_url is used. With neither, the request is refused.

code is refused. It is printed in videos, bios and newsletters, so renaming it would silently break every place a partner already shared it, and a script could do that to two hundred people in one call. Retire this link (status: archived) and mint another.

partner_id and program_id are refused too: moving a link would reassign the clicks it has already recorded.

This does not create a discount in your payment provider. Refficks connects to Stripe as a platform and holds no credential of yours. What this creates is the record that says this code belongs to this partner.

To register a promotion code you already made, send external_promotion_id, with account_id naming which connected account holds it when you have more than one.

Security review F-15: Stripe is asked what the promotion's code is, and a claim whose code is not this code is refused with 422; a promotion another code already claims is refused with 409. A key made for an automation platform cannot claim one at all (403), nor switch a code or link on or off.

code is optional: left out, one is derived from the partner's name, which is what a server looping over two hundred partners wants.

One code per partner per programme, unless the merchant has turned on more than one. A second is a 409.

code is refused, for the reason a link's is: it is what somebody types at the checkout. Retire this one and make another.

uses_count is refused because it is Refficks' count of redemptions: a merchant who could edit it could hand somebody another fifty uses with no record of having done so.

Sending external_promotion_id: null takes a placement back, which is a different instruction from not sending the field at all.

occurred_from / occurred_to filter on occurred_at, not created_at: a sale in March recorded in April belongs to March's books.

Paged by id, because a ULID only grows while occurred_at does not: a late-arriving event carries an older date and would insert rows behind a crawler.

No total. A ledger holds several currencies and this API will not sum across them; a figure nobody can spend is worse than none.

There is no POST. Refficks moves no money: a payout's status is recorded and the merchant downloads a file for their bank, so there is no transfer for an endpoint to trigger. Read status: paid as the merchant recorded that they sent it.

The question a reconciling merchant actually has, answered without making them filter the whole ledger by a payout id and trust that they got all of it.

The subscriptions this key made, oldest first, never the merchant's own receivers and never another key's. Needs hooks:manage. Each has url_hint (host and last four characters), never the address.

What a REST-hook subscribe sends: {url, event} or {url, events: [...]}, optional description. The address is kept encrypted. Asking again for the same address from the same key answers the same subscription (200, no secret) and starts it again if it had ended; asking from another key while it is live is a 409. Every event needs partners:read; commission and payout events need money:read too (403 naming the ability). At most 200 active per key.

Every event something in the product raises, with label, needs (the abilities it takes) and subscribable for this key: the dropdown an automation platform shows.

Up to three of the merchant's own newest facts for event, newest first, in the shape a delivery has (docs/events.md, "Delivered outward") and with the same id a live delivery of the same fact carries. An empty list when there is nothing yet; nothing is invented. Needs hooks:manage and the read ability the event carries.

Ends it and keeps it, with its delivery log; nothing more is sent. A second call is answered the same, because platforms retry.

Minor units plus an ISO-4217 currency. Never a float.

One line of a merchant's ledger. Read only.

An entry carries its own arithmetic: amount, the base_amount it was worked out from, and the rate. A merchant reconciling should be able to see that £14.25 is ten per cent of £142.50 rather than take the figure on trust.

A reversal is a new entry, never an edit: a refund writes a negative row whose parent_entry_id points at the original, and both stay.

What a programme pays. Read only: a key may set no rate, so a POST or PATCH here is a 405.

rules is published verbatim because the rules are the plan: a payload saying type: tiered and declining to say what the tiers were would answer a question nobody asked. The shape inside it belongs to the calculation engine, so changing that shape changes this contract.

The code a partner's audience types at the checkout. This is the Refficks record, not a discount in anybody's payment provider.

This code, as it exists in one connected payment account. Refficks holds no credential, only the non-secret acct_… id.

A partner's own figure on one rule. What the rule covers (its conditions) is the rule's; only the figure is the partner's.

A partner as the management API publishes one.

Distinct from Partner, which is the dashboard's shape and follows its screens. Every property below is always present; absent data is null, never missing. Within v1 properties are added and never removed or repurposed.

The scores (score, potential_score, risk_score) are deliberately absent: they are recomputed on a schedule we change, against a scale nobody outside has agreed to, and automating against one would be automating against an implementation detail.

A payout. Read only, and Refficks moves no money: status: paid means the merchant recorded that they sent it.

payment_details is not here and never will be. Payout details are encrypted at rest and the stored value is never returned to anybody. payment_hint is the mask, and is all this surface says about where money went.

A programme as the management API publishes one. Every property is always present; absent data is null.

One partner's place in one programme: where the terms live. custom_commission_plan_id is readable and never writable.

A partner's link. url and destination_url are derived, not stored: a merchant who changes their link base expects every existing link to move.