Payouts - Grade SDK API

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"]
}

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

​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

POST /sdk/v1/payouts/cancel

Headers

Body

Response

GET /sdk/v1/payouts

Query parameters

Response

GET /sdk/v1/payouts/export

Query parameters

Responses