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

# Create an Order

> Place an order with a declared vendor fee — recorded against the order and passed through to the exchange in one idempotent call.

<Warning>
  **BETA — SUBJECT TO CHANGE.** This API is in beta and may change without notice.
</Warning>

`CreateVendorOrder` is the partner order-entry call: it validates the supported structure of an embedded public `polymarket.v1.InsertOrderRequest`, **records your declared vendor fee against the order**, passes the order through to EP3, and waits for the exchange's durable outcome before returning.

No money moves in this call — the order trades against cash already in the participant's account, and the vendor fee [accrues for later collection](/partners/funding/vendor-fees). EP3 is authoritative for order economics and buying-power validation; `CreateVendorOrder` does not calculate or return order economics.

## Service definition

* **Service:** `polymarket.us.orderfunding.v1.OrderFundingService`
* **RPC:** `CreateVendorOrder`
* **Type:** Unary (request/response)

```protobuf theme={null}
service OrderFundingService {
  rpc CreateVendorOrder(CreateVendorOrderRequest)
      returns (CreateVendorOrderResponse);
}

message CreateVendorOrderRequest {
  polymarket.v1.InsertOrderRequest order = 1;
  MoneyAmount vendor_fee = 2;
  string idempotency_key = 3;
}
```

## Request

### CreateVendorOrderRequest

| Field             | Type                               | Required | Description                                                                                                                                                                                           |
| ----------------- | ---------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order`           | `polymarket.v1.InsertOrderRequest` | Yes      | The public order-entry shape. Set only the [supported fields](/partners/orders/data-model#supported-fields).                                                                                          |
| `vendor_fee`      | `MoneyAmount`                      | Yes      | Your fixed USD vendor fee for this order. It is recorded against the exchange order ID and collected later with a [`VENDOR_FEES` transfer](/partners/funding/vendor-fees), never moved at order time. |
| `idempotency_key` | `string`                           | Yes      | Your unique key for this placement request. Persist it before calling the service.                                                                                                                    |

The participant is identified **only by `order.account`**. Use the DCM trading account returned by the KYC approval webhook—the same account identifier used to match the participant's Drop Copy activity. There is no separate customer-account field in this request. Do not set `order.user` or `order.session_id`; both are rejected.

<Warning>
  The embedded public message is wider than the partner launch surface. The service uses a fail-closed allowlist: if you populate an unsupported field, the request is rejected with `INVALID_ARGUMENT` and an error that names the offending field. Do not copy a generic `InsertOrderRequest` wholesale; construct one of the supported shapes below.
</Warning>

## Response

### CreateVendorOrderResponse

| Field                | Type                 | Description                                                                                                                                                                                                                   |
| -------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `funding_request_id` | `string`             | Service-assigned durable identifier for this placement workflow. Persist it even if `id` is empty, and include it in support requests.                                                                                        |
| `id`                 | `string`             | Exchange order identifier, when EP3 assigned one. The vendor fee for an accepted order is recorded under this ID, which is also `order_id` on the [Vendor Fees report](/partners/funding/vendor-fees#the-vendor-fees-report). |
| `status`             | `VendorOrderStatus`  | Durable or current placement outcome. See below.                                                                                                                                                                              |
| `correlation`        | `FundingCorrelation` | Partner and service identifiers for recovery, audit, and support. Log these.                                                                                                                                                  |

### FundingCorrelation

| Field                | Type     | Description                                                                                              |
| -------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `idempotency_key`    | `string` | Your idempotency key from the request.                                                                   |
| `funding_request_id` | `string` | The same durable placement-workflow identifier as the top-level field. It remains stable across retries. |
| `request_id`         | `string` | Per-attempt service request identifier for support and audit. It changes on each retry.                  |
| `clord_id`           | `string` | Your `order.clord_id`, echoed for recovery and Drop Copy correlation.                                    |

### VendorOrderStatus

| Status                         | Meaning                                                                                                                                                                                                                                                                         |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VENDOR_ORDER_STATUS_ACCEPTED` | EP3 durably accepted the order — including an order that matched immediately or was cancelled under fill-or-kill. Acceptance does not mean the order is resting or filled; learn execution outcomes from Drop Copy. The vendor fee is recorded against the order. **Terminal.** |
| `VENDOR_ORDER_STATUS_REJECTED` | The order was rejected. Nothing was recorded and no fee accrues. **Terminal.**                                                                                                                                                                                                  |
| `VENDOR_ORDER_STATUS_PENDING`  | The service could not establish the durable exchange outcome before its deadline. No collectible vendor fee exists yet. **Durable, but not terminal.**                                                                                                                          |

