Notix
API reference

Billing.

Read the wallet ledger, receipts, invoices, this period's usage against your limits, your plan and your prices. Every request needs an API key in the Authorization header; the reference overview covers keys, errors and rate limits.

List wallet transactions

GET/v1/billing/transactionsFull access key

Every row of the team's wallet, as the billing page's ledger lists it: top-ups, Pro months, units, SMS charges and releases, sender ID fees and refunds, adjustments and reversals. amountMinor is signed (positive into the wallet) in the wallet's currency; receiptReference is set on a row that has a receipt. type lists one kind of row only. Newest first. Filter with from (inclusive) and to (exclusive) as ISO 8601 times. Pass nextCursor back as cursor for the next page; limit is 1 to 100 (20 by default). A team with no wallet yet answers an empty list and a null currency.

Who can call it

A full access or read only key made by someone who is a team admin today (the team owner always is), as the billing page is for admins. A key made by a member answers 403 FORBIDDEN, and so does a key made before Notix recorded who made each key. Sandbox, send-only and live AI keys answer 403 SCOPE_DENIED; a key limited to one domain answers 403 DOMAIN_PINNED. Every read is recorded in the key's audit log (GET /v1/audit-log).

The team can make 60 billing reads a minute through the API (20 for invoices, which are read from Stripe, within a limit shared by every team); when Notix cannot count them the answer is 503 SERVICE_UNAVAILABLE (try again shortly), never a 429.

Query parameters
FieldTypeAbout
typestring

Only rows of this type.

One of TOPUP, PRO_CHARGE, UNITS_CHARGE, ADJUSTMENT, REVERSAL, SMS_CHARGE, SMS_RELEASE, SENDER_ID_FEE, SENDER_ID_REFUND, TOPUP_FEE, REFERRAL_CREDIT.

fromstring

Only rows made at or after this time (ISO 8601).

tostring

Only rows made before this time (ISO 8601).

cursorstring

`nextCursor` from the previous page.

limitinteger

Default 20.

terminal
curl -X GET "https://app.usenotix.dev/api/v1/billing/transactions" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

Responses

200A page of the wallet's rows, newest first, with the cursor for the next page.
200 response fields
FieldTypeAbout
currencyrequiredstring

The wallet's currency; null when the team has no wallet yet.

One of USD, NGN, KES. Can be null.

datarequiredobject[]
data[].idrequiredstring
data[].typerequiredstring

One of TOPUP, PRO_CHARGE, UNITS_CHARGE, ADJUSTMENT, REVERSAL, SMS_CHARGE, SMS_RELEASE, SENDER_ID_FEE, SENDER_ID_REFUND, TOPUP_FEE, REFERRAL_CREDIT.

data[].amountMinorrequiredinteger

Signed, in the currency's minor unit: positive into the wallet, negative out of it.

data[].amountFormattedrequiredstring
data[].balanceAfterMinorrequiredinteger
data[].balanceAfterFormattedrequiredstring
data[].referencerequiredstring
data[].customerDescriptionrequiredstring

What Notix wrote for you on this row, when anything.

Can be null.

data[].receiptReferencerequiredstring

Set when the row has a receipt: read it with GET /v1/billing/receipts/{reference}.

Can be null.

data[].createdAtrequiredstring (date-time)
nextCursorrequiredstring

Can be null.

400A query value is not valid, or the cursor is not from this list.
403`SCOPE_DENIED`: a sandbox, send-only or live AI key. `DOMAIN_PINNED`: a key limited to one domain. `FORBIDDEN`: the key was made by a member who is not a team admin, or before Notix recorded who made each key.
422The read took longer than 10 seconds.
429The team read billing 60 times in the last minute.
503The rate counters cannot be read just now; try again shortly.

List receipts

GET/v1/billing/receiptsFull access key

The receipts in the team's wallet: paid top-ups, Pro months paid from the wallet (with their invoice number), sender ID fees and their refunds. Newest first. Filter with from (inclusive) and to (exclusive) as ISO 8601 times. Pass nextCursor back as cursor for the next page; limit is 1 to 100 (20 by default). A page can hold fewer than limit receipts and still have a nextCursor.

