Create an Order

BETA — SUBJECT TO CHANGE. This API is in beta and may change without notice.

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. 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)

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.
`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, 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.

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.

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.
`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.

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. An order the exchange rejects asynchronously after submission is returned as REJECTED, not as a phantom accepted order.

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. This order buys 100 shares at a limit price of $0.45 and must fill immediately in full or cancel.

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.

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 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. 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.

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.

Start Here

Partner Types & Eligibility

Get Connected

Onboard Participants

Funding & Transfers

Submitting Orders

Monitor & Reconcile

Service definition

Request

CreateVendorOrderRequest

Response

CreateVendorOrderResponse

FundingCorrelation

VendorOrderStatus

Funding request lifecycle

Supported order examples

Consumer cash order: spend $20

Buying power and previews

Idempotency and retries

Cancelling an order

Errors

​Service definition

​Request

​CreateVendorOrderRequest

​Response

​CreateVendorOrderResponse

​FundingCorrelation

​VendorOrderStatus

​Funding request lifecycle

​Supported order examples

​Consumer FOK share limit order

​Consumer cash order: spend $20

​Buying power and previews

​Idempotency and retries

​Cancelling an order

​Errors

Service definition

Request

CreateVendorOrderRequest

Response

CreateVendorOrderResponse

FundingCorrelation

VendorOrderStatus

Funding request lifecycle

Supported order examples

Consumer FOK share limit order

Consumer cash order: spend $20

Buying power and previews

Idempotency and retries

Cancelling an order

Errors