Payouts - Grade SDK API

For a one-off payment attributed to an existing campaign creator, use Campaign quick pay. The trigger endpoints below send standalone payouts without campaign attribution. All endpoints below require:

X-Application-Id
X-Api-Key

POST /sdk/v1/payouts/trigger

Create a single payout. Supports immediate execution or returning a pending confirmation token.

This endpoint does not calculate campaign contract terms or tiered bonus templates. To configure reusable campaign bonuses, use /sdk/v1/bonus-templates, apply the returned templateId to a campaign contract, and let Grade calculate eligible bonus line items from tracked campaign media.

Headers

X-Idempotency-Key (required)

Body

You must provide:

payoutRecipientEmail (required; must be a valid email)
payoutCurrency (required; one of USD, CAD, GBP, EUR)
exactly one of:
- payoutAmount (positive; max 2 decimals)
- lineItems (array; each item requires quantity and perItemAmount)
requireConfirmation (optional; defaults to true)
returnPayoutLink (optional boolean; when true, successful executed payout responses include payout_link)
platformFeePayerOverride (optional; one of INHERIT, CREATOR_PAYS_ALL, AGENCY_PAYS_ALL, CUSTOM_SPLIT)
platformFeeAgencySharePercent (required when platformFeePayerOverride is CUSTOM_SPLIT; number between 0 and 100)

{
  "payoutRecipientEmail": "[email protected]",
  "payoutCurrency": "USD",
  "requireConfirmation": true,
  "lineItems": [
    { "lineItemDescription": "Instagram post", "quantity": 1, "perItemAmount": "150.00" },
    { "lineItemDescription": "Story set", "quantity": 2, "perItemAmount": "25.00" }
  ]
}

If you need to override who covers the platform fee for this payout only, send:

{
  "payoutRecipientEmail": "[email protected]",
  "payoutCurrency": "USD",
  "payoutAmount": "200.00",
  "platformFeePayerOverride": "CUSTOM_SPLIT",
  "platformFeeAgencySharePercent": 40
}

Omit platformFeePayerOverride, or set it to INHERIT, to use the agency default. The returned preview.platformFee values reflect the effective override. Set returnPayoutLink to true when you need the payout link in the execution response. Pending trigger responses do not include a link because the payout has not been executed yet; the confirmed payout response includes payout_link if the original trigger requested it. If the link cannot be resolved at response time after a successful payout, payout_link is null.

Response

If requireConfirmation: true: 201

{
  "success": true,
  "pending_payout_id": "pnd_...",
  "preview": {
    "payoutRecipientEmail": "[email protected]",
    "payoutCurrency": "USD",
    "payoutAmount": 200,
    "lineItems": [
      { "lineItemDescription": "Instagram post", "quantity": 1, "perItemAmount": 150, "lineTotal": 150 },
      { "lineItemDescription": "Story set", "quantity": 2, "perItemAmount": 25, "lineTotal": 50 }
    ],
    "creatorCurrency": "USD",
    "amountInCreatorCurrency": 200,
    "platformFee": {
      "displayCurrency": "USD",
      "feeTotalDisplayAmount": 0,
      "feePaidByCreatorDisplayAmount": 0,
      "feePaidByAgencyDisplayAmount": 0,
      "netDisplayAmount": 200
    }
  },
  "expiresAt": "2026-02-19T00:00:00.000Z"
}

If requireConfirmation: false: 200 (example includes payout_link when returnPayoutLink is true)

{
  "success": true,
  "payoutId": "pay_...",
  "invoiceId": "inv_...",
  "currency": "USD",
  "amount": 200,
  "email": "[email protected]",
  "payout_link": "https://payout.example/..."
}

Common errors

400: invalid payload (missing fields, currency not supported, >2 decimals, etc.)
400: insufficient funds (includes sufficient: false, requiredAmount, currency: "USD")
401: missing/invalid SDK headers
403: origin not allowed (when allowlist is configured and Origin is present)

POST /sdk/v1/payouts/trigger-bulk

Create up to 100 payouts in one request.

Headers

X-Idempotency-Key (required)

Body

