Billing API

Base path: https://gateway.useyona.com/b/v1

Get billing account

GET /b/v1/billing-accounts/me

Get your billing account details and credit balance.

bash

curl https://gateway.useyona.com/b/v1/billing-accounts/me \
  -H "Authorization: Bearer sk_test_your_key_here"

Check balance

GET /b/v1/billing-accounts/:id/check-balance

Check if your balance can cover a given number of credits.

Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	Billing account UUID

Query parameters

Parameter	Type	Required	Description
`credits`	number	Yes	Number of credits to check

bash

curl "https://gateway.useyona.com/b/v1/billing-accounts/1a2b3c4d-5e6f-7890-abcd-ef1234567890/check-balance?credits=100" \
  -H "Authorization: Bearer sk_test_your_key_here"

Create subscription

POST /b/v1/subscriptions

Subscribe to a plan. Uses planCode to identify the plan.

Request body

Field	Type	Required	Description
`planCode`	string	Yes	Plan code, e.g. `starter_monthly`
`interval`	string	Yes	Billing interval: `monthly` or `yearly`
`currency`	string	No	Payment currency
`trialDays`	number	No	Trial period in days

bash

curl -X POST https://gateway.useyona.com/b/v1/subscriptions \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "planCode": "starter_monthly", "interval": "monthly" }'

Status	Code	Trigger
409	RES002	Active subscription already exists

Get active subscription

GET /b/v1/subscriptions/active

bash

curl https://gateway.useyona.com/b/v1/subscriptions/active \
  -H "Authorization: Bearer sk_test_your_key_here"

Cancel subscription

PUT /b/v1/subscriptions/:id/cancel

bash

curl -X PUT https://gateway.useyona.com/b/v1/subscriptions/sub_2b3c4d5e-6f7a-8901-bcde-f12345678901/cancel \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
404	RES001	Subscription not found
409	RES003	Subscription already cancelled

Resume subscription

PUT /b/v1/subscriptions/:id/resume

bash

curl -X PUT https://gateway.useyona.com/b/v1/subscriptions/sub_2b3c4d5e-6f7a-8901-bcde-f12345678901/resume \
  -H "Authorization: Bearer sk_test_your_key_here"

Change plan

PUT /b/v1/subscriptions/:id/change-plan

Request body

Field	Type	Required	Description
`newPlanCode`	string	Yes	Target plan code

bash

curl -X PUT https://gateway.useyona.com/b/v1/subscriptions/sub_2b3c4d5e-6f7a-8901-bcde-f12345678901/change-plan \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "newPlanCode": "professional_monthly" }'

Purchase credits

POST /b/v1/payments/purchase

Buy a credit package. Returns a checkout URL to redirect the user.

Request body

Field	Type	Required	Description
`packageId`	string	Yes	Credit package ID
`currency`	string	No	Payment currency
`paymentMethod`	string	No	Payment method ID
`successUrl`	string	No	Redirect URL after successful payment
`cancelUrl`	string	No	Redirect URL if payment cancelled
`useSavedPaymentMethod`	boolean	No	Use saved payment method
`customCreditAmount`	number	No	Custom credit amount

bash

curl -X POST https://gateway.useyona.com/b/v1/payments/purchase \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "packageId": "pkg_5000_credits", "currency": "NGN" }'

Subscription history

GET /b/v1/subscriptions/history

bash

curl https://gateway.useyona.com/b/v1/subscriptions/history \
  -H "Authorization: Bearer sk_test_your_key_here"

Payment history

GET /b/v1/payments/history

bash

curl https://gateway.useyona.com/b/v1/payments/history \
  -H "Authorization: Bearer sk_test_your_key_here"

Credit transfer

POST /b/v1/payments/transfer

Transfer PAYG credits between parent and child organizations. Both must be in payg or hybrid billing mode.

Request body

Field	Type	Required	Description
`targetOrganizationId`	string	Yes	Child organization UUID
`amount`	number	Yes	Number of credits to transfer
`description`	string	No	Transfer description

bash

curl -X POST https://gateway.useyona.com/b/v1/payments/transfer \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "targetOrganizationId": "e5f6a7b8-c9d0-1234-5678-90abcdef1234",
    "amount": 1000,
    "description": "Monthly credit allocation - May 2026"
  }'

Status	Code	Trigger
400	BIZ001	Insufficient credits for transfer

List payment methods

GET /b/v1/payment-methods

bash

curl https://gateway.useyona.com/b/v1/payment-methods \
  -H "Authorization: Bearer sk_test_your_key_here"

Add payment method

POST /b/v1/payment-methods

Returns a setup URL to add a new payment method.

bash

curl -X POST https://gateway.useyona.com/b/v1/payment-methods \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "paystack" }'

