Offers

Reuse structured value propositions, proof points, pricing shape, ICP hints, and deal-stage fit across GTM work.

An Offer is the organization-scoped catalog object for what a brand sells. It gives Playbooks, Campaigns, templates, and Outcome attribution one structured source of selling context. Creating or reading an Offer performs no research, pricing calculation, provider call, or outbound action.

Create an offer#

Operation create_offer_v1_offers_post requires an active brand_profile_id and name. An optional stable key is derived from the name when omitted.

OFFER=$(curl --fail-with-body --silent --show-error \
  --request POST "$BLACKPEARL_API_BASE_URL/v1/offers" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{
    \"brand_profile_id\": \"$BRAND_ID\",
    \"name\": \"AI SDR co-pilot\",
    \"key\": \"ai_sdr_copilot\",
    \"description\": \"Evidence-backed research, qualification, and drafting for SDR teams.\",
    \"value_props\": [\"Cut account research from hours to minutes\"],
    \"proof_points\": [\"Customer-approved proof point\"],
    \"pricing_model\": \"Per-seat subscription\",
    \"icp\": {
      \"industries\": [\"B2B SaaS\"],
      \"company_sizes\": [\"51-200\"],
      \"regions\": [\"ANZ\"],
      \"personas\": [\"VP Sales\"],
      \"signals\": [\"Hiring SDRs\"]
    },
    \"stage_fit\": [\"cold_outreach\", \"discovery\"],
    \"status\": \"active\"
  }")

OFFER_ID=$(printf '%s' "$OFFER" | jq -er '.id')

Allowed stages are cold_outreach, discovery, evaluation, proposal, negotiation, closing, onboarding, expansion, renewal, and winback. icp is a closed object; unknown fields and credentials are rejected. pricing_model is descriptive text, not executable quote or discount logic.

Create is not an idempotent replay operation. A duplicate key returns offer_key_exists; after an ambiguous network failure, list and match by key before retrying.

Read and reuse offers#

Operation list_offers_v1_offers_get returns up to 200 organization offers. include_archived=true includes catalog entries retained for historical attribution. Operation get_offer_v1_offers__offer_id__get returns one Offer in the caller's organization.

Pass an active offer_id to Playbooks or bind it to a Campaign. Record the same ID on Outcomes and group insights by offer to measure which selling proposition is landing. Archived Offers remain readable historical attribution targets but cannot be selected for new generation work.

Common failures include brand_profile_not_found, brand_profile_archived, offer_key_exists, offer_limit_exceeded, invalid field or stage values, and offer_not_found. Follow Errors and safe retries.