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

# Capital

> Create and manage capital investments on behalf of your entities.

Capital lets an entity invest idle balances in Fixed Return or Share Offering products. An order holds an immutable quote for 15 minutes; confirming it debits the entity's funding account and creates the capital account, which is tracked through accrual to payout.

All monetary values are in the smallest currency unit.

## The Capital Product object

<ResponseField name="id" type="string">
  The ULID of the capital product.
</ResponseField>

<ResponseField name="capital_product_type" type="string">
  The product type. One of `FIXED_RETURN`, `SHARE_OFFERING`.
</ResponseField>

<ResponseField name="is_external" type="boolean">
  Whether the product is managed by an external partner rather than Nuvion directly.
</ResponseField>

<ResponseField name="name" type="string">
  The display name of the product.
</ResponseField>

<ResponseField name="description" type="string">
  Description of what the product offers, as HTML.
</ResponseField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code. The funding account used to order must match this currency.
</ResponseField>

<ResponseField name="start_date" type="number">
  Unix-ms start of the sale window. `null` when not configured.
</ResponseField>

<ResponseField name="end_date" type="number">
  Unix-ms end of the sale window. `null` when not configured.
</ResponseField>

<ResponseField name="config" type="object">
  Commercial terms for the product. Detail responses additionally include `documents`; list responses never do.

  <Expandable title="config fields">
    <ResponseField name="principal" type="object">
      The accepted investment sizes: `min`, `max`, and a `bands` array of `{ name, value }` exact-value bands.
    </ResponseField>

    <ResponseField name="tenor" type="object">
      Fixed Return only. `tenor_days` is one of `7`, `30`, `60`, `90`, `180`. `earliest_withdrawal_days` is the number of days before an early withdrawal may be requested.
    </ResponseField>

    <ResponseField name="rates" type="object">
      `interest.primary` is the annual decimal rate, e.g. `0.18` for 18%. `interest.bands` carries principal-tiered rates. `deductibles` lists each `{ name, value, value_type, applicable_to }`, where `value_type` is `flat` or `percentage` and `applicable_to` is `principal` or `interest`. Fixed Return exposes interest rates and deductibles; Share Offering exposes deductibles only.
    </ResponseField>

    <ResponseField name="orders" type="object">
      Fixed Return only. `orders.liquidation.allow_early_withdrawal` states explicitly whether early withdrawal is permitted on this product.
    </ResponseField>

    <ResponseField name="share_offering" type="object">
      Share Offering only. `issuer_name`, `offer_price` (whole-share price in minor units), `lock_period_days` (180 or greater), and `prospectus_url`.
    </ResponseField>

    <ResponseField name="documents" type="array">
      Detail responses only. Each document carries `name` and `url`. Every document must be affirmed when creating an order.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="availability" type="object">
  Present only for `SHARE_OFFERING`. `status` is `available` or `sold_out`; `quantity` is the current sellable inventory in whole shares.
</ResponseField>

***

```json Example Capital Product Object theme={null}
{
  "id": "01HXYZ0085ABCDEFGHJKMNPQRS",
  "capital_product_type": "FIXED_RETURN",
  "name": "Nuvion Fixed Return 90",
  "description": "Earn a locked-in return over 90 days.",
  "currency": "NGN",
  "start_date": 1784419200000,
  "end_date": 1795737600000,
  "config": {
    "principal": {
      "min": 10000000,
      "max": 500000000,
      "bands": []
    },
    "tenor": {
      "tenor_days": 90,
      "earliest_withdrawal_days": 30
    },
    "rates": {
      "interest": {
        "primary": 0.16,
        "bands": [
          {
            "name": "Tier 1",
            "rate": 0.16,
            "min_principal_amount": 10000000,
            "max_principal_amount": 49999999
          },
          {
            "name": "Tier 2",
            "rate": 0.18,
            "min_principal_amount": 50000000,
            "max_principal_amount": 500000000
          }
        ]
      },
      "deductibles": [
        {
          "name": "Withholding Tax",
          "value": 0.1,
          "value_type": "percentage",
          "applicable_to": "interest"
        },
        {
          "name": "Early Withdrawal Penalty",
          "value": 0.25,
          "value_type": "percentage",
          "applicable_to": "interest"
        }
      ]
    },
    "orders": {
      "liquidation": {
        "allow_early_withdrawal": true
      }
    }
  }
}
```

### Capital product types

| Type | Description |
| - | - |
| `FIXED_RETURN` | A fixed principal at a rate locked in at purchase, over a set tenor. Interest accrues daily |
| `SHARE_OFFERING` | Whole shares bought at a fixed offer price and held for a lock period before becoming transferable |

### Day count conventions

| Currency | Day count |
| - | - |
| `NGN` | 365 |
| `USD`, `GBP`, `EUR`, `CAD` | 360 |

***

## The Capital Order object

<ResponseField name="id" type="string">
  The ULID of the product order.
</ResponseField>

<ResponseField name="entity_id" type="string">
  The ID of the entity that placed the order.
</ResponseField>

<ResponseField name="reference" type="string">
  The order reference. Distinct from `id`.
</ResponseField>

<ResponseField name="product_id" type="string">
  The ULID of the capital product ordered.
</ResponseField>

<ResponseField name="funding_account_id" type="string">
  The ULID of the funding wallet account debited for this order. Matches the `account_id` submitted at creation.
</ResponseField>

<ResponseField name="product_type" type="string">
  One of `FIXED_RETURN`, `SHARE_OFFERING`.
</ResponseField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code.
</ResponseField>

<ResponseField name="amount" type="number">
  The reserved debit amount. The principal for Fixed Return; `total_debit` for Share Offering.
</ResponseField>

<ResponseField name="reserved_quantity" type="number">
  Share Offering reserved shares. `null` for Fixed Return.
</ResponseField>

<ResponseField name="status" type="string">
  One of `RESERVED`, `CONFIRMING`, `APPROVED`, `EXPIRED`, `REJECTED`, `RECOVERY_REQUIRED`.
</ResponseField>

<ResponseField name="status_reason" type="string">
  A human-readable reason accompanying the current status.
</ResponseField>

<ResponseField name="expires_at" type="number">
  Unix-ms reservation expiry, 15 minutes from creation.
</ResponseField>

<ResponseField name="confirmed_at" type="number">
  Unix-ms confirmation timestamp.
</ResponseField>

