All documentation
Documentation
POST /sdk/v1/campaign-creators/:campaignCreatorRecordId/contract-history
Adds a contract version that becomes effective for media uploaded on or after the selected date. This is the same contract timeline used throughout Grade.
All requests require X-Application-Id and X-Api-Key.
Path parameter
campaignCreatorRecordId(required): the campaign creator whose contract you want to update.
Body
effectiveDate(required): a real date inYYYY-MM-DDformat.basedOnVersionId(required): theversionIdof the contract version that currently governseffectiveDate. Get it from Read campaign creator contract history. Send an explicit JSONnullonly when that response has an emptyhistoryand bothcurrentandnextScheduledarenull. This creates the first contract without guessing that the timeline is still empty.contract(required): the complete contract terms that should apply from that date.
Grade-managed test-phase cutoffs, template identity, and internal history IDs are intentionally not writable through this public shape. Existing values are preserved from the governing unified version; for a first contract, test-phase guards are copied from the creator record. Payment amounts, source currencies, conversion behavior, eligibility dates, grouping, timing, and schedules are all explicit in the request and are never inferred from omitted fields.
Contract fields
type(required):NONE,FIXED,PERFORMANCE,BONUS,HYBRID, orRULES. A classic type must match the enabled payment sections.RULEScarries its payments inpaymentRulesinstead; see Simplified payment terms.currency(required):USD,EUR,GBP,CAD,AUD,CHF,JPY,HKD,NZD,CNY,INR, orSGD.fixedPayment(required): a complete fixed-payment object, ornull.currency: the currency in which the fixed amount is authored.conversionPolicy:nullwhen this matchescontract.currency; otherwise it must beLEGACY_PAYMENT_REPOSITORY_FX.amount: payment amount.per:CREATORorPOST.calculation:STANDARD,PER_POST,SPLIT,PRORATED, orUPLOAD_THRESHOLD.- Also required:
upfrontPercentage,expectedPosts,minimumPosts,prorateByTime,platforms, andcrossposts. Usenull,false, or[]when a field does not apply. upfrontPercentageis non-null only forSPLIT;expectedPostsis non-null only forPRORATED;minimumPostsis non-null only forUPLOAD_THRESHOLD;crosspostsisEACH_POSTorONE_PAYMENT_PER_GROUPonly forPER_POST, and otherwise isnull.prorateByTimecan betrueonly forSTANDARD, andplatformsmust be empty whenperisCREATOR.
cpmPayment(required): a complete view-based payment object, ornull.- Required:
currency,conversionPolicy,rate,perViews,viewsFrom,minimumViews,maximumViews,excludeMinimumViews,maximumSpend,crossposts, andpays. Currency rules are the same as fixed payments. maximumSpendisnullor an object containingamount,per(CREATORorPOST), andperiod(LIFETIME,DAY,WEEK, orMONTH).crosspostsisEACH_POST,BEST_POST, orCOMBINE_POSTS.paysisCAMPAIGN_COMPLETION,NOW, orNOW_AND_STOP.
- Required:
bonusPayment(required): complete bonus rules, ornull.appliesTo:CREATOR,POST, orBEST_POST.pays:CAMPAIGN_COMPLETION,NOW, orNOW_AND_STOP. See bonus payout timing for when further tiers stop.rules:VIEWSrules and theirminimum/amounttiers. Every rule also requirescurrencyandconversionPolicyunder the same currency rules.VIEWSis the only supported metric.
crosspostRequirements(required):minimumPlatforms,requiredPlatforms, andcaptionContains, ornull.captionContains: a caption grouping override, ornullto disable it. Matching posts are grouped by the same local calendar day, using campaign timezone, then agency timezone, then UTC. This overrides the upload window and duration tolerance and permits multiple posts from the same platform. Read caption matching before using a hashtag shared by several videos. This differs from an account's tracking filter.
recurringPayment(required):paymentsPerPeriod,period,weekday,dayOfMonth,startsImmediately,firstPaymentAt, andtimeZone, ornull.- Use
weekdayonly for weekly schedules anddayOfMonthonly for a once-monthly schedule.firstPaymentAtmust benullwhenstartsImmediatelyistrue; otherwise provide an ISO timestamp.
- Use
postsUploadedOnOrAfter(required): aYYYY-MM-DDeligibility date ornull.
Bonus payout timing
Set bonusPayment.pays to one of:
| Value | Behavior |
|---|---|
CAMPAIGN_COMPLETION |
Wait until the media tracking window ends before the earned bonus becomes payable. |
NOW |
Make the currently earned bonus payable. Higher tiers can pay the additional amount later. |
NOW_AND_STOP |
Make the currently earned bonus payable. Once a positive bonus payout settles, stop all further tiers for that rule and payout scope within the current contract instance. |
NOW_AND_STOP is the API value for Now, stop after payout in Grade. It
controls bonus eligibility; saving the contract does not initiate a payout.
For appliesTo: "POST", a payout closes the rule only for the paid post or
crosspost group. Other posts or groups remain eligible. For CREATOR and
BEST_POST, it closes the rule across the creator's current contract instance,
including later uploads. Other bonus rules and manual bonuses are unaffected.
A pending approval or processing payout reserves that rule and scope against another payout. If the reservation is released after cancellation or failure, the scope becomes eligible again. After settlement, only a verified full reversal of that payout reopens it; a partial reversal does not.
Existing payouts and older approvals retain the timing recorded when they
were created. Changing the contract to NOW_AND_STOP does not retroactively
close scopes paid under NOW.
Simplified payment terms (RULES)
Agencies that use Simplified payment terms save terms as a payment agreement:
the agreement the Grade payment terms editor and the Grade assistant save. Send
it with "type": "RULES" and Grade stores the version exactly as the editor
would store the same terms on the same date.
A RULES contract sends the same eight fields as any contract, plus
paymentRules:
type:RULES.currency(required):USD,CAD,GBP, orEUR.paymentRules(required): the payment agreement,version3.fixedPayment,cpmPayment,bonusPayment,crosspostRequirements, andrecurringPayment(required):null. Every payment, crosspost setting, and payout schedule is part ofpaymentRules.postsUploadedOnOrAfter(required): the value of the version the new terms follow, which isnullfor a first contract.RULESterms keep that version's eligibility date, as the editor does, so this field cannot change it.
The new version also keeps the payout time zone of the version it follows. A first contract uses the campaign's effective time zone.
Start from an agreement you read: the history GET returns paymentRules on
every RULES version, and you can send it back with your changes. Each
element of rules is one payment component with an id, a name, and
parts:
Part kind |
Fields | Meaning |
|---|---|---|
PAYMENT (required) |
reward, amount, unitSize, tiers, tierMode |
FIXED pays amount; RATE pays amount per unitSize views; BONUS pays the reached tiers. |
SCOPE (required) |
scope |
What one payment counts: CREATOR, VIDEO (each post), or CROSSPOST_GROUP. |
MINIMUM |
minimumViews, excludeMinimumViews |
Views a post needs before it earns. |
VIEW_LIMIT |
maximumViews |
Views a payment for views counts at most. |
VIDEO_LIMIT |
videoLimit, period |
Posts paid at most. period is WINDOW. |
MONEY_LIMIT |
spendLimit, period, spendLimitScope |
Spend cap, for the creator (CREATOR) or each post (UNIT). period is WINDOW. |
SPLIT |
upfrontPercentage |
Part of a fixed payment paid upfront. |
CONDITIONS |
conditions |
Requirements such as a number of posts before payment. |
PLATFORMS |
platforms |
Platforms the component pays for. |
SELECTION |
selection, metric |
Count only the creator's best post. |
period sets the earning period for the whole agreement (window is ONCE,
ONGOING, DAY, WEEK, MONTH, or BATCH). qualification holds the
crosspost settings, and payout holds when earnings become payable. Every
part needs an id that is unique in the agreement. Grade validates the
agreement with the same rules as the editor and answers a refusal with
400 and a message that starts with contract.paymentRules:.
Daily, weekly, and monthly agreements need their own start date: their
effectiveDate must be 1901-01-01 or later, so they cannot use
1900-01-01, the date that covers every upload.
After a RULES version, send RULES terms. A classic type is refused after
RULES terms.
curl -sS "$BASE_URL/sdk/v1/campaign-creators/CCR_123/contract-history" \
-X POST \
-H "Content-Type: application/json" \
-H "X-Application-Id: $APP_ID" \
-H "X-Api-Key: $API_KEY" \
-d '{
"basedOnVersionId": null,
"effectiveDate": "2026-08-15",
"contract": {
"type": "RULES",
"currency": "USD",
"fixedPayment": null,
"cpmPayment": null,
"bonusPayment": null,
"crosspostRequirements": null,
"recurringPayment": null,
"postsUploadedOnOrAfter": null,
"paymentRules": {
"version": 3,
"period": { "window": "ONCE", "batchSize": 17 },
"rules": [
{
"id": "fixed_fee",
"name": "Fixed payment",
"parts": [
{ "id": "fixed_fee_pay", "kind": "PAYMENT", "reward": "FIXED", "amount": "500", "unitSize": 1000, "tiers": [], "tierMode": "HIGHEST" },
{ "id": "fixed_fee_scope", "kind": "SCOPE", "scope": "CREATOR" }
]
},
{
"id": "view_pay",
"name": "View payment",
"parts": [
{ "id": "view_pay_pay", "kind": "PAYMENT", "reward": "RATE", "amount": "2", "unitSize": 1000, "tiers": [], "tierMode": "HIGHEST" },
{ "id": "view_pay_scope", "kind": "SCOPE", "scope": "CREATOR" },
{ "id": "view_pay_cap", "kind": "MONEY_LIMIT", "spendLimit": "1000", "period": "WINDOW", "spendLimitScope": "CREATOR" }
]
}
],
"qualification": {
"platforms": [],
"captionIncludes": "",
"minimumPlatforms": 1,
"requiredPlatforms": [],
"groupViews": "BEST"
},
"payout": {
"timing": "NOW",
"date": null,
"schedule": "ON_DEMAND",
"weekdays": [1],
"monthDays": [15],
"stackMissed": true,
"prorateFirstPeriod": false,
"stopAfterPayment": false,
"remainderTiming": "AFTER_UPFRONT",
"remainderDate": null
}
}
}
}'
This saves a fixed payment of 500 USD and 2 USD per 1,000 views, capped at
1,000 USD for the creator. The response returns the saved contract, with
paymentRules as Grade stored it.
The agency must have Simplified payment terms. Otherwise a RULES contract is
refused with 403.
Example request
curl -sS "$BASE_URL/sdk/v1/campaign-creators/CCR_123/contract-history" \
-X POST \
-H "Content-Type: application/json" \
-H "X-Application-Id: $APP_ID" \
-H "X-Api-Key: $API_KEY" \
-d '{
"basedOnVersionId": "CCCH_CURRENT",
"effectiveDate": "2026-08-15",
"contract": {
"type": "HYBRID",
"currency": "USD",
"fixedPayment": {
"currency": "USD",
"conversionPolicy": null,
"amount": 500,
"per": "CREATOR",
"calculation": "STANDARD",
"upfrontPercentage": null,
"expectedPosts": null,
"minimumPosts": null,
"prorateByTime": false,
"platforms": [],
"crossposts": null
},
"cpmPayment": {
"currency": "USD",
"conversionPolicy": null,
"rate": 5,
"perViews": 1000,
"viewsFrom": "POST",
"minimumViews": 1000,
"maximumViews": null,
"excludeMinimumViews": false,
"maximumSpend": null,
"crossposts": "EACH_POST",
"pays": "NOW"
},
"bonusPayment": {
"appliesTo": "POST",
"pays": "NOW_AND_STOP",
"rules": [
{
"currency": "USD",
"conversionPolicy": null,
"metric": "VIEWS",
"tiers": [
{ "minimum": 1000, "amount": 10 },
{ "minimum": 10000, "amount": 50 },
{ "minimum": 100000, "amount": 100 }
]
}
]
},
"crosspostRequirements": null,
"recurringPayment": null,
"postsUploadedOnOrAfter": "2026-08-15"
}
}'
Response
Successful creation returns 201 with the public contract that was saved.
{
"success": true,
"data": {
"campaignId": "camp_123",
"campaignCreatorRecordId": "CCR_123",
"creatorProfileId": "CP_123",
"versionId": "CCCH_NEW",
"effectiveDate": "2026-08-15",
"contract": {
"type": "HYBRID",
"currency": "USD",
"fixedPayment": {
"currency": "USD",
"conversionPolicy": null,
"amount": 500,
"per": "CREATOR",
"calculation": "STANDARD",
"upfrontPercentage": null,
"expectedPosts": null,
"minimumPosts": null,
"prorateByTime": false,
"platforms": [],
"crossposts": null
},
"cpmPayment": {
"currency": "USD",
"conversionPolicy": null,
"rate": 5,
"perViews": 1000,
"viewsFrom": "POST",
"minimumViews": 1000,
"maximumViews": null,
"excludeMinimumViews": false,
"maximumSpend": null,
"crossposts": "EACH_POST",
"pays": "NOW"
},
"bonusPayment": {
"appliesTo": "POST",
"pays": "NOW_AND_STOP",
"rules": [
{
"currency": "USD",
"conversionPolicy": null,
"metric": "VIEWS",
"tiers": [
{ "minimum": 1000, "amount": 10 },
{ "minimum": 10000, "amount": 50 },
{ "minimum": 100000, "amount": 100 }
]
}
]
},
"crosspostRequirements": null,
"recurringPayment": null,
"postsUploadedOnOrAfter": "2026-08-15"
}
}
}
Safeguards
The endpoint applies the same contract-history safeguards as the Grade app. It will not add a version that changes protected paid or approved work, conflicts with another effective date, bypasses a pending payout approval, or changes a completed campaign where edits are not allowed.
The server also checks basedOnVersionId twice: once before validating the
contract and again in the transaction that writes it. For a first contract,
the explicit null assertion is also checked while the creator record is
locked. If the timeline changes between your read and write, the API returns
409 CONTRACT_VERSION_STALE.
Writing the same effectiveDate is allowed and replaces that date's version
when basedOnVersionId identifies the existing same-date version and all
other safeguards pass.
Common errors
400 CONTRACT_VERSION_REQUIRED:basedOnVersionIdis omitted or invalid; it must be a governing version ID or explicitnullfor an empty timeline400: invalid date, incomplete contract, or unsupported contract terms401: missing or invalid SDK credentials403: aRULEScontract for an agency without Simplified payment terms404: campaign creator record not found409 CONTRACT_VERSION_STALE: the governing contract version changed; read history again before retrying409: no existing contract covers the effective date, or the change crosses a protected contract boundary
Read the updated timeline with Read campaign creator contract history.
