Troubleshooting

Check one stage at a time: capture → checkout handoff → provider payment → LiftVector attribution and commission. A working earlier stage does not prove the next one works.

Setup is confirmed, but referrals are missing

Merchant-confirmed records that you completed the instructions. It is not an installation check or payment test. Choosing or copying a method also does not install it.

1. Open Settings → Website integration for the correct merchant.
2. Confirm the selected method matches the checkout control customers use.
3. Compare your deployed installation with the actual copyable workspace snippet, including its merchant and method.
4. Check Settings → Connection for the connected provider account, environment, and active status.
5. Follow a current affiliate link and complete a referred checkout. Test purchases must use the environment connected to that merchant; do not expect sandbox purchases to appear under a live connection.

For initial setup, follow the quickstart and integration guide.

The browser has no referral

On a page with hosted capture installed, your developer can inspect window.LiftVector?.referral ?? null in browser developer tools. This reads the current candidate; it does not prove payment or affiliate eligibility.

• Check that the arrival URL actually contains the affiliate’s current via token and that redirects preserve it until capture.
• Check exact syntax: 4–64 lowercase ASCII letters, digits, underscores, or hyphens. Do not repair a token by trimming or changing case.
• Confirm https://static.liftvector.app/script/liftvector.js loads once on both the referral landing page and the page that hands off to checkout. In the browser Network panel, check that it returns JavaScript successfully; check network and console errors for blocked requests, including a Content Security Policy that does not allow https://static.liftvector.app as a script source.
• Check expiry and storage. Retention is 30 days after capture on the same origin and browser, not across subdomains or devices. Blocked storage can leave only the current-page candidate.
• For custom checkout code, check loading order: LiftVector’s classic deferred script must run before code that reads the value. An inline script or async loader does not guarantee that order.

If you deliberately use server-only capture, the browser API is not required. Inspect your server’s capture, retention, and checkout request instead.

The token is captured but does not reach Stripe

Inspect the actual resulting Checkout Session, not only a link or DOM attribute. Its client_reference_id must contain the original public token.

Checkout path	What to check
Payment Links	The selected method is Payment Links and the destination is a recognized HTTPS buy.stripe.com link. Custom domains and hosted Session URLs are not decorated. Check for an existing client_reference_id, including an empty one.
Buy Button or Pricing Table	Keep the real Stripe embed, ID, and publishable key. Use the ordered workspace scripts: LiftVector first, then Stripe, both deferred and loaded once. Check for an existing client-reference-id. Wait for dynamic components to finish loading.
Marked HTML anchor or form	The control has data-liftvector="true" and is in the ordinary document, not an iframe or shadow root. Generated values go in the query for anchors/GET forms and form data for POST forms. Existing via values win: GET action references are carried into a hidden field; POST action references stay in the query without a generated form field.
JSON checkout	Your code explicitly includes the browser candidate in the existing request. Marking a control does not rewrite JSON.
Server-created Session	Your backend reads the matching request field or retained server value, validates it, and sets client_reference_id when creating the Session. The browser script cannot do this for the server.

Do not overwrite a reference used by your application or combine it with an order ID. Resolve the conflict in the checkout integration. Metadata is not a fallback for this direct-link contract.

After correcting a missing handoff, create a new referred checkout to verify it. Do not assume an already completed Session can be retrofitted with attribution.

The Session has the token, but the sale or commission is missing

1. Verify collection at the provider. A completed but unpaid Session or a success-page redirect is insufficient. Check the associated payment or paid invoice and the correct provider account and environment.
2. Open Sales in LiftVector. Inspect the sale’s status, review reason, Last updated, Affiliate attribution, and Attributed through. An existing association or recognized promotion may take precedence over your new link.
3. Check campaign eligibility. Verify the affiliate belongs to the merchant and campaign, the purchase is within the relevant enrollment period, and the product and commission terms apply. A sale does not automatically mean a payable commission. See campaigns and commissions.
4. Update existing evidence. On the sale detail page, use Update sale to request current payment, refund, dispute, and attribution facts. Wait for the result and inspect it; an accepted update request is not itself proof of success.
5. Check Activity and the connection. Activity shows provider processing and updates needing attention. If the connection requires recovery, use the available reconnect or Retry payment sync action in Connection settings. Reconnection uses the retained account and environment.

Needs review is not a confirmed zero. Missing or conflicting payment facts require resolution before they can support confirmed totals. An unknown refund or dispute amount is not evidence that no refund or dispute exists. See attribution rules for precedence and scope.

Prove the complete path

For a merchant connected to a sandbox, use an eligible affiliate and campaign to complete a referred sandbox purchase. Check all three results:

• The resulting provider Session contains the unchanged public token.
• Provider records show the collected payment and its related objects.
• LiftVector shows the corresponding sale, expected affiliate association, and commission outcome under the campaign terms.

Use a fresh customer or subscription as appropriate when testing new attribution; an existing association can correctly override the new candidate. Updating the same sale again should not create duplicate earnings. For embedded checkout, exercise the real component rather than stopping at an attribute inspection.

Information to collect for support

Provide the merchant, connected environment, selected checkout method, approximate purchase time with timezone, affected page, and the relevant Checkout Session/payment/invoice identifiers. Include the LiftVector sale identifier if present, its status and review reason, last update time, and any safe error shown in Activity.

State which stages you verified: browser candidate, outbound request, Session reference, collected payment, and LiftVector outcome. Screenshots of confirmation alone cannot establish these facts.

Do not send secret API keys, authorization headers, session cookies, full customer records, or unredacted network exports. Share only the minimum evidence needed to identify the affected checkout.