> ## 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.

# Payment templates

> Manage full contract and bonus templates and apply them to campaign creators.

Reads require `campaigns:read`; create, edit, delete, and apply require `campaigns:write`. Every template and target must belong to the API key's agency. Responses contain JSON in `data`, not a JSON-encoded string. Template records retain their platform field names, including `template_id`, `template_kind`, `contract_terms`, and `rule_terms`.

## List, create, edit, and delete

| Method and path | Purpose |
| - | - |
| `GET /sdk/v1/payment-templates` | List templates; accepts `templateKind`, `includeHidden`, and `includeDeleted` |
| `POST /sdk/v1/payment-templates` | Create a template |
| `PATCH /sdk/v1/payment-templates/:templateId` | Edit supplied fields (`PUT` is also supported) |
| `DELETE /sdk/v1/payment-templates/:templateId` | Hide/remove a template according to platform rules, preserving existing usage |

Kinds are `BONUS`, `CONTRACT`, and `SIMPLIFIED`. Simplified templates retain the agency feature gate. The existing [bonus-template API](/bonus-templates.md) remains available.

Example full contract template:

```json theme={null}
{
  "name": "Standard creator fee",
  "colorCode": "#2563EB",
  "templateKind": "CONTRACT",
  "contractTerms": {
    "schemaVersion": 1,
    "payoutType": "FIXED",
    "currency": "USD",
    "fixed": { "amount": 500, "paymentOption": "STANDARD", "rateScope": "CREATOR", "platforms": [] },
    "performance": null,
    "payCycle": { "enabled": false, "timesPerPeriod": null, "period": null, "weekday": null, "startImmediately": true },
    "bonus": null
  }
}
```

Bonus templates use `components` and optional `tierScope`. Simplified templates use `ruleTerms`. Names and a valid `colorCode` are required for creation. Editing accepts `name`, `description`, `colorCode`, `components`, `isDefault`, `templateKind`, `contractTerms`, and `ruleTerms`, subject to the platform's template-kind and validation rules. Hidden/deleted templates cannot be applied to new creators.

## Apply to one creator

`POST /sdk/v1/payment-templates/apply`

```json theme={null}
{
  "templateId": "template-id",
  "campaignCreatorRecordId": "creator-record-id",
  "applicablePostsUploadedOnOrAfter": "2026-10-01"
}
```

You may identify the target with `campaignId` plus `creatorProfileId` instead of a record ID. The date is optional where the existing contract history permits it; when a new effective boundary is required, the API returns the platform's validation error. Paid history, pending approvals, currency compatibility, and completed-campaign protections remain enforced. Simplified templates cannot be applied through the legacy apply workflow.

## Preview and apply a contract template in bulk

`GET /sdk/v1/payment-templates/:templateId/apply-candidates` lists eligible and ineligible candidates. Query parameters: `campaignId`, `search`, `page`, and `pageSize`. `GET /sdk/v1/payment-templates/apply-candidates` provides the general candidate list.

`POST /sdk/v1/payment-templates/:templateId/apply-bulk`

```json theme={null}
{
  "campaignCreatorRecordIds": ["creator-record-1", "creator-record-2"],
  "applicablePostsUploadedOnOrAfter": "2026-10-01"
}
```

Alternatively pass `campaignId` to target its creators. Bulk apply is for full contract templates. It validates each target and returns per-row results; inspect failures and skipped rows before treating the operation as complete. These operations reuse the platform's contract-history boundaries rather than overwriting past payments.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.