Credits & Pricing

TokPortal uses a credit-based system as its unified currency. The same credit balance is shared between the API and the web UI — there is no separate API billing.

TIP: Check the price before you pay it Credits are debited when a bundle is created, not when it is published, and there is no cancellation or refund path. Add X-TokPortal-Dry-Run: true to any write and it is simulated instead: the same validation, the same errors, and credits_would_charge with the real price for your workspace — nothing created, nothing charged. See Sandbox (dry run).

Credit Costs

Operation	Cost
TikTok or Instagram account setup	32 credits, unless `contract_bundle_allowance` returns a workspace-specific price
YouTube account setup	100 credits — not orderable through the API. The price is real and `GET /credit-costs` returns it, but `POST /bundles` rejects a YouTube bundle with `YOUTUBE_DELAYED`; YouTube accounts are delivered through a separate flow arranged with the team. YouTube is outside TokPortal Coverage
Video slot	2 credits per video
Advanced Niche Warming	5 credits per niche target — never per day. Targets are bought 3 to 30 at a time in multiples of 3, so the minimum order is 15 credits. Requires `wants_advanced_warming: true` in the same body, otherwise the call is refused and nothing is charged. Unless `contract_bundle_allowance` returns a workspace-specific price
TokPortal Coverage	25 credits every 30 days per eligible saved account; first period included
Credential or verification-code reveal (Account Owning Fee)	Account-specific: 0 credits under the prior policy for a saved account created before the immutable cutoff; 150 credits for an account created at or after it unless an admin-approved Account Owning Fee agreement applies
Video editing	3 credits per edit slot
Comments API task (comment or reply)	1 credit per task; the former per-bundle moderation add-on is unavailable
Sound volume control	1 credit per video
Story repost link (`story_repost_url`)	1 credit per story, charged once
Instant repost as story (`instant_repost_as_story`)	1 credit per video, charged once
Ad code (TikTok Spark Code / Instagram Partner Code)	7 credits per finalized video
Account edit request	8 credits per request

Advanced Niche Warming is the only warming TokPortal sells. The niche_warming and deep_warming entries you may still see in a GET /credit-costs payload are legacy: they are kept only for accounts being re-created after a refund, they are not part of the current offer, and new deep-warming orders are rejected outright with DEEP_WARMING_DEPRECATED. Do not price a new order from them.

Current pricing and the August 2026 cutover

Every price in the table above is the current standard rate. Older material — earlier newsletters, the marketing site, or a cached copy of these docs — may still show the pre-transition rates (25 credits per account setup, 3 or 4 credits per warming target, a 25-credit "comment moderation" add-on). Those rates are historical: only GET /credit-costs and the checkout quote are authoritative.

Two figures are easy to confuse because both are 25 credits: the recurring 25 credits every 30 days is TokPortal Coverage, charged per eligible saved account. The old per-bundle "comment moderation" add-on has been removed entirely — comment work is now billed per task at 1 credit through the Comments API, with no monthly component.

The production migration records one authoritative pricing cutover timestamp. GET /credit-costs returns it in pricing_transition; clients must not hard-code the deployment time. At the time of writing it is 2026-08-12T08:02:34.814507Z.
Workspaces that had not bought credits before that instant moved to the current rates immediately. Workspaces that had already paid for credits kept the previous rates until August 14, 2026 at 11:00 UTC. Both grace windows are now closed: every workspace pays 32 credits for account setup and 5 credits per Advanced Warming target, except where the live API returns a contractual allowance in contract_bundle_allowance.
TokPortal Coverage grandfathering is account-specific and still uses the recorded production cutover. Every TikTok or Instagram saved account that already existed at that instant remains permanently grandfathered. A saved account created after it is Coverage-eligible unless its creation response marks it contractually exempt.
Credential and verification-code reveal policy is also selected permanently from the saved account's creation timestamp, not the workspace transition. A pre-cutoff saved account keeps the prior 0-credit access policy; a saved account created at or after the cutoff uses the 150-credit managed policy unless Account Owning is already approved.
The server always computes the effective workspace and account price before debit.

INFO: Grandfathered accounts keep their old terms — permanently

Grandfathering is decided per saved account, from that account's created_at, against the immutable production cutover (pricing_transition.managed_account_eligibility_at in GET /credit-costs, currently 2026-08-12T08:02:34.814507Z).

