API referenceEndpoints

Promo codes

The attribution that survives a creator saying it out loud.

What a code is

A promo code is the only attribution that survives a creator saying it out loud. No click, no redirect, no link in the bio: somebody watches a video, remembers a word, and types it at your checkout days later on a different device. Everything else in this API needs a tap.

One code per creator per campaign. The code resolves to their link, so a redemption credits the same creator a click would have, and the two land in the same reports with different evidence tiers.

The mode comes from the key, never from the body. A test key issues, lists and validates test codes only. There is no field that crosses that line, because a sandbox credential minting something that pays real money is the one mistake this surface must make impossible.

Issuing

Issue one per creator on a campaign. Idempotent by default: creators who already hold a code come back under skipped with the code they hold, so you can call it again after adding creators without tracking who was in the last batch.

curl -X POST "https://track.acrune.com/v1/promo-codes" \
  -H "Authorization: Bearer $ACRUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"campaign":"cmp_4471","maxRedemptions":500}'

Cap them. Aggregators scrape and republish creator codes, and an uncapped code turns one scraped post into an unbounded claim on your budget. maxRedemptions null means uncapped and is the wrong default for anything public.

reissue: true mints a fresh code for a creator who already holds one. It is off by default because their first code is already printed in a clip and already typed into your store's console, so a second one orphans every redemption of the first. Use it after disabling a leaked code, not before.

Validating at checkout

Call validate from your checkout before you accept the code. This is what makes the cap mean anything: without it a code past its ceiling is taken at the till and simply fails to credit anybody later, which to the creator is indistinguishable from being cheated.

curl -X POST "https://track.acrune.com/v1/promo-codes/JANCLIPS-APEXLAPS-K3R7/validate" \
  -H "Authorization: Bearer $ACRUNE_KEY"

reason is one of unknown, disabled or exhausted, and null when the code is good. An unknown code reports nothing else: there is no creator named, because naming one would make this an oracle for guessing codes.

Validate does not redeem, however many times you call it. A checkout validates on every keystroke and on every cart nobody pays for; counting there would burn a creator's cap on sales that never happened. The count belongs to the payment.

Every verdict answers 200. A code that is no good is a successful answer to the question you asked, and a 404 would make your error handling treat an exhausted code as an outage.

Redeeming

Report the sale to POST /v1/conversions with the code in the body. That is where the redemption is counted, keyed on your idempotencyKey, so a retried webhook credits the creator once.

cURL
curl -X POST "https://track.acrune.com/v1/conversions" \
  -H "Authorization: Bearer $ACRUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"JANCLIPS-APEXLAPS-K3R7","idempotencyKey":"ord_88412","grossMinor":4900,"currency":"USD"}'

Codes are matched the way a person types them: case, spaces, hyphens, underscores and full stops are all noise. ALICE-10, alice 10 and Alice10 are one code. Send whatever the customer typed.

A code outranks an identity binding when both are present, and is outranked by a click id. The order is about evidence: a click id is this checkout, a code is also this checkout because the customer typed the creator's name at the moment they paid, and a binding was made at signup and may since have been superseded.

Disabling and listing

PATCH a code to turn it off, turn it back on, or move its cap. Disabling is what you do when a code leaks, and it is reversible on purpose: the code you are stopping is already printed in a clip, so stopping the wrong one has to be undoable in the next second.

cURL
curl -X PATCH "https://track.acrune.com/v1/promo-codes/JANCLIPS-APEXLAPS-K3R7" \
  -H "Authorization: Bearer $ACRUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"disabled":true}'

A cap may be lowered below what has already been redeemed, which means exactly what it says: no further redemptions. Refusing that would make a leak unstoppable at the moment you most want to stop it.

GET /v1/promo-codes lists them, narrowed with campaign and account and paged with limit and offset. GET /v1/promo-codes/:code reads one. Neither the code string, its creator nor its campaign can be changed after issue, because all three are printed on somebody's clip by then and a code that can be repointed is a redemption history that silently changes whose it was.