<ResponseField name="rejected_at" type="number">
  Unix-ms rejection timestamp.
</ResponseField>

<ResponseField name="expired_at" type="number">
  Unix-ms expiry timestamp.
</ResponseField>

<ResponseField name="capital_account" type="object">
  A summary of the capital account created by the order. `null` until the order is approved.
</ResponseField>

<ResponseField name="agreements" type="array">
  Detail responses only. Each entry pairs the `document` with the requesting entity's `affirmations`, each carrying `action_type` and `actioned_at`. Only the requesting entity's affirmations are exposed.
</ResponseField>

### Capital order statuses

| Status | Terminal | Description |
| - | - | - |
| `RESERVED` | No | Quote reserved, awaiting confirmation. Expires after 15 minutes |
| `CONFIRMING` | No | Confirmation in progress; the funding wallet debit is being applied |
| `APPROVED` | Yes | Debit settled and the capital account created |
| `EXPIRED` | Yes | The reservation expired before it was confirmed |
| `REJECTED` | Yes | Confirmation failed eligibility, product, or sale window re-checks |
| `RECOVERY_REQUIRED` | No | The debit succeeded but post-debit persistence failed. Under review |

***

## The Capital Account object

The capital account is created on confirmation and holds the immutable terms of the investment.

<ResponseField name="id" type="string">
  The ULID of the capital account.
</ResponseField>

<ResponseField name="product_order_id" type="string">
  The ULID of the order that created the account.
</ResponseField>

<ResponseField name="product_id" type="string">
  The ULID of the capital product this account was opened against.
</ResponseField>

<ResponseField name="product_type" type="string">
  One of `FIXED_RETURN`, `SHARE_OFFERING`.
</ResponseField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code.
</ResponseField>

<ResponseField name="account_number" type="string">
  The account number issued for this capital holding.
</ResponseField>

<ResponseField name="principal" type="number">
  Fixed Return only. The invested principal in minor units.
</ResponseField>

<ResponseField name="locked_rate" type="number">
  Fixed Return only. The annual decimal rate locked at purchase.
</ResponseField>

<ResponseField name="day_count" type="number">
  Fixed Return only. `365` or `360`, resolved from the currency.
</ResponseField>

<ResponseField name="tenor_days" type="number">
  Fixed Return only. One of `7`, `30`, `60`, `90`, `180`.
</ResponseField>

<ResponseField name="start_date" type="number">
  Fixed Return only. The Unix-ms confirmation timestamp from which interest accrues.
</ResponseField>

<ResponseField name="maturity_date" type="number">
  Fixed Return only. The business-day maturity in UTC. A contractual end falling on a Saturday or Sunday shifts to the following Monday.
</ResponseField>

<ResponseField name="early_action_date" type="number">
  Fixed Return only. The earliest Unix-ms at which an early withdrawal may be requested. `null` when the investment is locked or early withdrawal is disabled.
</ResponseField>

<ResponseField name="accrued_interest" type="number">
  Fixed Return only. Computed on read from the account terms and the elapsed days, bounded by the tenor. It is not a stored balance.
</ResponseField>

<ResponseField name="due_interest" type="number">
  Fixed Return only. The projected net interest at maturity: `gross_interest` minus `total_deductions`. Fixed at confirmation; does not reflect elapsed time. See `accrued_interest` for the current accrued amount.
</ResponseField>

<ResponseField name="expected_net_payout" type="number">
  Fixed Return only. The projected payout at maturity: `principal` plus `due_interest`.
</ResponseField>

<ResponseField name="total_deductions" type="number">
  Fixed Return only. Interest-based deductibles, such as withholding tax, projected at maturity.
</ResponseField>

<ResponseField name="gross_interest" type="number">
  Fixed Return only. The projected total interest at maturity, before deductibles. Fixed at confirmation; does not reflect elapsed time.
</ResponseField>

<ResponseField name="expected_gross_payout" type="number">
  Fixed Return only. `principal` plus `gross_interest`, before deductibles.
</ResponseField>

<ResponseField name="net_payout" type="number">
  Fixed Return only. `null` until a payout is initiated. Persisted by the withdrawal action and used by the settlement workers.
</ResponseField>

<ResponseField name="settlement_date" type="number">
  Fixed Return only. Unix-ms date the payout is scheduled to settle. `null` until settlement is scheduled, which can be after the payout is initiated.
</ResponseField>

<ResponseField name="shares_purchased" type="number">
  Share Offering only. The originally allocated quantity. Never rewritten by allotment adjustments.
</ResponseField>

<ResponseField name="units_held" type="number">
  Share Offering only. Adjusted by allotment; initially equal to `shares_purchased`.
</ResponseField>

<ResponseField name="base_cost" type="number">
  Share Offering only. `allocated_shares` multiplied by `offer_price`.
</ResponseField>

<ResponseField name="brokerage_fee_charged" type="number">
  Share Offering only. The brokerage fee charged at purchase.
</ResponseField>

<ResponseField name="cross_deal_fee_charged" type="number">
  Share Offering only. The cross-deal fee charged at purchase.
</ResponseField>

<ResponseField name="total_amount_debited" type="number">
  Share Offering only. The full amount debited from the funding wallet.
</ResponseField>

<ResponseField name="lock_expiry_date" type="number">
  Share Offering only. The immutable lock expiry computed from the confirmed purchase date.
</ResponseField>

<ResponseField name="cost_basis" type="number">
  Share Offering only. The cost basis of the units held.
</ResponseField>

<ResponseField name="average_cost_per_unit" type="number">
  Share Offering only. The cost basis divided by the units held.
</ResponseField>

<ResponseField name="current_market_value" type="number">
  Share Offering only. `null` rather than zero before a valid price update exists.
</ResponseField>

<ResponseField name="pending_refund_amount" type="number">
  Share Offering only. The unallocated value awaiting refund.
</ResponseField>

<ResponseField name="lifecycle" type="object">
  `status` carries the account state. `payout_status` (or `refund_status` for Share Offering) is one of `pending`, `completed`, `failed` and is present once a payout exists.
</ResponseField>

### Capital account lifecycle statuses

Fixed Return:

| Status | Terminal | Description |
| - | - | - |
| `ACTIVE` | No | Accruing interest daily, before maturity |
| `MATURED` | No | Tenor complete and awaiting the maturity payout |
| `EARLY_LIQUIDATING` | No | Early withdrawal initiated; payout being settled |
| `WITHDRAWN` | Yes | Early liquidation payout settled |
| `CLOSING` | No | Maturity payout initiated; payment being settled |
| `CLOSED` | Yes | Maturity payout settled and the account closed |

