API Reference
- Getting started
- Add-ons
- Analytics
- Billable metrics
- Coupons
- Credit notes
- Customer usage
- Customers
- Events
- Fees
- Invoices
- Organizations
- Payments
- Payment receipts
- Payment requests
- Plans
- Resources
- Subscriptions
- Taxes
- Wallets
- Webhook endpoints
- Webhooks
Create a wallet
This endpoint is used to create a wallet with prepaid credits.
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
curl --location --request POST "$LAGO_URL/api/v1/wallets" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"wallet": {
"name": "Prepaid",
"rate_amount": "1.5",
"paid_credits": "20.0",
"granted_credits": "10.0",
"currency": "USD",
"expiration_at": "2022-07-07",
"external_customer_id": "hooli_1234"
}
}'
{
"wallet": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"external_customer_id": "hooli_1234",
"status": "active",
"currency": "USD",
"name": "Prepaid",
"rate_amount": "1.5",
"credits_balance": "28.0",
"balance_cents": 1000,
"consumed_credits": "2.0",
"created_at": "2022-04-29T08:59:51Z",
"expiration_at": null,
"last_balance_sync_at": "2022-04-29T08:59:51Z",
"last_consumed_credit_at": "2022-04-29T08:59:51Z",
"terminated_at": "2022-09-14T16:35:31Z",
"invoice_requires_successful_payment": false,
"recurring_transaction_rules": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"trigger": "interval",
"method": "target",
"interval": "monthly",
"status": "active",
"threshold_credits": "20.0",
"paid_credits": "20.0",
"granted_credits": "10.0",
"started_at": "2022-08-08T00:00:00Z",
"target_ongoing_balance": "200.0",
"created_at": "2022-04-29T08:59:51Z",
"expiration_at": "2023-09-30T23:59:59Z",
"invoice_requires_successful_payment": false,
"transaction_metadata": [
{
"key": "example_key",
"value": "example_value"
},
{
"key": "another_key",
"value": "another_value"
}
]
}
],
"ongoing_balance_cents": 800,
"ongoing_usage_balance_cents": 200,
"credits_ongoing_balance": "8.0",
"credits_ongoing_usage_balance": "2.0"
}
}LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
curl --location --request POST "$LAGO_URL/api/v1/wallets" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"wallet": {
"name": "Prepaid",
"rate_amount": "1.5",
"paid_credits": "20.0",
"granted_credits": "10.0",
"currency": "USD",
"expiration_at": "2022-07-07",
"external_customer_id": "hooli_1234"
}
}'
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
The rate of conversion between credits and the amount in the specified currency. It indicates the ratio or factor used to convert credits into the corresponding monetary value in the currency of the transaction.
"1.5"
The currency of the wallet.
AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BIF, BMD, BND, BOB, BRL, BSD, BWP, BYN, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ETB, EUR, FJD, FKP, GBP, GEL, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, ISK, JMD, JPY, KES, KGS, KHR, KMF, KRW, KYD, KZT, LAK, LBP, LKR, LRD, LSL, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SEK, SGD, SHP, SLL, SOS, SRD, STD, SZL, THB, TJS, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW "USD"
The customer external unique identifier (provided by your own application)
"hooli_1234"
The name of the wallet.
"Prepaid"
The number of paid credits. Required only if there is no granted credits.
"20.0"
The number of free granted credits. Required only if there is no paid credits.
"10.0"
The date and time that determines when the wallet will expire. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
"2022-07-07T23:59:59Z"
A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
false
This optional field allows you to store a list of key-value pairs that provide additional information or custom attributes. These key-value pairs will be included in the metadata of wallet transactions generated during the wallet creation process.
[
{
"key": "example_key",
"value": "example_value"
},
{
"key": "another_key",
"value": "another_value"
}
]
List of recurring transaction rules. Currently, we only allow one recurring rule per wallet.
Object that represents rule for wallet recurring transactions.
The trigger. Possible values are interval or threshold.
interval, threshold "interval"
The number of paid credits used for recurring top-up.
"20.0"
The number of free granted credits used for recurring top-up.
"10.0"
The method used for recurring top-up. Possible values are fixed or target.
fixed, target "target"
The interval used for recurring top-up. It represents the frequency at which automatic top-up occurs. The interval can be one of the following values: weekly, monthly, quarterly or yearly. Required only when trigger is interval.
weekly, monthly, quarterly, yearly "monthly"
The effective start date for recurring top-ups. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
"2022-08-08T00:00:00Z"
The expiration date and time for this specific recurring transaction rule. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
"2023-09-30T23:59:59Z"
The threshold for recurring top-ups is the value at which an automatic top-up is triggered. For example, if this threshold is set at 10 credits, an automatic top-up will occur whenever the wallet balance falls to or below 10 credits. Required only when trigger is set to threshold.
"20.0"
The target ongoing balance is the value set for the ongoing balance to be reached by the automatic top-up. Required only when trigger is set to target.
"200.0"
A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
false
This optional field allows you to store a list of key-value pairs containing additional information or custom attributes. These key-value pairs will populate the metadata of the wallet transactions triggered by this rule.
[
{
"key": "example_key",
"value": "example_value"
},
{
"key": "another_key",
"value": "another_value"
}
]
Response
Unique identifier assigned to the wallet within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet's record within the Lago system.
"1a901a90-1a90-1a90-1a90-1a901a901a90"
Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system.
"1a901a90-1a90-1a90-1a90-1a901a901a90"
The customer external unique identifier (provided by your own application)
"hooli_1234"
The status of the wallet. Possible values are active or terminated.
active, terminated "active"
The currency of the wallet.
AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BIF, BMD, BND, BOB, BRL, BSD, BWP, BYN, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ETB, EUR, FJD, FKP, GBP, GEL, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, ISK, JMD, JPY, KES, KGS, KHR, KMF, KRW, KYD, KZT, LAK, LBP, LKR, LRD, LSL, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SEK, SGD, SHP, SLL, SOS, SRD, STD, SZL, THB, TJS, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW "USD"
The rate of conversion between credits and the amount in the specified currency. It indicates the ratio or factor used to convert credits into the corresponding monetary value in the currency of the transaction.
"1.5"
The current wallet balance expressed in credits. This reflects the available balance after all transactions are settled.
"28.0"
The current wallet balance expressed in cents. This reflects the available balance after all transactions are settled.
1000
The number of consumed credits.
"2.0"
The date of the wallet creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
"2022-04-29T08:59:51Z"
The ongoing wallet balance expressed in cents. This represents the balance_cents minus the ongoing_usage_balance_cents, showing the real time balance after accounting for current usage including taxes.
800
The ongoing usage balance of the wallet, expressed in cents. This reflects all current usage and draft invoices including taxes.
200
The ongoing wallet balance expressed in credits. This represents the credits_balance minus the credits_ongoing_usage_balance, showing the real time balance after accounting for current usage including taxes.
"8.0"
The ongoing usage balance of the wallet, expressed in credits. This reflects all current usage and draft invoices including taxes.
"2.0"
The name of the wallet.
"Prepaid"
The date and time that determines when the wallet will expire. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
null
The date and time of the last balance top-up. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
"2022-04-29T08:59:51Z"
The date and time of the last credits consumption. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
"2022-04-29T08:59:51Z"
The date of terminaison of the wallet. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
"2022-09-14T16:35:31Z"
A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
false
List of recurring transaction rules. Currently, we only allow one recurring rule per wallet.
Object that represents rule for wallet recurring transactions.
A unique identifier for the recurring transaction rule in the Lago application. Can be used to update a recurring transaction rule.
"1a901a90-1a90-1a90-1a90-1a901a901a90"
The trigger. Possible values are interval or threshold.
interval, threshold "interval"
The method used for recurring top-up. Possible values are fixed or target.
fixed, target "target"
The interval used for recurring top-up. It represents the frequency at which automatic top-up occurs. The interval can be one of the following values: weekly, monthly, quarterly or yearly. Required only if trigger is set to interval.
weekly, monthly, quarterly, yearly "monthly"
The threshold for recurring top-ups is the value at which an automatic top-up is triggered. For example, if this threshold is set at 10 credits, an automatic top-up will occur whenever the wallet balance falls to or below 10 credits. Required only when trigger is set to threshold.
"20.0"
The number of paid credits. Required only if there is no granted credits.
"20.0"
The number of free granted credits. Required only if there is no paid credits.
"10.0"
The target ongoing balance is the value set for the ongoing balance to be reached by the automatic top-up. Required only when trigger is set to target.
"200.0"
The date of the metadata object creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). The creation_date provides a standardized and internationally recognized timestamp for when the metadata object was created
"2022-04-29T08:59:51Z"
The status of the recurring transaction rule. Possible values are active or terminated.
active, terminated "active"
The effective start date for recurring top-ups. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
"2022-08-08T00:00:00Z"
The expiration date and time for this specific recurring transaction rule. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
"2023-09-30T23:59:59Z"
A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
false
This field allows you to store a list of key-value pairs containing additional information or custom attributes. These key-value pairs will populate the metadata of the wallet transactions triggered by this rule.
[
{
"key": "example_key",
"value": "example_value"
},
{
"key": "another_key",
"value": "another_value"
}
]
Was this page helpful?
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
curl --location --request POST "$LAGO_URL/api/v1/wallets" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"wallet": {
"name": "Prepaid",
"rate_amount": "1.5",
"paid_credits": "20.0",
"granted_credits": "10.0",
"currency": "USD",
"expiration_at": "2022-07-07",
"external_customer_id": "hooli_1234"
}
}'
{
"wallet": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"external_customer_id": "hooli_1234",
"status": "active",
"currency": "USD",
"name": "Prepaid",
"rate_amount": "1.5",
"credits_balance": "28.0",
"balance_cents": 1000,
"consumed_credits": "2.0",
"created_at": "2022-04-29T08:59:51Z",
"expiration_at": null,
"last_balance_sync_at": "2022-04-29T08:59:51Z",
"last_consumed_credit_at": "2022-04-29T08:59:51Z",
"terminated_at": "2022-09-14T16:35:31Z",
"invoice_requires_successful_payment": false,
"recurring_transaction_rules": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"trigger": "interval",
"method": "target",
"interval": "monthly",
"status": "active",
"threshold_credits": "20.0",
"paid_credits": "20.0",
"granted_credits": "10.0",
"started_at": "2022-08-08T00:00:00Z",
"target_ongoing_balance": "200.0",
"created_at": "2022-04-29T08:59:51Z",
"expiration_at": "2023-09-30T23:59:59Z",
"invoice_requires_successful_payment": false,
"transaction_metadata": [
{
"key": "example_key",
"value": "example_value"
},
{
"key": "another_key",
"value": "another_value"
}
]
}
],
"ongoing_balance_cents": 800,
"ongoing_usage_balance_cents": 200,
"credits_ongoing_balance": "8.0",
"credits_ongoing_usage_balance": "2.0"
}
}