Who can call it

A full access or read only key made by someone who is a team admin today (the team owner always is), as the billing page is for admins. A key made by a member answers 403 FORBIDDEN, and so does a key made before Notix recorded who made each key. Sandbox, send-only and live AI keys answer 403 SCOPE_DENIED; a key limited to one domain answers 403 DOMAIN_PINNED. Every read is recorded in the key's audit log (GET /v1/audit-log).

The team can make 60 billing reads a minute through the API (20 for invoices, which are read from Stripe, within a limit shared by every team); when Notix cannot count them the answer is 503 SERVICE_UNAVAILABLE (try again shortly), never a 429.

Query parameters
FieldTypeAbout
typestring

Only receipts of this type.

One of TOPUP, PRO_CHARGE, SENDER_ID_FEE, SENDER_ID_REFUND.

fromstring

Only rows made at or after this time (ISO 8601).

tostring

Only rows made before this time (ISO 8601).

cursorstring

`nextCursor` from the previous page.

limitinteger

Default 20.

terminal
curl -X GET "https://app.usenotix.dev/api/v1/billing/receipts" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

Responses

200A page of receipts, newest first.
200 response fields
FieldTypeAbout
currencyrequiredstring

One of USD, NGN, KES. Can be null.

datarequiredobject[]
data[].invoiceNumberrequiredstring

Set on a Pro month paid from the wallet.

Can be null.

data[].referencerequiredstring
data[].typerequiredstring

One of TOPUP, PRO_CHARGE, SENDER_ID_FEE, SENDER_ID_REFUND.

data[].titlerequiredstring
data[].descriptionrequiredstring
data[].amountMinorrequiredinteger

Negative for money that left the wallet, positive for money that entered it.

data[].amountFormattedrequiredstring

The amount without its sign.

data[].directionrequiredstring

One of charge, credit.

data[].balanceAfterMinorrequiredinteger
data[].balanceAfterFormattedrequiredstring
data[].currencyrequiredstring

One of USD, NGN, KES.

data[].createdAtrequiredstring (date-time)
nextCursorrequiredstring

A page can hold fewer than `limit` receipts and still have a next one.

Can be null.

400A query value is not valid, or the cursor is not from this list.
403`SCOPE_DENIED`: a sandbox, send-only or live AI key. `DOMAIN_PINNED`: a key limited to one domain. `FORBIDDEN`: the key was made by a member who is not a team admin, or before Notix recorded who made each key.
422The read took longer than 10 seconds.
429The team read billing 60 times in the last minute.
503The rate counters cannot be read just now; try again shortly.

Get a receipt

GET/v1/billing/receipts/{reference}Full access key

