> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.usegrade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Campaign contracts

> Manage campaign creator contracts and payment terms via /sdk/v1.

All endpoints below require:

* `X-Application-Id`
* `X-Api-Key`

Contracts are **optional**. A campaign creator can exist and have media tracked without any contract or payment terms set. Contracts define how a creator gets paid for their work on a campaign.

For the human-readable contract timeline addressed by
`campaignCreatorRecordId`, see [Read contract history](/campaign-creators/contract-history)
and [Create a contract version](/campaign-creators/create-contract-version).

## Unified contract history

Contract history is an ordered timeline of complete, frozen payment-term
snapshots. An effective date is an inclusive upload/published business date:
media uploaded on or after that date uses that version until the next version
starts. Every write supplies one complete snapshot and identifies the version
it was based on; the API does not merge a partial payload with an older
version. The API never creates separate fixed, performance, bonus, or
pay-cycle history items.

Reserved, settled, and ambiguous payout coverage is protected. A history
mutation that could reprice, hide, or resurface that coverage returns `409`
with `errorCode: "CONTRACT_HISTORY_PROTECTED_BOUNDARY"` and an
`earliestAllowedEffectiveDate` explanation in the message. Previously paid
items remain paid.

### GET /sdk/v1/campaigns/:campaignId/creators/contract/history

Returns all active complete versions, their inclusive effective windows, the
protected payout boundary, and retained revision provenance.

Query parameter:

* `email` (required)

```json theme={null}
{
  "success": true,
  "data": {
    "campaignId": "camp_...",
    "creatorEmail": "creator@example.com",
    "campaignCreatorRecordId": "ccr_...",
    "contractInstanceId": "CCCI_...",
    "contractInstanceState": "OPEN",
    "protectedCoverage": {
      "protectedThroughUploadDate": "2026-06-12",
      "earliestAllowedEffectiveDate": "2026-06-13",
      "protectedEntitlementCount": 4,
      "stateCounts": { "SETTLED": 4 },
      "coverageKinds": ["MEDIA"]
    },
    "versions": [
      {
        "campaignCreatorContractHistoryId": "CCCH_...",
        "effectiveFromUploadDate": "2026-06-01",
        "effectiveThroughUploadDate": null,
        "isCurrent": true,
        "termsSnapshot": {
          "schemaVersion": 2,
          "contractInstanceId": "CCCI_...",
          "effectiveFromUploadDate": "2026-06-01",
          "payoutType": "FIXED",
          "currency": "USD",
          "fixed": {
            "active": true,
            "amount": "15",
            "paymentOption": "STANDARD",
            "rateScope": "CREATOR",
            "mediaPayoutMode": null,
            "platforms": [],
            "proratedByUploads": false,
            "prorationAssumedUploads": null,
            "minimumUploads": null,
            "prorateByTime": false,
            "upfrontPercentage": null
          },
          "performance": {
            "active": false,
            "amount": null,
            "unitSize": null,
            "unit": null,
            "viewScope": null,
            "minViews": null,
            "maxViews": null,
            "excludeMinimumViews": false,
            "payoutTiming": null,
            "spendCaps": {
              "amount": null,
              "scope": "NONE",
              "period": "LIFETIME"
            },
            "groupingMode": "NONE"
          },
          "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": ["phase5-writer:SDK_CONTRACT_ENDPOINT"]
          },
          "compatibility": {
            "state": "COMPLETE",
            "missingEvidence": []
          }
        }
      }
    ],
    "revisionHistory": []
  }
}
```

### POST /sdk/v1/campaigns/:campaignId/creators/contract/history

Uses one mutation contract for `CREATE`, `MOVE`, `REPLACE`, and `VOID`.

For `CREATE`, send the complete `desiredTerms` snapshot and the
`predecessorContractHistoryId` returned by the timeline GET. The server rejects
a stale predecessor rather than merging fields from different versions.

```json theme={null}
{
  "email": "creator@example.com",
  "operation": "CREATE",
  "contractInstanceId": "CCCI_...",
  "predecessorContractHistoryId": "CCCH_...",
  "effectiveFromUploadDate": "2026-06-13",
  "desiredTerms": {
    "schemaVersion": 2,
    "contractInstanceId": "CCCI_...",
    "effectiveFromUploadDate": "2026-06-13",
    "...": "all other complete snapshot fields"
  },
  "changeReason": "CPM rate increased"
}
```

For `MOVE`, send `campaignCreatorContractHistoryId`, the new effective date,
and one complete `desiredTerms` snapshot whose effective date matches the new
date. The existing immutable row is superseded in the same transaction that
inserts the moved version. The server rejects moves that cross another active
version or overlap reserved or settled payout coverage.

For `REPLACE`, send `campaignCreatorContractHistoryId`, the unchanged effective
date, and one complete `desiredTerms` snapshot. For `VOID`, send the history ID,
effective date, and reason, but omit `desiredTerms`.

Every active bonus component in `desiredTerms` must use `metric: "VIEWS"`.
Other metrics are rejected because the payout calculator does not support them.

## Deprecated campaign contract resource

The following legacy resource is fully deprecated:

* `GET /sdk/v1/campaigns/:campaignId/creators/contract`
* `PUT /sdk/v1/campaigns/:campaignId/creators/contract`
* `DELETE /sdk/v1/campaigns/:campaignId/creators/contract`

Every method returns `410 Gone`:

```json theme={null}
{
  "success": false,
  "errorCode": "SDK_CONTRACT_API_DEPRECATED",
  "message": "This endpoint has been deprecated. Use GET or POST /sdk/v1/campaign-creators/:campaignCreatorRecordId/contract-history immediately."
}
```

Use [Read contract history](/campaign-creators/contract-history) and
[Create a contract version](/campaign-creators/create-contract-version)
immediately. Those endpoints use the unified contract timeline and require a
complete, explicit human-readable contract plus stale-write protection.