Balance clear → wallet (pending approval) - Cosmic Agency Ad Accounts API

Balance clear

Hard rate limit: 1 request / 5 seconds per API client (money_write bucket).

Requires Idempotency-Key (same key within 24h replays first response).

Each item also requires unique_id UUID stored on the row; reuse → 409 DUPLICATE_UNIQUE_ID.

Failed requests also count. Over limit → 429 RATE_LIMITED + Retry-After.

Scope: ad_accounts:clear.

Remaining balance must be >= 1. Pending approval; no Meta call.

Body items[{meta_id, unique_id}]. meta_id is the Meta ad account id (act_ prefix optional). Reuse unique_id → 409 DUPLICATE_UNIQUE_ID.

Webhook

We POST this JSON to the webhook_url saved in Developer Settings. This is not an endpoint you call.

unique_id is the item id from the request. status is success or fail. reason is present on fail only.

Success is deduped by (api_client, unique_id, type) for about 24 hours. Any 2xx from your URL counts as received.

Not sent for validation errors.

This call only creates a pending-approval ticket. No webhook is sent at submit time.

After an admin approves and the clear completes, type is clear and status is success. After an admin denies, status is fail.

{ "type": "clear", "unique_id": "550e8400-e29b-41d4-a716-446655440001", "status": "success" }
{ "type": "clear", "unique_id": "550e8400-e29b-41d4-a716-446655440001", "status": "fail", "reason": "denied" }

请求参数

Authorization

Bearer Token

在 Header 添加参数

Authorization

，其值为在 Bearer 之后拼接 Token

示例：

Authorization: Bearer ********************

Header 参数

Body 参数application/json必填

示例

{
    "items": [
        {
            "meta_id": "123456789012345",
            "unique_id": "677cf8c4-9b37-4a4b-b000-2ee947357c3a"
        }
    ]
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200

application/json

Created pending clear

Bodyapplication/json

示例

{
    "code": 0,
    "msg": "ok",
    "data": {
        "records": [
            {
                "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
                "unique_id": "e5f6a7b8-c9d0-1234-ef01-345678901234",
                "from_ad_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "status": "pending approval",
                "amount": 50,
                "is_all_amount": false,
                "is_to_wallet": true,
                "created_at": "2026-10-01T00:00:00.000Z"
            }
        ]
    },
    "request_id": "string"
}

🟠400

🟠403

🟠409

🟠429