All documentation
Documentation
POST /sdk/v1/campaign-creators/:campaignCreatorRecordId/quick-pay
Send a one-off payment to an existing campaign creator, using the same direct
payout flow as the campaign screen. You supply the line items and amounts.
Grade records the payment as DIRECT against that creator and campaign,
includes it in campaign spend and payout history, and creates the invoices.
Quick pay does not settle calculated fixed fees, CPM earnings, or tiered bonuses, and does not change the creator's contract. Those earnings remain payable through calculated campaign payouts. For a payment without campaign attribution, use Payouts.
Prerequisites
- An SDK application and API key with
payouts:write. Usecampaigns:readto discover records andpayouts:readto check payment status and invoices. - An existing, active campaign creator record in your agency. Find its
campaignCreatorRecordIdthrough the creator list. A creator profile ID or email cannot replace this record ID. - An eligible creator and usable wallets. Sufficient funds are required when payment executes, under your agency's settlement settings; submitting an approval does not reserve or debit funds. Removed or deleted records, staged creators, and test phase creators when that feature is enabled cannot be paid.
Headers
| Header | Required | Meaning |
|---|---|---|
X-Application-Id |
Yes | Your SDK application ID. |
X-Api-Key |
Yes | An API key with payouts:write. |
X-Idempotency-Key |
Yes | A unique key for this intended payment, 1–100 characters after trimming. Persist it before sending the request. |
Content-Type |
Yes | application/json. |
The authenticated application determines the agency. Do not send an agencyId,
campaignId, recipient email, or creator profile ID in the body.
Request body
| Field | Type | Required | Meaning |
|---|---|---|---|
currency |
string | Yes | USD, CAD, GBP, or EUR, in uppercase. Applies to every line item. |
lineItems |
array | Yes | 1–100 custom line items. The gross payout is their sum. |
lineItems[].amount |
number | Yes | Positive amount with at most two decimal places. Send a JSON number, not a numeric string. |
lineItems[].description |
string | No | Up to 255 characters after trimming. Omitted or blank descriptions become Direct payout. |
requireApproval |
boolean | No | Defaults to false. Set to true to queue for approval even when agency approvals are disabled. false cannot bypass agency approvals. |
confirmHighValuePayout |
boolean | No | Defaults to false. Set to true to acknowledge a payout above your agency's threshold. |
platformFeePayerOverride |
object | No | Override who pays the platform fee for this payment only. Omit to inherit configured defaults. |
Unknown fields are rejected, including fields inside line items and fee overrides. Amounts and their sum must fit within JavaScript's safe integer range when expressed in cents. Sub-cent amounts are rejected rather than rounded.
Platform fees
platformFeePayerOverride accepts one of these objects:
{ "mode": "INHERIT" }
{ "mode": "CREATOR_PAYS_ALL" }
{ "mode": "AGENCY_PAYS_ALL" }
{ "mode": "CUSTOM_SPLIT", "agencySharePercent": 40 }
For CUSTOM_SPLIT, agencySharePercent is required and must be between 0 and
100 inclusive. Other modes do not accept it. This changes fee allocation, not
the configured fee rate or cap. The creator's net receipt can be lower than the
gross line-item sum; the agency's debit can be higher when it pays fees.
Currency conversion and confirmation
Grade converts the requested amount to the creator's existing wallet currency when needed. A new creator wallet uses the requested currency. The response includes both the requested gross total and its creator-currency equivalent. Neither amount is a guarantee of the final net receipt after fees.
The high-value threshold is evaluated in your agency's preferred currency. If
confirmation is required, the API returns 400 with
code: "THRESHOLD_CONFIRMATION_REQUIRED", requiresThresholdConfirmation: true,
thresholdAmount, and thresholdCurrency. Review the amount, then send
confirmHighValuePayout: true with a new idempotency key, because the request
body has changed. Confirmation does not bypass eligibility or balance checks.
Example request
BASE_URL is the API origin and prefix before /sdk/v1, for example
https://infra-sandbox.usegrade.com/api for sandbox or
https://infra.usegrade.com/api/email for production. Use credentials issued for
the selected environment.
curl -sS "$BASE_URL/sdk/v1/campaign-creators/CCR_123/quick-pay" \
-X POST \
-H "Content-Type: application/json" \
-H "X-Application-Id: $APP_ID" \
-H "X-Api-Key: $API_KEY" \
-H "X-Idempotency-Key: event-appearance-2026-10-03-001" \
-d '{
"currency": "USD",
"lineItems": [
{ "description": "Event appearance fee", "amount": 150 },
{ "description": "Travel reimbursement", "amount": 75.5 }
],
"platformFeePayerOverride": { "mode": "AGENCY_PAYS_ALL" }
}'
JavaScript integration
Persist your payment record, body, and idempotency key together before calling the API. Pass that same saved record to this function again after a timeout.
async function quickPayCampaignCreator({ recordId, idempotencyKey, body }) {
const response = await fetch(
`${process.env.GRADE_BASE_URL}/sdk/v1/campaign-creators/${encodeURIComponent(recordId)}/quick-pay`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Application-Id": process.env.GRADE_APP_ID,
"X-Api-Key": process.env.GRADE_API_KEY,
"X-Idempotency-Key": idempotencyKey,
},
body: JSON.stringify(body),
},
);
const result = await response.json();
if (!response.ok) {
const error = new Error(result.message || "Quick pay failed");
error.status = response.status;
error.code = result.code;
throw error;
}
return result;
}
Immediate payment response — HTTP 200
{
"success": true,
"payoutId": "CCPAY_123",
"invoiceId": "INV_CREATOR_123",
"agencyInvoiceId": "INV_AGENCY_123",
"transactionId": "TXN_123",
"campaignId": "CAMP_123",
"campaignCreatorRecordId": "CCR_123",
"amount": 225.5,
"currency": "USD",
"creatorAmount": 225.5,
"creatorCurrency": "USD",
"lineItems": [
{ "description": "Event appearance fee", "amount": 150 },
{ "description": "Travel reimbursement", "amount": 75.5 }
]
}
amountandcurrency: the gross sum in the currency you requested.creatorAmountandcreatorCurrency: the gross amount in the creator's wallet currency.lineItems: normalized descriptions and amounts in the requested currency.payoutId: use with payout status and breakdowns.invoiceIdandagencyInvoiceId: creator and agency invoice IDs for PDF downloads.transactionId: the agency payment transaction.
200 means the payment was initiated, or the original response was replayed.
It does not mean the creator has received or withdrawn the funds. Check
POST /sdk/v1/payouts/status using the same application and a key with
payouts:read. Campaign quick pay creates no pending_payout_id.
Require approval — HTTP 202
Add "requireApproval": true to the same request body to request review:
{
"currency": "USD",
"requireApproval": true,
"lineItems": [{ "description": "Event appearance fee", "amount": 150 }]
}
| Agency approvals | requireApproval |
Result |
|---|---|---|
| Off | Omitted or false |
200: payment initiated. |
| Off | true |
202: queued for approval. |
| On | Any value or omitted | 202: queued for approval. |
A queued request creates invoices in PENDING_APPROVAL and a request in the
Grade Approvals queue. No payment transaction or wallet debit occurs at
submission. Admins or finance users with access to the campaign can review it
there, including when agency approvals are disabled. The submitter is displayed
as API application. Approval uses the existing permissions and review workflow.
{
"success": true,
"status": "PENDING",
"approvalId": "cd098819-cb2c-442b-a44b-80bd1de6e0e3",
"invoiceId": "INV_CREATOR_123",
"agencyInvoiceId": "INV_AGENCY_123",
"campaignId": "CAMP_123",
"campaignCreatorRecordId": "CCR_123",
"amount": 150,
"currency": "USD",
"creatorAmount": 150,
"creatorCurrency": "USD",
"lineItems": [{ "description": "Event appearance fee", "amount": 150 }]
}
202 means submitted for approval, not paid. There is no payoutId or
transactionId yet. Both 200 and 202 are successful HTTP responses; check
for approvalId before attempting to track a payout. High-value confirmation
is still required when applicable and does not replace approval.
Requested line items and fee allocation are frozen for review. USD settlement amounts are repriced at approval time using the current exchange rate. Wallet, funding, campaign, and creator checks still apply at execution. Rejected or cancelled requests do not execute a payment. To submit a replacement, use a new idempotency key. Changing the agency approval setting does not approve an existing pending request.
GET /sdk/v1/campaign-creators/:campaignCreatorRecordId/quick-pay/approvals/:approvalId
Read the current approval state using the same application that submitted it
and an API key with payouts:read. This endpoint needs no idempotency key. It
returns 404 if the approval, agency, application, or creator record does not
match. A different application in the same agency cannot read the request.
curl -sS "$BASE_URL/sdk/v1/campaign-creators/CCR_123/quick-pay/approvals/$APPROVAL_ID" \
-H "X-Application-Id: $APP_ID" \
-H "X-Api-Key: $API_KEY"
{
"success": true,
"approvalId": "cd098819-cb2c-442b-a44b-80bd1de6e0e3",
"status": "APPROVED",
"campaignId": "CAMP_123",
"campaignCreatorRecordId": "CCR_123",
"invoiceId": "INV_CREATOR_123",
"agencyInvoiceId": "INV_AGENCY_123",
"payoutId": "CCPAY_123",
"rejectionNote": null,
"createdAt": "2026-10-05T09:00:00.000Z",
"decidedAt": "2026-10-05T10: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 payout status to track delivery. |
REJECTED |
Review declined; rejectionNote contains the reason when supplied. |
CANCELLED |
Request cancelled; no payout from this request. |
payoutId and decidedAt are null until applicable; rejectionNote is nullable.
After approval, the originating application can access payout status, breakdowns,
and invoice PDFs using its existing payouts:read permission. Pending invoice
IDs identify the frozen approval invoices. Invoice PDF access follows the
existing agency access rules. The status endpoint returns 401 for invalid
credentials, 403 for missing read permission, and 500 for a temporary read
failure. Retry read failures with backoff.
Safe retries
Keys are scoped to your application and the campaign quick pay operation.
The URL record ID and normalized request body are part of the request identity.
Reusing a key for another creator or changed amounts returns 409.
Successful payment or approval submission and replay data commit together.
Replaying a queued submission always returns its original 202 response, even
after review. Use the GET approval endpoint for its current state. Completed responses have
no time-based expiry. If the network times out or the server returns 500,
retry with the same record ID, body, and key. Do not generate a fresh key to
recover an uncertain payment. A request still running returns 409; retry it
with backoff. An interrupted worker's processing lease becomes recoverable
after five minutes.
Business failures after processing starts, such as insufficient funds or a required high-value confirmation, are also replayed. After resolving a known failure, use a new key for the new payment attempt. Authentication and input validation failures happen before the key is claimed.
Errors
Errors return { "success": false, "code": "...", "message": "..." }, except
authentication and scope errors, which may omit code.
| HTTP | Code | Meaning and next step |
|---|---|---|
400 |
INVALID_IDEMPOTENCY_KEY, INVALID_REQUEST |
Correct the key or request fields. No payment started. |
400 |
CREATOR_NOT_PAYABLE, TEST_PHASE_CREATOR |
Resolve the creator's eligibility before a new attempt. |
400 |
PAYOUT_PREPARATION_FAILED, CURRENCY_CONVERSION_FAILED |
The amount could not be prepared or the threshold could not be evaluated. |
400 |
THRESHOLD_CONFIRMATION_REQUIRED |
Review, then explicitly confirm with a new key. |
400 |
APPROVAL_SUBMISSION_FAILED |
Invoice or approval validation failed; no payment started. |
400 |
PAYOUT_FAILED |
Wallet, balance, fee, or payment validation failed. insufficientFundsDetails may include available and required USD amounts. |
401 |
— | Missing or invalid credentials. |
403 |
— | Missing payouts:write, SDK access disabled, or origin disallowed. |
404 |
NOT_FOUND |
No active campaign creator in your agency matches the record ID. |
409 |
IDEMPOTENCY_PAYLOAD_MISMATCH |
This key belongs to a different request. |
409 |
IDEMPOTENCY_IN_PROGRESS, PAYOUT_IN_PROGRESS |
Retry the original request and key with backoff. |
500 |
INTERNAL_ERROR |
Outcome may be uncertain; retry the original request and key. |
503 |
IDEMPOTENCY_UNAVAILABLE |
Protection unavailable; retry the original request and key. |