One receipt by its reference (a transaction's receiptReference), with the figures the printable receipt shows. Another team's reference, a row that is not a receipt and a top-up that never paid answer 404.

Who can call it

A full access or read only key made by someone who is a team admin today (the team owner always is), as the billing page is for admins. A key made by a member answers 403 FORBIDDEN, and so does a key made before Notix recorded who made each key. Sandbox, send-only and live AI keys answer 403 SCOPE_DENIED; a key limited to one domain answers 403 DOMAIN_PINNED. Every read is recorded in the key's audit log (GET /v1/audit-log).

The team can make 60 billing reads a minute through the API (20 for invoices, which are read from Stripe, within a limit shared by every team); when Notix cannot count them the answer is 503 SERVICE_UNAVAILABLE (try again shortly), never a 429.

Path parameters
FieldTypeAbout
referencerequiredstring
terminal
curl -X GET "https://app.usenotix.dev/api/v1/billing/receipts/<reference>" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

Responses

200One receipt, as the printable receipt page shows it.
200 response fields
FieldTypeAbout
invoiceNumberrequiredstring

Set on a Pro month paid from the wallet.

Can be null.

referencerequiredstring
typerequiredstring

One of TOPUP, PRO_CHARGE, SENDER_ID_FEE, SENDER_ID_REFUND.

titlerequiredstring
descriptionrequiredstring
amountMinorrequiredinteger

Negative for money that left the wallet, positive for money that entered it.

amountFormattedrequiredstring

The amount without its sign.

directionrequiredstring

One of charge, credit.

balanceAfterMinorrequiredinteger
balanceAfterFormattedrequiredstring
currencyrequiredstring

One of USD, NGN, KES.

createdAtrequiredstring (date-time)
teamNamerequiredstring
403`SCOPE_DENIED`: a sandbox, send-only or live AI key. `DOMAIN_PINNED`: a key limited to one domain. `FORBIDDEN`: the key was made by a member who is not a team admin, or before Notix recorded who made each key.
404No receipt with this reference in the team's wallet.
422The read took longer than 10 seconds.
429The team read billing 60 times in the last minute.
503The rate counters cannot be read just now; try again shortly.

List invoices

GET/v1/billing/invoicesFull access key

The team's latest 12 Stripe invoices, newest first, as the billing page lists them: id, number, date, amounts in cents and status. The id is Stripe's own (in_...), since Notix has no other id for an invoice; it opens nothing by itself. The link to pay or download an invoice is not returned: open it from the billing page. A team Stripe has never billed answers an empty list. A Pro month paid from the wallet is a receipt, not a Stripe invoice: see GET /v1/billing/receipts.

Who can call it

A full access or read only key made by someone who is a team admin today (the team owner always is), as the billing page is for admins. A key made by a member answers 403 FORBIDDEN, and so does a key made before Notix recorded who made each key. Sandbox, send-only and live AI keys answer 403 SCOPE_DENIED; a key limited to one domain answers 403 DOMAIN_PINNED. Every read is recorded in the key's audit log (GET /v1/audit-log).

The team can make 60 billing reads a minute through the API (20 for invoices, which are read from Stripe, within a limit shared by every team); when Notix cannot count them the answer is 503 SERVICE_UNAVAILABLE (try again shortly), never a 429.

terminal
curl -X GET "https://app.usenotix.dev/api/v1/billing/invoices" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

Responses

200The team's latest 12 Stripe invoices, newest first. Empty for a team Stripe has never billed.
200 response fields
FieldTypeAbout
datarequiredobject[]
data[].idrequiredstring

Stripe's own invoice id (`in_...`): Notix has no other id for it.

data[].numberrequiredstring

Can be null.

data[].createdAtrequiredstring (date-time)
data[].amountDuerequiredinteger

Minor units (cents).

data[].amountPaidrequiredinteger

Minor units (cents).

data[].currencyrequiredstring
data[].statusrequiredstring
403`SCOPE_DENIED`: a sandbox, send-only or live AI key. `DOMAIN_PINNED`: a key limited to one domain. `FORBIDDEN`: the key was made by a member who is not a team admin, or before Notix recorded who made each key.
429The team read invoices 20 times in the last minute, or Notix's invoice reads across every team are at their limit.
503Stripe or the rate counters cannot be reached just now.

Get an invoice

GET/v1/billing/invoices/{id}Full access key

One Stripe invoice of the team, by its Stripe id (in_...). An invoice of any other Stripe customer answers 404. The link to pay or download it is not returned: open it from the billing page.

Who can call it

A full access or read only key made by someone who is a team admin today (the team owner always is), as the billing page is for admins. A key made by a member answers 403 FORBIDDEN, and so does a key made before Notix recorded who made each key. Sandbox, send-only and live AI keys answer 403 SCOPE_DENIED; a key limited to one domain answers 403 DOMAIN_PINNED. Every read is recorded in the key's audit log (GET /v1/audit-log).

The team can make 60 billing reads a minute through the API (20 for invoices, which are read from Stripe, within a limit shared by every team); when Notix cannot count them the answer is 503 SERVICE_UNAVAILABLE (try again shortly), never a 429.

Path parameters
FieldTypeAbout
idrequiredstring
terminal
curl -X GET "https://app.usenotix.dev/api/v1/billing/invoices/<id>" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

Responses

200One Stripe invoice of the team.
200 response fields
FieldTypeAbout
idrequiredstring

Stripe's own invoice id (`in_...`): Notix has no other id for it.

numberrequiredstring

Can be null.

createdAtrequiredstring (date-time)
amountDuerequiredinteger

Minor units (cents).

amountPaidrequiredinteger

Minor units (cents).

currencyrequiredstring
statusrequiredstring
400The id is not an invoice id.
403`SCOPE_DENIED`: a sandbox, send-only or live AI key. `DOMAIN_PINNED`: a key limited to one domain. `FORBIDDEN`: the key was made by a member who is not a team admin, or before Notix recorded who made each key.
404No invoice with this id for this team.
429The team read invoices 20 times in the last minute, or Notix's invoice reads across every team are at their limit.
503Stripe or the rate counters cannot be reached just now.

Get the plan

GET/v1/billing/subscriptionFull access key

The team's plan and how it is paid: the card subscription (status, period, whether it cancels at the period's end), the wallet's state (renewal date, grace, whether units are blocked), the Pro price in the wallet's currency (a fixed local price for NGN and KES) and the Pro month the team is on, owes or is paying, with its status and whether it is cancelled at the period's end. Read only: change the plan in the dashboard.