payouts must be a non-empty array, max length 100. Each item is the same shape as POST /payouts/trigger. All items must share the same requireConfirmation value. Each item can set its own platformFeePayerOverride and platformFeeAgencySharePercent.

{
  "payouts": [
    {
      "payoutRecipientEmail": "[email protected]",
      "payoutCurrency": "USD",
      "requireConfirmation": true,
      "payoutAmount": "10.00"
    },
    {
      "payoutRecipientEmail": "[email protected]",
      "payoutCurrency": "USD",
      "requireConfirmation": true,
      "payoutAmount": "15.00"
    }
  ]
}

Response

If requireConfirmation: true: 201

{
  "success": true,
  "requireConfirmation": true,
  "results": [
    {
      "index": 0,
      "pending_payout_id": "pnd_...",
      "preview": { "payoutRecipientEmail": "[email protected]", "payoutCurrency": "USD", "payoutAmount": 10 },
      "expiresAt": "2026-02-19T00:00:00.000Z"
    }
  ]
}

If requireConfirmation: false: 200 (example includes payout_link when an item sets returnPayoutLink to true)

{
  "success": true,
  "requireConfirmation": false,
  "results": [
    {
      "index": 0,
      "success": true,
      "payoutId": "pay_...",
      "invoiceId": "inv_...",
      "currency": "USD",
      "amount": 10,
      "email": "[email protected]",
      "payout_link": "https://payout.example/..."
    }
  ]
}

If any entry fails in immediate mode, the response success will be false and results will contain both successes and failures.

POST /sdk/v1/payouts/pending

Fetch a single pending payout preview/status by pending_payout_id.

Body

{ "pending_payout_id": "pnd_..." }

Response

{
  "success": true,
  "data": {
    "pending_payout_id": "pnd_...",
    "createdAt": "2026-02-19T00:00:00.000Z",
    "expiresAt": "2026-02-26T00:00:00.000Z",
    "confirmedAt": null,
    "expired": false,
    "preview": { "payoutRecipientEmail": "[email protected]", "payoutCurrency": "USD", "payoutAmount": 10 },
    "result": null
  }
}

POST /sdk/v1/payouts/pending-bulk

Fetch multiple pending payout previews/statuses.

Body

Accepts a string (comma-separated) or an array:

{ "pending_payout_ids": ["pnd_1", "pnd_2"] }

Response

Returns found items plus missing IDs:

{
  "success": true,
  "data": [{ "pending_payout_id": "pnd_1", "preview": { "payoutAmount": 10 } }],
  "missing": ["pnd_2"]
}

GET /sdk/v1/payouts/pending

List pending payouts for the application (table-friendly).

Query parameters

page (default 1)
limit (default 50, max 100)
includeExpired (true|false, default false)
includeConfirmed (true|false, default false)

Response

Each row includes expiresInSeconds and expired.

{
  "success": true,
  "data": [
    {
      "pending_payout_id": "pnd_...",
      "createdAt": "2026-02-19T00:00:00.000Z",
      "expiresAt": "2026-02-26T00:00:00.000Z",
      "confirmedAt": null,
      "expired": false,
      "expiresInSeconds": 604800,
      "preview": { "payoutRecipientEmail": "[email protected]", "payoutCurrency": "USD", "payoutAmount": 10 },
      "result": null
    }
  ],
  "pagination": { "page": 1, "limit": 50, "totalPages": 1, "totalItems": 1 }
}

POST /sdk/v1/payouts/confirm

Confirm and execute a pending payout.

Headers

X-Idempotency-Key (required)

Body

{ "pending_payout_id": "pnd_..." }

Response

On success: 200 (example includes payout_link when the original trigger set returnPayoutLink to true)

{
  "success": true,
  "payoutId": "pay_...",
  "invoiceId": "inv_...",
  "currency": "USD",
  "amount": 10,
  "email": "[email protected]",
  "payout_link": "https://payout.example/..."
}

If the pending payout is expired: 410 { "success": false, "message": "Pending payout has expired." }

POST /sdk/v1/payouts/confirm-bulk

Confirm and execute up to 100 pending payouts.

