Add ad account funds
Creates a top-up and a payment page for it, and returns the top-up with its fees and checkoutUrl. The call itself moves no money: the user pays on the page, by the payment method chosen here only, and Koast adds the funds to the ad account once the payment is received. A card payment is received at once; a US bank transfer takes 1-3 business days to arrive. Follow it with GET /v1/ad-account-requests/{requestId}: the top-up moves from AWAITING_PAYMENT to PAID to CREDITED. Every call creates a new payment page; send an Idempotency-Key so that a retry returns the same one. Refusals are those of GET /v1/ad-account-requests/{requestId}/top-ups/quote, and 409 conflict with reason use_funding_details for a bank transfer or crypto when the organization sends those to its funding details (GET /v1/ad-account-funding) instead of a payment page.
bearerAuthAuthorizationBearer <token>An organization API key (koast_sk_…) with the API surface enabled, or an OAuth access token issued by Koast (koast_at_…) whose audience covers this API. REST access requires an active Agency plan.
requestId*stringThe ad account request id, or its Koast reference (KST-…).
1 <= length <= 40Idempotency-Key?stringRetrying with the same key within 24 hours returns the first response without acting again.
length <= 255application/json- body
adAccountId*stringThe ad account to fund, act_…: one of the request's accounts.
1 <= length <= 40budgetCents*integerThe budget to land on the ad account, in cents of the request's currency. Koast's fee and the platform location fee are added on top of it.
0 < value <= 9007199254740991paymentMethod*stringHow the customer pays: card, bank_transfer (a US bank transfer, USD accounts only) or crypto (USDC, USD accounts only, when Koast offers it). Koast's fee depends on it.
"card""bank_transfer""crypto"Add ad account funds
application/json- response
topUp*checkoutUrl*stringThe payment page. The user opens it to pay; nothing is charged until they do. It expires after 24 hours unpaid.
curl -X POST "https://example.com/v1/ad-account-requests/string/top-ups" \ -H "Authorization: Bearer koast_sk_..." \ -H "Content-Type: application/json" \ -d '{ "adAccountId": "string", "budgetCents": 1, "paymentMethod": "card" }'{ "topUp": { "id": "string", "adAccountId": "string", "budgetCents": -9007199254740991, "commissionCents": -9007199254740991, "locationFeeCents": -9007199254740991, "netCents": -9007199254740991, "amountCents": -9007199254740991, "currency": "string", "status": "AWAITING_PAYMENT", "paymentMethod": "card", "createdAt": "string", "paidAt": "string", "creditedAt": "string" }, "checkoutUrl": "string"}Required scope: write. CLI: koast add-ad-account-funds, see Ad Account Requests commands. Authentication, headers, errors and pagination work the same on every operation. See Conventions.
Request ad account replacement
Asks the ad account partner to replace an ad account of the request that is not running, and returns the request with the replacement on that account (accounts[].replacement). Koast follows it through on its own: once the partner hands the new account over, Koast connects it to the brand the old one was on, moves the budget left on the old account to the new one (movedCents) and emails the person who requested the account. The request must be SHARED or READY. Refused with 409 conflict and reason account_running while the ad account is still running, replacement_open while a replacement is under way, already_replaced once it was replaced, request_not_replaceable before the account is shared, and replacement_refused when the partner refuses it. Another organization's request answers 404.
Quote ad account funds
Prices a top-up exactly as POST /v1/ad-account-requests/{requestId}/top-ups would, and creates nothing. The customer chooses the budget that lands on the ad account; Koast's fee (a rate per payment method) and the platform location fee are added on top, and amountCents is what the payment page charges. Refusals are those of the top-up: 400 validation_failed naming the field for a budget under the minimum or over the maximum, a payment method not offered for the account's currency (bank transfer and crypto are USD only; crypto paid on a payment page is at most 10,000.00 USD per payment) or an ad account the request does not hold; 409 conflict before the ad account is shared.