Share Offering:

| Status | Terminal | Description |
| - | - | - |
| `LOCKED` | No | Shares held within the lock period |
| `ALLOTMENT_ADJUSTED` | No | Units held adjusted by the issuer's allotment |
| `ALLOTMENT_CONFIRMED` | No | All units requested were allotted by the issuer |
| `TRANSFERABLE` | No | Lock period expired; units are transferable |
| `REFUNDED` | Yes | Unallocated value refunded to the funding wallet |

***

## The Capital Transaction object

<ResponseField name="id" type="string">
  The ULID of the capital transaction.
</ResponseField>

<ResponseField name="entity_id" type="string">
  The ID of the entity that owns the capital transaction.
</ResponseField>

<ResponseField name="event_type" type="string">
  The event the transaction records. See the table below.
</ResponseField>

<ResponseField name="amount" type="number">
  The amount in minor units. Its meaning depends on `event_type`.
</ResponseField>

<ResponseField name="accrual_date" type="number">
  Unix-ms accrual date. Present only on `DAILY_ACCRUAL` events.
</ResponseField>

<ResponseField name="funded_amount" type="number">
  The amount funded through an investment vehicle, in minor units. `null` when not applicable.
</ResponseField>

<ResponseField name="placement_fee_charged" type="number">
  The placement fee charged for this transaction, in minor units. `null` when not applicable.
</ResponseField>

<ResponseField name="vehicle_expense_charged" type="number">
  Expenses charged by the investment vehicle for this transaction, in minor units. `null` when not applicable.
</ResponseField>

<ResponseField name="created" type="number">
  Unix-ms event creation timestamp.
</ResponseField>

### Capital transaction event types

| Event type | Description |
| - | - |
| `PURCHASE` | The confirmed debit that opened the capital account |
| `DAILY_ACCRUAL` | A day's interest accrued on a Fixed Return account |
| `EARLY_WITHDRAWAL_PENALTY` | The penalty applied to accrued interest on early exit |
| `WITHHOLDING_TAX` | Tax withheld from interest |
| `WITHDRAWAL` | The instruction that initiates a payout |
| `MATURITY_PAYOUT` | The payout raised at maturity |
| `MATURITY_SETTLEMENT` | The settlement of the maturity payout |
| `EARLY_LIQUIDATION_PAYOUT` | The payout raised on early liquidation |
| `ALLOTMENT_ADJUSTED` | Units held adjusted by the issuer's allotment |
| `REFUND` | Unallocated value returned to the funding wallet |
| `LOCK_EXPIRY` | The share lock period ended |
| `PRICE_UPDATE` | A market price update applied to the holding |
| `DIVIDEND_ACCRUED` | A dividend accrued on the holding |
| `DIVIDEND_DISTRIBUTED` | An accrued dividend paid out |

***

## Retrieve capital products

`GET /products`

Lists the capital products visible to the authenticated entity. Hidden products, ineligible products, products whose owner is inactive, and share offerings with zero inventory are excluded. Sold-out share offerings are returned as not orderable.

### Query parameters

<ParamField query="capital_product_type" type="string">
  Filter by product type. One of `FIXED_RETURN`, `SHARE_OFFERING`.
</ParamField>

<ParamField query="currency" type="string">
  Filter by ISO 4217 currency code.
</ParamField>