Who can call it

A full access or read only key made by someone who is a team admin today (the team owner always is), as the billing page is for admins. A key made by a member answers 403 FORBIDDEN, and so does a key made before Notix recorded who made each key. Sandbox, send-only and live AI keys answer 403 SCOPE_DENIED; a key limited to one domain answers 403 DOMAIN_PINNED. Every read is recorded in the key's audit log (GET /v1/audit-log).

The team can make 60 billing reads a minute through the API (20 for invoices, which are read from Stripe, within a limit shared by every team); when Notix cannot count them the answer is 503 SERVICE_UNAVAILABLE (try again shortly), never a 429.

terminal
curl -X GET "https://app.usenotix.dev/api/v1/billing/subscription" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

Responses

200The team's plan: how it is paid, its renewal and grace dates, and the Pro month it is on.
200 response fields
FieldTypeAbout
planrequiredstring
isActiverequiredboolean
billingMethodrequiredstring

One of STRIPE, WALLET.

striperequiredobject

The card subscription, when the team has one.

Can be null.

stripe.statusrequiredstring
stripe.currentPeriodStartrequiredstring (date-time)

Can be null.

stripe.currentPeriodEndrequiredstring (date-time)

Can be null.

stripe.cancelAtPeriodEndrequiredboolean
stripe.cancelAtrequiredstring (date-time)

Can be null.

walletrequiredobject
wallet.staterequiredstring

One of ACTIVE, GRACE, DOWNGRADED.

wallet.proRenewsAtrequiredstring (date-time)

Can be null.

wallet.graceStartedAtrequiredstring (date-time)

Can be null.

wallet.graceEndsAtrequiredstring (date-time)

Can be null.

wallet.unitsBlockedrequiredboolean
planPaymentrequiredobject
planPayment.currencyrequiredstring

One of USD, NGN, KES.

planPayment.priceMinorrequiredinteger
planPayment.priceFormattedrequiredstring
planPayment.priceConfiguredrequiredboolean
planPayment.fixedPricerequiredboolean

True for NGN and KES, which pay a fixed local price.

planPayment.walletPaysPlanrequiredboolean
planPayment.liverequiredobject

The Pro month the team is on, owes or is paying (wallet or saved card).

Can be null.

planPayment.live.statusrequiredstring

One of DUE, CHARGING, ACTIVE, GRACE, ENDED, LAPSED, CANCELLED.

planPayment.live.paidViarequiredstring

One of WALLET, CARD. Can be null.