<Info>
  **`ACCEPTED` means durable acceptance, not an execution state.** The service does not report acceptance based on submission alone, but an accepted order may have rested, matched immediately, or been cancelled under FOK. Track fills and other execution outcomes on [Drop Copy](/streaming-endpoints/dropcopy-stream). An order the exchange rejects asynchronously after submission is returned as `REJECTED`, not as a phantom accepted order.
</Info>

## Funding request lifecycle

Every successful `CreateVendorOrder` call returns a durable `funding_request_id` and the workflow's current `status`. `PENDING` is a valid durable response, not a gRPC error: submission may have happened, but the service has not yet established the final EP3 outcome.

When a response is `PENDING`, re-check it by calling `CreateVendorOrder` again with the **identical request**, including the same `idempotency_key` and `order.clord_id`. The service resumes the existing workflow and returns the same `funding_request_id` with its current status. Continue bounded re-checks until the status is terminal:

* `VENDOR_ORDER_STATUS_ACCEPTED` — terminal accepted outcome.
* `VENDOR_ORDER_STATUS_REJECTED` — terminal rejected outcome.

Do **not** rotate the idempotency key while a funding request is pending. A new key identifies a new placement workflow and can create a duplicate order. If you reuse the original key with any caller-controlled field changed, the service returns gRPC `ALREADY_EXISTS` instead of modifying the existing workflow.

Persist the `funding_request_id`, `idempotency_key`, and `clord_id` together. The funding request ID identifies the workflow even before an exchange order ID exists and is the primary identifier to quote in support requests.

## Supported order examples

These examples deliberately populate only the launch fields. They assume the instrument uses `price_scale = 2` and `fractional_quantity_scale = 2`; use each instrument's published scales when converting decimal prices and quantities to integers.

### Consumer FOK share limit order

This order buys 100 shares at a limit price of \$0.45 and must fill immediately in full or cancel.

```python theme={null}
import uuid
from polymarket.v1 import trading_pb2
from polymarket.us.orderfunding.v1 import order_funding_pb2

clord_id = f"order-{uuid.uuid4()}"
idempotency_key = str(uuid.uuid4())

request = order_funding_pb2.CreateVendorOrderRequest(
    order=trading_pb2.InsertOrderRequest(
        type=trading_pb2.ORDER_TYPE_LIMIT,
        side=trading_pb2.SIDE_BUY,
        order_qty=10_000,  # 100.00 shares at fractional_quantity_scale=2
        symbol="<market-symbol>",
        price=45,  # $0.45 at price_scale=2
        time_in_force=trading_pb2.TIME_IN_FORCE_FILL_OR_KILL,
        clord_id=clord_id,
        account="<participant-dcm-account>",
        manual_order_indicator=trading_pb2.MANUAL_ORDER_INDICATOR_MANUAL,
    ),
    vendor_fee=order_funding_pb2.MoneyAmount(value="0.10", currency="USD"),
    idempotency_key=idempotency_key,
)

response = stub.CreateVendorOrder(request, metadata=metadata)
```

### Consumer cash order: spend \$20

Set `cash_order_qty` instead of `order_qty` when the participant specifies a dollar amount. This order spends up to $20 at the same $0.45 limit.

```python theme={null}
request = order_funding_pb2.CreateVendorOrderRequest(
    order=trading_pb2.InsertOrderRequest(
        type=trading_pb2.ORDER_TYPE_LIMIT,
        side=trading_pb2.SIDE_BUY,
        cash_order_qty=2_000,  # $20.00 at price_scale=2; omit order_qty
        symbol="<market-symbol>",
        price=45,  # $0.45 at price_scale=2
        time_in_force=trading_pb2.TIME_IN_FORCE_FILL_OR_KILL,
        clord_id=f"order-{uuid.uuid4()}",
        account="<participant-dcm-account>",
        manual_order_indicator=trading_pb2.MANUAL_ORDER_INDICATOR_MANUAL,
    ),
    vendor_fee=order_funding_pb2.MoneyAmount(value="0.10", currency="USD"),
    idempotency_key=str(uuid.uuid4()),
)

response = stub.CreateVendorOrder(request, metadata=metadata)
```