<ParamField query="entity_id" type="string">
  Defaults to the authenticating entity when omitted. Required when acting on a child entity. See [Managing child entities](/core-concepts/entities#managing-child-entities) for details.
</ParamField>

<ParamField query="limit" type="number">
  Page size. Between `1` and `100`. Defaults to `25`.
</ParamField>

<ParamField query="cursor" type="string">
  Next-page cursor.
</ParamField>

<ParamField query="prev_cursor" type="string">
  Previous-page cursor. Mutually exclusive with `cursor`.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.nuvion.dev/products?capital_product_type=FIXED_RETURN&currency=NGN&limit=25" \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```json 200 OK theme={null}
  {
    "status": "success",
    "message": "Capital products retrieved successfully",
    "data": {
      "data": [
        {
          "id": "01HXYZ0080ABCDEFGHJKMNPQRS",
          "capital_product_type": "FIXED_RETURN",
          "is_external": false,
          "name": "Nuvion Prime 30",
          "description": "<p><strong>Nuvion Prime 30</strong> is a short-term, fixed-income deposit product for clients seeking high-yield returns with minimal lock-in duration.</p>",
          "currency": "NGN",
          "start_date": null,
          "end_date": null,
          "config": {
            "principal": {
              "min": 10000000,
              "max": 500000000,
              "bands": []
            },
            "tenor": {
              "tenor_days": 30,
              "earliest_withdrawal_days": 30
            },
            "rates": {
              "interest": {
                "primary": 0.12,
                "bands": [
                  {
                    "name": "Tier 2",
                    "rate": 0.18,
                    "min_principal_amount": 50000000,
                    "max_principal_amount": 500000000
                  }
                ]
              },
              "deductibles": [
                {
                  "name": "Withholding Tax",
                  "value": 0.1,
                  "value_type": "percentage",
                  "applicable_to": "interest"
                }
              ]
            },
            "orders": {
              "liquidation": {
                "allow_early_withdrawal": true
              }
            }
          }
        },
        {
          "id": "01HXYZ0081ABCDEFGHJKMNPQRS",
          "capital_product_type": "SHARE_OFFERING",
          "is_external": false,
          "name": "Meridian Holdings Series A",
          "description": "<p>Private placement in Meridian Holdings Plc.</p>",
          "currency": "USD",
          "start_date": 1786752000000,
          "end_date": 1789344000000,
          "config": {
            "principal": {
              "min": 100000,
              "bands": []
            },
            "rates": {
              "deductibles": [
                {
                  "name": "Brokerage Fee",
                  "value": 0.015,
                  "value_type": "percentage",
                  "applicable_to": "principal"
                },
                {
                  "name": "Cross-Deal Fee",
                  "value": 0.005,
                  "value_type": "percentage",
                  "applicable_to": "principal"
                }
              ]
            },
            "share_offering": {
              "issuer_name": "Meridian Holdings Plc",
              "offer_price": 25000,
              "lock_period_days": 180,
              "prospectus_url": "https://cdn.nuvion.dev/capital/meridian-prospectus.pdf"
            }
          },
          "availability": {
            "status": "available",
            "quantity": 12500
          }
        }
      ],
      "meta": {
        "pagination": {
          "order": "asc",
          "has_next": true,
          "limit": 25,
          "has_previous": false,
          "next_cursor": "01HXYZ0081ABCDEFGHJKMNPQRS",
          "previous_cursor": null
        },
        "filters_applied": {
          "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
          "sort": {
            "field": "created",
            "order": "desc"
          }
        }
      }
    }
  }
  ```
</CodeGroup>

<Note>
  Product documents are never included in list responses. Call `GET /products/{id}` to retrieve the documents to affirm before ordering.
</Note>

***

## Retrieve a capital product

`GET /products/{id}`

Retrieves the detail view of a single capital product, including its displayable documents.

### Path parameters

<ParamField path="id" type="string" required>
  The ULID of the capital product.
</ParamField>

### Query parameters

<ParamField query="entity_id" type="string">
  Defaults to the authenticating entity when omitted. Required when acting on a child entity. See [Managing child entities](/core-concepts/entities#managing-child-entities) for details.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.nuvion.dev/products/01HXYZ0080ABCDEFGHJKMNPQRS \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```json 200 OK theme={null}
  {
    "status": "success",
    "message": "Capital product retrieved successfully",
    "data": {
      "id": "01HXYZ0080ABCDEFGHJKMNPQRS",
      "capital_product_type": "FIXED_RETURN",
      "is_external": false,
      "name": "Nuvion Prime 30",
      "description": "<p><strong>Nuvion Prime 30</strong> is a short-term, fixed-income deposit product for clients seeking high-yield returns with minimal lock-in duration.</p>",
      "currency": "NGN",
      "start_date": null,
      "end_date": null,
      "config": {
        "principal": {
          "min": 10000000,
          "max": 500000000,
          "bands": []
        },
        "documents": [
          {
            "name": "Fixed Return Terms and Conditions.pdf",
            "url": "https://cdn.nuvion.dev/capital/fixed-return-terms.pdf"
          }
        ],
        "tenor": {
          "tenor_days": 30,
          "earliest_withdrawal_days": 30
        },
        "rates": {
          "interest": {
            "primary": 0.12,
            "bands": [
              {
                "name": "Tier 2",
                "rate": 0.18,
                "min_principal_amount": 50000000,
                "max_principal_amount": 500000000
              }
            ]
          },
          "deductibles": [
            {
              "name": "Withholding Tax",
              "value": 0.1,
              "value_type": "percentage",
              "applicable_to": "interest"
            },
            {
              "name": "Early Withdrawal Penalty",
              "value": 0.25,
              "value_type": "percentage",
              "applicable_to": "interest"
            }
          ]
        },
        "orders": {
          "liquidation": {
            "allow_early_withdrawal": true
          }
        }
      }
    }
  }
  ```
</CodeGroup>

<Note>
  A `404` is returned rather than disclosing existence when the product is inactive, ineligible, misconfigured, or holds an unsupported Share Offering quantity.
</Note>

***

## Create a capital order

`POST /product-orders`

Creates a 15-minute reservation holding an immutable commercial quote and the entity's agreement evidence. No funds move. The product type is resolved from `product_id` and determines whether `principal` or `amount` is permitted. Share Offering inventory is conditionally reserved in the same transaction; where inventory is insufficient the order is allocated down to the remaining shares and the adjusted quote must be confirmed.

### Request parameters

<ParamField body="product_id" type="string" required>
  The ULID of the capital product being ordered.
</ParamField>

<ParamField body="account_id" type="string" required>
  The ULID of the funding wallet account to debit. Must match the product currency.
</ParamField>

<ParamField body="entity_id" type="string">
  Defaults to the authenticating entity when omitted. Required when acting on a child entity. See [Managing child entities](/core-concepts/entities#managing-child-entities) for details.
</ParamField>

<ParamField body="principal" type="number">
  Required for `FIXED_RETURN`, rejected for `SHARE_OFFERING`. Positive minor units. Must match an exact configured band, or fall within the configured minimum and maximum.
</ParamField>

<ParamField body="lock_investment" type="boolean">
  Required for `FIXED_RETURN`, rejected for `SHARE_OFFERING`. Set to `true` to waive early withdrawal for the full tenor. Write-once; it cannot be changed after the order is created.
</ParamField>

<ParamField body="amount" type="number">
  Required for `SHARE_OFFERING`, rejected for `FIXED_RETURN`. The desired spend in minor units, from which whole shares are derived.
</ParamField>

<ParamField body="agreement_acceptances" type="array" required>
  One affirmation per configured product document. Unknown, duplicate, stale, or missing entries are rejected.

  <Expandable title="agreement_acceptances fields">
    <ParamField body="document_name" type="string" required>
      Must match a configured product document name.
    </ParamField>

    <ParamField body="action_type" type="string" required>
      `affirmation`. Click-through affirmation is the only supported action type.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash Fixed Return theme={null}
  curl -X POST https://api.nuvion.dev/product-orders \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
      "account_id": "01HXYZ0086ABCDEFGHJKMNPQRS",
      "principal": 50000000,
      "lock_investment": false,
      "agreement_acceptances": [
        {
          "document_name": "Fixed Return Terms and Conditions",
          "action_type": "affirmation"
        }
      ]
    }'
  ```

  ```bash Share Offering theme={null}
  curl -X POST https://api.nuvion.dev/product-orders \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "product_id": "01HXYZ0081ABCDEFGHJKMNPQRS",
      "account_id": "01HXYZ0109ABCDEFGHJKMNPQRS",
      "amount": 10060000,
      "agreement_acceptances": [
        {
          "document_name": "Offer Prospectus",
          "action_type": "affirmation"
        }
      ]
    }'
  ```
</CodeGroup>

### Response

<CodeGroup>
  ```json 201 created Fixed Return theme={null}
  {
    "status": "success",
    "message": "Capital order reserved successfully",
    "data": {
      "id": "01HXYZ0088ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "status": "RESERVED",
      "expires_at": 1787098500000,
      "currency": "NGN",
      "quote": {
        "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
        "product_owner_id": "01HXYZ0087ABCDEFGHJKMNPQRS",
        "product_type": "FIXED_RETURN",
        "currency": "NGN",
        "principal": 50000000,
        "total_debit": 50000000,
        "tenor_days": 90,
        "locked_rate": 0.18,
        "rate_source": "band:Tier 2",
        "day_count": 365,
        "is_locked": false,
        "allow_early_withdrawal": true,
        "earliest_withdrawal_days": 30,
        "penalty": {
          "primary": 0.25
        },
        "deductibles": [
          {
            "name": "Withholding Tax",
            "value": 0.1,
            "value_type": "percentage",
            "applicable_to": "interest"
          }
        ]
      }
    }
  }
  ```

  ```json 201 created Share Offering theme={null}
  {
    "status": "success",
    "message": "Capital order reserved successfully",
    "data": {
      "id": "01HXYZ0108ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "status": "RESERVED",
      "expires_at": 1787098500000,
      "currency": "USD",
      "quote": {
        "product_id": "01HXYZ0081ABCDEFGHJKMNPQRS",
        "product_owner_id": "01HXYZ0087ABCDEFGHJKMNPQRS",
        "product_type": "SHARE_OFFERING",
        "currency": "USD",
        "requested_amount": 10060000,
        "requested_shares": 402,
        "allocated_shares": 402,
        "unallocated_amount": 10000,
        "offer_price": 25000,
        "base_cost": 10050000,
        "brokerage_fee": 150750,
        "cross_deal_fee": 50250,
        "total_debit": 10251000,
        "deductibles": [
          {
            "name": "Brokerage Fee",
            "value": 0.015,
            "value_type": "percentage",
            "applicable_to": "principal",
            "amount": 150750
          },
          {
            "name": "Cross-Deal Fee",
            "value": 0.005,
            "value_type": "percentage",
            "applicable_to": "principal",
            "amount": 50250
          }
        ],
        "lock_period_days": 180
      }
    }
  }
  ```
</CodeGroup>

<Note>
  Where the requested shares exceed the remaining inventory, `allocated_shares` and `total_debit` reflect the adjusted amounts.
</Note>

***

## Confirm a capital order

`POST /product-orders/{id}/confirm`

Confirms an unexpired reservation. Eligibility, product and owner status, and the sale window are re-evaluated before any debit; the stored quote is authoritative. Nuvion debits the funding wallet once using a deterministic transfer reference, then creates the approved capital account and a `PURCHASE` capital transaction.

### Path parameters

<ParamField path="id" type="string" required>
  The ULID of the capital order to confirm.
</ParamField>

### Request parameters

<ParamField body="entity_id" type="string">
  Defaults to the authenticating entity when omitted. Required when acting on a child entity. See [Managing child entities](/core-concepts/entities#managing-child-entities) for details.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.nuvion.dev/product-orders/01HXYZ0088ABCDEFGHJKMNPQRS/confirm \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```json 200 OK theme={null}
  {
    "status": "success",
    "message": "Capital order confirmed successfully",
    "data": {
      "id": "01HXYZ0088ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "status": "APPROVED",
      "capital_account_id": "01HXYZ0089ABCDEFGHJKMNPQRS",
      "user_capital_account_id": "01HXYZ0090ABCDEFGHJKMNPQRS",
      "transfer_reference": "capital-fixed-return:01HXYZ0088ABCDEFGHJKMNPQRS"
    }
  }
  ```
</CodeGroup>

<ResponseField name="user_capital_account_id" type="string">
  A secondary identifier for the capital account, in addition to `capital_account_id`.
</ResponseField>

This endpoint does not require a request body. Nuvion never accepts client-supplied amounts, rates, inventory, or agreements.

A retry resumes from the persisted transfer and order state and never issues a second debit. Where post-debit persistence fails, the order transitions to `RECOVERY_REQUIRED` for reconciliation rather than being retried as a new debit, and subsequent calls return `409 error_transfer_already_processing`.

***

## Retrieve capital orders

`GET /product-orders`

Lists the capital orders belonging to the authenticated entity. Each item includes a linked capital account summary where one exists.

### Query parameters

<ParamField query="status" type="string">
  Filter by order status. One of `RESERVED`, `CONFIRMING`, `APPROVED`, `EXPIRED`, `REJECTED`, `RECOVERY_REQUIRED`.
</ParamField>

<ParamField query="product_type" type="string">
  Filter by product type. One of `FIXED_RETURN`, `SHARE_OFFERING`.
</ParamField>

<ParamField query="entity_id" type="string">
  Defaults to the authenticating entity when omitted. Required when acting on a child entity. See [Managing child entities](/core-concepts/entities#managing-child-entities) for details.
</ParamField>

<ParamField query="limit" type="number">
  Page size. Between `1` and `100`. Defaults to `25`.
</ParamField>

<ParamField query="cursor" type="string">
  Next-page cursor.
</ParamField>

<ParamField query="prev_cursor" type="string">
  Previous-page cursor. Mutually exclusive with `cursor`.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.nuvion.dev/product-orders?status=APPROVED&product_type=FIXED_RETURN&limit=25" \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```json 200 OK theme={null}
  {
    "status": "success",
    "message": "Capital orders retrieved successfully",
    "data": {
      "data": [
        {
          "id": "01HXYZ0088ABCDEFGHJKMNPQRS",
          "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
          "reference": "01HXYZ0091ABCDEFGHJKMNPQRS",
          "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
          "funding_account_id": "01HXYZ0086ABCDEFGHJKMNPQRS",
          "product_type": "FIXED_RETURN",
          "currency": "NGN",
          "amount": 50000000,
          "reserved_quantity": null,
          "status": "APPROVED",
          "status_reason": null,
          "expires_at": 1787098500000,
          "confirmed_at": 1787097640000,
          "rejected_at": null,
          "expired_at": null,
          "created": 1787097600000,
          "updated": 1787097640000,
          "capital_account": {
            "id": "01HXYZ0089ABCDEFGHJKMNPQRS",
            "product_order_id": "01HXYZ0088ABCDEFGHJKMNPQRS",
            "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
            "product_type": "FIXED_RETURN",
            "currency": "NGN",
            "account_number": "0019876543",
            "principal": 50000000,
            "locked_rate": 0.18,
            "day_count": 365,
            "tenor_days": 90,
            "start_date": 1787097640000,
            "maturity_date": 1794873600000,
            "early_action_date": 1789689600000,
            "accrued_interest": 739726,
            "due_interest": 1997261,
            "expected_net_payout": 51997261,
            "total_deductions": 221917,
            "gross_interest": 2219178,
            "expected_gross_payout": 52219178,
            "net_payout": null,
            "settlement_date": null,
            "lifecycle": {
              "status": "ACTIVE",
              "payout_status": null
            },
            "created": 1787097640000,
            "updated": 1789689600000
          }
        },
        {
          "id": "01HXYZ0108ABCDEFGHJKMNPQRS",
          "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
          "reference": "01HXYZ0110ABCDEFGHJKMNPQRS",
          "product_id": "01HXYZ0081ABCDEFGHJKMNPQRS",
          "funding_account_id": "01HXYZ0086ABCDEFGHJKMNPQRS",
          "product_type": "SHARE_OFFERING",
          "currency": "USD",
          "amount": 10251000,
          "reserved_quantity": 402,
          "status": "EXPIRED",
          "status_reason": "The reservation expired before it was confirmed.",
          "expires_at": 1787012100000,
          "confirmed_at": null,
          "rejected_at": null,
          "expired_at": 1787012100000,
          "created": 1787011200000,
          "updated": 1787012100000,
          "capital_account": null
        }
      ],
      "meta": {
        "pagination": {
          "order": "desc",
          "has_next": false,
          "limit": 25,
          "has_previous": false,
          "next_cursor": null,
          "previous_cursor": null
        },
        "filters_applied": {
          "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
          "sort": {
            "field": "created",
            "order": "desc"
          }
        }
      }
    }
  }
  ```
</CodeGroup>

***

## Retrieve a capital order

`GET /product-orders/{id}`

Retrieves a capital order with its linked account summary and agreement snapshots. Agreements expose only the requesting entity's affirmations and never internal signatory metadata.

### Path parameters

<ParamField path="id" type="string" required>
  The ULID of the capital order.
</ParamField>

### Query parameters

<ParamField query="entity_id" type="string">
  Defaults to the authenticating entity when omitted. Required when acting on a child entity. See [Managing child entities](/core-concepts/entities#managing-child-entities) for details.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.nuvion.dev/product-orders/01HXYZ0088ABCDEFGHJKMNPQRS \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```json 200 OK theme={null}
  {
    "status": "success",
    "message": "Capital order retrieved successfully",
    "data": {
      "id": "01HXYZ0088ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "reference": "01HXYZ0091ABCDEFGHJKMNPQRS",
      "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
      "funding_account_id": "01HXYZ0086ABCDEFGHJKMNPQRS",
      "product_type": "FIXED_RETURN",
      "currency": "NGN",
      "amount": 50000000,
      "reserved_quantity": null,
      "status": "APPROVED",
      "status_reason": null,
      "expires_at": 1787098500000,
      "confirmed_at": 1787097640000,
      "rejected_at": null,
      "expired_at": null,
      "created": 1787097600000,
      "updated": 1787097640000,
      "capital_account": {
        "id": "01HXYZ0089ABCDEFGHJKMNPQRS",
        "product_order_id": "01HXYZ0088ABCDEFGHJKMNPQRS",
        "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
        "product_type": "FIXED_RETURN",
        "currency": "NGN",
        "account_number": "0019876543",
        "principal": 50000000,
        "locked_rate": 0.18,
        "day_count": 365,
        "tenor_days": 90,
        "start_date": 1787097640000,
        "maturity_date": 1794873600000,
        "early_action_date": 1789689600000,
        "accrued_interest": 739726,
        "due_interest": 1997261,
        "expected_net_payout": 51997261,
        "total_deductions": 221917,
        "gross_interest": 2219178,
        "expected_gross_payout": 52219178,
        "net_payout": null,
        "settlement_date": null,
        "lifecycle": {
          "status": "ACTIVE",
          "payout_status": null
        },
        "created": 1787097640000,
        "updated": 1789689600000
      },
      "agreements": [
        {
          "document": {
            "name": "Fixed Return Terms and Conditions",
            "url": "https://cdn.nuvion.dev/capital/fixed-return-terms.pdf"
          },
          "affirmations": [
            {
              "action_type": "affirmation",
              "actioned_at": 1787097600000
            }
          ]
        }
      ]
    }
  }
  ```
</CodeGroup>

***

## Preview a withdrawal

`GET /product-orders/{id}/withdrawal/preview`

Returns a read-only payout preview for a Fixed Return capital order. Nuvion resolves the order and its linked capital account, then selects one path from the account snapshot and the current time: before maturity, the early-liquidation preview applies where the account is active, unlocked, and eligible; from `MATURED`, the contractual maturity payout applies with no early penalty.

The preview has no side effects. It never opens a session, writes a record, or schedules a settlement job.

### Path parameters

<ParamField path="id" type="string" required>
  The ULID of the capital order.
</ParamField>

### Query parameters

<ParamField query="entity_id" type="string">
  Defaults to the authenticating entity when omitted. Required when acting on a child entity. See [Managing child entities](/core-concepts/entities#managing-child-entities) for details.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.nuvion.dev/product-orders/01HXYZ0088ABCDEFGHJKMNPQRS/withdrawal/preview \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```json 200 OK EARLY theme={null}
  {
    "status": "success",
    "message": "Capital withdrawal preview generated successfully",
    "data": {
      "id": "01HXYZ0089ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "gross_interest": 739726,
      "penalty_rate": 0.25,
      "penalty_amount": 184931,
      "total_deductions": 55479,
      "net_payout": 50499316,
      "days_elapsed": 30
    }
  }
  ```

  ```json 200 OK MATURE theme={null}
  {
    "status": "success",
    "message": "Capital withdrawal preview generated successfully",
    "data": {
      "id": "01HXYZ0089ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "gross_interest": 2219178,
      "penalty_rate": 0,
      "penalty_amount": 0,
      "total_deductions": 221917,
      "net_payout": 51997261,
      "days_elapsed": 90
    }
  }
  ```
</CodeGroup>

<ResponseField name="id" type="string">
  The ULID of the capital account being previewed.
</ResponseField>

<ResponseField name="entity_id" type="string">
  The ID of the entity that owns the capital account.
</ResponseField>

<ResponseField name="gross_interest" type="number">
  Accrued interest for an early preview, or the contractual interest at maturity.
</ResponseField>

<ResponseField name="penalty_rate" type="number">
  The decimal penalty rate applied to gross interest. `0` for a maturity withdrawal.
</ResponseField>

<ResponseField name="penalty_amount" type="number">
  `gross_interest` multiplied by `penalty_rate`, rounded down. `0` for a maturity withdrawal.
</ResponseField>

<ResponseField name="total_deductions" type="number">
  Interest-based deductibles such as withholding tax. Applied to the penalty-excluded base for an early withdrawal, and to the full interest base at maturity.
</ResponseField>

<ResponseField name="net_payout" type="number">
  `principal + gross_interest - penalty_amount - total_deductions`.
</ResponseField>

<ResponseField name="days_elapsed" type="number">
  Whole days elapsed since the start date for an early preview, or the account tenor at maturity.
</ResponseField>

***

## Initiate a withdrawal

`POST /product-orders/{id}/withdrawal`

Initiates the payout for a Fixed Return capital order. Nuvion resolves the order and its linked capital account, then selects one guarded path from the account snapshot:

* An `ACTIVE` account before maturity follows the early withdrawal rules: `ACTIVE` moves to `EARLY_LIQUIDATING`, with the penalty and interest-based deductibles applied. Nuvion writes the penalty, withholding, and payout capital transactions and schedules the early-liquidation settlement job.
* A `MATURED` account follows the contractual maturity payout: `MATURED` moves to `CLOSING`, with no early penalty. Nuvion creates a `pending` payment backed by the order's funding account and schedules the maturity settlement job.
* A `CLOSING` or terminal account returns its current state rather than starting a second payout.

### Path parameters

<ParamField path="id" type="string" required>
  The ULID of the capital order.
</ParamField>

### Request parameters

<ParamField body="entity_id" type="string">
  Defaults to the authenticating entity when omitted. Required when acting on a child entity. See [Managing child entities](/core-concepts/entities#managing-child-entities) for details.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.nuvion.dev/product-orders/01HXYZ0088ABCDEFGHJKMNPQRS/withdrawal \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```json 200 OK theme={null}
  {
    "status": "success",
    "message": "Capital withdrawal initiated successfully",
    "data": {
      "id": "01HXYZ0088ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "reference": "01HXYZ0091ABCDEFGHJKMNPQRS",
      "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
      "funding_account_id": "01HXYZ0086ABCDEFGHJKMNPQRS",
      "product_type": "FIXED_RETURN",
      "currency": "NGN",
      "amount": 50000000,
      "reserved_quantity": null,
      "status": "APPROVED",
      "status_reason": null,
      "expires_at": 1787098500000,
      "confirmed_at": 1787097640000,
      "rejected_at": null,
      "expired_at": null,
      "created": 1787097600000,
      "updated": 1789689600000,
      "capital_account": {
        "id": "01HXYZ0089ABCDEFGHJKMNPQRS",
        "product_order_id": "01HXYZ0088ABCDEFGHJKMNPQRS",
        "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
        "product_type": "FIXED_RETURN",
        "currency": "NGN",
        "account_number": "0019876543",
        "principal": 50000000,
        "locked_rate": 0.18,
        "day_count": 365,
        "tenor_days": 90,
        "start_date": 1787097640000,
        "maturity_date": 1794873600000,
        "early_action_date": 1789689600000,
        "accrued_interest": 739726,
        "due_interest": 1997261,
        "expected_net_payout": 51997261,
        "total_deductions": 221917,
        "gross_interest": 2219178,
        "expected_gross_payout": 52219178,
        "net_payout": 50499316,
        "settlement_date": null,
        "lifecycle": {
          "status": "EARLY_LIQUIDATING",
          "payout_status": "pending"
        },
        "created": 1787097640000,
        "updated": 1789689600000
      },
      "agreements": [
        {
          "document": {
            "name": "Fixed Return Terms and Conditions",
            "url": "https://cdn.nuvion.dev/capital/fixed-return-terms.pdf"
          },
          "affirmations": [
            {
              "action_type": "affirmation",
              "actioned_at": 1787097600000
            }
          ]
        }
      ]
    }
  }
  ```
</CodeGroup>

This endpoint does not require a request body. The stored account snapshot is authoritative; Nuvion never accepts client-supplied amounts, rates, or settlement accounts.

<Note>
  A `400 error_operation_invalid_for_state` covers locked accounts, non-Fixed-Return accounts, accounts already `EARLY_LIQUIDATING`, `CLOSING`, or `CLOSED`, accounts at or after maturity that are still `ACTIVE`, products with early withdrawal disabled, and requests made before the earliest action day.
</Note>

***

## Retrieve the capital portfolio

`GET /capital-portfolio`

Returns the authenticated entity's current capital investment totals grouped by currency. Nuvion accrues Fixed Return interest from the account terms at request time; Share Offering value uses the units held and the latest market price.

Fixed Return holdings in `ACTIVE`, `MATURED`, `EARLY_LIQUIDATING`, and `CLOSING`, and Share Offering holdings in `LOCKED`, `ALLOTMENT_ADJUSTED`, `ALLOTMENT_CONFIRMED`, and `TRANSFERABLE`, are included.

### Query parameters

<ParamField query="entity_id" type="string">
  Defaults to the authenticating entity when omitted. Required when acting on a child entity. See [Managing child entities](/core-concepts/entities#managing-child-entities) for details.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.nuvion.dev/capital-portfolio \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```json 200 OK theme={null}
  {
    "message": "Capital portfolio retrieved successfully",
    "status": "success",
    "data": {
      "currencies": [
        {
          "currency": "NGN",
          "totals": {
            "investment": {
              "amount_invested": 50000000,
              "total_return": 739726,
              "current_value": 50739726
            }
          }
        },
        {
          "currency": "USD",
          "totals": {
            "investment": {
              "amount_invested": 10251000,
              "total_return": null,
              "current_value": null
            }
          }
        }
      ]
    }
  }
  ```
</CodeGroup>

<ResponseField name="currency" type="string">
  ISO 4217 currency code. Currencies are sorted ascending.
</ResponseField>

<ResponseField name="amount_invested" type="number">
  The total invested amount in minor units.
</ResponseField>

<ResponseField name="total_return" type="number">
  The total accrued or unrealized return in minor units. `null` when valuation is unavailable.
</ResponseField>

<ResponseField name="current_value" type="number">
  The invested amount plus the return in minor units. `null` when valuation is unavailable.
</ResponseField>

<Note>
  Valuation fields are `null` for a currency when any included holding lacks a valid valuation, rather than being reported as zero.
</Note>

***

## Retrieve capital transactions

`GET /capital-transactions`

Lists the immutable capital transaction records belonging to the authenticated entity for a single capital account. Transaction metadata is redacted from the entity's view.

### Query parameters

<ParamField query="capital_id" type="string" required>
  The ULID of the capital account that owns the transactions.
</ParamField>

<ParamField query="entity_id" type="string">
  Defaults to the authenticating entity when omitted. Required when acting on a child entity. See [Managing child entities](/core-concepts/entities#managing-child-entities) for details.
</ParamField>

<ParamField query="limit" type="number">
  Page size. Between `1` and `100`. Defaults to `25`.
</ParamField>

<ParamField query="cursor" type="string">
  Next-page cursor.
</ParamField>

<ParamField query="prev_cursor" type="string">
  Previous-page cursor. Mutually exclusive with `cursor`.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.nuvion.dev/capital-transactions?capital_id=01HXYZ0089ABCDEFGHJKMNPQRS&limit=25" \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```json 200 OK theme={null}
  {
    "status": "success",
    "message": "Capital transactions retrieved successfully",
    "data": {
      "data": [
        {
          "id": "01HXYZ0107ABCDEFGHJKMNPQRS",
          "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
          "event_type": "DAILY_ACCRUAL",
          "amount": 24657,
          "accrual_date": 1787184000000,
          "created": 1787184032118,
          "funded_amount": null,
          "placement_fee_charged": null,
          "vehicle_expense_charged": null
        },
        {
          "id": "01HXYZ0106ABCDEFGHJKMNPQRS",
          "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
          "event_type": "PURCHASE",
          "amount": 50000000,
          "accrual_date": null,
          "created": 1787097640000,
          "funded_amount": null,
          "placement_fee_charged": null,
          "vehicle_expense_charged": null
        }
      ],
      "meta": {
        "pagination": {
          "order": "desc",
          "has_next": false,
          "limit": 25,
          "has_previous": false,
          "next_cursor": null,
          "previous_cursor": null
        },
        "filters_applied": {
          "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
          "capital_account_id": "01HXYZ0089ABCDEFGHJKMNPQRS",
          "sort": {
            "field": "created",
            "order": "desc"
          }
        }
      }
    }
  }
  ```
</CodeGroup>

***

## Retrieve a capital transaction

`GET /capital-transactions/{id}`

Retrieves a capital transaction. Transaction metadata is redacted from the entity's view.

### Path parameters

<ParamField path="id" type="string" required>
  The ULID of the capital transaction.
</ParamField>

### Query parameters

<ParamField query="entity_id" type="string">
  Defaults to the authenticating entity when omitted. Required when acting on a child entity. See [Managing child entities](/core-concepts/entities#managing-child-entities) for details.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.nuvion.dev/capital-transactions/01HXYZ0106ABCDEFGHJKMNPQRS \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```json 200 OK theme={null}
  {
    "status": "success",
    "message": "Capital transaction retrieved successfully",
    "data": {
      "id": "01HXYZ0106ABCDEFGHJKMNPQRS",
      "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
      "event_type": "PURCHASE",
      "amount": 50000000,
      "accrual_date": null,
      "created": 1787097640000,
      "funded_amount": null,
      "placement_fee_charged": null,
      "vehicle_expense_charged": null
    }
  }
  ```
</CodeGroup>

***

## Error Response

* Validation errors: triggered if the payload or query parameters do not meet the endpoint specification
* State errors: triggered where the order or capital account is in a state that does not permit the requested action
* Transfer errors: triggered where the funding wallet cannot be debited, or a debit is already being reconciled

| Type | HTTP | Description |
| - | - | - |
| `error_operation_invalid_for_state` | 400 | Terminal or invalid order or account transition |
| `error_transfer_insufficient_funds` | 400 | The funding wallet does not hold enough funds for the debit |
| `error_auth_permission_denied` | 403 | The authenticated entity is not permitted to perform the action |
| `error_resource_not_found` | 404 | The product, order, capital account, or transaction could not be found |
| `error_concurrent_modification_detected` | 409 | A concurrent reservation or confirmation claim was lost |
| `error_transfer_already_processing` | 409 | Transfer recovery or reconciliation is pending. No additional debit is attempted |
| `error_resource_expired` | 410 | The reservation expired before it was confirmed |
| `error_validation_error` | 422 | One or more fields failed validation |
| `error_system_internal_error` | 500 | Malformed live product configuration or an invalid capital account valuation |
| `error_system_dependency_unavailable` | 503 | A required ledger mapping, AUM account, fee account, or payout account is missing |

<CodeGroup>
  ```json 400 Bad request theme={null}
  {
    "status": "error",
    "message": "This capital order can no longer be confirmed.",
    "type": "error_operation_invalid_for_state"
  }
  ```

  ```json 400 Insufficient funds theme={null}
  {
    "status": "error",
    "message": "The funding account does not have enough funds to complete this transfer.",
    "type": "error_transfer_insufficient_funds"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "status": "error",
    "message": "We couldn't authenticate this request. Please check your credentials and try again.",
    "type": "error_auth_credentials_invalid"
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "status": "error",
    "message": "You do not have permission to perform this action.",
    "type": "error_auth_permission_denied"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "status": "error",
    "message": "We couldn't find that {resource}. It may have been deleted or the ID might be incorrect.",
    "type": "error_resource_not_found"
  }
  ```

  ```json 409 Conflict theme={null}
  {
    "status": "error",
    "message": "This order is already being processed. Please check back shortly before retrying.",
    "type": "error_transfer_already_processing"
  }
  ```

  ```json 410 Gone theme={null}
  {
    "status": "error",
    "message": "This reservation has expired. Please create a new order.",
    "type": "error_resource_expired"
  }
  ```

  ```json 422 Unprocessed content theme={null}
  {
    "status": "error",
    "message": "Validation failed for one or more fields",
    "type": "error_validation_error",
    "validations": [
      {
        "fieldName": "principal",
        "type": "error_validation_value_out_of_range",
        "message": "The value for 'principal' should be between 10000000 and 500000000."
      },
      {
        "fieldName": "lock_investment",
        "type": "error_validation_required_field_missing",
        "message": "The field 'lock_investment' is required for FIXED_RETURN orders."
      }
    ]
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "status": "error",
    "message": "We couldn't complete this request due to an internal processing failure. Please try again.",
    "type": "error_system_internal_error"
  }
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.