Funding and billing

Agents can request reusable advertising credit with a live API key. The owner authorizes payment on a secure hosted checkout. A signed webhook verifies the receipt and updates the balance; the agent can then fund multiple separately approved campaigns.

Create a top-up

Read GET /api/v1/balance first using a live key with campaigns:read. available_cents is reusable credit; reserved_cents is committed lifetime campaign budgets. on_hold blocks new spending. topups_enabled reports preliminary readiness; provider permission is checked again during checkout creation.

curl "$BASE_URL/api/v1/balance/topups" \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: advertising-credit-001' \
  -d '{"amount_cents":10000,"currency":"USD"}'

Use campaigns:write. Amounts are integer USD cents, from 5000 to 100000 ($50–$1,000). The first request returns 201; an identical replay returns 200 and Idempotency-Replayed: true. Keep the exact body and key after a timeout. A changed amount with the same key returns idempotency_conflict. At most ten unresolved top-ups and the operator's total funding allowance are permitted.

Read the response's data.id, status, checkout_url, and next_action. When next_action.type is owner_checkout, give its URL to the owner. It is a secure hosted payment page. Creating a link does not debit a saved card, subscribe the owner, or authorize advertising. Never send your MarketingRouter API key to the checkout URL.

The response separates amount_cents (advertising credit), service_fee_cents (currently zero during beta), subtotal_cents, charged_cents, tax_cents, and payment_cost_cents. Actual charge and tax remain null until verified. Payment costs are not quoted by this API: null is unknown, not zero. The owner reviews the final total, including applicable provider costs and taxes, at checkout before paying. These extras do not reduce the selected advertising credit. No automatic refill or off-session card charge is implemented.

Read and reconcile

Request	Scope	Result
GET /api/v1/balance	campaigns:read	Verified funding, available credit, reserved budgets, hold, shortfall and the last 20 ledger entries.
GET /api/v1/balance/topups?cursor=UUID	campaigns:read	Up to 50 top-ups in descending UUID order; follow next_cursor until null.
GET /api/v1/balance/topups/{id}	campaigns:read	Current top-up state and owner action, if needed.
POST /api/v1/balance/topups/{id}/reconcile	campaigns:read	Refresh provider receipts and apply verified credit. No body, charge, refund or new checkout.

All endpoints accept the owner session too. Sandbox keys cannot access real balances. Only the authenticated owner's records are returned.

Poll the individual top-up with bounded backoff (2, 4, 8, then 30 seconds). The normal update path is automatic webhook processing. Reconcile explicitly when payment appears delayed, then stop retrying and retain the request ID for support if the provider remains unavailable. A checkout redirect, URL query parameter, or client-side success callback never establishes payment.

States: creating → checkout_ready → payment_pending → funded. Pending can be skipped. outcome_unknown means preserve the original key and reconcile the original operation; failed requires correction. review_required means operator review, not another payment attempt. Only funded credits the ledger.

Spending and reversals

An approved campaign reserves its lifetime budget atomically. Concurrent campaigns cannot reserve the same credit. Funds, owner spending approval, operator allowance, and advertising purchasing capacity are separate checks. A successful customer payment can still be subject to processor fees, reserves and delayed settlement; the operator supplies the working capital for ad delivery.

Reservations remain after a pause. Final spend settlement and automatic unused-credit refunds are not implemented. A refund, dispute, duplicate paid receipt or invalid funded payment removes that order's credit and holds the workspace for operator review. Affected campaigns receive pause requests; network/provider delays can still accrue spend. A later or repeated success event cannot remove that hold automatically.

Payment verification and recovery

MarketingRouter receives authenticated payment notifications and verifies receipts automatically. Customers and agents do not need to create a webhook. A checkout redirect never proves payment; only a funded response establishes credit.

Duplicate and out-of-order notifications do not double-credit the balance. Background reconciliation retries delayed receipts. Refund/dispute holds require operator resolution; retries do not remove them. If a paid checkout stays pending, reconcile the original top-up and retain its ID and request ID for support. Do not create another payment to work around an uncertain result.

Creative generation is billed through a separate provider workflow and does not debit this advertising balance. Its nullable cost observation is not a settled customer invoice.

Existing campaign-specific checkout

The owner can also use POST /api/v1/funding with campaign_id and Idempotency-Key for one exact prepared draft. It remains owner-only. GET /api/v1/funding and GET /api/v1/funding/{id} expose those records; POST /api/v1/funding/{id}/reconcile is owner-only. A campaign-specific receipt funds its matching campaign, while reusable balance funds any eligible approved campaign. Never pay both for the same intended budget.