All documentation
Documentation
All endpoints below require:
X-Application-IdX-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
- 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
includeHidden boolean query default falseInclude 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 requiredBonus template ID returned by create or list.
Query parameters
includeHidden boolean query default falseAllow 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 requiredDisplay name. Names must be unique among visible bonus templates for the agency.
description string bodyOptional description.
colorCode string body requiredSix-digit hex color, such as #22C55E.
currency string body requiredBonus payout currency. All tiers in one template use the same currency.
metric string body default VIEWSMust be VIEWS. Other metrics are rejected because they are not supported
by the payout calculator.
tierScope string body default CREATORHow views are counted for the bonus. Use CREATOR, MEDIA, or BEST_MEDIA.
tiers object[] body requiredThreshold/amount pairs. Each threshold and amount must be a non-negative number.
isDefault boolean body default falseMarks 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 values400: metric is notVIEWS400: component type is notTIERED409: 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:
namedescriptioncolorCodetierscomponentstierScopeisDefault
{
"name": "Launch view bonus v2",
"applicablePostsUploadedOnOrAfter": "2026-07-24",
"tiers": [
{ "threshold": 100000, "amount": 75 },
{ "threshold": 500000, "amount": 300 }
]
}
applicablePostsUploadedOnOrAfter string bodyRequired 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 fields400: invalid tier values or non-tiered components400: missing or invalidapplicablePostsUploadedOnOrAfterfor an in-use tier change400: attempted currency, metric, or scope change while the template is applied409: a visible template with this name already exists409: 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.