Saved account created TokPortal Coverage Credential / verification-code reveal
Before the cutover (accounts delivered up to August 12, 2026) Never charged. managed_subscription is null and stays null; the account keeps full task access forever Prior policy, 0 credits. The reveal is still irreversible and ends support plus ban coverage, but the account is not detached and keeps its task access
At or after the cutover 25 credits every 30 days, first 30-day period included Managed policy, 150 credits, or the approved Account Owning Fee rate. Reveal permanently detaches the account and ends Coverage

Grandfathering follows the account, not the workspace: a long-standing client who creates a new account today pays the current rates on that new account while their older accounts stay grandfathered. Nothing you can send in a request changes an account's cohort, and there is no expiry date on a grandfathered account.

Workspace action prices (account setup, Advanced Warming) are a separate axis and are no longer grandfathered at all — both transition windows closed on August 14, 2026.

Saved account created	TokPortal Coverage	Credential / verification-code reveal
Before the cutover (accounts delivered up to August 12, 2026)	Never charged. `managed_subscription` is `null` and stays `null`; the account keeps full task access forever	Prior policy, 0 credits. The reveal is still irreversible and ends support plus ban coverage, but the account is not detached and keeps its task access
At or after the cutover	25 credits every 30 days, first 30-day period included	Managed policy, 150 credits, or the approved Account Owning Fee rate. Reveal permanently detaches the account and ends Coverage

TokPortal Coverage

TokPortal Coverage is attached to the saved account, never to a bundle. One account has at most one Coverage record. Creating several bundles for the same account does not create or charge another period.

Each covered account reserves a limited slot on a real manager phone. The recurring charge therefore covers ongoing hardware and manager capacity, not only the moments when a task is actively running. See TokPortal Coverage for the client-facing service explanation.

Bundle creation checkout charges 32 setup credits, or the exact account price returned in an active contract_bundle_allowance. No Coverage period is charged at checkout. For a non-grandfathered, non-exempt saved account created after the production cutover, TokPortal Coverage becomes active when the manager submits it for client review. The first 30 days are included, so the first 25-credit Coverage debit occurs on day 30 and pays for the following 30 days. A TikTok or Instagram saved account that already existed at the cutover remains grandfathered permanently. Every successful renewal is written to the credit transaction history. A bundle that is still in pending_setup or only published cannot start this clock.

Coverage is unique per saved_account_id, not per bundle. Additional bundles never duplicate the charge, and completed, cancelled, or inactive bundles do not stop Coverage. If there are not enough credits at a renewal boundary, Coverage lapses and all tasks are paused. A client may also pause it manually. Pausing stops benefits immediately but does not refund or extend the current period. Reactivation before the current paid or included period expires is free and resumes benefits only until its original end date. After that date, reactivation atomically pays exactly the unpaid 30-day periods, with no extra overlapping period, then resumes withheld work with updated scheduling. Coverage periods are never refunded.

A current managed-policy credential or verification-code reveal ends Coverage permanently. A historical prior-policy reveal keeps its grandfathered task-access behavior. Coverage also ends after staff confirms a banned-account resolution that restores or refunds the eligible account, warming, and unused-video credits. Terminal Coverage does not renew and cannot be reactivated.

For a confirmed eligible platform ban, TokPortal can restore the initial account setup, warming and unused video-slot credits. Coverage must have been active when the ban occurred, the account must never have been revealed, and the claim must be opened within 15 days and satisfy the Ban and Replacement Policy. Restored credits expire 60 days after restoration. Used or published work and the Coverage period itself are not restored.

Credential reveal and Owning Fee

The first password reveal or verification-code retrieval is one irreversible reveal event. A saved account created before the immutable production cutoff keeps the prior policy at 0 credits: support and ban coverage end, but the account is not detached and existing task access remains. A saved account created at or after the cutoff costs 150 credits unless an admin-approved Account Owning Fee agreement applies. For a new-policy account, the API first returns HTTP 428 with the exact current policy and policy_version; the caller must resend both acknowledge_support_forfeit: true and that exact version. A stale nonempty version returns 409 CREDENTIAL_REVEAL_QUOTE_CHANGED without a debit or reveal, so clients must fetch and show the changed policy before requesting fresh confirmation.

