# Wallet Products

Define product templates that control wallet behavior: tiers, currency, and account code patterns.

URL: https://docs.shiwake.app/docs/banking/wallet-products



A **wallet product** is a template that defines how wallets of that type
behave. Think of it as a blueprint: when you create a wallet, you specify
which product it belongs to, and the product determines the default tier,
currency, and underlying ledger account code.

The WalletProduct object [#the-walletproduct-object]

```json
{
  "id": "wp_01HZ...",
  "name": "Savings Account",
  "code": "SAVINGS",
  "ownerType": "Individual",
  "defaultTier": "Unverified",
  "defaultCurrency": "GHS",
  "accountCodeTemplate": "CLIENT-{ownerId}",
  "isActive": true,
  "metadata": null,
  "createdAt": "2026-04-01T10:00:00Z",
  "updatedAt": null
}
```

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, required: true, description: &#x22;Unique identifier&#x22; },
  name: { type: &#x22;string&#x22;, required: true, description: &#x22;Human-readable product name&#x22; },
  code: { type: &#x22;string&#x22;, required: true, description: <>Unique code within the tenant (e.g. <code>SAVINGS</code>, <code>MERCHANT</code>)</> },
  ownerType: { type: &#x22;string | null&#x22;, required: true, description: <>Restricts who can open this product: <code>Individual</code>, <code>Business</code>, or <code>null</code> (any)</> },
  defaultTier: { type: &#x22;string&#x22;, required: true, description: <>Starting tier new wallets inherit: <code>Unverified</code>, <code>Basic</code>, or <code>Full</code></> },
  defaultCurrency: { type: &#x22;string&#x22;, required: true, description: &#x22;ISO 4217 currency code&#x22; },
  accountCodeTemplate: { type: &#x22;string&#x22;, required: true, description: <>Pattern for the underlying ledger account, must contain <code>&#123;ownerId&#125;</code></> },
  isActive: { type: &#x22;bool&#x22;, required: true, description: &#x22;Only active products can create new wallets&#x22; },
  metadata: { type: &#x22;object | null&#x22;, required: true, description: &#x22;Arbitrary JSON&#x22; },
  createdAt: { type: &#x22;datetime&#x22;, required: true, description: &#x22;Creation timestamp&#x22; },
  updatedAt: { type: &#x22;datetime | null&#x22;, required: true, description: &#x22;Last modification&#x22; },
}"
/>

<Callout type="info">
  The `accountCodeTemplate` controls how ledger accounts are named. For
  example, `CLIENT-{ownerId}` creates accounts like `CLIENT-user_42`. A
  merchant product might use `MERCHANT-{ownerId}` to separate account
  namespaces.
</Callout>

`ownerType`: who is allowed to open this product [#ownertype-who-is-allowed-to-open-this-product]

`ownerType` is an **access restriction**. Every wallet owner is either an
`Individual` (a person) or a `Business` (an organization). Setting this
field pins the product to one kind of owner:

* `Individual`: only individuals can open a wallet on this product. A
  request with `ownerType: "Business"` is rejected with `422`.
* `Business`: only organizations.
* `null` (omit it): **any** owner type is accepted.

The check happens at wallet creation: if the product declares an
`ownerType` and the request's `ownerType` doesn't match, the wallet is
refused. This is how you stop, say, a personal wallet from being opened
against a merchant product by mistake.

<Callout type="info">
  **Example.** A school-fees platform might define a `WARD` product with
  `ownerType: "Individual"` (each student is a person) and a `SCHOOL`
  product with `ownerType: "Business"` (each school is an org). The engine
  then guarantees student wallets and school wallets can never be opened
  against the wrong product.
</Callout>

`defaultTier`: the starting limits level for new wallets [#defaulttier-the-starting-limits-level-for-new-wallets]

A **tier** is a trust/verification level that governs **how much money a
wallet is allowed to move**. `defaultTier` is simply the tier every new
wallet inherits at creation; individual wallets can later be moved up or
down with [upgrade-tier](/docs/banking/wallets#upgrade-tier).

There are exactly three tiers, in increasing order of trust:

| Tier         | Typical meaning                                        |
| ------------ | ------------------------------------------------------ |
| `Unverified` | Brand-new wallet, no KYC done yet. Tightest limits.    |
| `Basic`      | Some identity verification completed. Moderate limits. |
| `Full`       | Fully verified (full KYC). Highest or no limits.       |

<Callout type="warn">
  The tier by itself does nothing. It's just a label until you attach
  [transaction limits](/docs/banking/limits) to it. Limits are resolved by
  `(product, tier, transaction type, currency)`, so a limit you create for
  the `Unverified` tier only applies to wallets currently at that tier.
  Raising a wallet's tier is what unlocks the higher limits you configured
  for that tier. If you define **no** limits for a tier, wallets at that
  tier are effectively unlimited.
</Callout>

***

Create a product [#create-a-product]

<Endpoint method="POST" path="/api/v1/banking/wallet-products" />

Request body [#request-body]

<TypeTable
  type="{
  name: { type: &#x22;string&#x22;, required: true, description: &#x22;Product name&#x22; },
  code: { type: &#x22;string&#x22;, required: true, description: &#x22;Unique code within the tenant&#x22; },
  ownerType: { type: &#x22;string&#x22;, description: <><code>Individual</code>, <code>Business</code>, or omit for unrestricted</> },
  defaultTier: { type: &#x22;string&#x22;, description: <>Default <code>Unverified</code></> },
  defaultCurrency: { type: &#x22;string&#x22;, required: true, description: &#x22;3-letter ISO code&#x22; },
  accountCodeTemplate: { type: &#x22;string&#x22;, description: <>Default <code>CLIENT-&#123;ownerId&#125;</code></> },
  metadata: { type: &#x22;object&#x22;, description: &#x22;Arbitrary JSON&#x22; },
}"
/>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X POST "https://api.shiwake.example.com/api/v1/banking/wallet-products" \
      -H "X-Api-Key: sk_live_..." \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Savings Account",
        "code": "SAVINGS",
        "ownerType": "Individual",
        "defaultTier": "Unverified",
        "defaultCurrency": "GHS",
        "accountCodeTemplate": "CLIENT-{ownerId}"
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 201,
      "message": "Created successfully",
      "data": {
        "id": "wp_01HZ...",
        "name": "Savings Account",
        "code": "SAVINGS",
        "ownerType": "Individual",
        "defaultTier": "Unverified",
        "defaultCurrency": "GHS",
        "accountCodeTemplate": "CLIENT-{ownerId}",
        "isActive": true,
        "metadata": null,
        "createdAt": "2026-04-01T10:00:00Z",
        "updatedAt": null
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes]

| Code  | When                                                                              |
| ----- | --------------------------------------------------------------------------------- |
| `201` | Product created                                                                   |
| `409` | A product with this code already exists                                           |
| `422` | Validation error (missing fields, invalid currency, template missing `{ownerId}`) |

***

List products [#list-products]

<Endpoint method="GET" path="/api/v1/banking/wallet-products" />

Query parameters [#query-parameters]

<TypeTable
  type="{
  isActive: { type: &#x22;bool&#x22;, description: &#x22;Filter by active/inactive status&#x22; },
}"
/>

```bash
curl "https://api.shiwake.example.com/api/v1/banking/wallet-products?isActive=true" \
  -H "X-Api-Key: sk_live_..."
```

***

Get a product [#get-a-product]

<Endpoint method="GET" path="/api/v1/banking/wallet-products/{id}" />

```bash
curl "https://api.shiwake.example.com/api/v1/banking/wallet-products/wp_01HZ..." \
  -H "X-Api-Key: sk_live_..."
```

***

Get by code [#get-by-code]

<Endpoint method="GET" path="/api/v1/banking/wallet-products/by-code/{code}" />

```bash
curl "https://api.shiwake.example.com/api/v1/banking/wallet-products/by-code/SAVINGS" \
  -H "X-Api-Key: sk_live_..."
```

***

Update a product [#update-a-product]

<Endpoint method="PATCH" path="/api/v1/banking/wallet-products/{id}" />

Only include the fields you want to change.

Request body [#request-body-1]

<TypeTable
  type="{
  name: { type: &#x22;string&#x22;, description: &#x22;New name&#x22; },
  defaultTier: { type: &#x22;string&#x22;, description: &#x22;New default tier&#x22; },
  accountCodeTemplate: { type: &#x22;string&#x22;, description: <>Must contain <code>&#123;ownerId&#125;</code></> },
  isActive: { type: &#x22;bool&#x22;, description: &#x22;Deactivate to prevent new wallets&#x22; },
  metadata: { type: &#x22;object&#x22;, description: &#x22;Replaces existing metadata&#x22; },
}"
/>

<Callout type="warn">
  Deactivating a product does not close existing wallets. It only prevents
  new wallets from being created with this product.
</Callout>

```bash
curl -X PATCH "https://api.shiwake.example.com/api/v1/banking/wallet-products/wp_01HZ..." \
  -H "X-Api-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'
```
