Documentation / Campaign management / Campaign creators

Campaign quick pay

Send or submit a campaign payment for approval, with custom line items, fee allocation, and safe retries.

campaign quick pay · json
{ "mode": "INHERIT" }
All 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. Use campaigns:read to discover records and payouts:read to check payment status and invoices.
  • An existing, active campaign creator record in your agency. Find its campaignCreatorRecordId through 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 }
  ]
}
  • amount and currency: the gross sum in the currency you requested.
  • creatorAmount and creatorCurrency: 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.
  • invoiceId and agencyInvoiceId: 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.

Describe your program.

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