Headers

X-Idempotency-Key (required)

Body

Accepts a string (comma-separated) or an array:

{ "pending_payout_ids": ["pnd_1", "pnd_2"] }

Response

success is true only if all confirmations returned status: 200.

{
  "success": false,
  "results": [
    { "pending_payout_id": "pnd_1", "status": 200, "response": { "success": true, "payoutId": "pay_..." } },
    { "pending_payout_id": "pnd_2", "status": 410, "response": { "success": false, "message": "Pending payout has expired." } }
  ]
}

POST /sdk/v1/payouts/status

Fetch payout status records for specific payout IDs (up to 100).

Body

Accepts multiple aliases; preferred:

{ "payout_ids": ["pay_1", "pay_2"] }

Response

Results preserve request order for found items and include missing.

{
  "success": true,
  "data": [{ "payoutId": "pay_1", "status": "sent", "currency": "USD" }],
  "missing": ["pay_2"]
}

GET /sdk/v1/payouts/:payoutId/breakdown

Fetch the saved line items and contract breakdown for a campaign or direct payout using its CCPAY_... ID. The payout must belong to the agency authenticated by your SDK credentials. This includes payouts created in the dashboard, as with GET /sdk/v1/payouts.

Path parameters

payoutId (required): the CCPAY_... reference returned by the payout list or trigger endpoint.

curl "$GRADE_API_BASE_URL/sdk/v1/payouts/$PAYOUT_ID/breakdown" \
  -H "X-Application-Id: $APPLICATION_ID" \
  -H "X-Api-Key: $API_KEY"

Response

{
  "success": true,
  "data": {
    "payoutId": "CCPAY_example_1776686400",
    "campaignId": "campaign_123",
    "campaignCreatorRecordId": "ccr_123",
    "lineItems": [
      { "type": "FIXED_FULL", "description": "Fixed payment", "quantity": 1, "amount": 100, "amountCurrency": "EUR" }
    ],
    "lineItemsSource": "payout",
    "lineItemsCurrency": "EUR",
    "contractBreakdown": {
      "capturedAt": "2026-04-20T12:00:00.000Z",
      "terms": {
        "schemaVersion": 1,
        "payoutType": "FIXED",
        "currency": "EUR",
        "fixed": {
          "amount": 100,
          "paymentOption": "STANDARD",
          "proratedByUploads": false,
          "prorateByTime": false,
          "rateScope": "CREATOR",
          "platforms": []
        },
        "performance": null,
        "bonus": null,
        "payCycle": { "enabled": false, "timesPerPeriod": null, "period": null, "weekday": null, "startImmediately": true }
      },
      "components": [],
      "tierScope": "CREATOR",
      "templateId": null,
      "snapshots": []
    }
  }
}

lineItems preserves the stored item fields, including media IDs, view counts, and per-media breakdowns when available. Item fields vary by payout type and age.
lineItemsSource is payout when saved payout items exist, invoice when falling back to invoice items, or none when neither is available. Invoice items can include platform fee adjustments.
lineItemsCurrency is the shared output currency recorded on every saved payout item (amountCurrency/amount_currency, outputCurrency/output_currency, or governing-history segments’ output currency). It is null if any item’s output currency is unknown or the currencies differ. Contract, historical, and display currencies can describe amounts before conversion, so they are not used to label the payable amounts. For invoice items, this field is the invoice currency; displayAmount and displayCurrency describe the original amount separately.
contractBreakdown contains the captured contract terms (fixed, performance, bonus, and pay-cycle settings) and payment-term components. Current contract edits do not change this response. Older snapshots can contain components with terms: null.
contractBreakdown.snapshots preserves all captured contract versions for payouts spanning multiple historical contracts. Each snapshot includes campaign_creator_contract_history_id, line_item_indexes (zero-based indexes of the captured payout items), terms_snapshot, and contract_terms. terms is the primary contract projection; use snapshots for each governing version. Older payouts return an empty array.
Direct payouts have campaignId: null and campaignCreatorRecordId: null. Payouts without saved contract details return contractBreakdown: null; missing line items return [].

