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

# Bid into an offering

> Commit funds to an offering on behalf of a customer

Places a bid into an offering's book. The funds are held on **your organisation's wallet** —
in `offer_hold`, its own bucket, distinct from escrow — for the whole offer period, and either
buy units at allotment or are released back.

You are the counterparty, exactly as you are on a [buy](/docs/api-reference/endpoint/Trade/buy-token).
The `customer` object records which of your end users the bid was for; GetEquity never
provisions an account for that person, so reconciling the position to them remains yours.

<ParamField path="id" type="string" required>
  The id of the offering to bid into.
</ParamField>

<ParamField body="amount" type="number" required>
  The cash being committed. Held on the wallet until allotment.
</ParamField>

<ParamField body="bid_price" type="number">
  The highest price you will pay. Price-based offerings only. Mutually exclusive with `bid_rate`.
</ParamField>

<ParamField body="bid_rate" type="number">
  The lowest rate you will accept. Rate-based offerings — debt and fixed interest — only.
</ParamField>

<ParamField body="is_strike_bid" type="boolean">
  Bid at whatever the book settles at, naming no limit. Only where the offering allows it.
</ParamField>

<ParamField body="tranche" type="string">
  **Required on a combined offering, refused on every other type.** The tranche's `key`, from
  the order book. See below.
</ParamField>

<ParamField body="meta" type="object">
  Anything you want echoed back on the commitment.
</ParamField>

<ParamField body="customer" type="object">
  `name` and `email` of the end user this bid belongs to.
</ParamField>

<RequestExample>
  ```json Book build theme={null}
  {
    "amount": 5000000,
    "bid_price": 10.5,
    "customer": { "name": "Ada Lovelace", "email": "ada@example.com" }
  }
  ```

  ```json Combined offering theme={null}
  {
    "amount": 5000000,
    "bid_rate": 19,
    "tranche": "retail",
    "customer": { "name": "Ada Lovelace", "email": "ada@example.com" }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "message": "Commitment recorded. The funds are held until allotment.",
    "data": {
      "_id": "68f1c1a3e1b2c3d4e5f60615",
      "token": "68f1c2a4e1b2c3d4e5f60718",
      "amount": 5000000,
      "hold_amount": 5025000,
      "bid_rate": 19,
      "tranche": "retail",
      "status": "SUBMITTED"
    }
  }
  ```
</ResponseExample>

## Offerings that have tranches

Some offerings are split into separate books called **tranches** — a commercial paper issued as
retail and institutional slices, or as 90/180/270-day series. Each is priced and allotted against
its own size, so they can clear at different levels.

Read the offering's `tranches` from the
[order book](/docs/api-reference/endpoint/Trade/offering-book). If the array is present you **must**
send `tranche`; if it is absent you must **not**.

```json theme={null}
"tranches": [
  { "key": "retail",        "name": "Retail",        "size": 40000000, "min_commitment": 100000 },
  { "key": "institutional", "name": "Institutional", "size": 60000000, "min_commitment": 50000000 }
]
```

Send the `key`, not the name. A tranche may set its own ticket size and its own audience
(`investors`: `ANY`, `user` or `organisation`), and a bid outside either is refused. A bid cannot
move between tranches afterwards — withdraw it and place a fresh one.

## Price or rate?

Debt and fixed-interest offerings discover a **rate**; everything else discovers a **price**. Send
`bid_rate` on the former and `bid_price` on the latter — never both. Check the offering's
`investment_type` before deciding which.

## What a bid is checked against

The bounds come from the tranche where the offering has them, and from the offering otherwise.

| Refusal                                                       | Meaning                                                |
| ------------------------------------------------------------- | ------------------------------------------------------ |
| `OFFERING_NOT_OPEN_ERROR`                                     | The book is not open for bids.                         |
| `BID_BELOW_GUIDANCE_ERROR` / `BID_ABOVE_GUIDANCE_ERROR`       | Outside an enforced range.                             |
| `BID_OFF_TICK_ERROR`                                          | Not on the guidance step.                              |
| `BID_BEYOND_RESERVE_ERROR`                                    | Past the worst level the issuer will accept.           |
| `BID_LIMIT_REQUIRED_ERROR`                                    | No limit named, and strike bids are not allowed here.  |
| `STRIKE_BIDS_NOT_ALLOWED_ERROR`                               | This offering requires a limit on every bid.           |
| `WALLET_INSUFFICIENT_BALANCE_ERROR`                           | Not enough to cover the bid and its fee.               |
| `TRANCHE_REQUIRED_ERROR`                                      | Combined offering, no tranche named.                   |
| `OFFERING_HAS_NO_TRANCHES_ERROR`                              | Tranche named on a single-book offering.               |
| `TRANCHE_NOT_OPEN_ERROR`                                      | The tranche is restricted to the other kind of holder. |
| `BELOW_TRANCHE_MINIMUM_ERROR` / `ABOVE_TRANCHE_MAXIMUM_ERROR` | Outside the tranche's ticket size.                     |