## TL;DR

INVALID_REF_KEY means the vendor internal ID or external ID you sent does not resolve to a vendor record. Verify the vendor exists, is active, and that you are using the right key type: internal ID for internalId references, external ID only where the API supports it. Cache vendor ID mappings and refresh them when vendors are merged or inactivated.

## Error

```text
INVALID_REF_KEY: Invalid reference key [12345] for vendor
```

## Steps

1. Search for the vendor by name in NetSuite to confirm it exists and is active.
   Expected: The real vendor record or proof it is missing.
2. Check whether you sent an internal ID where an external ID was expected or vice versa.
   Expected: The key-type mismatch, if any.
3. Correct the reference and retry the call.
   Expected: A successful reference.
4. Cache the vendor internal ID keyed by your system's vendor code.
   Expected: No repeated lookups.
5. Handle vendor merges: update the cache when NetSuite merges duplicates.
   Expected: Stale IDs stop breaking integrations.

## When to use

- SuiteTalk or REST calls fail on vendor references
- Vendor sync from another system
- After vendor merges or cleanups

## When not to use

- Item, location, or subsidiary reference errors
- CSV import key errors (different messages)
- Permission errors

## Compatibility

NetSuite SuiteTalk SOAP and REST web services.

## Variant phrasings

### INVALID_REF_KEY vendor

### invalid reference key vendor NetSuite

### vendor internal ID invalid

## Root cause

Reference keys are validated against live records. Vendors get inactivated, merged, or created in the wrong subsidiary, and integrations holding stale IDs fail with INVALID_REF_KEY.

## Edge cases

- Vendors inactive fail the same way; check status
- External IDs are only unique per record type; scope the lookup
- Multi-subsidiary vendor records need the right subsidiary context

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_8i6g1c1H_fm0zINOlyzHZA