Documentation / Campaign management / Campaign creators

Create a campaign creator contract version

Add a dated contract version to a campaign creator's contract timeline.

create a campaign creator contract version ยท bash
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
        }
      }
    }
  }'
All 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 in YYYY-MM-DD format.
  • basedOnVersionId (required): the versionId of the contract version that currently governs effectiveDate. Get it from Read campaign creator contract history. Send an explicit JSON null only when that response has an empty history and both current and nextScheduled are null. 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, or RULES. A classic type must match the enabled payment sections. RULES carries its payments in paymentRules instead; see Simplified payment terms.
  • currency (required): USD, EUR, GBP, CAD, AUD, CHF, JPY, HKD, NZD, CNY, INR, or SGD.
  • fixedPayment (required): a complete fixed-payment object, or null.
    • currency: the currency in which the fixed amount is authored.
    • conversionPolicy: null when this matches contract.currency; otherwise it must be LEGACY_PAYMENT_REPOSITORY_FX.
    • amount: payment amount.
    • per: CREATOR or POST.
    • calculation: STANDARD, PER_POST, SPLIT, PRORATED, or UPLOAD_THRESHOLD.
    • Also required: upfrontPercentage, expectedPosts, minimumPosts, prorateByTime, platforms, and crossposts. Use null, false, or [] when a field does not apply.
    • upfrontPercentage is non-null only for SPLIT; expectedPosts is non-null only for PRORATED; minimumPosts is non-null only for UPLOAD_THRESHOLD; crossposts is EACH_POST or ONE_PAYMENT_PER_GROUP only for PER_POST, and otherwise is null. prorateByTime can be true only for STANDARD, and platforms must be empty when per is CREATOR.
  • cpmPayment (required): a complete view-based payment object, or null.
    • Required: currency, conversionPolicy, rate, perViews, viewsFrom, minimumViews, maximumViews, excludeMinimumViews, maximumSpend, crossposts, and pays. Currency rules are the same as fixed payments.
    • maximumSpend is null or an object containing amount, per (CREATOR or POST), and period (LIFETIME, DAY, WEEK, or MONTH).
    • crossposts is EACH_POST, BEST_POST, or COMBINE_POSTS. pays is CAMPAIGN_COMPLETION, NOW, or NOW_AND_STOP.
  • bonusPayment (required): complete bonus rules, or null.
    • appliesTo: CREATOR, POST, or BEST_POST.
    • pays: CAMPAIGN_COMPLETION, NOW, or NOW_AND_STOP. See bonus payout timing for when further tiers stop.
    • rules: VIEWS rules and their minimum/amount tiers. Every rule also requires currency and conversionPolicy under the same currency rules. VIEWS is the only supported metric.
  • crosspostRequirements (required): minimumPlatforms, requiredPlatforms, and captionContains, or null.
    • captionContains: a caption grouping override, or null to 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, and timeZone, or null.
    • Use weekday only for weekly schedules and dayOfMonth only for a once-monthly schedule. firstPaymentAt must be null when startsImmediately is true; otherwise provide an ISO timestamp.
  • postsUploadedOnOrAfter (required): a YYYY-MM-DD eligibility date or null.

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, or EUR.
  • paymentRules (required): the payment agreement, version 3.
  • fixedPayment, cpmPayment, bonusPayment, crosspostRequirements, and recurringPayment (required): null. Every payment, crosspost setting, and payout schedule is part of paymentRules.
  • postsUploadedOnOrAfter (required): the value of the version the new terms follow, which is null for a first contract. RULES terms 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: basedOnVersionId is omitted or invalid; it must be a governing version ID or explicit null for an empty timeline
  • 400: invalid date, incomplete contract, or unsupported contract terms
  • 401: missing or invalid SDK credentials
  • 403: a RULES contract for an agency without Simplified payment terms
  • 404: campaign creator record not found
  • 409 CONTRACT_VERSION_STALE: the governing contract version changed; read history again before retrying
  • 409: 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.

Describe your program.

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