Bonus templates

All endpoints below require:

X-Application-Id
X-Api-Key

Bonus templates define reusable tiered view bonuses for campaign creator contracts. The legacy contract endpoint that accepted paymentTermTemplateId is deprecated. To use a template through the API, read its scope and tiers and put those values into bonusPayment on the unified human-readable contract-history endpoint.

These endpoints configure tiered campaign bonuses. They do not issue a payout. POST /sdk/v1/payouts/trigger is still a direct payout endpoint and only pays the explicit payoutAmount or lineItems you send.

Bonus flow

Create a bonus template with thresholds and amounts.
Read the creator’s current contract and its versionId.
Copy the template’s scope and tiers into the contract’s bonusPayment.
Write the complete contract with basedOnVersionId.
Add tracked campaign media for those creators.
Grade calculates eligible tiered bonus line items from tracked views and the contract’s bonus settings.

GET /sdk/v1/bonus-templates

List active tiered bonus templates for your agency.

Query parameters

boolean

default:"false"

Include templates hidden by DELETE /sdk/v1/bonus-templates/:templateId.

Response

{
  "success": true,
  "data": [
    {
      "templateId": "ptt_...",
      "name": "Launch view bonus",
      "description": "Bonus for high-performing launch posts",
      "colorCode": "#22C55E",
      "currency": "USD",
      "metric": "VIEWS",
      "tierScope": "CREATOR",
      "tiers": [
        { "threshold": 100000, "amount": 50 },
        { "threshold": 500000, "amount": 250 }
      ],
      "components": [
        {
          "type": "TIERED",
          "currency": "USD",
          "metric": "VIEWS",
          "tier_scope": "CREATOR",
          "tiers": [
            { "threshold": 100000, "amount": 50 },
            { "threshold": 500000, "amount": 250 }
          ]
        }
      ],
      "isDefault": false,
      "hidden": false,
      "createdAt": "2026-05-19T12:00:00.000Z",
      "updatedAt": "2026-05-19T12:00:00.000Z"
    }
  ]
}

GET /sdk/v1/bonus-templates/:templateId

Fetch one tiered bonus template.

Path parameters

string

required

Bonus template ID returned by create or list.

Query parameters

boolean

default:"false"

Allow fetching a hidden template.

Common errors

404: template not found, belongs to another agency, is hidden, or is not a tiered bonus template

POST /sdk/v1/bonus-templates

Create a tiered bonus template.

Body

{
  "name": "Launch view bonus",
  "description": "Bonus for high-performing launch posts",
  "colorCode": "#22C55E",
  "currency": "USD",
  "metric": "VIEWS",
  "tierScope": "CREATOR",
  "tiers": [
    { "threshold": 100000, "amount": 50 },
    { "threshold": 500000, "amount": 250 }
  ]
}

string

required

Display name. Names must be unique among visible bonus templates for the agency.

string

Optional description.

string

required

Six-digit hex color, such as #22C55E.

string

required

Bonus payout currency. All tiers in one template use the same currency.

string

default:"VIEWS"

Must be VIEWS. Other metrics are rejected because they are not supported by the payout calculator.

string

default:"CREATOR"

How views are counted for the bonus. Use CREATOR, MEDIA, or BEST_MEDIA.

object[]

required

Threshold/amount pairs. Each threshold and amount must be a non-negative number.

boolean

default:"false"

Marks this template as an agency default for selection UIs.

You can also send raw tiered components instead of currency plus tiers:

{
  "name": "Per-video bonus",
  "colorCode": "#0EA5E9",
  "components": [
    {
      "type": "TIERED",
      "currency": "USD",
      "metric": "VIEWS",
      "tier_scope": "MEDIA",
      "tiers": [
        { "threshold": 250000, "amount": 100 }
      ]
    }
  ]
}

Response

Returns 201 with the created template in data.

Common errors

400: missing name, color, currency, tiers, or invalid tier values
400: metric is not VIEWS
400: component type is not TIERED
409: a visible template with this name already exists

PATCH /sdk/v1/bonus-templates/:templateId

Edit a tiered bonus template. PUT is also accepted with the same body.

Body

Send at least one updatable field:

name
description
colorCode
tiers
components
tierScope
isDefault

{
  "name": "Launch view bonus v2",
  "applicablePostsUploadedOnOrAfter": "2026-07-24",
  "tiers": [
    { "threshold": 100000, "amount": 75 },
    { "threshold": 500000, "amount": 300 }
  ]
}

string

Required when changing tiers on a template that is already applied to creator contracts. The same date creates the new bonus-term history boundary for every linked contract.

If a template is already applied to creator contracts, you can only edit TIERED threshold and amount values, and you must provide applicablePostsUploadedOnOrAfter. Currency, metric, component shape, and tierScope are locked until those contracts use a different template.

Common errors

400: no updatable fields
400: invalid tier values or non-tiered components
400: missing or invalid applicablePostsUploadedOnOrAfter for an in-use tier change
400: attempted currency, metric, or scope change while the template is applied
409: a visible template with this name already exists
409: template is locked by a pending payout approval

DELETE /sdk/v1/bonus-templates/:templateId

Hide a tiered bonus template from future selection.

Delete is a soft delete. Hidden templates stay available to existing calculations if they were already applied to contracts.

Response

{
  "success": true,
  "message": "Deleted"
}

Use a bonus template in a contract

After you create or fetch a template, read the creator’s contract history, copy the template values into bonusPayment, and submit the complete contract. Map tierScope to appliesTo as follows: CREATOR → CREATOR, MEDIA → POST, and BEST_MEDIA → BEST_POST. For a template with tierScope: "MEDIA", use appliesTo: "POST":

{
  "basedOnVersionId": "CCCH_CURRENT",
  "effectiveDate": "2026-05-01",
  "contract": {
    "...": "all fields returned by the contract-history GET",
    "bonusPayment": {
      "appliesTo": "POST",
      "pays": "CAMPAIGN_COMPLETION",
      "rules": [
        {
          "currency": "USD",
          "conversionPolicy": null,
          "metric": "VIEWS",
          "tiers": [
            { "minimum": 100000, "amount": 50 },
            { "minimum": 500000, "amount": 250 }
          ]
        }
      ]
    }
  }
}

See Create a contract version for the required complete contract shape and stale-write safeguard.

SDK v1

Campaign management

Bonus flow

GET /sdk/v1/bonus-templates

Query parameters

Response

GET /sdk/v1/bonus-templates/:templateId

Path parameters

Query parameters

Common errors

POST /sdk/v1/bonus-templates

Body

Response

Common errors

PATCH /sdk/v1/bonus-templates/:templateId

Body

Common errors

DELETE /sdk/v1/bonus-templates/:templateId

Response

Use a bonus template in a contract

​Bonus flow

​GET /sdk/v1/bonus-templates

​Query parameters

​Response

​GET /sdk/v1/bonus-templates/:templateId

​Path parameters

​Query parameters

​Common errors

​POST /sdk/v1/bonus-templates

​Body

​Response

​Common errors

​PATCH /sdk/v1/bonus-templates/:templateId

​Body

​Common errors

​DELETE /sdk/v1/bonus-templates/:templateId

​Response

​Use a bonus template in a contract

Bonus flow

GET /sdk/v1/bonus-templates

Query parameters

Response

GET /sdk/v1/bonus-templates/:templateId

Path parameters

Query parameters

Common errors

POST /sdk/v1/bonus-templates

Body

Response

Common errors

PATCH /sdk/v1/bonus-templates/:templateId

Body

Common errors

DELETE /sdk/v1/bonus-templates/:templateId

Response

Use a bonus template in a contract