Remove payment method

DELETE /b/v1/payment-methods/:provider/:id

bash

curl -X DELETE https://gateway.useyona.com/b/v1/payment-methods/paystack/pm_4d5e6f7a-8b9c-0123-4567-890abcdef123 \
  -H "Authorization: Bearer sk_test_your_key_here"

Set default payment method

PUT /b/v1/payment-methods/:provider/default

bash

curl -X PUT https://gateway.useyona.com/b/v1/payment-methods/paystack/default \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "paymentMethodId": "pm_4d5e6f7a-8b9c-0123-4567-890abcdef123" }'

Credit transactions

GET /b/v1/transactions

List credit transaction history.

bash

curl "https://gateway.useyona.com/b/v1/transactions?page=1&limit=20" \
  -H "Authorization: Bearer sk_test_your_key_here"

List plans (public)

GET /b/v1/plans/subscriptions

No authentication required.

bash

curl https://gateway.useyona.com/b/v1/plans/subscriptions

List credit packages (public)

GET /b/v1/plans/packages

No authentication required.

bash

curl https://gateway.useyona.com/b/v1/plans/packages

List credit costs (public)

GET /b/v1/plans/credit-costs

No authentication required. Returns every billable action with its credit cost, label, and description. Sorted alphabetically by action for stable client-side diffing.

bash

curl https://gateway.useyona.com/b/v1/plans/credit-costs

Usage analytics

GET /b/v1/transactions/analytics/usage

bash

curl https://gateway.useyona.com/b/v1/transactions/analytics/usage \
  -H "Authorization: Bearer sk_test_your_key_here"

Consumption breakdown

GET /b/v1/transactions/breakdown/by-endpoint

bash

curl https://gateway.useyona.com/b/v1/transactions/breakdown/by-endpoint \
  -H "Authorization: Bearer sk_test_your_key_here"

Get account statistics

GET /b/v1/billing-accounts/:id/stats

Get aggregated statistics for a billing account.

Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	Billing account UUID

bash

curl https://gateway.useyona.com/b/v1/billing-accounts/1a2b3c4d-5e6f-7890-abcd-ef1234567890/stats \
  -H "Authorization: Bearer sk_test_your_key_here"

Get single transaction

GET /b/v1/transactions/:id

Retrieve a single credit transaction by ID.

Path parameters

Parameter	Type	Required	Description
`id`	string	Yes	Transaction UUID

bash

curl https://gateway.useyona.com/b/v1/transactions/5e6f7a8b-9c0d-1234-5678-90abcdef1234 \
  -H "Authorization: Bearer sk_test_your_key_here"

POST /b/v1/subscriptions/subscribe

Create a subscription and initiate payment in one step. Returns a checkout URL or client secret for payment completion.

Request body

Field	Type	Required	Description
`planCode`	string	Yes	Plan code, e.g. `starter_monthly`
`interval`	string	Yes	Billing interval: `monthly` or `yearly`
`currency`	string	No	Payment currency
`successUrl`	string	Yes	Redirect URL after successful payment
`cancelUrl`	string	Yes	Redirect URL if payment cancelled

bash

curl -X POST https://gateway.useyona.com/b/v1/subscriptions/subscribe \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "planCode": "starter_monthly",
    "interval": "monthly",
    "currency": "NGN",
    "successUrl": "https://app.useyona.com/billing/success",
    "cancelUrl": "https://app.useyona.com/billing/cancel"
  }'

Renewal history

GET /b/v1/subscriptions/renewals

List subscription renewal history.

Query parameters

Parameter	Type	Required	Description
`page`	number	No	Page number
`pageSize`	number	No	Results per page

bash

curl "https://gateway.useyona.com/b/v1/subscriptions/renewals?page=1&pageSize=20" \
  -H "Authorization: Bearer sk_test_your_key_here"

Renewal statistics

GET /b/v1/subscriptions/renewals/stats

Get aggregated renewal statistics.

bash

curl https://gateway.useyona.com/b/v1/subscriptions/renewals/stats \
  -H "Authorization: Bearer sk_test_your_key_here"

Billing API

Get billing account

Check balance

Path parameters

Query parameters

Create subscription

Request body

Get active subscription

Cancel subscription

Resume subscription

Change plan

Request body

Purchase credits

Request body

Subscription history

Payment history

Credit transfer

Request body

List payment methods

Add payment method

Remove payment method

Set default payment method

Credit transactions

List plans (public)

List credit packages (public)

List credit costs (public)

Usage analytics

Consumption breakdown

Get account statistics

Path parameters

Get single transaction

Path parameters

Subscribe and pay

Request body

Renewal history

Query parameters

Renewal statistics