Replace a resource's SEO override
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Headers
A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.
Body
A FULL REPLACE, not a merge, which is why this is PUT and not PATCH. Every field you omit is CLEARED: there is no COALESCE anywhere in the upsert, so a title-only body wipes the description, the og image and the canonical url. Read the override first and send it back whole. The write is an UPSERT on the (resource_type, resource_id) pair in the path, so replaying the same body converges rather than accumulating, and it answers 200 on both the first write and every replay: the status never tells you whether an override already existed. A resource_id naming nothing is ACCEPTED rather than 404, because the column carries no foreign key to any catalogue table, which is what lets an import write SEO ahead of the products it describes. THE STOREFRONT CHANGES IMMEDIATELY. The override is read at render time and never snapshotted, so there is no draft, no preview and no publish step, and this family emits no webhook topic: a client reconciling has to poll. IT WRITES THE SOURCE LANGUAGE ONLY. A translated meta title is dropped once the source it recorded no longer matches what is stored here, so editing a title through this route silently disables its translations until they are rewritten through PUT /api/v1/translations, under the field names meta_title and meta_description on the same (resource_type, resource_id). LAST WRITE WINS. There is no If-Match and no version, so replaying an old body after a newer write reverts the row.
REQUIRED, and the only required field. true asks search engines not to index the resource. It is required because an absent key and an explicit false are indistinguishable once decoded, so accepting the omission would let any title-only write put a resource the merchant deliberately hid back into search results with nothing on the storefront looking any different. It is the tripwire that teaches you this route is a full replace before the replace can cost you anything.
The meta title override. Omit it or send null to CLEAR it, which returns the resource to its own catalogue title rather than blanking anything. Empty string and null are the same stored state, because the column is NOT NULL DEFAULT '' and there is no distinct empty title to preserve.
255The meta description override. Omitting it clears it, exactly as for title.
500Absolute http(s) URL, or empty. A relative path is refused rather than stored: it would be pasted into a head tag on a domain this API does not know and would resolve somewhere nobody intended.
2048Absolute http(s) URL, or empty. Same validation as og_image_url.
2048Response
Success