Campaigns

A Campaign is a hosted fundraising page with a goal, story, and a stream of contributions. Peer-to-peer sub-pages and matching gifts attach here.

The Campaign object

{
  "id":           "cmp_01HZ...",
  "name":         "Spring Build-a-Well Drive",
  "slug":         "spring-build-a-well",
  "description":  "12 wells, one season.",
  "story":        "Long-form markdown body.",
  "goal_cents":   7500000,
  "raised_cents": 4821300,
  "currency":     "USD",
  "status":       "live",
  "starts_at":    "2026-04-01T00:00:00Z",
  "ends_at":      null,
  "url":          "https://2026.bequest.org/c/spring-build-a-well",
  "created_at":   "2026-03-20T17:02:13Z"
}

POST /v1/campaigns

Create a campaign. Can launch immediately or save as draft.

Field	Type		Description
name	string	required	Display name.
goal_cents	integer	optional	Optional target. Renders progress bar when set.
description	string	optional	Short summary, used in social cards.
story	string	optional	Long-form body, plain text or simple markdown.
starts_at	string	optional	RFC 3339. Defaults to now when status is live.
ends_at	string	optional	RFC 3339. Optional close time.
status	string	optional	draft (default) or live.
branding	object	optional	Optional brand override: colors, hero image, button label.

Example request

curl -X POST https://api.bequest.org/v1/campaigns \
  -H "Authorization: Bearer $BQ_KEY" \
  -d '{
    "name":       "Spring Build-a-Well Drive",
    "goal_cents": 7500000,
    "story":      "12 wells, one season.",
    "status":     "live"
  }'

const campaign = await bq.campaigns.create({
  name:       'Spring Build-a-Well Drive',
  goal_cents: 7500000,
  story:      '12 wells, one season.',
  status:     'live',
});

campaign = bq.campaigns.create(
    name='Spring Build-a-Well Drive',
    goal_cents=7500000,
    story='12 wells, one season.',
    status='live',
)

$campaign = $bq->campaigns->create([
    'name'       => 'Spring Build-a-Well Drive',
    'goal_cents' => 7500000,
    'story'      => '12 wells, one season.',
    'status'     => 'live',
]);

campaign = bq.campaigns.create(
  name:       'Spring Build-a-Well Drive',
  goal_cents: 7_500_000,
  story:      '12 wells, one season.',
  status:     'live'
)

campaign, err := bq.Campaigns.Create(ctx, &bequest.CampaignCreateParams{
    Name:      "Spring Build-a-Well Drive",
    GoalCents: bequest.Int64(7500000),
    Story:     bequest.String("12 wells, one season."),
    Status:    bequest.String("live"),
})

Example response

{ "id": "cmp_01HZ...", "status": "live", "url": "https://2026.bequest.org/c/spring-build-a-well", ... }

Returns: The newly-created Campaign object.

GET /v1/campaigns/{id}

Retrieve a campaign by id.

Field	Type		Description
id	string	required	Campaign id, prefixed `cmp_`.

Example request

curl https://api.bequest.org/v1/campaigns/cmp_01HZ... -H "Authorization: Bearer $BQ_KEY"

const campaign = await bq.campaigns.retrieve('cmp_01HZ...');

campaign = bq.campaigns.retrieve('cmp_01HZ...')

$campaign = $bq->campaigns->retrieve('cmp_01HZ...');

campaign = bq.campaigns.retrieve('cmp_01HZ...')

campaign, err := bq.Campaigns.Retrieve(ctx, "cmp_01HZ...")

Example response

{ "id": "cmp_01HZ...", "raised_cents": 4821300, "status": "live", ... }

GET /v1/campaigns

List campaigns, filterable by status.

Field	Type		Description
status	string	optional	draft\|live\|paused\|ended\|archived
limit	integer	optional	Default 25.
cursor	string	optional	Pagination cursor.

PATCH /v1/campaigns/{id}

Update campaign fields. Same fields as POST, all optional.

Field	Type		Description
name	string	optional	New display name.
goal_cents	integer	optional	Updated target.
status	string	optional	Transition to live/paused/ended/archived.
story	string	optional	Updated body.

GET /v1/campaigns/{id}/contributions

List the gifts that funded a campaign.

Field	Type		Description
id	string	required	Campaign id.
limit	integer	optional	Default 25.
cursor	string	optional	Pagination cursor.

Returns: A page of Gift objects with `campaign_id` set.

Peer-to-peer pages

Sub-pages off a campaign use the same shape under /v1/campaigns/{id}/p2p_pages. Each carries its own raised total, optional goal, and URL.

Events

campaign.created
campaign.published
campaign.contribution — one event per gift, includes the gift body.
campaign.ended