planPayment.live.periodStartrequiredstring (date-time)
planPayment.live.periodEndrequiredstring (date-time)
planPayment.live.amountMinorrequiredinteger
planPayment.live.amountFormattedrequiredstring
planPayment.live.cancelAtPeriodEndrequiredboolean
planPayment.live.graceEndsAtrequiredstring (date-time)

Can be null.

planPayment.live.invoiceNumberrequiredstring

Can be null.

planPayment.live.receiptReferencerequiredstring

Can be null.

403`SCOPE_DENIED`: a sandbox, send-only or live AI key. `DOMAIN_PINNED`: a key limited to one domain. `FORBIDDEN`: the key was made by a member who is not a team admin, or before Notix recorded who made each key.
429The team read billing 60 times in the last minute.
503The rate counters cannot be read just now; try again shortly.

Get usage

GET/v1/billing/usageFull access key

The figures the Usage and billing pages show: this billing period's emails against the monthly and daily limits (the daily limit is the one enforced today), the plan's units and an estimate of any overage, the team's domains, contact books, members and webhooks against the plan, the API rate limit, and this calendar month's emails, texts and one-time codes. thisMonth.textSpendFormatted (what the texts cost the wallet) is only given to a key made by a team admin that is not limited to one domain; it is null otherwise.

Who can call it

Full access, read only and live AI keys, including a key limited to one domain: they help a caller stay within the team's limits. Sandbox and send-only keys answer 403 SCOPE_DENIED.

The team can make 60 billing reads a minute through the API (20 for invoices, which are read from Stripe, within a limit shared by every team); when Notix cannot count them the answer is 503 SERVICE_UNAVAILABLE (try again shortly), never a 429.

terminal
curl -X GET "https://app.usenotix.dev/api/v1/billing/usage" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

Responses

200This period's sending and resources against the plan's limits, and this calendar month's texts and codes.
200 response fields
FieldTypeAbout
periodrequiredobject
period.startDayrequiredstring
period.endDayrequiredstring

Exclusive; null when the period has no set end.

Can be null.

period.labelrequiredstring
planrequiredobject
plan.keyrequiredstring
plan.effectiveKeyrequiredstring

The plan the limits are enforced against today.

plan.displayNamerequiredstring
plan.monthlyUsdrequirednumber
plan.statusrequiredstring

Can be null.

plan.isEntitledrequiredboolean
emailsrequiredobject
emails.marketingThisMonthrequiredinteger
emails.transactionalThisMonthrequiredinteger
emails.totalThisMonthrequiredinteger
emails.totalTodayrequiredinteger
sendingrequiredobject
sending.monthlyrequiredobject
sending.monthly.usedrequiredinteger
sending.monthly.limitrequiredinteger

-1 means no limit.

sending.monthly.unlimitedrequiredboolean
sending.monthly.percentUsedrequirednumber
sending.dailyrequiredobject
sending.daily.usedrequiredinteger
sending.daily.limitrequiredinteger

-1 means no limit.

sending.daily.unlimitedrequiredboolean
sending.daily.percentUsedrequirednumber
unitsrequiredobject

Null on the free plan, which is not metered.

Can be null.

units.includedrequiredinteger
units.usedrequiredinteger
units.overagerequiredinteger
units.overageUsdrequirednumber
units.overageMinorrequiredinteger
units.overageFormattedrequiredstring
units.unitPriceFormattedrequiredstring

Can be null.

units.noterequiredstring
billingrequiredobject
billing.methodrequiredstring

One of STRIPE, WALLET.

billing.currencyrequiredstring

One of USD, NGN, KES.

billing.unitPriceMicrorequiredinteger

Can be null.

resourcesrequiredobject
resources.domainsrequiredobject
resources.domains.usedrequiredinteger
resources.domains.limitrequiredinteger

-1 means no limit.

resources.domains.unlimitedrequiredboolean
resources.domains.percentUsedrequirednumber
resources.contactBooksrequiredobject
resources.contactBooks.usedrequiredinteger
resources.contactBooks.limitrequiredinteger

-1 means no limit.