For a new-policy account, reveal permanently detaches the account from TokPortal Coverage. The account can no longer receive tasks or analytics refreshes on TokPortal, and no support, replacement, ban protection, refund, credit restoration, compensation or modification is provided. The reveal debit and Coverage shutdown are atomic. Do not send Idempotency-Key because the response contains secrets; TokPortal rejects it before execution. The prior policy for pre-cutoff saved accounts remains grandfathered: support and ban protection end after access, while existing task access remains and the account is not detached.

Account Owning Fee activation requires TokPortal admin approval. Reaching the threshold of 25 live accounts with at least 25 percent revealed creates a pending request and alerts TokPortal. While pending, the client can still use the 150-credit reveal. After approval, revealing an account activates or uses the stored agreement rate instead of the one-time credit charge. Existing legacy agreements remain at $10 per account every 30 days; newly approved agreements use $15.

How Credits Are Debited

Bundle creation: Credits for account creation, video slots, warming and editing are calculated server-side and debited atomically when the bundle is created. The client never determines the cost; the server computes the total from the bundle configuration. The former per-bundle moderation add-on is unavailable.
Comments API tasks: Each comment or reply task costs 1 credit, debited up front and refunded automatically when it cannot be fulfilled under the Comments API rules.
Add video slots — When you add video slots to an existing bundle, credits are debited immediately.
Add edit slots — When you add edit slots to an existing bundle, credits are debited immediately.
Sound volume control — 1 credit is debited the first time volume_original_sound or volume_added_sound is set on a video. Subsequent updates to the same fields on the same video are free.
Refund boundary - TokPortal Coverage periods are never refunded. Outside a confirmed eligible ban resolution, only unused video slots, eligible unconfigured warming, and the initial account creation charge in an eligible cancellation flow may be refunded. Eligible ban restoration follows the separate scope and 60-day validity described above.

Endpoints

Get Credit Balance

curl -X GET https://app.tokportal.com/api/ext/credits/balance \
  -H "X-API-Key: sk_xxx"

{
  "data": {
    "total_credits": 1250,
    "expiring_within_7_days": 0,
    "upcoming_expirations": [
      {
        "amount": 638,
        "expires_at": "2026-06-08T04:47:51.413+00:00",
        "source": "farmer_topup"
      }
    ],
    "last_updated": "2026-05-19T22:42:36.885166+00:00"
  }
}

Field	Type	Description
`total_credits`	number	Current available credit balance.
`expiring_within_7_days`	number	Sum of credits that will expire in the next 7 days.
`upcoming_expirations`	array	Credit lots expiring in the next 30 days (sorted by `expires_at` ascending). Each entry has `amount`, `expires_at` (ISO-8601), and `source`.
`last_updated`	string \| null	Timestamp of the last balance update.

Get Credit History

curl -X GET https://app.tokportal.com/api/ext/credits/history?page=1&per_page=10 \
  -H "X-API-Key: sk_xxx"

