> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evomarketing.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Creator codes

> Codes a customer types at checkout or in the app, and how they credit a creator

A creator code is the second way credit reaches a creator. A link carries credit through a click token or an install match; a code carries it through the customer, who types `JANE10` at checkout or into the app.

That makes a code the only path that survives word of mouth, podcasts, and screenshots — nothing has to be clicked, and no clipboard has to survive an in-app browser.

## How a code resolves

A code match resolves at **0.9 confidence** with `resolution_method: "code"`. It sets no link and credits the code's creator directly.

It is a confirmed, payout-grade method — deterministic, but a notch below a click token because a code can be reshared by someone other than the creator who earned it. When both a clipboard token and a code are present, the token wins.

Codes belong to one brand. Another brand's code never matches, and an inactive code never matches.

## Format

`AttributionCode::FORMAT` is `/\A[A-Z0-9]{3,24}\z/` — 3 to 24 uppercase letters and digits.

Customers retype codes with spaces, dashes, and stray case, so codes are normalized identically on write and on lookup: trimmed, upcased, everything outside `A-Z0-9` removed, then capped at 24 characters.

```
"jane-10"  → JANE10
"Jane 10"  → JANE10
" JANE10 " → JANE10
```

## Generation

When an operator creates a code without dictating one, EVO suggests the creator's first name plus two digits — short, because codes get said out loud.

* The stem is the normalized first name, trimmed to leave room for the two digits.
* A name shorter than 3 characters falls back to the stem `EVO`.
* Ten attempts look for a free suffix; if all are taken, the code becomes `EVO` plus 4 random uppercase alphanumerics, then `EVO` plus 12 as a last resort.

An operator can always dictate the code instead — useful when a creator already says one on camera.

### Automatic codes on deal start

Once a brand uses attribution (it holds a pixel key, a billing connection, a link, or a code), every creator whose deal with that brand goes active is minted a code automatically, in the background, from the same first-name rule. A creator who already holds an active code for the brand gets nothing new. Brands that never set up attribution get no codes.

## Where a customer enters it

<CodeGroup>
  ```javascript Web (EVO pixel) theme={null}
  evo("purchase", {
    orderId: "1234",
    amount: 49.99,
    currency: "USD",
    code: "JANE10",
  })
  ```

  ```swift iOS (SDK) theme={null}
  _ = await EVOAttribution.trackInstall(readClipboard: true, code: enteredCode)
  await EVOAttribution.trackPurchase(
      transactionId: transaction.id,
      amount: 49.99,
      currency: "USD",
      code: enteredCode
  )
  ```

  ```ts React Native (SDK) theme={null}
  await trackInstall(true, enteredCode)
  await trackPurchase("store-transaction-id", 49.99, "USD", enteredCode)
  ```
</CodeGroup>

Both public endpoints — `POST /api/public/attribution/installs` and `POST /api/public/attribution/events` — accept an optional `code` string.

An install resolved by code reports `attributed: true` with `link: null`, the matched `code`, and its creator.

### As the store's discount code

A creator code can double as a real discount. Create the discount in Shopify or Stripe under the same string (`JANE42`) and the billing webhook credits the creator on its own; no pixel call is needed for that sale. See [billing connectors](/attribution/billing-connectors) for what each provider sends.

## Managing codes

### From the client portal

A brand manages its own codes under **Results → Sales → Links & codes → Codes**:

* **New code** picks a creator from the brand's roster (or none, for a brand-wide code), optionally dictates the code, and saves. Leave the code blank and EVO suggests one from the creator's first name. A roster creator outside the brand's own roster is refused with `creator_not_on_roster`.
* **Not on EVO** lets the brand mint a code for a creator it works with outside EVO, by name (`creator_name`). Their sales group under that name in **By creator**, on the code's row, and in the activity feed with a "Not on EVO" tag. EVO reports these sales and never pays that creator; the brand does.
* **Generate for all creators** mints one code per active creator who does not hold one yet. Pressing it twice creates nothing new.
* **Deactivate / Reactivate** on a row. Clients cannot delete codes; an inactive code stops matching immediately and keeps every sale it credited.

| Action                             | Endpoint                                                                                   |
| ---------------------------------- | ------------------------------------------------------------------------------------------ |
| List                               | `GET /api/client/attribution/codes`                                                        |
| Create (dictated or generated)     | `POST /api/client/attribution/codes` with `user_id?` or `creator_name?`, `code?`, `label?` |
| One per active creator without one | `POST /api/client/attribution/codes/generate`                                              |
| Activate, deactivate, relabel      | `PATCH /api/client/attribution/codes/:id`                                                  |

### From the EVO team console

EVO team, in the admin console under **Sales Attribution → Codes** (`/api/internal/attribution-codes`):

| Action                                 | Endpoint                                     |
| -------------------------------------- | -------------------------------------------- |
| List, filtered by brand or creator     | `GET /api/internal/attribution-codes`        |
| Create (dictated or generated)         | `POST /api/internal/attribution-codes`       |
| Rename the label, activate, deactivate | `PATCH /api/internal/attribution-codes/:id`  |
| Delete                                 | `DELETE /api/internal/attribution-codes/:id` |

A code with no creator is a brand-level code that no single creator owns.

<Warning>
  Deleting a code that already credited conversions returns `code_in_use` (`409`). Deleting it would orphan the ledger rows it credited, so deactivate it instead — an inactive code stops matching immediately and keeps its history.
</Warning>

### Usage counters

Every resolved event bumps the code's `uses_count` and `last_used_at`. A deduplicated retry of the same transaction does not, so the counter never inflates from a double-fired beacon.

## What the brand sees

The client portal lists each brand's codes read-only under **Results → Attribution → Creator codes**:

| Column                           | Meaning                                               |
| -------------------------------- | ----------------------------------------------------- |
| Code / label                     | The code itself and its optional label                |
| Creator                          | The credited creator, or blank for a brand-level code |
| Active                           | Whether the code currently matches                    |
| Uses                             | `uses_count`, with `last_used_at`                     |
| Installs / conversions / revenue | Ledger totals for rows credited to this code          |

Totals exclude sandbox rows, so a test purchase confirms your setup without moving the client-facing numbers.