# Offers

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

Canonical guide: <https://api.blackpearl.com/docs/offers>

Raw Markdown: <https://api.blackpearl.com/docs/raw/offers.md>

OpenAPI: <https://api.blackpearl.com/v1/openapi.json>

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.

```bash
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](https://api.blackpearl.com/docs/errors).