Documentation / Syncing

Contract versions

Incrementally sync contract versions with complete records, removals, and durable cursors.

contract versions · bash
curl --get "$BASE_URL/sdk/v1/campaigns/$CAMPAIGN_ID/contracts/sync" \
  -H "X-Application-Id: $APP_ID" \
  -H "X-Api-Key: $API_KEY" \
  --data-urlencode "limit=100"
All documentation

GET /sdk/v1/campaigns/:campaignId/contracts/sync

Sync contract history across an entire campaign without requesting each creator separately. Each version is a separate record, so large histories are paginated. Replace by id, which equals campaignCreatorContractHistoryId.

Requires X-Application-Id, X-Api-Key, and campaigns:read. Follow the shared syncing workflow for pagination, cursor storage, retries and removals. Only cursor and limit are accepted.

curl --get "$BASE_URL/sdk/v1/campaigns/$CAMPAIGN_ID/contracts/sync" \
  -H "X-Application-Id: $APP_ID" \
  -H "X-Api-Key: $API_KEY" \
  --data-urlencode "limit=100"

On subsequent requests, add --data-urlencode "cursor=$SAVED_CURSOR".

Record format

Each item in data is a complete replacement with these fields:

{
  "id": "CCCH_123",
  "campaignCreatorContractHistoryId": "CCCH_123",
  "campaignId": "CAMPAIGN_123",
  "campaignCreatorRecordId": "CCR_123",
  "creatorProfileId": "CP_123",
  "contractInstanceId": "CCI_123",
  "contractInstanceState": "OPEN",
  "isCurrentInstance": true,
  "effectiveFromUploadDate": "2027-01-01",
  "status": "ACTIVE",
  "schemaVersion": 2,
  "semanticHash": "75109c26d59db01613e34605d7f76299b7ef9942aa4f4cc655f42fc6f7eabd64",
  "termsSnapshot": {
    "schemaVersion": 2,
    "contractInstanceId": "CCI_123",
    "effectiveFromUploadDate": "2027-01-01",
    "payoutType": "NONE",
    "currency": "USD",
    "fixed": {
      "active": false,
      "amount": null,
      "paymentOption": null,
      "upfrontPercentage": null,
      "proratedByUploads": false,
      "prorationAssumedUploads": null,
      "minimumUploads": null,
      "prorateByTime": false,
      "rateScope": null,
      "platforms": [],
      "mediaPayoutMode": null
    },
    "performance": {
      "active": false,
      "amount": null,
      "unitSize": null,
      "unit": null,
      "viewScope": null,
      "minViews": null,
      "maxViews": null,
      "excludeMinimumViews": false,
      "spendCaps": {
        "amount": null,
        "scope": "NONE",
        "period": "LIFETIME"
      },
      "groupingMode": "NONE",
      "payoutTiming": null
    },
    "crosspost": {
      "minDistinctPlatforms": 1,
      "requiredPlatforms": [],
      "captionFilter": null
    },
    "bonus": {
      "active": false,
      "payoutTiming": null,
      "tierScope": null,
      "components": [],
      "templateProvenance": null
    },
    "payCycle": {
      "active": false,
      "timesPerPeriod": null,
      "period": null,
      "weekday": null,
      "monthDay": null,
      "startImmediately": false,
      "firstDueAt": null,
      "timeZone": "UTC"
    },
    "eligibility": {
      "uploadedOnOrAfter": null,
      "postTestPhaseUploadCutoff": null,
      "testPhaseCreator": false
    },
    "provenance": {
      "source": "AUTHORED",
      "sourceIds": []
    },
    "compatibility": {
      "state": "COMPLETE",
      "missingEvidence": []
    }
  },
  "supersedesContractHistoryId": null,
  "createdAt": "2026-10-26T10:00:00.000Z",
  "retiredAt": null,
  "timeZone": "UTC"
}

termsSnapshot contains the complete stored contractual terms, interpreted according to schemaVersion. The example above is a valid version with no active payment components. The contract history endpoint presents these terms in its public display format. semanticHash describes those terms. This feed excludes internal author IDs, repair references, and audit reasons outside the terms snapshot.

Versions include future effective dates, superseded/voided versions, and previous contract instances for available memberships. isCurrentInstance identifies the membership's current instance; it does not mean that the version governs every upload or is already effective. contractInstanceState is OPEN or CLOSED; version status is ACTIVE, SUPERSEDED, or VOIDED.

Keep effective dates locally. A future version is delivered when created; merely reaching that date does not change the stored version or emit a new record. Contract terms are governed by upload dates and the returned campaign/agency timeZone, not just the polling date. Use the existing contract read and payout preview endpoints when you need Grade's current interpretation or payable value.

Edits, retirement, replacement, instance closure, changes to the current instance, and timezone changes produce replacements. A superseded version stays in the feed with its status; physical deletion or an unavailable membership produces a removal. A membership without history contributes no version records.

Stored terms schema

termsSnapshot is the versioned stored contract, distinct from the display contract object on the contract-history list. Persist the entire object, including fields added in later schema versions.

Field Contents
schemaVersion, contractInstanceId, effectiveFromUploadDate Version and governing identity/date.
payoutType, currency Payment type and contract currency.
fixed Active flag, decimal amount, payment option, creator/media scope, supported platforms and proration settings.
performance Active flag, decimal rate, unit size, view thresholds, spend caps, grouping and payout timing.
crosspost Required platforms, minimum distinct platforms and caption filter.
bonus Active flag, timing, scope, tier components and template provenance.
payCycle Recurrence, first due date and timezone.
eligibility Upload cutoff and test-phase eligibility facts.
provenance, compatibility Origin references and whether historical evidence is complete. These are stored version facts, not payment authorization.
contentStart, paymentRules Present on rule-based contract versions; preserve the stored rule tree.

An inactive component has active: false; its other fields can be null. Contractual decimal values in the stored snapshot are strings. Do not derive payout totals by applying only part of the snapshot. Grade's payout preview accounts for the full rules, upload dates and settlement history.

Describe your program.

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