# Transaction Limits

Per-transaction, daily, weekly, and monthly limits with product and tier-based resolution.

URL: https://docs.shiwake.app/docs/banking/limits



**Transaction limits** let you cap how much money can move through a wallet
in a given period. Limits are enforced automatically on deposits and
withdrawals. If a transaction would exceed a limit, it is rejected with a
`422` response.

Limit periods [#limit-periods]

| Period           | Window                                           |
| ---------------- | ------------------------------------------------ |
| `PerTransaction` | Each individual transaction                      |
| `Daily`          | Midnight-to-midnight UTC                         |
| `Weekly`         | Monday 00:00 UTC to Sunday 23:59 UTC             |
| `Monthly`        | 1st of the month 00:00 UTC to last day 23:59 UTC |

Resolution priority [#resolution-priority]

Limits are scoped by **product** and **wallet tier**. When checking a
transaction, the engine finds the most specific matching rule for each
period:

| Priority          | Product | Tier | Score |
| ----------------- | ------- | ---- | ----- |
| 1 (most specific) | Set     | Set  | 3     |
| 2                 | Set     | Any  | 2     |
| 3                 | Any     | Set  | 1     |
| 4 (catch-all)     | Any     | Any  | 0     |

For each period, the rule with the highest score wins. This means you can:

* Set a tenant-wide daily limit (product=null, tier=null)
* Override it for fully-verified wallets (product=null, tier=Full)
* Override it again for a specific product's `Full` tier

<Callout type="info">
  If no limit rule matches for a period, there is no limit for that period.
  Limits are opt-in. You only enforce what you configure.
</Callout>

The TransactionLimit object [#the-transactionlimit-object]

```json
{
  "id": "tl_01HZ...",
  "productId": "wp_01HZ...",
  "productName": "Savings Account",
  "walletTier": "Basic",
  "transactionType": "Deposit",
  "period": "Daily",
  "maxAmount": 500000,
  "currency": "GHS",
  "isActive": true,
  "createdAt": "2026-04-01T10:00:00Z",
  "updatedAt": null
}
```

<TypeTable
  type="{
  productId: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Null = applies to all products&#x22; },
  walletTier: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Null = applies to all tiers&#x22; },
  transactionType: { type: &#x22;string&#x22;, required: true, description: <><code>Deposit</code> or <code>Withdrawal</code></> },
  period: { type: &#x22;string&#x22;, required: true, description: <><code>PerTransaction</code>, <code>Daily</code>, <code>Weekly</code>, <code>Monthly</code></> },
  maxAmount: { type: &#x22;long&#x22;, required: true, description: &#x22;Maximum amount in minor units&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;ISO 4217 code&#x22; },
  isActive: { type: &#x22;bool&#x22;, required: true, description: &#x22;Only active limits are enforced&#x22; },
}"
/>

***

Create a limit [#create-a-limit]

<Endpoint method="POST" path="/api/v1/banking/limits" />

Request body [#request-body]

<TypeTable
  type="{
  productId: { type: &#x22;string&#x22;, description: &#x22;Tie to a product, or omit for all products&#x22; },
  walletTier: { type: &#x22;string&#x22;, description: <><code>Unverified</code>, <code>Basic</code>, <code>Full</code>, or omit for all tiers</> },
  transactionType: { type: &#x22;string&#x22;, required: true, description: <><code>Deposit</code> or <code>Withdrawal</code></> },
  period: { type: &#x22;string&#x22;, required: true, description: <><code>PerTransaction</code>, <code>Daily</code>, <code>Weekly</code>, <code>Monthly</code></> },
  maxAmount: { type: &#x22;long&#x22;, required: true, description: &#x22;Maximum amount in minor units&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;3-letter ISO code&#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/limits" \
      -H "X-Api-Key: sk_live_..." \
      -H "Content-Type: application/json" \
      -d '{
        "transactionType": "Deposit",
        "period": "Daily",
        "maxAmount": 500000,
        "currency": "GHS",
        "walletTier": "Basic"
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 201,
      "message": "Created successfully",
      "data": {
        "id": "tl_01HZ...",
        "productId": null,
        "walletTier": "Basic",
        "transactionType": "Deposit",
        "period": "Daily",
        "maxAmount": 500000,
        "currency": "GHS",
        "isActive": true
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

***

List limits [#list-limits]

<Endpoint method="GET" path="/api/v1/banking/limits" />

<TypeTable
  type="{
  productId: { type: &#x22;string&#x22;, description: &#x22;Filter by product&#x22; },
  walletTier: { type: &#x22;string&#x22;, description: &#x22;Filter by tier&#x22; },
  transactionType: { type: &#x22;string&#x22;, description: <><code>Deposit</code> or <code>Withdrawal</code></> },
  isActive: { type: &#x22;bool&#x22;, description: &#x22;Filter by active/inactive&#x22; },
}"
/>

***

Update a limit [#update-a-limit]

<Endpoint method="PATCH" path="/api/v1/banking/limits/{id}" />

<TypeTable
  type="{
  maxAmount: { type: &#x22;long&#x22;, description: &#x22;New maximum&#x22; },
  isActive: { type: &#x22;bool&#x22;, description: &#x22;Enable/disable&#x22; },
}"
/>

***

Delete a limit [#delete-a-limit]

<Endpoint method="DELETE" path="/api/v1/banking/limits/{id}" />

***

Check wallet usage [#check-wallet-usage]

<Endpoint method="GET" path="/api/v1/banking/wallets/{id}/limits/usage" />

Returns the wallet's current usage against all applicable limits. See
[Wallets: Get limit usage](/docs/banking/wallets#get-limit-usage) for the
response shape.

This is useful for showing users how much of their limit they've consumed
before they attempt a transaction.
