Request ad account replacement

Asks for a new ad account to replace one Koast created that stopped running (Meta disabled or restricted it).

Tool name: request-ad-account-replacement.

Asks for a new ad account to replace one Koast created that stopped running (Meta disabled or restricted it). Koast then connects the new account to the same brand and moves the budget left on the old one to it, and emails the user when it is ready.

When to use

Use when the user says an ad account from an ad account request stopped running, was disabled or cannot spend, and wants a new one. Confirm which ad account first. An account that is still running is refused; follow the replacement with get-ad-account-request.

Access

Property	Value
Required scope	`write`
Publishes	No
Read-only	No
Destructive	No
Idempotent	No
Open world	Yes

Input

Field	Type	Required	Description
`requestId`	`string`	Yes	The ad account request id, or its Koast reference (`KST-…`). At most 40 characters.
`adAccountId`	`string`	Yes	The ad account that stopped running, `act_…`: one of the request's `accounts`. At most 40 characters.
`reason`	`string`	No	What happened to the ad account, in the user's words, passed on to the ad account partner. At most 500 characters.

Output

Field	Type	Required	Description
`id`	`string`	Yes
`reference`	`string`	Yes	The Koast reference shown in the app and in emails, `KST-…`.
`status`	`string`	Yes	`QUEUED` and `SUBMITTED` while the request is sent, `VERIFYING` while the business is checked, `CREATING` while the account is created, `SHARED` once it is shared into the Business Manager, `READY` once it is connected in Koast, `REJECTED` (see `rejectionReason`) or `CANCELLED`. Funds can be added from `SHARED`. One of `QUEUED`, `SUBMITTED`, `VERIFYING`, `CREATING`, `SHARED`, `READY`, `REJECTED`, `CANCELLED`.
`accountName`	`string`	Yes	The ad account name the customer asked for.
`count`	`integer`	Yes	How many ad accounts were requested.
`currency`	`string`	Yes
`createdAt`	`string`	Yes
`brandId`	`integer \| null`	Yes	The Koast brand the first ad account was connected to, once connected.
`adAccountIds`	`string[]`	Yes	The ad accounts connected in Koast, `act_…`.
`rejectionReason`	`string \| null`	Yes
`stage`	`integer`	Yes	The last stage reached: 1 request sent, 2 business verified, 3 account being created, 4 shared into your Business Manager, 5 connected in Koast, 6 funds added. Minimum 0, maximum 6.
`awaitingReview`	`boolean`	Yes	True while Koast reviews the request before sending it on. It stays `QUEUED` at stage 1 until Koast approves it, or `REJECTED` with a `rejectionReason`.
`accounts`	`object[]`	Yes	The ad accounts created for the request, once shared.
`topUps`	`object[]`	Yes	Every top-up started for the request, oldest first.

REST equivalent

POST /v1/ad-account-requests/{requestId}/accounts/{adAccountId}/replacement, Request ad account replacement. CLI: koast request-ad-account-replacement.