Payers

Reset a payee's W-8BEN tax form state

When a non-US payee has submitted an incorrect, incomplete, or outdated W-8BEN form, you can reset their W-8BEN state through the internal tooling endpoint. This clears their existing form data and allows them to complete the form again from the beginning.

This workflow is for internal admin and support staff only. Payees cannot reset their own tax form state. If a payee asks about updating their W-8BEN, they must ask their payer to resend the form link or contact support.

When to reset W-8BEN

Use the W-8BEN reset when a payee's tax form needs to be collected fresh:

  • Wrong form submitted: The payee accidentally completed W-9 instead of W-8BEN, or uploaded an incorrect document

  • Skipped form: The payee skipped the W-8BEN flow and needs to complete it now

  • Stale or outdated submission: The form is expired or has errors that cannot be corrected through normal updates

  • Foreign-owned LLC flag: The is_foreign_owned_llc status was incorrectly set and needs to be cleared

For simpler cases where the payee just needs theform link resent without resetting state, the payer can resend the link directly. Reserve the reset workflow for cases where the existing form data must be cleared.

What the reset does

Calling the reset endpoint clears the W-8BEN state for a specific app connection:

  • Clears form flags: Resets nextform_w8ben102021_id, _skip_w8ben, and is_foreign_owned_llc to allow a fresh submission

  • Deletes the form record: Removes any existing UserTaxForm row for W-8BEN tied to that user and app connection

  • Logs the action: Writes a note to the user record with the requestor, reason, and timestamp for audit purposes

After a reset, the payee is routed through the W-8BEN form flow as if they had never submitted it. They can complete a new form with correct information.

Request format

Send a POST request to the tooling endpoint with the following fields:

Field

Type

Required

Description

app_connection_id

string (UUID)

Yes

The app connection ID for this payee-payer relationship.

requestor_email

string (email)

Yes

Your email address for the audit log.

reason

string

Yes

The reason for the reset. Cannot be blank.

Example request

{
  "app_connection_id": "conn_01abc123def456",
  "requestor_email": "[email protected]",
  "reason": "Payee submitted W-9 instead of W-8BEN; needs to submit correct form"
}

Responses

The endpoint returns a JSON response:

  • Success (200): {"success": true, "message": "W-8BEN reset successfully", "user_id": "...", "app_connection_id": "..."}

  • AppConnection not found (404): {"success": false, "message": "AppConnection not found"}

  • Alias chain conflict (409): {"success": false, "message": "AppConnection alias chain — resolve aliasing first"}

The reset is scoped to a single app connection, not the entire user account. If a payee has multiple payer connections, each connection's W-8BEN state must be reset independently.

What happens after the reset

Once the reset completes:

  1. The payee's W-8BEN form record is deleted.

  2. Their form completion flags are cleared.

  3. When the payee next accesses their tax form flow, they will see the W-8BEN form as if it were never submitted.

  4. The request is logged to the user's notes with your email and the reason provided.

Common errors

"AppConnection not found"

This error means the app_connection_id does not exist. Verify the ID matches the payee's connection for this specific app. You can find app connection IDs in the admin dashboard or via the API.

"AppConnection alias chain — resolve aliasing first"

This error indicates the app connection is aliased to another connection and cannot be modified directly. Resolve the alias chainbefore attempting the reset. Contact the engineering team if you need help tracing the alias.

Form still shows as submitted after reset

If the payee reports their formstill appears submitted, they may be viewing a cached page. Ask them to refresh or clear their browser cache. If the issue persists, verify the reset was applied to the correct app connection ID.

Resending vs resetting

Two approaches exist for handling W-8BEN issues:

  • Resend the form link: The payer sends a new link to the payee. This works when the payee needs to access the form again but their existing submission is still valid.

  • Reset W-8BEN state: Use this (admin-only) workflow when the existing form data must be cleared—wrong form submitted, skipped form, stale record, or incorrect LLC status.

For payees asking about updating their W-8BEN, direct them to contact their payer first. The payer can resend the form link or escalate to support if a reset is needed.

Related content

Was this helpful?
Was this helpful?