Prepaid credit
Pay upfront for future usage, then use the balance to pay for campaigns and invoices. Each team's credit is held on its own Stripe billing customer. Approved provisioning partners can also fund their client teams.
Requirements
- Contact Scribeless to enable prepaid credit for your team.
- You can buy credit without a subscription, saved card or invoice auto-charging. Scribeless creates a billing customer on the first top-up if needed.
- Teams that use a separate billing customer for each checkout cannot buy prepaid credit.
- Authenticate with the team's API key or its provisioning partner's key.
The same endpoints accept a signed-in user session. API examples below use X-API-Key.
Currency and amounts
Client teams inherit their provisioning partner's billing currency unless a currency is configured directly on the client team. Top-ups use that billing currency automatically.
Send amounts as integers in the currency's minor unit. For example, 100000 represents 1,000 in the team's billing currency. Responses include the currency code, shown as TEAM_CURRENCY in the examples below.
Check the balance
Use availableCredit to show how much the team can spend. In the example below, 100000 means 1,000 available in the team's billing currency.
curl 'https://platform.scribeless.co/api/teams/TEAM_ID/credits' \
--header 'X-API-Key: YOUR_API_KEY'
API-key response:
{
"teamId": "TEAM_ID",
"currency": "TEAM_CURRENCY",
"availableCredit": 100000
}
| Field | Meaning |
|---|---|
teamId | The team whose balance was requested. |
currency | Billing currency. |
availableCredit | Remaining credit to display to the customer, in minor units. Always zero or positive. |
Before a team has a Stripe customer, availableCredit is 0.
Buy credit
curl --request POST 'https://platform.scribeless.co/api/teams/TEAM_ID/credits/checkout' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data '{
"amount": 100000,
"redirectUrl": "https://partner.example.com/scribeless/credit-return"
}'
| Field | Type | Meaning |
|---|---|---|
amount | integer | Required. Between 100 and 10000000, inclusive, in the team's currency minor unit. |
redirectUrl | string | Optional HTTPS URL for the payment return. |
{
"checkoutUrl": "https://platform.scribeless.co/partner-checkout?sessionId=CHECKOUT_SESSION_SECRET",
"amount": 100000,
"currency": "TEAM_CURRENCY"
}
Open the returned checkoutUrl or share it with the payer to confirm payment in Stripe Checkout. The link expires after one hour and contains a session secret, so do not log or publish it. Opening it does not charge a saved card, and paying does not save the top-up card or change the team's invoice payment settings.
Successful payment adds the amount paid to the team's credit, with no tax, discounts or generated invoice. To pay for pending recipients, continue with recipient checkout.
Payment return
When redirectUrl is supplied, successful payment returns with:
https://partner.example.com/scribeless/credit-return?status=payment_succeeded
Check the balance to confirm the credit after the return:
status=payment_succeeded: payment was received. Ifreason=credit_pendingis also present, credit is still processing; check again without asking the customer to pay again.status=payment_failed: payment failed or is incomplete. Areasonmay provide more detail.
Repeated notifications for the same payment do not add credit twice. Each new Checkout Session is a separate purchase, so reuse an existing payment link while it remains valid.
Fund a partner's client
Use the partner's API key with the client's TEAM_ID in each endpoint. The partner must have provisioning access and the client must be linked to it. Funds go to the client's balance.
List credit transactions
Fetch the team's credit activity, newest first. Use the team's API key or its provisioning partner's key. Each transaction returns only the six fields shown below.
curl 'https://platform.scribeless.co/api/teams/TEAM_ID/credits/transactions?limit=25' \
--header 'X-API-Key: YOUR_API_KEY'
API-key response:
{
"data": [
{
"id": "cbtxn_example",
"creditAmount": 100000,
"currency": "TEAM_CURRENCY",
"description": "Prepaid credit top-up",
"invoiceUrl": null,
"createdAt": "2026-11-02T12:00:00.000Z"
}
],
"hasMore": false,
"nextCursor": null
}
| Field | Meaning |
|---|---|
id | Transaction ID. |
creditAmount | Amount added or deducted, in minor units. Positive adds credit; negative records spending or a credit reversal. |
currency | Transaction currency. |
description | Description of the activity, when available. |
invoiceUrl | Link to the related invoice, when available. |
createdAt | UTC timestamp in ISO 8601 format. |
limit defaults to 25 and accepts 1 to 100. When hasMore is true, pass nextCursor as startingAfter to fetch the next page:
GET https://platform.scribeless.co/api/teams/TEAM_ID/credits/transactions?limit=25&startingAfter=cbtxn_example
An empty history returns data: [], hasMore: false and nextCursor: null.
Spending credit
Credit applies to eligible invoices in the same currency, including subscription invoices. Recurring campaigns on subscription-backed teams continue to use subscription metering; credit applies when the subscription invoice is finalized.
For invoice-billed one-time campaigns, Stripe applies credit first and charges the saved card for any shortfall. If a credited invoice needs further payment, checkout returns its hosted invoice URL. Recipients remain pending until payment succeeds; use that URL to finish paying the existing invoice.
For one-time campaign and cart Checkout flows without invoice auto-charging, Scribeless reserves available credit and asks the payer to pay the remainder. If available credit pays the full campaign or cart total, no card payment is needed. An expired Checkout releases its reserved credit.
These flows require a valid billing address for tax calculation. If the remainder is below Stripe's minimum charge, the card payment may include that minimum, with less credit used.
For example, a credit balance of 1,000 pays for a campaign costing 300, leaving 700. A later campaign costing 800 uses the remaining 700 and requires a payment of 100. All figures are in the team's billing currency and include any applicable tax.
Status codes
| Status | Meaning |
|---|---|
200 | Balance, transaction history or a new Checkout link returned. A new link is not a completed payment. |
400 | Invalid amount, redirect URL, page size or cursor. |
401 | Missing, invalid or unauthorized authentication. |
404 | Team not found or outside the caller's team/partner access. |
409 | Top-up blocked by team eligibility, billing customer or currency configuration. |
502 | Stripe balance, transaction history or Checkout could not be retrieved or created. Retry or contact support if it persists. |