Documentation / SDK v1

Bonus templates

Create, list, edit, and delete tiered bonus templates via /sdk/v1.

bonus templates · json
{
  "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"
    }
  ]
}
All documentation

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.

Bonus flow

  1. Create a bonus template with thresholds and amounts.
  2. Read the creator's current contract and its versionId.
  3. Copy the template's scope and tiers into the contract's bonusPayment.
  4. Write the complete contract with basedOnVersionId.
  5. Add tracked campaign media for those creators.
  6. 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

includeHidden boolean query 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

templateId string path required

Bonus template ID returned by create or list.

Query parameters

includeHidden boolean query 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 }
  ]
}
name string body required

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

description string body

Optional description.

colorCode string body required

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

currency string body required

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

metric string body default VIEWS

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

tierScope string body default CREATOR

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

tiers object[] body required

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

isDefault boolean body 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 }
  ]
}
applicablePostsUploadedOnOrAfter string body

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.

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.

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.

Payout timing is a contract setting, separate from the template's tiers. Choose bonusPayment.pays as CAMPAIGN_COMPLETION, NOW, or NOW_AND_STOP. The last option makes the currently earned bonus payable and closes further tiers for that rule and payout scope after settlement. Read bonus payout timing before selecting it.

Describe your program.

Grade turns it into a program it can track and pay.