Documentation / SDK v1

Payouts

Trigger, confirm, list, export, and manage payouts via /sdk/v1.

payouts ยท json
{
  "success": false,
  "code": "CREATOR_RESTRICTED_COUNTRY",
  "message": "We can't pay this creator through Grade because of where they're located. Please pay them directly."
}
All documentation

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

Creator location restrictions

A blocked creator cannot receive a new payout, including a pending payout confirmation. Single-payout requests return HTTP 409 with this response:

{
  "success": false,
  "code": "CREATOR_RESTRICTED_COUNTRY",
  "message": "We can't pay this creator through Grade because of where they're located. Please pay them directly."
}

Immediate bulk payouts return this code and message on the failed item. Bulk confirmations return it in the item's response, with status: 409; other items can still succeed. A bulk trigger requesting confirmation fails before saving pending payouts if any recipient is blocked. Retrying verification, changing the payout provider, or creating another agency connection does not remove the block. Previously completed idempotent requests continue to replay their saved response.

Approval mode and high-value payouts

Standalone payouts follow the same two agency settings as payments sent from the Grade app and Campaign quick pay. They apply to every request that would send money:

  • POST /payouts/trigger and POST /payouts/trigger-bulk with requireConfirmation: false
  • POST /payouts/confirm and POST /payouts/confirm-bulk

A trigger with requireConfirmation: true only creates a pending payout, so both settings are applied when you confirm it. Campaign creator payouts pay at once and cannot wait for approval: with approval mode on, that endpoint pays nothing and answers 409 APPROVAL_REQUIRED.

High-value threshold. When the agency has a payout threshold, Grade compares the requested amount (payoutAmount, or the sum of lineItems) with it in the agency's preferred currency. Above the threshold, the request returns 400 and sends nothing:

{
  "success": false,
  "code": "THRESHOLD_CONFIRMATION_REQUIRED",
  "message": "Confirm this high-value payout before sending it.",
  "requiresThresholdConfirmation": true,
  "thresholdAmount": 1000,
  "thresholdCurrency": "USD"
}

Review the amount, then repeat the request with confirmHighValuePayout: true. On a trigger, set it on the payout (on each item in a bulk trigger). On a confirmation, set it in the confirm body; it is the only place it counts for a two-step payout, and it covers every ID in a bulk confirmation. A single trigger or confirmation that was refused for the threshold is not saved against its idempotency key, so you can retry with the same key. Bulk responses are saved with their per-item results, so retry the refused items with a new key. Confirming a high-value payout does not skip approval or balance checks.

Approval mode. When the agency has approval mode on, Grade does not pay. It freezes the creator and agency invoices as PENDING_APPROVAL and adds an approval request to the Grade Approvals queue, where the submitter shows as API application. No wallet debit or payment transaction happens, and no funds are reserved. The request answers 202:

{
  "success": true,
  "status": "PENDING_APPROVAL",
  "approvalId": "cd098819-cb2c-442b-a44b-80bd1de6e0e3",
  "invoiceId": "inv_...",
  "agencyInvoiceId": "inv_...",
  "currency": "USD",
  "amount": 200,
  "email": "creator@example.com"
}
  • status: "PENDING_APPROVAL" and approvalId identify an approval request. A paid response has payoutId instead and no status. Both are successful responses; check for approvalId before you track a payout.
  • currency and amount are in the creator's wallet currency, as in a paid response.
  • payout_link is never returned for an approval request, even with returnPayoutLink: true, because nothing was paid.
  • Follow the request with GET /sdk/v1/payouts/approvals/:approvalId, described below. Once it is approved, the payout belongs to your application: use its payoutId with POST /payouts/status, breakdowns, and invoices as usual.

The threshold is checked first, so a high-value payout under approval mode needs confirmHighValuePayout: true before it can be queued. Approving the request in Grade, or with an approvals:write key through Payout approvals, executes the payout; rejecting or cancelling it pays nothing. Funds and wallet checks apply when it executes.

POST /sdk/v1/payouts/trigger

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

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)
  • confirmHighValuePayout (optional boolean; defaults to false; acknowledges a payout above the agency's threshold. Only read when requireConfirmation is false)
  • 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": "creator@example.com",
  "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": "creator@example.com",
  "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": "creator@example.com",
    "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": "creator@example.com",
  "payout_link": "https://payout.example/..."
}
  • If requireConfirmation: false and the agency has approval mode on: 202 with the approval request instead of a payout. Replays return the same 202.