resources.contactBooks.unlimitedrequiredboolean
resources.contactBooks.percentUsedrequirednumber
resources.teamMembersrequiredobject
resources.teamMembers.usedrequiredinteger
resources.teamMembers.limitrequiredinteger

-1 means no limit.

resources.teamMembers.unlimitedrequiredboolean
resources.teamMembers.percentUsedrequirednumber
resources.webhooksrequiredobject
resources.webhooks.usedrequiredinteger
resources.webhooks.limitrequiredinteger

-1 means no limit.

resources.webhooks.unlimitedrequiredboolean
resources.webhooks.percentUsedrequirednumber
apiRateLimitrequiredinteger

Requests a second the team's keys may make.

thisMonthrequiredobject

This calendar month (UTC), as the billing page's "This month" card shows it.

thisMonth.emailsrequiredobject
thisMonth.emails.usedrequiredinteger
thisMonth.emails.limitrequiredinteger
thisMonth.emails.unlimitedrequiredboolean
thisMonth.emails.percentrequirednumber
thisMonth.textsrequiredinteger
thisMonth.codesrequiredinteger
thisMonth.textSpendFormattedrequiredstring

What this month's texts cost the wallet. Only for a key a team admin made that is not limited to one domain.

Can be null.

403`SCOPE_DENIED`: a sandbox or send-only key.
422The read took longer than 10 seconds.
429The team read billing 60 times in the last minute.
503The rate counters cannot be read just now; try again shortly.

Get prices

GET/v1/billing/pricingFull access key

The package price list the billing page's Pricing table shows, in the team's billing currency (USD for a team that has not chosen one): each channel's volume tiers and the price of each product line per tier, in millionths of the currency's major unit per message. A null cell is "On request". pro is the Pro plan's monthly price in the same currency; NGN and KES pay a fixed local price.

Who can call it

Full access, read only and live AI keys, including a key limited to one domain: they help a caller stay within the team's limits. Sandbox and send-only keys answer 403 SCOPE_DENIED.

The team can make 60 billing reads a minute through the API (20 for invoices, which are read from Stripe, within a limit shared by every team); when Notix cannot count them the answer is 503 SERVICE_UNAVAILABLE (try again shortly), never a 429.

terminal
curl -X GET "https://app.usenotix.dev/api/v1/billing/pricing" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

Responses

200The package price list in the team's billing currency, and the Pro plan's monthly price.
200 response fields
FieldTypeAbout
currencyrequiredstring

One of USD, NGN, KES.

channelsrequiredobject[]
channels[].channelrequiredstring

One of EMAIL, SMS, VOICE, WHATSAPP.

channels[].labelrequiredstring
channels[].tiersrequiredobject[]
channels[].tiers[].idrequiredstring
channels[].tiers[].positionrequiredinteger
channels[].tiers[].namerequiredstring
channels[].tiers[].minVolumerequiredinteger
channels[].tiers[].maxVolumerequiredinteger

Can be null.

channels[].tiers[].recommendedrequiredboolean
channels[].tiers[].volumeLabelrequiredstring
channels[].linesrequiredobject[]
channels[].lines[].productLinerequiredstring

One of TRANSACTIONAL, CAMPAIGN, OTP, PROMOTIONAL, VOICE_SMS, TEXT_TO_SPEECH, VOICE_OTP, UTILITY_AUTH, MARKETING, MONTHLY_FEE.

channels[].lines[].labelrequiredstring
channels[].lines[].monthlyFeerequiredboolean
channels[].lines[].cellsrequiredobject[]
prorequiredobject
pro.currencyrequiredstring

One of USD, NGN, KES.

pro.monthlyMinorrequiredinteger
pro.monthlyFormattedrequiredstring
pro.unitPriceMicrorequiredinteger
pro.fixedPricerequiredboolean

True for NGN and KES, which pay a fixed local price.

pro.configuredrequiredboolean

False when Notix has not priced this currency yet.

403`SCOPE_DENIED`: a sandbox or send-only key.
429The team read billing 60 times in the last minute.
503The rate counters cannot be read just now; try again shortly.