Historical breakdowns remain available for cancelled payouts and archived or deleted campaigns. A breakdown does not indicate that funds were delivered; use the payout status endpoint to check delivery.

Common errors

400: invalid CCPAY ID (maximum 64 characters).
401: missing or invalid SDK credentials.
404: payout does not exist or belongs to another agency.

POST /sdk/v1/payouts/cancel

Cancel an in-flight payout.

Headers

X-Idempotency-Key (required)

Body

Provide either payoutId or payoutReferenceId:

{ "payoutId": "pay_..." }

Response

{
  "success": true,
  "data": { "refundedUsd": 10 }
}

If the payout was already cancelled, the response may include:

{
  "success": true,
  "data": { "refundedUsd": 10, "alreadyCancelled": true }
}

GET /sdk/v1/payouts

List agency payouts.

Query parameters

page (default 1)
limit (default 50, max 100)
sortBy (optional)
sortOrder (asc|desc, default desc)
search (optional)
payoutType (optional; currently supports DIRECT)
statuses (optional; comma-separated)
from and to (optional; ISO timestamps)

If from/to is provided without a timezone offset, it is treated as UTC. Supported statuses values (invalid values are ignored): processing, created, delivery_pending, delivery_failed, sent, delivered, claimed, reversed, canceled, expired, failed, pending, completed, flagged, delayed

Response

{
  "success": true,
  "data": [{ "payoutId": "pay_...", "status": "claimed", "currency": "USD" }],
  "pagination": { "page": 1, "limit": 50, "totalPages": 1, "totalItems": 1 },
  "meta": { "bufferBusinessDays": 1, "accelerated": false, "bankClosedDates": [] }
}

GET /sdk/v1/payouts/export

Export payouts as CSV or PDF.

Query parameters

format (required): csv or pdf
from and to (required): ISO timestamps
All filters supported by GET /sdk/v1/payouts (statuses, search, sortBy, sortOrder, …)
timeZone (optional; used for PDF rendering)

Responses

text/csv with Content-Disposition: attachment; filename="payout-transactions-YYYY-MM-DD.csv"
application/pdf with Content-Disposition: attachment; filename="payout-transactions-YYYY-MM-DD.pdf"

If the export would exceed 10,000 rows: 413 with a JSON error.

​POST /sdk/v1/payouts/trigger

​Headers

​Body

​Response

​Common errors

​POST /sdk/v1/payouts/trigger-bulk

​Headers

​Body

​Response

​POST /sdk/v1/payouts/pending

​Body

​Response

​POST /sdk/v1/payouts/pending-bulk

​Body

​Response

​GET /sdk/v1/payouts/pending

​Query parameters

​Response

​POST /sdk/v1/payouts/confirm

​Headers

​Body

​Response

​POST /sdk/v1/payouts/confirm-bulk

​Headers

​Body

​Response

​POST /sdk/v1/payouts/status

​Body

​Response

​GET /sdk/v1/payouts/:payoutId/breakdown

​Path parameters

​Response

​Common errors

​POST /sdk/v1/payouts/cancel

​Headers

​Body

​Response

​GET /sdk/v1/payouts

​Query parameters

​Response

​GET /sdk/v1/payouts/export

​Query parameters

​Responses

POST /sdk/v1/payouts/trigger

Headers

Body

Response

Common errors

POST /sdk/v1/payouts/trigger-bulk

Headers

Body

Response

POST /sdk/v1/payouts/pending

Body

Response

POST /sdk/v1/payouts/pending-bulk

Body

Response

GET /sdk/v1/payouts/pending

Query parameters

Response

POST /sdk/v1/payouts/confirm

Headers

Body

Response

POST /sdk/v1/payouts/confirm-bulk

Headers

Body

Response

POST /sdk/v1/payouts/status

Body

Response

GET /sdk/v1/payouts/:payoutId/breakdown

Path parameters

Response

Common errors

POST /sdk/v1/payouts/cancel

Headers

Body

Response

GET /sdk/v1/payouts

Query parameters

Response

GET /sdk/v1/payouts/export

Query parameters

Responses