Billing

A free trial, then a prepaid balance. New workspaces publish for free for 7 days from their first published post (14 days at most from signing up); X and phone numbers need balance. After the first top-up, connected accounts are charged day by day and usage (X API, messages, phone numbers, calls, SMS) as it happens. Topping it up happens in the dashboard.

Get the balance

GET/v1/billing

Balance, the free trial, connected accounts and what they cost. Once the trial ends without a top-up, or the balance is used up after paying, connecting accounts and publishing or sending answer 402; scheduled posts of an ended trial wait as paused until the first top-up.

Response 200

data

enabledbooleanrequired
False while billing is not available: nothing is charged or limited.
balancenumberrequired
Prepaid balance in euro cents (up to three decimals): 1250.5 is 12.505 €. Negative when charges outran it.
currencystringrequired
connectedAccountsintegerrequired
max 9,007,199,254,740,991
trialobject
The free trial: connect any network (X and phone numbers need balance) and publish without paying. When it ends unpaid, scheduled posts pause until the first top-up.
trial
- statusstringrequired
  pending: nothing published yet; active: the free days run; expired: ended without paying; converted: paid.
  Values: pending · active · expired · converted
- registeredAtstring (date-time)required
- startedAtstring (date-time)
  First published post: the free days count from here.
- endsAtstring (date-time)required
  7 days after the first published post, and never more than 14 days after signing up.
- daysLeftinteger | nullrequired
  Whole days left (0 on the last day); null once it ended or was paid.
- trialDaysintegerrequired
  Free days once it starts: 7, fewer when the 14-day limit cuts it.
  max 9,007,199,254,740,991
- maxAccountsintegerrequired
  Accounts the trial covers (20). Connecting a 21st needs balance, and the first top-up ends the trial.
  max 9,007,199,254,740,991
- bannerstring
  What the dashboard shows now about the trial.
  Values: first_post · two_days_left · running · day6 · ended
- statsobjectrequired
  stats
  - publishedintegerrequired
    max 9,007,199,254,740,991
  - scheduledintegerrequired
    max 9,007,199,254,740,991
  - pausedintegerrequired
    Scheduled posts on hold since the trial ended.
    max 9,007,199,254,740,991
  - accountsintegerrequired
    max 9,007,199,254,740,991
monthlyEstimateintegerrequired
Monthly price of the accounts connected now, in cents. It is charged day by day.
max 9,007,199,254,740,991
dailyEstimatenumberrequired
What those accounts cost today, in cents (up to three decimals).
daysLeftinteger | nullrequired
Whole days the balance covers at that cost; null when nothing is charged daily.
linesobject[]required
lines
- fromintegerrequired
  max 9,007,199,254,740,991
- tointeger | nullrequired
- accountsintegerrequired
  max 9,007,199,254,740,991
- unitAmountintegerrequired
  Cents per account and month.
  max 9,007,199,254,740,991
- amountintegerrequired
  max 9,007,199,254,740,991
canConnectMorebooleanrequired
Whether one more account can be connected right now.
blockedbooleanrequired
Publishing is on hold: the free trial ended without a top-up, or the balance is used up. Nothing is deleted.
cardobject
The saved payment method, for automatic recharges.
card
- brandstringrequired
  Card brand (visa, mastercard…) or another saved method (link, sepa_debit).
- last4string
- expMonthinteger
  max 9,007,199,254,740,991
- expYearinteger
  max 9,007,199,254,740,991
autoRechargeobject
autoRecharge
- enabledbooleanrequired
- thresholdintegerrequired
  Recharge when the balance falls below this, in cents.
  max 9,007,199,254,740,991
- amountintegerrequired
  What each recharge adds, in cents.
  max 9,007,199,254,740,991
- monthlyLimitintegerrequired
  Most that automatic recharges add in a calendar month, in cents.
  max 9,007,199,254,740,991
autoRechargeErrorobject
Why the last automatic recharge failed; it switched itself off.
autoRechargeError
- atstring (date-time)required
- messagestringrequired
autoRechargedThisMonthintegerrequired
Added by automatic recharges this calendar month, in cents.
max 9,007,199,254,740,991
topUpobjectrequired
Allowed top-up amounts, in cents.
topUp
- minintegerrequired
  max 9,007,199,254,740,991
- maxintegerrequired
  max 9,007,199,254,740,991
hasPortalbooleanrequired
Whether the billing portal (invoices, payment method) is available.

curl "https://api.marsial.dev/v1/billing" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/billing', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/billing",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

List balance movements

GET/v1/billing/movements

Top-ups and charges, newest first.

Parameters

limitinteger
max 200

Response 200

data []

idstringrequired
kindstringrequired
Values: top_up · auto_recharge · accounts · usage · adjustment
amountnumberrequired
Euro cents, up to three decimals: positive adds, negative debits. -9.678 is 0.09678 €.
currency"eur"required
The currency of amount (in cents).
atstring (date-time)required
daystring
UTC day (YYYY-MM-DD) a charge covers.
accountsinteger
Accounts a day was charged for.
max 9,007,199,254,740,991
familystring
Usage family of a usage charge: X API, messages, phone numbers, calls, SMS or SMS registration.
Values: xApi · messages · numbers · calls · sms · dlc

curl "https://api.marsial.dev/v1/billing/movements" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/billing/movements', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/billing/movements",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Top up the balance

POST/v1/billing/top-upDashboard only

Opens a payment page. The balance grows once the payment succeeds; the card is saved for automatic recharges.

