Submit topup (aligns with New Top-up modal) - Cosmic Agency Ad Accounts API

Top-up

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:topup.

Validates min top-up, amount>0, same account type, wallet currency rules.

Each item meta_id is the Meta ad account id (act_ prefix optional). It is resolved to the tenant ad account.

Each item requires unique_id (UUID); reuse → 409 DUPLICATE_UNIQUE_ID.

Creates topup rows; if client.recharge, may call Meta. Response data.failed_items lists per-row FB/insufficient failures.

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.

When auto-recharge is on (client.recharge), complete sends success. Insufficient wallet or a Meta failure sends fail.

When auto-recharge is off, the row stays pending and no webhook is sent until it later becomes complete or denied.

{ "type": "topup", "unique_id": "550e8400-e29b-41d4-a716-446655440000", "status": "success" }
{ "type": "topup", "unique_id": "550e8400-e29b-41d4-a716-446655440000", "status": "fail", "reason": "insufficient wallet balance" }

请求参数

Authorization

Bearer Token

在 Header 添加参数

Authorization

，其值为在 Bearer 之后拼接 Token

示例：

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

Header 参数

Body 参数application/json必填

示例

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

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200

application/json

Created / partially completed (see failed_items)

Bodyapplication/json

示例

{
    "code": 0,
    "msg": "ok",
    "data": {
        "records": [
            {
                "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
                "unique_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
                "ad_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "status": "requested",
                "amount": 100,
                "amount_paid": 100,
                "currency_code": "USD",
                "converted_from_code": "USD",
                "invoice_number": 10001,
                "created_at": "2026-10-01T00:00:00.000Z"
            }
        ],
        "facebook_executed": false,
        "completed_ids": [
            "b2c3d4e5-f6a7-8901-bcde-f12345678901"
        ],
        "failed_items": [
            {
                "meta_id": "123456789012345",
                "ad_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "topup_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
                "reason": "insufficient wallet balance"
            }
        ]
    },
    "request_id": "string"
}

🟠400

🟠403

🟠409

🟠429