Common errors

  • 400: invalid payload (missing fields, currency not supported, >2 decimals, etc.)
  • 400: insufficient funds (includes sufficient: false, requiredAmount, currency: "USD")
  • 400 THRESHOLD_CONFIRMATION_REQUIRED: above the agency threshold; resend with confirmHighValuePayout: true
  • 400 CURRENCY_CONVERSION_FAILED: the threshold could not be evaluated; nothing was sent
  • 400 APPROVAL_SUBMISSION_FAILED: approval mode is on and the approval request could not be created (for example, a frozen wallet); nothing was sent
  • 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": "creator1@example.com",
      "payoutCurrency": "USD",
      "requireConfirmation": true,
      "payoutAmount": "10.00"
    },
    {
      "payoutRecipientEmail": "creator2@example.com",
      "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": "creator1@example.com", "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": "creator1@example.com",
      "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.

In immediate mode each item meets the threshold and approval mode on its own. An item above the threshold without its own confirmHighValuePayout: true fails with code: "THRESHOLD_CONFIRMATION_REQUIRED" while the other items continue. With approval mode on, each accepted item is an approval request rather than a payout:

{
  "success": false,
  "requireConfirmation": false,
  "results": [
    {
      "index": 0,
      "success": true,
      "status": "PENDING_APPROVAL",
      "approvalId": "cd098819-cb2c-442b-a44b-80bd1de6e0e3",
      "invoiceId": "inv_...",
      "agencyInvoiceId": "inv_...",
      "currency": "USD",
      "amount": 10,
      "email": "creator1@example.com"
    },
    {
      "index": 1,
      "success": false,
      "code": "THRESHOLD_CONFIRMATION_REQUIRED",
      "message": "Confirm this high-value payout before sending it.",
      "requiresThresholdConfirmation": true,
      "thresholdAmount": 1000,
      "thresholdCurrency": "USD"
    }
  ]
}

POST /sdk/v1/payouts/pending

Fetch a single pending payout preview/status by pending_payout_id. Once confirmed, result holds the confirm response: a payout, or an approval request when approval mode was on.

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": "creator@example.com", "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": "creator@example.com", "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, or submit it for approval when the agency has approval mode on.

Headers

  • X-Idempotency-Key (required)

Body

{ "pending_payout_id": "pnd_...", "confirmHighValuePayout": true }
  • pending_payout_id (required)
  • confirmHighValuePayout (optional boolean; defaults to false; acknowledges a payout above the agency's threshold)

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": "creator@example.com",
  "payout_link": "https://payout.example/..."
}

With approval mode on: 202 with the approval request. The pending payout is then confirmed: confirming it again, with any idempotency key, returns the same 202 and never creates a second request, even after approval mode is turned off or the request is decided.

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

Above the agency threshold without confirmHighValuePayout: true: 400 with code: "THRESHOLD_CONFIRMATION_REQUIRED". If the approval request cannot be created: 400 with code: "APPROVAL_SUBMISSION_FAILED". In both cases the pending payout stays unconfirmed.

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"], "confirmHighValuePayout": true }

confirmHighValuePayout (optional boolean) applies to every listed payout.

Response

success is true only if all confirmations returned status: 200 or 202. Each response is what POST /payouts/confirm would return for that ID, so 202 items are approval requests.

{
  "success": false,
  "results": [
    { "pending_payout_id": "pnd_1", "status": 200, "response": { "success": true, "payoutId": "pay_..." } },
    { "pending_payout_id": "pnd_2", "status": 202, "response": { "success": true, "status": "PENDING_APPROVAL", "approvalId": "cd098819-cb2c-442b-a44b-80bd1de6e0e3" } },
    { "pending_payout_id": "pnd_3", "status": 400, "response": { "success": false, "code": "THRESHOLD_CONFIRMATION_REQUIRED" } },
    { "pending_payout_id": "pnd_4", "status": 410, "response": { "success": false, "message": "Pending payout has expired." } }
  ]
}

GET /sdk/v1/payouts/approvals/:approvalId

Read the current state of an approval request your application created, through these endpoints or Campaign quick pay. Requires payouts:read and no idempotency key. Another application in the same agency gets 404.

{
  "success": true,
  "approvalId": "cd098819-cb2c-442b-a44b-80bd1de6e0e3",
  "status": "APPROVED",
  "invoiceId": "inv_...",
  "agencyInvoiceId": "inv_...",
  "payoutId": "CCPAY_...",
  "campaignId": null,
  "campaignCreatorRecordId": null,
  "rejectionNote": null,
  "createdAt": "2026-10-28T09:00:00.000Z",
  "decidedAt": "2026-10-28T10:00:00.000Z"
}
Status Meaning
PENDING Waiting for review; no debit.
APPROVING Execution is in progress; poll with backoff.
APPROVED Payment initiated. Use payoutId with POST /payouts/status.
REJECTED Review declined; rejectionNote holds the reason when supplied.
CANCELLED Request cancelled; nothing was paid.

payoutId and decidedAt are null until they apply. campaignId and campaignCreatorRecordId are set only for Campaign quick pay requests.

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

Restricted-country refunds

The payout keeps its original payoutId and authorization scope. This endpoint, the payout list, and creator payout reads include creatorRestricted and a nullable refund object. A refund does not mean the creator was paid.

Refund state Meaning
refund: null No restricted-country refund is reported for this payout.
refund.status: pending Grade is checking and returning eligible funds. No refund amount is confirmed yet.
refund.status: needs_review Support must review the return of funds. No refund amount is confirmed yet.
status: refunded, refund.status: completed The agency wallet credit has committed. amountUsd is the full original agency debit, including Grade fees.

Only completed refunds include amountUsd and completedAt. Use the safe message for display; the response does not include a country, region, provider error, or verification evidence.

{
  "payoutId": "pay_1",
  "status": "refunded",
  "creatorRestricted": true,
  "refund": {
    "status": "completed",
    "reasonCode": "restricted_country",
    "message": "We can't pay this creator through Grade because of where they're located. The money is back in your wallet. Please pay them directly.",
    "amountUsd": "50.00",
    "completedAt": "2026-10-19T12:00:00.000Z"
  }
}

Disable new payments and withdrawal-email resends when creatorRestricted is true. Grade also rejects new payments to a blocked creator with 409 and code: CREATOR_RESTRICTED_COUNTRY. An override does not reissue completed refunds. Poll the existing payout reads for updates; outbound payout status webhooks are not yet available.

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, refunded, 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.

CSV exports include refundStatus, refundReasonCode, refundMessage, refundAmountUsd, and refundCompletedAt. Amount and completion time remain empty until the refund commits. PDF exports distinguish refunds from paid payouts and show the confirmed USD return amount.

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.

Describe your program.

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