Create Order

Creating an Order

This guide explains how to create an Order in the Optimize Everything API system.

📚 Full API Documentation: For all endpoints, see https://api.opteverything.com/docs

Prerequisites

• You have created a contract (see Contract Creation Guide)
• You have your authentication token
• You have a value function ID
• You have a payment method nonce from your payment gateway

Step 1: Create a Ride Order

This endpoint allows riders to create a new ride order by specifying a contract, value function, and payment details.

Endpoint

POST /rider/ride-orders

Description

• When the order is created the maximum possible price (max of the contract’s value-function range) is authorised on the rider’s payment method. No funds move yet; the hold guarantees the rider can pay.
• Operators (or Market Makers) can then place bids. Each bid has its own authorisation hold.
• When the trip result is generated the final payable amount (value function applied to trip result) is captured and any remaining hold is released.

Create a new ride order by providing contract_id, value_function_id, minimum_price, bidding_end_time, and payment_method_nonce.

Required Information

Name	Type	Required	Description	Default
contract_id	UUID	Yes	ID of the contract this order is based on	—
value_function_id	integer	Yes	ID of the value function to use for pricing	—
minimum_price	float	Yes	Minimum acceptable price for the ride	—
bidding_end_time	datetime	Yes	Deadline for operators to submit bids (must be in the future)	—
payment_method_nonce	string	Yes	Payment method token from payment gateway	—

Example Request

curl -X POST "https://api.opteverything.com/rider/ride-orders" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -d '{
    "contract_id": "550e8400-e29b-41d4-a716-446655440000",
    "value_function_id": 1,
    "minimum_price": 25.00,
    "bidding_end_time": "2024-06-01T18:00:00Z",
    "payment_method_nonce": "fake-valid-nonce"
  }'

Responses

Success (200 OK)

Status Code: 200 OK

{
  "order_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "contract_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "minimum_price": 0,
  "status": "Pending"
}

Field	Type	Description
order_id	string	Unique identifier of the newly created order
contract_id	string	ID of the contract this order is based on
minimum_price	integer	Minimum acceptable price for the ride
status	string	Current status of the order

Error (400 Bad Request)

Status Code: 400 Bad Request

{
  "success": false,
  "error_code": "INVALID_CONTRACT_ID",
  "message": "The contract_id provided does not exist"
}

Field	Type	Description
success	boolean	Always false on error
error_code	string	Machine-readable error identifier
message	string	Human-readable error explanation

Order Details

Order Status

• PENDING: Order is waiting for bids
• ACTIVE: Order has been assigned and is in progress
• COMPLETED: Order has been completed
• CANCELLED: Order has been cancelled

Order Information

• contract_type: Type of contract (e.g., RideShare, Delivery)
• minimum_price: Minimum acceptable price for the order
• bidding_end_time: Deadline for accepting bids
• operator_contract_id: ID of the operator contract if assigned
• deviation_km: Allowed deviation from route in kilometers

Validation Rules

Bidding End Time

• Must be in the future (timezone-aware)
• If timezone is not specified, UTC is assumed
• Cannot be in the past

Minimum Price

• Must be a positive number
• Represents the minimum acceptable bid amount

Next Steps

Continue to the next guide: Bid Creation

Or see the full API documentation.