> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new wallet

> Use when giving a customer a prepaid or credit balance (e.g. prepaid plans or promotional credits).



## OpenAPI

````yaml /api-reference/openapi.json post /wallets
openapi: 3.0.1
info:
  title: Flexprice API
  description: Flexprice API Service
  contact:
    name: API Support
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
  version: '1.0'
servers:
  - url: https://us.api.flexprice.io/v1
    description: US Region
  - url: https://api.cloud.flexprice.io/v1
    description: India Region
security: []
paths:
  /wallets:
    post:
      tags:
        - Wallets
      summary: Create a new wallet
      description: >-
        Use when giving a customer a prepaid or credit balance (e.g. prepaid
        plans or promotional credits).
      operationId: createWallet
      requestBody:
        description: Create wallet request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWalletRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors.ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateWalletRequest:
      required:
        - currency
      type: object
      properties:
        alert_settings:
          $ref: '#/components/schemas/types.AlertSettings'
        auto_topup:
          $ref: '#/components/schemas/types.AutoTopup'
        conversion_rate:
          type: string
          description: |-
            amount in the currency =  number of credits * conversion_rate
            ex if conversion_rate is 1, then 1 USD = 1 credit
            ex if conversion_rate is 2, then 1 USD = 0.5 credits
            ex if conversion_rate is 0.5, then 1 USD = 2 credits
          default: '1'
        currency:
          type: string
        customer_id:
          type: string
        description:
          type: string
        external_customer_id:
          type: string
          description: external_customer_id is the customer id in the external system
        initial_credits_expiry_date_utc:
          type: string
          description: >-
            initial_credits_expiry_date_utc is the expiry date in UTC timezone
            (optional to set nil means no expiry)

            ex 2025-01-01 00:00:00 UTC
        initial_credits_to_load:
          type: string
          description: >-
            initial_credits_to_load is the number of credits to load to the
            wallet

            if not provided, the wallet will be created with 0 balance

            NOTE: this is not the amount in the currency, but the number of
            credits
          default: '0'
        initial_credits_to_load_expiry_date:
          type: integer
          description: >-
            initial_credits_to_load_expiry_date YYYYMMDD format in UTC timezone
            (optional to set nil means no expiry)

            for ex 20250101 means the credits will expire on 2025-01-01 00:00:00
            UTC

            hence they will be available for use until 2024-12-31 23:59:59 UTC
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        price_unit:
          type: string
          description: >-
            price_unit is the code of the price unit to use for wallet creation

            If provided, the price unit will be used to set the currency and
            conversion rate of the wallet:

            - currency: set to price unit's base_currency

            - conversion_rate: set to price unit's conversion_rate
        topup_conversion_rate:
          type: string
          description: >-
            topup_conversion_rate is the conversion rate for the topup to the
            currency

            ex if topup_conversion_rate is 1, then 1 USD = 1 credit

            ex if topup_conversion_rate is 2, then 1 USD = 0.5 credits

            ex if topup_conversion_rate is 0.5, then 1 USD = 2 credits
        wallet_type:
          $ref: '#/components/schemas/types.WalletType'
    WalletResponse:
      type: object
      properties:
        alert_settings:
          $ref: '#/components/schemas/types.AlertSettings'
        alert_state:
          $ref: '#/components/schemas/types.AlertState'
        auto_topup:
          $ref: '#/components/schemas/types.AutoTopup'
        balance:
          type: string
        config:
          $ref: '#/components/schemas/types.WalletConfig'
        conversion_rate:
          type: string
          description: |-
            amount in the currency =  number of credits * conversion_rate
            ex if conversion_rate is 1, then 1 USD = 1 credit
            ex if conversion_rate is 2, then 1 USD = 0.5 credits
            ex if conversion_rate is 0.5, then 1 USD = 2 credits
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        credit_balance:
          type: string
        credits_available_breakdown:
          $ref: '#/components/schemas/types.CreditBreakdown'
        currency:
          type: string
        customer_id:
          type: string
        description:
          type: string
        environment_id:
          type: string
        id:
          type: string
        metadata:
          $ref: '#/components/schemas/types.Metadata'
        name:
          type: string
        status:
          $ref: '#/components/schemas/types.Status'
        tenant_id:
          type: string
        topup_conversion_rate:
          type: string
          description: >-
            topup_conversion_rate is the conversion rate for the topup to the
            currency

            ex if topup_conversion_rate is 1, then 1 USD = 1 credit

            ex if topup_conversion_rate is 2, then 1 USD = 0.5 credits

            ex if topup_conversion_rate is 0.5, then 1 USD = 2 credits
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
        wallet_status:
          $ref: '#/components/schemas/types.WalletStatus'
        wallet_type:
          $ref: '#/components/schemas/types.WalletType'
    errors.ErrorResponse:
      type: object
      properties:
        code:
          type: string
          enum:
            - not_found
            - already_exists
            - version_conflict
            - validation_error
            - invalid_operation
            - permission_denied
            - http_client_error
            - database_error
            - system_error
            - internal_error
            - service_unavailable
        details:
          type: object
          additionalProperties:
            type: object
        http_status_code:
          type: integer
        message:
          type: string
      x-speakeasy-name-override: ErrorResponse
    types.AlertSettings:
      type: object
      properties:
        alert_enabled:
          type: boolean
        critical:
          $ref: '#/components/schemas/types.AlertThreshold'
        info:
          $ref: '#/components/schemas/types.AlertThreshold'
        warning:
          $ref: '#/components/schemas/types.AlertThreshold'
      x-speakeasy-name-override: AlertSettings
    types.AutoTopup:
      type: object
      properties:
        amount:
          type: number
        enabled:
          type: boolean
        invoicing:
          type: boolean
        threshold:
          type: number
      x-speakeasy-name-override: AutoTopup
    types.Metadata:
      type: object
      additionalProperties:
        type: string
      x-speakeasy-name-override: Metadata
    types.WalletType:
      type: string
      enum:
        - PRE_PAID
        - POST_PAID
      x-enum-varnames:
        - WalletTypePrePaid
        - WalletTypePostPaid
      x-speakeasy-name-override: WalletType
    types.AlertState:
      type: string
      enum:
        - ok
        - info
        - warning
        - in_alarm
      x-enum-varnames:
        - AlertStateOk
        - AlertStateInfo
        - AlertStateWarning
        - AlertStateInAlarm
      x-speakeasy-name-override: AlertState
    types.WalletConfig:
      type: object
      properties:
        allowed_price_types:
          type: array
          description: >-
            AllowedPriceTypes is a list of price types that are allowed for the
            wallet

            nil means all price types are allowed
          items:
            $ref: '#/components/schemas/types.WalletConfigPriceType'
      x-speakeasy-name-override: WalletConfig
    types.CreditBreakdown:
      type: object
      properties:
        free:
          type: string
        purchased:
          type: string
      x-speakeasy-name-override: CreditBreakdown
    types.Status:
      type: string
      enum:
        - published
        - deleted
        - archived
      x-enum-varnames:
        - StatusPublished
        - StatusDeleted
        - StatusArchived
      x-speakeasy-name-override: Status
    types.WalletStatus:
      type: string
      enum:
        - active
        - frozen
        - closed
      x-enum-varnames:
        - WalletStatusActive
        - WalletStatusFrozen
        - WalletStatusClosed
      x-speakeasy-name-override: WalletStatus
    types.AlertThreshold:
      type: object
      properties:
        condition:
          $ref: '#/components/schemas/types.AlertCondition'
        threshold:
          type: number
      x-speakeasy-name-override: AlertThreshold
    types.WalletConfigPriceType:
      type: string
      enum:
        - ALL
        - USAGE
        - FIXED
      x-enum-varnames:
        - WalletConfigPriceTypeAll
        - WalletConfigPriceTypeUsage
        - WalletConfigPriceTypeFixed
      x-speakeasy-name-override: WalletConfigPriceType
    types.AlertCondition:
      type: string
      enum:
        - above
        - below
      x-enum-varnames:
        - AlertConditionAbove
        - AlertConditionBelow
      x-speakeasy-name-override: AlertCondition
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Enter your API key in the format *x-api-key <api-key>**
      name: x-api-key
      in: header

````