Filing eBay VeRO notices by API: how programmatic NOCI works (attestation first)

If you already run a VeRO program, you know the shape of the work: find the infringing listing, build the notice, and then do the clerical part — log into the VeRO Portal and paste, or compose an email to vero@ebay.com. The judgment is in the first two steps. The third is transcription, and transcription is exactly the kind of step that goes to an API. This post covers what the VeRO API actually changes, what it needs from you first, and — the part that matters in a legal-liability workflow — what it deliberately does not change. For how the VeRO program itself works (enrollment, what qualifies, counter-notices), read the VeRO program guide first; this is the API layer on top of it.

What manual step does the API replace?

Nothing about drafting or reviewing a NOCI moves. What moves is the submission channel. A VeRO takedown in Brand Protector has three possible submission_method values, chosen per tenant by what that tenant has connected:

The API path is strictly additive: the human-readable NOCI body is still generated for every takedown — it’s the record, and the fallback if a tenant later disconnects. The API branch just carries the extra structured fields (reason-code ids, message to seller, country) the endpoint needs alongside it.

What do you need before API filing works?

Two things, and they are separate grants that fail in different places. Getting this distinction wrong is the single most common source of “I connected it but nothing files” confusion.

• VeRO Program membership, then API reporting on your account. Membership is a legal enrollment — you email a completed NOCI plus proof of IP ownership to vero@ebay.com. No software files that for you. Separately, the exact eBay user account you connect needs an API-reporting subscription, which is bound to that user id, not to your brand or to our app.
• An OAuth connection from that account.A workspace owner or admin connects the eBay account once from Settings → Legal. eBay redirects back, we store a per-tenant refresh token in Secret Manager, and short-lived access tokens are minted on demand and never stored.

Here is the trap the integration is built around: OAuth connect succeeds even for an account that has membership but notthe API-reporting subscription. The consent screen, the callback, the “Connected” badge all complete — and the entitlement failure only surfaces at the first filing, as an HTTP 403. So a connect-time probe checks entitlement up front and the card warns you before you ever draft. (Verified against eBay on 2026-07-10; entitlement is a per-account state that consent-time OAuth never checks.)

The connect → attest → file flow, step by step

1. Connect once. An owner or admin clicks Connect eBay VeRO APIin Settings → Legal. That starts an OAuth flow; on return we stamp the account as connected and run the read-only entitlement probe. If the probe (or a later Re-check) comes back not_entitled— eBay’s own 403 verdict — the card shows the remediation and drafts fall back to portal or email until it’s fixed.
2. Draft and review as always.The detection is confirmed, a human reviews it (the anti-rubber-stamp step), and the NOCI body is generated. Nothing about this is API-specific — it’s the same flow the portal and email methods use.
3. Attest.At admin attestation the operator sees the exact eBay reason code and eBay’s brief text they’re swearing to, and confirms the specific identifier. This is the only place the sworn good-faith certification is captured, because eBay’s API request body has no declaration field. It runs before the call — never after.
4. File. The instant attestation passes, the app mints an access token and calls createVeroReport. On a 201, eBay’s write-once report id is persisted as the takedown’s reference number, an audit row is written, and the takedown moves to submitted.
5. Check status when you want it. eBay reports asynchronously with no inbound reply to parse, so a Check status action calls getVeroReport by the stored id on demand and reads back the report and item status.

Which reason code gets sent, and why the conservative one?

eBay’s VeRO reasons are a fixed, per-marketplace code list. Brand Protector maps its two honest claim types to the least-overclaiming codes available:

• Trademark → 9038 — “listing contains unlawful use of trademark.” Deliberately not9036 (“item is a counterfeit product which infringes a trademark”). Your monitoring establishes unlawful use of your mark; it does not, on its own, prove the physical good is counterfeit. Claiming the narrower, provable thing is the defensible posture — overclaiming counterfeit is precisely the kind of statement that draws a bad-faith-notice challenge.
• Copyright → 9046 — “listing contains unlawful copy of copyrighted image.” Our copyright detections are image-similarity based, so the image code is the precise claim rather than a broader copyright assertion.

These are EBAY_US ids verified against eBay’s getVeroReasonCodeson 2026-07-09 and treated as pinned constants, not fetched live at submit time. Because reason codes are per-marketplace and can change, they carry a re-verify-before-expansion note in the code — and the operator sees the chosen code plus eBay’s own brief text in the attestation modal, so nothing is filed behind their back.

What does eBay decide, not us?

This is where honesty about an external system matters most. The connect-time probe stamps one of three entitlement states, and only one of them is treated as certain:

• not_entitledis definitive — it only ever comes from eBay’s own 403 (errorId 235002 “subscription missing” or 235003 “insufficient subscription level”), via the probe, a Re-check, or a real filing. It drives behavior: newly drafted eBay VeRO takedowns fall back to portal or email automatically.
• entitled is advisory. It means the read probe reached VeRO resource resolution without hitting the entitlement gate — an inference that filing shouldwork, not a promise from eBay. The filing path’s own 403 handling stays authoritative.
• unknownis exactly that — the probe couldn’t decide (a 5xx, a network or token failure, a timeout) or has never run. It never downgrades anything, and an inconclusive Re-check never overwrites a stored definitive verdict.

The plain-language version we hold ourselves to: filing should work; eBay gives the final verdict at your first filing.We don’t promise entitlement, and we don’t render a confident green state that eBay hasn’t actually confirmed. If a filing does 403, the takedown stays drafted — nothing is marked submitted — and you can retry or disconnect to fall back. That failure-stays-honest behavior is the same discipline behind keeping false positives out of your takedown pipeline in general.

Where the API fits your existing takedown discipline

The VeRO API doesn’t make takedowns hands-off. It removes one clerical step — the portal paste — from a workflow whose judgment steps are all still there. Every eBay VeRO notice clears the triple-validated gate before it’s filed, the same as an Amazon counterfeit report does, and the same evidence discipline applies: the evidence pack that backs the notice is built whether it goes out by API, portal, or email. What you gain is speed and a clean audit trail on the transmission itself — the report id comes straight back from eBay and lives on the takedown record.

eBay VeRO API filing ships in Brand Protector’s $199/mo all-in plan with a 7-day trial, alongside the marketplace takedown workflow across Amazon, Walmart, eBay and more. If you want to see the connect flow and the attestation gate in a real workspace, take the product tour or read how marketplace takedowns work end to end.

This is not legal advice. VeRO Program membership, API-reporting entitlement, reason-code definitions, and eBay’s intake process are eBay’s to define and can change; verify the current requirements with eBay and your own counsel before filing.

Frequently asked questions