# Products

In order to enable [Financial Operations](/documentation/status_codes_for_financial_operations.md), it is necessary to create customer products. This document outlines product definitions, as well as creating and managing customer products.

### Products definitions

<table><thead><tr><th width="141.328125">Product name</th><th width="135.59765625">productType</th><th width="196.28515625">productCode</th><th>Description</th></tr></thead><tbody><tr><td><code>Balance</code></td><td><code>CASH</code></td><td><code>BALANCE_ACCOUNT</code></td><td><code>Balance account in EUR for natural persons or legal entities</code></td></tr><tr><td><code>Depository</code></td><td><code>DEPOSITORY</code></td><td><code>DEPOSITORY_ACCOUNT</code></td><td><code>Depository account for natural persons or legal entities</code></td></tr><tr><td><code>Wallet</code></td><td><code>WALLET</code></td><td><code>CURRENCY_WALLET</code></td><td><code>Crypto token wallet for natural persons or legal entities</code></td></tr></tbody></table>

Finding updated product definitions that are already or could be potentially available for partner, is always available with [Get Product Definitions](/api-reference/products/product-definitions-and-fees.md#get-products).

### Products dependencies

To better understand how different types of customer products support specific financial operations, it's helpful to look at the core dependencies by use case. The following section breaks down which account types are required for common scenarios, and how each component plays a role.

* Cash top/ups/payouts are possible with `BALANCE_ACCOUNT` only.
* [Traditional asset trading](/api-reference/asset-management/trading.md) requires operations on `DEPOSITORY_ACCOUNT` and `BALANCE_ACCOUNT` . In this case `BALANCE_ACCOUNT` reserves/settles cash, while `DEPOSITORY_ACCOUNT` holds positions; corporate actions post to Depository.
* [Crypto trading](/api-reference/asset-management/digital-assets.md)/custody will run only with active `BALANCE_ACCOUNT` and `CURRENCY_WALLET` . `BALANCE_ACCOUNT` is necessary for transfers with fiat currency and fees. `CURRENCY_WALLET` is required for on-chain assets custody.

### Creation & lifecycle <a href="#creation-and-lifecycle" id="creation-and-lifecycle"></a>

Understanding products creation and lifecycle of customers products is essential for smooth usage of the platform. The following section covers possible products actions and redirects to the right API references.

* Create products per customer with [`POST /customers/{customerId}/products`](/api-reference/products/customer-products.md#post-customers-customerid-products).
* Update status with [`PATCH /products/{customerProductId}`](/api-reference/products/customer-products.md#patch-products-customerproductid) (e.g., CLOSE).
* Cash movements via [`POST /transfers`](/api-reference/transfers/transfers.md#post-transfers) (SEPA-style); get full details of a transfer with [`/transfers/{transferId}`](/api-reference/transfers/transfers.md#get-transfers-transferid).
* Trades via [`/trading/order/{type}`](/api-reference/asset-management/digital-assets/create-order.md) (market/limit/stop) and [`/trading/order/{orderId}`](/api-reference/asset-management/digital-assets/create-order.md#patch-trading-order-orderid) (updates/cancel).
* Current balances and positions (cash, securities, crypto) via:
  * [`GET /customers/{customerId}/products`](/api-reference/products/customer-products.md#get-customers-customerid-products)
  * [`GET /products/{customerProductId}`](/api-reference/products/customer-products.md#get-products-customerproductid)
  * Includes `availableBalance` vs `withdrawableBalance` (cash) and `quantity` vs `availableQuantity` (positions).
* Event-level ledger of movements (trades, settlements, transfers) via:
  * [`GET /customers/{customerId}/transactions`](/api-reference/transaction-history.md#get-customers-customerid-transactions)
  * [`GET /transactions/{transactionId}`](/api-reference/transaction-history.md#get-transactions-transactionid)

### Product Status and Compliance

Customer products can transition to `BLOCKED` status due to regulatory compliance requirements. Key scenarios include:

* **Missing Tax Identification Number (TIN):** Under German tax office regulations, customers are required to have a valid TIN on file. If a TIN is not provided within the regulatory grace period (90 days), all associated products (BALANCE\_ACCOUNT, CURRENCY\_WALLET, DEPOSITORY\_ACCOUNT) will be automatically blocked. This applies to both natural persons and legal entities.
* **Entity suspension:** If the underlying entity (natural person or legal entity) is suspended or blocked for compliance reasons, all associated products are also blocked.

To resolve a `BLOCKED` status caused by missing tax information:

1. Ensure the required TIN is provided via the entity update endpoint.
2. Both the entity **and** the customer role must return to `ACTIVE` status before products are unblocked.
3. If the TIN was not provided within the 90-day regulatory period and the account has been suspended, the partner must contact the Tradevest support team to initiate the unsuspension process.
4. Product status changes are communicated via webhook notifications.

{% hint style="info" %}
**Monitor release notes:** Compliance enforcement rules may be introduced or updated in platform releases. Partners should regularly review the [release notes](https://github.com/Tradevest-GmbH/tvda-api/blob/release/test/dist/release-notes/README.md) to stay informed about regulatory changes that may affect existing customers.
{% endhint %}

### Operational notes

* `BALANCE_ACCOUNT` is prerequisite for any activity that settles fees or fiat legs.
* One customer can hold multiple `BALANCE_ACCOUNT`, `DEPOSITORY_ACCOUNT`, `CURRENCY_WALLET`; trading endpoints select the right product via IDs.
* For traditional assets, trades are executed T0 but settle on T+2:
  * On T0: cash reserved (`availableBalance ↓`), position booked in `quantity`.
  * On T+2: `withdrawableBalance` adjusted, `availableQuantity` updated.
* Securities bought are immediately visible and can be sold again (exposed in `quantity`), `availableQuantity` is the difference between blocked assets from e.g. limit orders and `quantity`.
* Cash proceeds from a sale are available for new trades right away (`availableBalance`), but only withdrawable after settlement (`withdrawableBalance`).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tradevest.ai/documentation/products.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.