{
  "data": [
    {
      "id": "txn_abc123",
      "type": "debit",
      "amount": -97,
      "description": "Bundle created: 1 TikTok account, 10 videos, 9 Advanced Niche Warming targets",
      "breakdown": {
        "account_creation": 32,
        "video_slots": 20,
        "advanced_warming": 45
      },
      "balance_after": 1153,
      "created_at": "2025-11-20T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 47,
    "total_pages": 5
  }
}

Get Credit Costs

Retrieve the current cost table programmatically immediately before creating a bundle. CUTOVER_TIMESTAMP_FROM_API stands for the real ISO 8601 timestamp returned by the live endpoint. To keep the example readable, each nested cost object shows only credits; the live response also includes its required description and note fields.

curl -X GET https://app.tokportal.com/api/ext/credit-costs \
  -H "X-API-Key: sk_xxx"

{
  "data": {
    "costs": {
      "account_creation": { "credits": 32 },
      "youtube_account_creation": { "credits": 100 },
      "video_upload": { "credits": 2 },
      "advanced_warming": { "credits": 5 },
      "niche_warming": { "credits": 7, "description": "LEGACY — not offered. Superseded by Advanced Niche Warming (advanced_warming)." },
      "deep_warming": { "credits": 40, "description": "LEGACY — discontinued, new orders are rejected. Superseded by advanced_warming." },
      "video_edit": { "credits": 3 },
      "comment_task": { "credits": 1 },
      "sound_volume": { "credits": 1 },
      "repost_url": { "credits": 1 },
      "ad_code": { "credits": 7 },
      "managed_account_subscription": { "credits": 25 },
      "credential_reveal": { "credits": 150 }
    },
    "workspace_pricing": {
      "cohort": "new_credit_customer",
      "effective_at": "CUTOVER_TIMESTAMP_FROM_API",
      "transition_active": true,
      "tokportal_coverage_eligible_for_new_accounts_now": true
    },
    "contract_bundle_allowance": null,
    "owning_fee": {
      "requires_admin_approval": true,
      "minimum_live_accounts": 25,
      "minimum_reveal_ratio": 0.25,
      "pending_reveal_credits": 150,
      "legacy_usd_per_account_per_30_days": 10,
      "new_agreement_usd_per_account_per_30_days": 15,
      "new_agreement_effective_at": "CUTOVER_TIMESTAMP_FROM_API",
      "note": "Crossing the threshold creates an approval request and never activates Account Owning Fee automatically."
    },
    "pricing_transition": {
      "users_without_paid_credit_purchase_before_transition": {
        "effective_at": "CUTOVER_TIMESTAMP_FROM_API",
        "tokportal_coverage_eligible_for_accounts_created_at_or_after": "CUTOVER_TIMESTAMP_FROM_API",
        "account_creation_credits": 32,
        "advanced_warming_per_term_credits": 5
      },
      "users_with_paid_credit_purchase_before_transition": {
        "effective_at": "2026-08-14T11:00:00.000Z",
        "tokportal_coverage_eligible_for_accounts_created_at_or_after": "CUTOVER_TIMESTAMP_FROM_API",
        "before_effective_at": {
          "account_creation_credits": 25,
          "advanced_warming_per_term_credits": 3
        },
        "after_effective_at": {
          "account_creation_credits": 32,
          "advanced_warming_per_term_credits": 5
        }
      },
      "managed_account_eligibility_at": "CUTOVER_TIMESTAMP_FROM_API",
      "managed_account_eligibility_at_deprecated": false,
      "managed_account_eligibility_note": "Production migration cutover and saved-account grandfathering boundary.",
      "grandfathering": "A TikTok or Instagram saved account that already existed at the production cutover is permanently grandfathered and has no managed_subscription record."
    },
    "examples": {
      "account_only": { "description": "1 TikTok account", "total": 32 },
      "account_with_10_videos": { "description": "1 account + 10 videos", "total": 52 },
      "account_with_10_videos_and_warming": { "description": "1 account + 10 videos + 3 Advanced Niche Warming targets", "total": 67 },
      "account_with_advanced_warming": { "description": "1 account + 12 Advanced Niche Warming targets", "total": 92 },
      "account_with_10_videos_and_advanced_warming": { "description": "1 account + 10 videos + 9 Advanced Niche Warming targets", "total": 97 }
    }
  }
}

contract_bundle_allowance is null for the standard tariff. When present, it is the authoritative workspace-specific contract for qualifying new bundles. It includes the platform, country, supported bundle types, remaining quantity, account setup price, Advanced Warming price and Coverage exemption. A qualifying slot is consumed only when POST /bundles or POST /bundles/bulk successfully creates the bundle and debits credits. Draft preparation and later publication consume nothing. Bulk allocation is deterministic and atomic. If the allowance changes between quote and checkout, the API returns 409 BUNDLE_PRICING_CHANGED; nothing is created or charged, and the client must fetch /credit-costs again and retry with a new Idempotency-Key.

repost_url is the cost of adding a story repost link — charged once, the first time story_repost_url is set on a story.

Cost Breakdown Example

Creating a bundle with the following configuration:

1 TikTok account
10 video slots
Advanced Niche Warming with 9 targets (wants_advanced_warming: true)
Video editing enabled (10 edit slots)

Item	Calculation	Cost
Account creation	1 x 32	32 credits
Video slots	10 x 2	20 credits
Advanced Niche Warming	9 x 5	45 credits
Video editing	10 x 3	30 credits
Total		127 credits

If your balance is below the required total, the API returns an INSUFFICIENT_CREDITS error with full details:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits to complete this operation.",
    "details": {
      "required": 127,
      "available": 50,
      "missing": 77,
      "breakdown": {
        "account_creation": 32,
        "video_slots": 20,
        "advanced_warming": 45,
        "edit_slots": 30
      }
    }
  }
}