Give your customers credits and price your operations in them
Add your customers, keep a balance of credits for each of them, top it up, set what an operation costs in credits, block a customer and read what was charged.
9 min read
Credits are the unit you count the usage of your own customers in. Slen keeps a balance of credits for each customer, takes credits when a flow runs for them and refuses a run the balance does not cover. This page is about the customers page of the console.
How credits work
A customer is an end customer of yours. Slen knows a customer by the id your application gives them, the one a request that runs a flow sends in context.user_id. Use an id of your own system, not an e-mail address or a name.
An operation gets a price in credits. Each model call of a run that names a customer holds the price on the customer's account before the model is called. The credits are spent when the call is settled and given back when it fails.
| The run | What happens to credits |
|---|---|
| Names no customer | Credits take no part |
| Is of an operation with no price, or with the price 0 | Credits take no part, whoever is named |
| Names a customer the project does not know | The run is refused with the code customer_not_found |
| Names a blocked customer | The run is refused with the code customer_blocked |
| Costs more credits than the account has available, or the customer has no account of the credit type | The run is refused with the code insufficient_credits |
| Fits the account | The price is held, then spent or given back |
Credits are not money. A run that holds credits is still checked against the policies and the budgets.
A customer can have several accounts, one for each credit type. A credit type is a name you choose. A request that runs a flow names it in context.credit_type, and one that names none uses default. The price is looked up for the operation and the credit type, so a credit type that has no price for the operation takes no credits.
Your application can also take credits by itself, for something it sells outside a flow: an export, a seat. Such a charge is made through the API — Customers and credits. The console does not charge.
Where the customers are
Open Customers. The page shows the customers of the project chosen in the header. Three tabs under the title choose what the page reads: Customers, Margin or Credit prices.
The page opens for whoever has the management:read permission. Adding a customer, moving credits, the settings of an account, blocking, deleting and pricing need management:write.
Add a customer
Press Add a customer, type the id of the customer in Customer id and press Add a customer again. The customer is added without credits and without an account, and its card opens. Adding a customer who is already in the list changes nothing.
A customer also appears when your application tops them up for the first time through the API.
Read the list
A row of Customers is one customer: the id, the mark Blocked when the customer is blocked, and for each account the credits available, the credits on hold and when it last changed. An account that may go negative is marked Overdraft allowed. Under the list the page counts the customers in it.
The balance is what the customer has. The credits on hold are reserved for calls that are not finished. What is available is the balance without the credits on hold, so the balance is the two together.
The search keeps the customers whose id contains the text you type.
Available below narrows the list to the customers with an account that has fewer credits available than the number you type. Credits on hold count against it.
The filters next to it keep the active or the blocked customers, and the customers with an account of one credit type.
Press a row to open the card of the customer. The card lists the accounts with their numbers and settings, and Activity under them lists the movements of the customer's credits. The menu of a row leads straight to Top up, Block and Delete.
Set up an account
An account belongs to one credit type. It is created by its first top-up or by its settings, so a customer can be given an account before any credits.
1. Open the settings
On the card, press Add an account for a new credit type, or Settings in an account that is there.
2. Choose the credit type
For a new account, type its credit type in Credit type. The credit type of an account that is there cannot be changed.
3. Decide on the overdraft
Leave Allow this account to go negative off, and a hold the account does not cover is refused. It can be switched off while the balance is below zero: the guard holds from the next movement.
4. Set the warning
In Warn when available falls below type a number of credits. A movement that takes what is available below it sends the customer.balance_low webhook event. 0 sends no warning.
5. Save
Press Save settings. Both settings are saved together.
Top up a customer
1. Open the top-up
On the card, press Top up in the account. For a credit type the customer has no account of, choose Top up in the menu of the row instead. The card of a customer without accounts has the button above the list.
2. Name the credit type
In Credit type type the credit type of the account. The top-up of a credit type the customer has no account of creates the account.
3. Enter the credits
In Credits to add type an amount above zero. Credits keep four decimals. In Note you may write what the credits are for, such as the number of an invoice: the note is shown in the statement.
4. Add the credits
Press Top up.
A top-up is never refused for the balance, even on an account below zero, and a blocked customer can be topped up too.
Correct a balance
On the card, press Adjust in the account. In Credits to add or remove type the credits to add, or a negative amount to take credits away, write a Note if you like, and press Apply adjustment. An amount of zero is refused.
An adjustment cannot take the balance below the credits on hold, unless the account may go negative.
Read the statement
Activity on the card lists every movement of the customer's credits, newest first, with the balance and the available credits each one left. Movement keeps one kind of movement, and the credit type filter keeps the movements of one account when the customer has several. Note shows the note a top-up, a charge or an adjustment was made with.
| Movement | What it does |
|---|---|
| Top-up | Adds credits to the balance |
| Held | Takes credits from what is available. The balance stays |
| Spent | Takes the held credits from the balance |
| Released | Gives held credits back to what is available |
| Adjusted | A correction, up or down |
| Charge | Credits your application took for something it sold, through the API |
Do not add the movements up to get what a customer spent: a call that spent credits is held first and then spent, and only Spent is what the calls cost the customer.
Block a customer
Block a customer to stop their runs, for example after a chargeback.
1. Open the block
On the card, press Block, or choose Block in the menu of the row.
2. Give a reason
In Reason you may write why the customer is blocked. The reason is shown on the card. Blocking again with an empty reason keeps the reason there is.
3. Block
Press Block. The card shows the mark Blocked with the time of the block.
A new run of a blocked customer is refused with the code customer_blocked before anything is created. A run of theirs that is already under way is refused at its next hold of credits. A run of an operation without a price holds no credits and runs to its end. The credits of a blocked customer can still be topped up, charged and adjusted, the settings changed and the statement read, so you can settle with the customer.
To let the customer in again, press Unblock on the card. Unblock in the menu of the row opens the card.
Delete a customer
On the card press Delete, or choose Delete in the menu of the row, then press Delete customer. Only a customer without history is deleted: every account at zero with nothing on hold, and not one movement in the statement. The customer and their empty accounts are gone.
A customer with history is kept, because the statement explains the balance. The card says why and offers to block the customer instead. Over the API the same refusal is the code customer_has_history.
Price an operation
1. Open the prices
Choose Credit prices and press Set a price.
2. Name the operation
In Operation code type the operation code your requests name. In Credit type type the credit type the price is charged in.
3. Set the price
In Credits per call type the price. A price of 0 makes the operation free and keeps it in the list.
4. Save
Press Save price. Setting a price for the same operation and credit type again replaces it.
A price turns credits on for the operation. From then on, a run of it for a customer without an account of the credit type is refused. Top up your customers, or set up their accounts, before you price an operation they already run.
A new price acts on the next hold. A call that already holds credits keeps the price it was held at, and each model call of a run holds the price once.
Compare credits with cost
Margin shows, for the period you choose, how many credits each customer was charged and what the same calls cost in money. Only settled calls count, and a charge of your application is not among them. The two figures are in different units, so the page shows no ratio between them.
Where to go next
Glossary — a customer, an account, credits, a charge and a block in one line each.
Policies — a policy can apply to the calls of one customer.
Customers and credits — customers, accounts, top-ups, charges, the block and prices over the API.
Customers and credits — the same customers from the SDK, and a run charged to a customer.
Manage API keys — the key your application keeps its customers with.
Error codes — every code of the API, what it means and what to do about it.