All documentation
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-IdX-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/triggerandPOST /payouts/trigger-bulkwithrequireConfirmation: falsePOST /payouts/confirmandPOST /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"andapprovalIdidentify an approval request. A paid response haspayoutIdinstead and nostatus. Both are successful responses; check forapprovalIdbefore you track a payout.currencyandamountare in the creator's wallet currency, as in a paid response.payout_linkis never returned for an approval request, even withreturnPayoutLink: 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 itspayoutIdwithPOST /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 ofUSD,CAD,GBP,EUR)- exactly one of:
payoutAmount(positive; max 2 decimals)lineItems(array; each item requiresquantityandperItemAmount)
requireConfirmation(optional; defaults totrue)returnPayoutLink(optional boolean; whentrue, successful executed payout responses includepayout_link)confirmHighValuePayout(optional boolean; defaults tofalse; acknowledges a payout above the agency's threshold. Only read whenrequireConfirmationisfalse)platformFeePayerOverride(optional; one ofINHERIT,CREATOR_PAYS_ALL,AGENCY_PAYS_ALL,CUSTOM_SPLIT)platformFeeAgencySharePercent(required whenplatformFeePayerOverrideisCUSTOM_SPLIT; number between0and100)
{
"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 includespayout_linkwhenreturnPayoutLinkistrue)
{
"success": true,
"payoutId": "pay_...",
"invoiceId": "inv_...",
"currency": "USD",
"amount": 200,
"email": "creator@example.com",
"payout_link": "https://payout.example/..."
}
- If
requireConfirmation: falseand the agency has approval mode on:202with the approval request instead of a payout. Replays return the same202.
Common errors
400: invalid payload (missing fields, currency not supported, >2 decimals, etc.)400: insufficient funds (includessufficient: false,requiredAmount,currency: "USD")400THRESHOLD_CONFIRMATION_REQUIRED: above the agency threshold; resend withconfirmHighValuePayout: true400CURRENCY_CONVERSION_FAILED: the threshold could not be evaluated; nothing was sent400APPROVAL_SUBMISSION_FAILED: approval mode is on and the approval request could not be created (for example, a frozen wallet); nothing was sent401: missing/invalid SDK headers403: origin not allowed (when allowlist is configured andOriginis 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 includespayout_linkwhen an item setsreturnPayoutLinktotrue)
{
"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(default1)limit(default50, max100)includeExpired(true|false, defaultfalse)includeConfirmed(true|false, defaultfalse)
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 tofalse; 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): theCCPAY_...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": []
}
}
}
lineItemspreserves the stored item fields, including media IDs, view counts, and per-media breakdowns when available. Item fields vary by payout type and age.lineItemsSourceispayoutwhen saved payout items exist,invoicewhen falling back to invoice items, ornonewhen neither is available. Invoice items can include platform fee adjustments.lineItemsCurrencyis the shared output currency recorded on every saved payout item (amountCurrency/amount_currency,outputCurrency/output_currency, or governing-history segments' output currency). It isnullif 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;displayAmountanddisplayCurrencydescribe the original amount separately.contractBreakdowncontains the captured contractterms(fixed, performance, bonus, and pay-cycle settings) and payment-termcomponents. Current contract edits do not change this response. Older snapshots can containcomponentswithterms: null.contractBreakdown.snapshotspreserves all captured contract versions for payouts spanning multiple historical contracts. Each snapshot includescampaign_creator_contract_history_id,line_item_indexes(zero-based indexes of the captured payout items),terms_snapshot, andcontract_terms.termsis the primary contract projection; usesnapshotsfor each governing version. Older payouts return an empty array.- Direct payouts have
campaignId: nullandcampaignCreatorRecordId: null. Payouts without saved contract details returncontractBreakdown: 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: invalidCCPAYID (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(default1)limit(default50, max100)sortBy(optional)sortOrder(asc|desc, defaultdesc)search(optional)payoutType(optional; currently supportsDIRECT)statuses(optional; comma-separated)fromandto(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):csvorpdffromandto(required): ISO timestamps- All filters supported by
GET /sdk/v1/payouts(statuses,search,sortBy,sortOrder, ...) timeZone(optional; used for PDF rendering)
Responses
text/csvwithContent-Disposition: attachment; filename="payout-transactions-YYYY-MM-DD.csv"application/pdfwithContent-Disposition: attachment; filename="payout-transactions-YYYY-MM-DD.pdf"
If the export would exceed 10,000 rows: 413 with a JSON error.
