Campaigns

Campaigns hold the defaults that the rest of the platform falls back to: the default commission, the cookie attribution window, the active date range and whether new affiliates need approval. Most fields are optional at creation time and can be updated later with PATCH /api/v1/campaigns/{id}.

Endpoints

Fields

The create body (CreateCampaignDto) accepts the following. Only title is required; everything else is optional.

• title — required, up to 160 characters.
• description — optional free text.
• startDate — optional ISO 8601 date-time string.
• endDate — optional ISO 8601 date-time string.
• defaultCommissionType — optional, one of PERCENTAGE or FIXED.
• defaultCommissionValue — optional decimal string (e.g. "15" or "250.00").
• cookieDurationDays — optional integer, 0–365.
• allowedTrafficSources — optional array of strings.
• termsAndConditions — optional free text.
• approvalRequired — optional boolean.

Commission setup

Commission resolves through a hierarchy, most specific first: product → campaign default → merchant default → platform default. The campaign default (defaultCommissionType plus defaultCommissionValue) applies when a product attached to the campaign sets no commission of its own. If a product defines its own commission, that product value wins over the campaign default. See Products for per-product overrides.

Cookie duration

cookieDurationDays (0–365) sets the attribution window: how long after a click a conversion is still credited to the referring affiliate. A value of 0 means last-click only with no persisted window. See Conversions for how attribution is applied at conversion time.

Start & end dates

startDate and endDate are optional ISO strings that bound when a campaign is live. A campaign whose endDate is in the past is treated as expired — its links stop converting regardless of stored status. Leave both unset for an open-ended campaign.

Status rules

A new campaign starts in DRAFT. Move it to ACTIVE by calling POST /api/v1/campaigns/{id}/activate, and to PAUSED with POST /api/v1/campaigns/{id}/pause. A paused campaign can be reactivated. Campaigns also reach EXPIRED (past endDate) and ARCHIVED (set via PATCH).

Product association

Products are not listed inside the campaign body. Instead, attach a product to a campaign by setting that product's campaignId (see Products). An attached product inherits the campaign's commission default unless it defines its own.

Public vs private campaigns

Campaigns are private by default and are visible only to you and to the affiliates you work with. A merchant or admin can opt a campaign into the PUBLIC marketing listing through the dashboard. Only campaigns that are opted in and active and approved appear in the public listing.

Endpoint reference

{
  "title": "Dashain Sale",
  "defaultCommissionType": "PERCENTAGE",
  "defaultCommissionValue": "12",
  "cookieDurationDays": 30,
  "approvalRequired": false
}

{
  "id": "uuid",
  "campaignCode": "CMP-AB12CD",
  "title": "Dashain Sale",
  "status": "DRAFT"
}

{
  "defaultCommissionValue": "15",
  "cookieDurationDays": 45
}