Campaign quick pay

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.

When agency approvals are enabled, Quick Pay always requires approval, including requests from admins and finance users in the campaign screen. Otherwise, it initiates payment immediately unless you set requireApproval: true. Keep keys with payouts:write on your server.

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`, `EUR`, `GBP`, or `CAD`, 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.

SDK v1

Campaign management

POST /sdk/v1/campaign-creators/:campaignCreatorRecordId/quick-pay

Prerequisites

Headers

Request body

Platform fees

Currency conversion and confirmation

Example request

JavaScript integration

Immediate payment response — HTTP 200

Require approval — HTTP 202

GET /sdk/v1/campaign-creators/:campaignCreatorRecordId/quick-pay/approvals/:approvalId

Safe retries

Errors

​POST /sdk/v1/campaign-creators/:campaignCreatorRecordId/quick-pay

​Prerequisites

​Headers

​Request body

​Platform fees

​Currency conversion and confirmation

​Example request

​JavaScript integration

​Immediate payment response — HTTP 200

​Require approval — HTTP 202

​GET /sdk/v1/campaign-creators/:campaignCreatorRecordId/quick-pay/approvals/:approvalId

​Safe retries

​Errors

POST /sdk/v1/campaign-creators/:campaignCreatorRecordId/quick-pay

Prerequisites

Headers

Request body

Platform fees

Currency conversion and confirmation

Example request

JavaScript integration

Immediate payment response — HTTP 200

Require approval — HTTP 202

GET /sdk/v1/campaign-creators/:campaignCreatorRecordId/quick-pay/approvals/:approvalId

Safe retries

Errors