Body

amountintegerrequired
Balance to add, in cents (taxes, if any, on top). Limits come with GET /v1/billing.
max 9,007,199,254,740,991
successUrlstring (uri)required
Dashboard page to come back to after paying.
cancelUrlstring (uri)required
Dashboard page to come back to if the user leaves Checkout.

Response 200

data

urlstring (uri)required
Send the user here.

curl -X POST "https://api.marsial.dev/v1/billing/top-up" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/billing/top-up', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/billing/top-up",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Set automatic recharges

PUT/v1/billing/auto-rechargeDashboard only

Tops up the saved card when the balance falls below the threshold, up to a monthly limit. Needs one top-up first.

Body

enabledbooleanrequired
thresholdintegerrequired
Recharge when the balance falls below this, in cents.
max 9,007,199,254,740,991
amountintegerrequired
What each recharge adds, in cents.
max 9,007,199,254,740,991
monthlyLimitintegerrequired
Most that automatic recharges may add in a calendar month, in cents.
max 9,007,199,254,740,991

Response 200

data

enabledbooleanrequired
False while billing is not available: nothing is charged or limited.
balancenumberrequired
Prepaid balance in euro cents (up to three decimals): 1250.5 is 12.505 €. Negative when charges outran it.
currencystringrequired
connectedAccountsintegerrequired
max 9,007,199,254,740,991
trialobject
The free trial: connect any network (X and phone numbers need balance) and publish without paying. When it ends unpaid, scheduled posts pause until the first top-up.
trial
- statusstringrequired
  pending: nothing published yet; active: the free days run; expired: ended without paying; converted: paid.
  Values: pending · active · expired · converted
- registeredAtstring (date-time)required
- startedAtstring (date-time)
  First published post: the free days count from here.
- endsAtstring (date-time)required
  7 days after the first published post, and never more than 14 days after signing up.
- daysLeftinteger | nullrequired
  Whole days left (0 on the last day); null once it ended or was paid.
- trialDaysintegerrequired
  Free days once it starts: 7, fewer when the 14-day limit cuts it.
  max 9,007,199,254,740,991
- maxAccountsintegerrequired
  Accounts the trial covers (20). Connecting a 21st needs balance, and the first top-up ends the trial.
  max 9,007,199,254,740,991
- bannerstring
  What the dashboard shows now about the trial.
  Values: first_post · two_days_left · running · day6 · ended
- statsobjectrequired
  stats
  - publishedintegerrequired
    max 9,007,199,254,740,991
  - scheduledintegerrequired
    max 9,007,199,254,740,991
  - pausedintegerrequired
    Scheduled posts on hold since the trial ended.
    max 9,007,199,254,740,991
  - accountsintegerrequired
    max 9,007,199,254,740,991
monthlyEstimateintegerrequired
Monthly price of the accounts connected now, in cents. It is charged day by day.
max 9,007,199,254,740,991
dailyEstimatenumberrequired
What those accounts cost today, in cents (up to three decimals).
daysLeftinteger | nullrequired
Whole days the balance covers at that cost; null when nothing is charged daily.
linesobject[]required
lines
- fromintegerrequired
  max 9,007,199,254,740,991
- tointeger | nullrequired
- accountsintegerrequired
  max 9,007,199,254,740,991
- unitAmountintegerrequired
  Cents per account and month.
  max 9,007,199,254,740,991
- amountintegerrequired
  max 9,007,199,254,740,991
canConnectMorebooleanrequired
Whether one more account can be connected right now.
blockedbooleanrequired
Publishing is on hold: the free trial ended without a top-up, or the balance is used up. Nothing is deleted.
cardobject
The saved payment method, for automatic recharges.
card
- brandstringrequired
  Card brand (visa, mastercard…) or another saved method (link, sepa_debit).
- last4string
- expMonthinteger
  max 9,007,199,254,740,991
- expYearinteger
  max 9,007,199,254,740,991
autoRechargeobject
autoRecharge
- enabledbooleanrequired
- thresholdintegerrequired
  Recharge when the balance falls below this, in cents.
  max 9,007,199,254,740,991
- amountintegerrequired
  What each recharge adds, in cents.
  max 9,007,199,254,740,991
- monthlyLimitintegerrequired
  Most that automatic recharges add in a calendar month, in cents.
  max 9,007,199,254,740,991
autoRechargeErrorobject
Why the last automatic recharge failed; it switched itself off.
autoRechargeError
- atstring (date-time)required
- messagestringrequired
autoRechargedThisMonthintegerrequired
Added by automatic recharges this calendar month, in cents.
max 9,007,199,254,740,991
topUpobjectrequired
Allowed top-up amounts, in cents.
topUp
- minintegerrequired
  max 9,007,199,254,740,991
- maxintegerrequired
  max 9,007,199,254,740,991
hasPortalbooleanrequired
Whether the billing portal (invoices, payment method) is available.

curl -X PUT "https://api.marsial.dev/v1/billing/auto-recharge" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/billing/auto-recharge', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.put(
    "https://api.marsial.dev/v1/billing/auto-recharge",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Open the billing portal

POST/v1/billing/portalDashboard only

Invoices and the saved payment method.

Body

returnUrlstring (uri)required
Dashboard page to come back to.

Response 200

data

urlstring (uri)required
Send the user here.

curl -X POST "https://api.marsial.dev/v1/billing/portal" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/billing/portal', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/billing/portal",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]