> For the complete documentation index, see [llms.txt](https://refkit.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://refkit.gitbook.io/docs/integrate-refkit/troubleshooting.md).

# Troubleshooting

Check the funnel in order: click, signup, payment, commission. Start with the first missing step.

## No click received

| Cause                                  | Fix                                                                                                 |
| -------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Landing page is static or pre-rendered | Move capture to middleware, a dynamic route, or another backend path that runs on the live request. |
| `via` is not a real link code          | Open the Test affiliate link created by the dashboard.                                              |
| Browser capture uses the wrong origin  | Use the dashboard Test link, which may include `refkit_app`, or use authenticated server capture.   |
| Browser fallback did not run           | Check JavaScript, storage, blockers, and required consent. Prefer server capture.                   |

`404 affiliate_link_not_found` means the link code or browser origin did not resolve to an affiliate link.

## Click received, signup missing

| Cause                                       | Fix                                                                                      |
| ------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `click_id` was lost                         | Store it in first-party storage that the signup backend can read.                        |
| Landing and signup use different subdomains | Use a shared parent-domain cookie or a server-side session handoff.                      |
| Identify does not run                       | Call `POST /v1/identify` when the Customer account is created.                           |
| Click expired                               | Retest with a fresh click. The attribution window is 30 days.                            |
| Customer already has a Referral             | This is expected. RefKit does not reattribute an existing Customer for the same Program. |

## Payment or commission missing

### Stripe

* Call identify before creating the Stripe billing object.
* Attach the exact `stripe_metadata` returned by identify.
* Check the actual Customer, Checkout Session, PaymentIntent, or Subscription used by the payment.
* Connect the Stripe mode that matches the API key and payment.

### API reporting

* Persist and send the RefKit `customer_id` and `program_id` returned by identify.
* Use a stable `payment_id`.
* Send the amount in minor units.
* Use the same test or live mode for identify and payment reporting.
* Report the parent payment before a refund or dispute, and reuse the same stable ID when retrying.

### Commission checks

* A positive payment can create commission. A zero-value payment records history without commission.
* The payment currency must match the Program currency.
* The payment must belong to the identified Customer and Program.
* A test payment can never create a payable balance.

## Common API errors

| Code                       | Meaning                                                        |
| -------------------------- | -------------------------------------------------------------- |
| `click_not_found`          | The `click_id` is missing, invalid, or belongs to another App. |
| `click_expired`            | The click is older than 30 days.                               |
| `affiliate_link_not_found` | The `via` value or public capture origin is wrong.             |
| `app_scope_required`       | Use an App-scoped API key.                                     |
| `revenue_source_mismatch`  | The App is using the other revenue source.                     |
| `transaction_id_conflict`  | An idempotency ID was reused with different details.           |
| `refund_exceeds_payment`   | Total refunds exceed the original payment.                     |
| `dispute_id_conflict`      | A dispute ID was reused for another payment or amount.         |
| `dispute_status_conflict`  | A dispute already has a conflicting terminal outcome.          |

After a fix, retry with a fresh Test affiliate link and a new `external_customer_id`.