Skip to main content
Skill buy-from-seller · version 1.0.0 · for buyers.

​
When to use

  • A person says “buy on Larkstone Media” or otherwise names the seller they want.
  • A person has a direct deal in mind and wants it staged on a campaign.
  • A seller is missing from a proposal request and the person wants to know why.
To send a brief to every eligible seller instead, use Set up a campaign.

​
Before you start

  • The account is ready to buy and the advertiser exists.
  • A draft campaign exists for the work, or you have what Set up a campaign needs to create one.

​
Steps

  1. Call get_status and confirm the account and advertiser.
  2. Find the seller with search and kind: "seller", then call get with kind: "seller" and its id. Add include: ["products"] when the person wants to see the catalog.
  3. Call open_connections_page with the sellerId so the person sees the seller’s status for this advertiser.
  4. If the seller is not active for the advertiser, call save_connection with target: { kind: "seller", id } and advertiserActivation with the advertiserId and decision: "ENABLED". If the person wants the seller on every brief, send selection: "ALWAYS_INCLUDE" in a separate call.
  5. Choose a path with the person:
    • Proposal. Call request_proposals with campaignId, expectedCampaignRevision, expectedSellerId set to the seller’s id, and an idempotencyKey. Collect results as in Set up a campaign, then call refine_proposal for any change the person asks for.
    • Products. Pick products and pricing options from the seller’s catalog with the person.
  6. Stage the buy with save_media_buy:
    • from a proposal: fromProposalId and an idempotencyKey;
    • from products: campaignId, sellerId, products (each with productId, pricingOptionId and budget), optionally flight, and an idempotencyKey.
  7. Call open_campaign_receipt to show the staged buy. Launch belongs to Manage a campaign.

​
Guardrails

  • Reach the seller only through Semicola tools. Do not guess or call a seller’s own agent URL.
  • If the seller is excluded for the account, or not available in the advertiser’s countries or channels, tell the person instead of changing their settings on your own.
  • Respect the seller’s answer. A seller may decline a refinement or a price below its floor.
  • A staged buy books nothing. Do not describe it as bought.

​
Done when

  • The draft campaign has a staged media buy with the named seller, and the person has seen it on the receipt; or
  • you have told the person why that seller cannot take this buy, and what would change that.