--- title: "A new wallet has been created" method: POST path: "wallet_created" --- # A new wallet has been created `POST wallet_created` (webhook) A new wallet has been created ## Headers - `X-Lago-Signature` string, required - `X-Lago-Signature-Algorithm` 'jwt' | 'hmac', required - `X-Lago-Unique-Key` string, uuid, required ## Payload - object - `webhook_type` 'wallet.created', required - `object_type` 'wallet', required - `organization_id` string, uuid, required: Unique identifier of the organization, created by Lago. - `wallet` WalletObject, required - `lago_id` string, uuid, required: 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. - `lago_customer_id` string, uuid, required: 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. - `external_customer_id` string, required: The customer external unique identifier (provided by your own application) - `billing_entity_code` string, required: The code of the billing entity associated with the wallet. - `status` 'active' | 'terminated', required: The status of the wallet. Possible values are `active` or `terminated`. - `currency` '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' | 'GHS' | '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' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW', required - `name` string, nullable, required: The name of the wallet. - `code` string, nullable, required: The code of the wallet. - `priority` integer, required: Wallet priority for ordering when a customer has multiple wallets. Allowed values: 1-50, where 1 is highest priority and 50 is lowest. Defaults to 50. Wallets with the same priority are applied by expiration date, soonest first, with wallets without an expiration date last, then by creation date, oldest first. - `rate_amount` string, required: 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. - `credits_balance` string, required: The current wallet balance expressed in credits. This reflects the available balance after all transactions are settled. - `balance_cents` integer, required: The current wallet balance expressed in cents. This reflects the available balance after all transactions are settled. - `consumed_credits` string, required: The number of consumed credits. - `created_at` string, date-time, required: The date of the wallet creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). - `expiration_at` string, date-time, nullable, required: 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). - `last_balance_sync_at` string, date-time, nullable, required: 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). - `last_consumed_credit_at` string, date-time, nullable, required: The date and time of the last credits consumption. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC). - `terminated_at` string, date-time, nullable, required: The date of termination of the wallet. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC). - `invoice_requires_successful_payment` boolean, required: 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. - `applies_to` object: Limitations that restrict where the wallet credits apply. They can be set on fee types, on billable metrics, or on both. - `fee_types` WalletFeeTypeEnum[]: An array of fee types to which the wallet is applicable. By specifying the fee types in this field, you can restrict the wallet's usage to specific fee types only. - `billable_metric_codes` string[]: An array of billable metric codes to which the wallet is applicable. By specifying the billable metric codes in this field, you can restrict the wallet's usage to specific metrics only. - `recurring_transaction_rules` WalletRecurringTransactionRule[]: List of recurring transaction rules. Only one recurring rule is allowed per wallet. Only the rules that are currently active are returned, so a rule that was terminated or that has passed its `expiration_at` is left out. - `lago_id` string, uuid, required: A unique identifier for the recurring transaction rule in the Lago application. Can be used to update a recurring transaction rule. - `trigger` 'interval' | 'threshold', required: The trigger. Possible values are `interval` or `threshold`. - `method` 'fixed' | 'target', required: The method used for recurring top-up. Possible values are `fixed` or `target`. - `interval` 'weekly' | 'monthly' | 'quarterly' | 'semiannual' | 'yearly' | 'null', nullable, required: 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`, `semiannual` or `yearly`. It is `null` when the trigger is `threshold` and no interval was set. - `status` 'active' | 'terminated', required: The status of the recurring transaction rule. Possible values are `active` or `terminated`. - `threshold_credits` string, required: 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`. - `paid_credits` string, required: The number of paid credits. Required only if there is no granted credits. - `granted_credits` string, required: The number of free granted credits. Required only if there is no paid credits. - `grants_target_top_up` boolean, nullable, required: Applies only to `target` rules. When `true`, the recurring top-up grants free credits to reach the target ongoing balance instead of creating a paid top-up (and bypasses the paid top-up minimum). When `false`, the gap is filled with a paid top-up. `null` for `fixed` rules. Defaults to `false` for target rules when omitted. - `started_at` string, date-time, nullable, required: 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). - `target_ongoing_balance` string, nullable, required: 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`. - `created_at` string, date-time, required: The date of the recurring transaction rule creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). - `expiration_at` string, date-time, nullable, required: 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). - `invoice_requires_successful_payment` boolean, required: 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. - `transaction_metadata` object[], required: 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` string: The unique identifier for the attribute. - `value` string: The value associated with the key. - `transaction_name` string, nullable, required: The name of the wallet transactions triggered by this rule. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`. - `ignore_paid_top_up_limits` boolean, required: When true, this rule can top up the wallet with transactions that exceed the paid top-up limits. Defaults to false. - `applied_invoice_custom_sections` AppliedInvoiceCustomSectionObject[], required: The invoice custom sections applied to invoices generated by this recurring transaction rule. - `lago_id` string, uuid, required: Unique identifier of the applied invoice custom section in the Lago application. - `created_at` string, date-time, required: The date of the applied invoice custom section creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). - `invoice_custom_section_id` string, uuid: **Deprecated.** Unique identifier of the invoice custom section that was applied. - `invoice_custom_section` InvoiceCustomSectionObject, required - `lago_id` string, uuid, required: Unique identifier for the invoice custom section in the Lago application, generated by Lago to ensure record uniqueness within the system. - `name` string, required: Name of the invoice custom section. - `code` string, required: Unique code identifying the invoice custom section for the API request. - `description` string: Internal description of the invoice custom section. - `details` string: The value shown on the invoice PDF. - `display_name` string: The name of the invoice custom section displayed on the invoice. - `applied_to_organization` boolean: **Deprecated.** This field will be removed in a future version. When set to true, it applies the invoice custom section to the organization's default billing entity. To apply or remove an invoice custom section from any billing entity (including the default one), please use the `PUT /billing_entities/:code` endpoint instead. - `organization_id` string, uuid: Unique identifier for the organization associated with the invoice custom section. - `created_at` string, date-time: Creation date of the tax. - `payment_method` PaymentMethodReference, required: Reference to a specific payment method for processing the payment. - `payment_method_type` 'provider' | 'manual': The type of payment method to use. - `payment_method_id` string, uuid: The unique identifier of the payment method (required when using a specific provider payment method). - `purchase_order_number` string, nullable, required: The purchase order number associated with this recurring transaction rule. It will be added to invoices generated for the resulting wallet top-ups. If not set, falls back to the wallet's `purchase_order_number`. - `ongoing_balance_cents` integer, required: 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. - `ongoing_usage_balance_cents` integer, required: The ongoing usage balance of the wallet, expressed in cents. This reflects all current usage and draft invoices including taxes. - `credits_ongoing_balance` string, required: 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. - `credits_ongoing_usage_balance` string, required: The ongoing usage balance of the wallet, expressed in credits. This reflects all current usage and draft invoices including taxes. - `paid_top_up_min_amount_cents` integer, nullable, required: The minimum amount, in cents, of a single paid top-up transaction. - `paid_top_up_max_amount_cents` integer, nullable, required: The maximum amount, in cents, of a single paid top-up transaction. - `applied_invoice_custom_sections` AppliedInvoiceCustomSectionObject[]: The invoice custom sections applied to invoices generated by this wallet. - `lago_id` string, uuid, required: Unique identifier of the applied invoice custom section in the Lago application. - `created_at` string, date-time, required: The date of the applied invoice custom section creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). - `invoice_custom_section_id` string, uuid: **Deprecated.** Unique identifier of the invoice custom section that was applied. - `invoice_custom_section` InvoiceCustomSectionObject, required - `lago_id` string, uuid, required: Unique identifier for the invoice custom section in the Lago application, generated by Lago to ensure record uniqueness within the system. - `name` string, required: Name of the invoice custom section. - `code` string, required: Unique code identifying the invoice custom section for the API request. - `description` string: Internal description of the invoice custom section. - `details` string: The value shown on the invoice PDF. - `display_name` string: The name of the invoice custom section displayed on the invoice. - `applied_to_organization` boolean: **Deprecated.** This field will be removed in a future version. When set to true, it applies the invoice custom section to the organization's default billing entity. To apply or remove an invoice custom section from any billing entity (including the default one), please use the `PUT /billing_entities/:code` endpoint instead. - `organization_id` string, uuid: Unique identifier for the organization associated with the invoice custom section. - `created_at` string, date-time: Creation date of the tax. - `payment_method` PaymentMethodReference, required: Reference to a specific payment method for processing the payment. - `payment_method_type` 'provider' | 'manual': The type of payment method to use. - `payment_method_id` string, uuid: The unique identifier of the payment method (required when using a specific provider payment method). - `purchase_order_number` string, nullable, required: The purchase order number associated with the wallet. It will be added to invoices generated for wallet top-ups, unless a more specific purchase order number is set on the wallet transaction or recurring transaction rule that triggered the top-up. - `metadata` MetadataObject, nullable: Custom metadata stored as key-value pairs. Keys are strings (max 100 characters), values can be strings (max 255 characters) or null. ## Acknowledgement `200` Return a 200 status to indicate that the data was received successfully --- [API](https://skmtc.dev/getlago/apis/lago-api-documentation.md) - [All operations](https://skmtc.dev/getlago/apis/lago-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/getlago/apis/lago-api-documentation/revisions/b216574b9612?raw)