## Buying power and previews

EP3 validates buying power when the order is placed and rejects an order unless the participant account's available cash covers its worst-case collateral plus the exchange fee. This authoritative placement check does not reserve accrued vendor fees. Before submission, you may provide client-side guidance by gating against:

```
spendable balance = account cash − accrued uncollected vendor fees
```

For a buy share limit order, client-side worst-case collateral is the share quantity multiplied by the limit price. For a cash order, `cash_order_qty` is the participant's requested maximum spend. Add the maximum exchange fee from the [fee schedule](/fees) when estimating required cash.

`CreateVendorOrder` does not calculate these amounts. You may calculate them in your client or separately call the public `polymarket.v1.OrderEntryAPI/PreviewOrder` with the participant's order shape. The preview is optional and informational, not a locked quote; EP3 validates the order again at placement.

## Idempotency and retries

The `idempotency_key` identifies one placement request for your authenticated firm, while `order.clord_id` is your standard FIX tag-11 client order ID and recovery key. Persist both **before** the first call. The service guarantees **at most one order per idempotency key — retrying with the same key can never place a duplicate order or double-charge the declared vendor fee.**

* **Retry transport failures and timeouts** with the same complete request and the **same `idempotency_key` and `clord_id`**. If the original attempt completed, the service returns its recorded result; otherwise it resumes or resolves the workflow.
* **Retry `PENDING`** the same way. The service re-checks the exchange outcome and returns the same funding request with its current status.
* **Match Drop Copy by account and `clord_id`.** `order.account` is the DCM account on Drop Copy, and the exchange echoes `order.clord_id` as `clOrdID`.
* **Never change the request under an existing key.** A different `clord_id`, account, order field, or vendor fee returns `ALREADY_EXISTS`.
* **Never rotate the key for a pending request.** A new key creates a new workflow and can submit a duplicate order.
* **Never reuse a `clord_id` across live orders for the same participant.** Use a fresh idempotency key and client order ID for each new order.

## Cancelling an order

An order placed through this service is a standard exchange order. Cancel it through the standard [order entry cancel](/institutional/trading/overview). Cancellation does not alter the recorded vendor fee: the platform records exactly what you declared at placement. If your fee policy waives fees on cancelled or unfilled orders, apply that policy in your books and in the amount you [collect](/partners/funding/vendor-fees#collecting-the-fees).

## Errors

| gRPC status           | Meaning                                                                                                                                                    | Retry guidance                                                                                |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `INVALID_ARGUMENT`    | A required field is missing; an order or vendor fee is malformed; or an unsupported embedded field is set. The error names an offending unsupported field. | Fix the request. Do not retry as-is.                                                          |
| `UNAUTHENTICATED`     | Missing or invalid access token.                                                                                                                           | Refresh the token and retry.                                                                  |
| `PERMISSION_DENIED`   | Your firm is disabled or the vendor-fee policy denies the request.                                                                                         | Do not retry unchanged until authorization or policy is corrected.                            |
| `NOT_FOUND`           | No customer relationship exists for your firm and `order.account`. The same generic error is returned if the account belongs to another firm.              | Correct `order.account`.                                                                      |
| `FAILED_PRECONDITION` | The customer relationship is inactive, ambiguous, stale, or draining.                                                                                      | Correct the relationship state, then retry according to whether the placement intent changed. |
| `ALREADY_EXISTS`      | The `idempotency_key` is already bound to a different caller-controlled request.                                                                           | Replay the original request, or use a fresh key only for a genuinely new placement intent.    |
| `UNAVAILABLE`         | Transient relationship, policy, persistence, token-minting, or exchange unavailability before a known submission outcome.                                  | Retry the identical request with the **same** `idempotency_key`.                              |

An EP3 order-level rejection, such as **insufficient buying power** or a price outside market limits, is not a gRPC error. The call returns `OK` with `status = VENDOR_ORDER_STATUS_REJECTED`; `FAILED_PRECONDITION` is reserved for relationship-state problems. Quote the `correlation` identifiers when requesting the underlying rejection detail from support.