save_playbook; see Lessons. The one historical exception is a storefront that retained its enabled Lessons-pilot marker: during the deprecation window, its v2 write is converted into proposed Lessons instead; after the window it returns 410 Gone.
What belongs here
Historical operating-instructions documents are readable. Each current fact has one writable home:
New versions that repeat facts owned by another field are rejected. Older immutable versions remain readable and return
ownershipIssues when a conflict is detected. A flagged older version cannot be reactivated; create a cleaned-up version instead. If a flagged version is already active, the conflicting lines are omitted from the Merchandising Agent’s runtime copy while the immutable saved version remains visible for cleanup. Structured Playbook pricing, Buyer Discounts, Buyer Instructions, the Listing, and AI Business Rules remain authoritative. A Product Marketing Media Kit is merchandising source material, not the owner of buyer-visible market configuration.
Versions are numbered per storefront. The first version is 1, and numbers are monotone and never reused. Activating a version does not delete older ones — they stay in history so you can re-read or re-activate a prior version.
All examples use the storefront base URL:
Authorization: Bearer $SCOPE3_API_KEY.
Deciding whether to answer at all
Before the Merchandising Agent composes anything, it decides whether this brief is yours to answer: pitch it in full, counter-pitch it with a credible reframe, or pass with a short branded decline. Those thresholds and the buyer-decline mode are structured selling settings, with their own immutable revision history. See Selling doctrine for the settings, the named starting points, and how to test a change before you activate it.Buyers do not see your rules
Historical operating instructions and Lessons are confidential to you. Approved Lessons steer how the Merchandising Agent composes; proposed Lessons have no effect until a seller account admin approves them. None of them are ever sent to a buyer or a buyer’s agent, and everything the agent does send a buyer is written in market terms rather than by quoting your rulebook. That splits the explanation of why a proposal looks the way it does into two audiences:
So a rule that keeps video out of a proposal reaches the buyer as “video is not part of this proposal”, never as your rule text. The same separation covers component and product ids, signal-vendor names, and setup vocabulary: they are yours, and they stay on your side of the conversation.
Telling buyers why a brief was declined
When a brief matches none of your inventory, whether the buyer hears why is your call — it is a negotiation decision, not a platform default. “Your budget is below what we can sell this inventory for” invites a better bid; sometimes you want that, sometimes you would rather say nothing. By default your storefront says nothing: the buyer is told that no products matched and how to broaden the brief. Authorize a fuller answer by writing the rule here, in your own terms — for example:Task reference
Legacy create endpoint
POST /operating-instructions — direct version write, with a historical pilot exceptionGet active version
GET /operating-instructions/active — the version in force nowLegacy activate endpoint
POST /operating-instructions/{version}/activate — direct activation, with a historical pilot exceptionSelling doctrine
Pitch, counter-pitch, or pass — the qualification judgment on the same versions