Creating Orders - Carpool Logistics

Endpoint

POST /api/orders

You may also pass quote_id as a query parameter (for example, POST /api/orders?quote_id=...) instead of in the JSON body.

Customer Identification

Every order must identify who will be billed. Your API token is tied to a parent account (the API consumer). You can bill that account directly, or bill an external party — a child customer under your account, such as a dealer or auction you manage.

Provide exactly one of the three mutually exclusive options below.

Choosing the right field

Scenario	Field to use	Who is billed
You (the API consumer) will be billed	provider_id	Your parent account
An external party already exists under your account	customer_id	The external party
Create an external party and order in one request	customer	The external party

Field reference

Field	Type	Description
provider_id	string	Use only for self-billing. Pass the `provider_id` on your parent account — the account tied to your API token. The order will be billed to you, not to an external party.
customer_id	string	Use when an external party will be billed. Pass the `id` (slug) returned from `POST /api/customers` or from a previous order response. Do not use this field to bill your own account — use top-level `provider_id` instead. See Creating Customers.
customer	object	Use when an external party will be billed and you want to create (or find) that party and the order in a single request. Creates a child customer under your account if one with the given `customer.provider_id` does not already exist; otherwise reuses the existing record.

Important: These fields are mutually exclusive. You must provide exactly one — including multiple will result in a validation error.

Two different provider_id fields: The top-level provider_id on the order request identifies your parent account for self-billing. The nested customer.provider_id inside the inline customer object is your external identifier for a third-party customer that will be billed. These serve different purposes and must not be confused.

Inline customer object fields

When using the customer object to bill an external party, the following fields are required:

Field	Type	Notes
name	string	Required.
provider_id	string	Required. Your external identifier for this external party. Not the same as the top-level `provider_id` used for self-billing.
address	string	Required.
address_2	string	Optional.
city	string	Required.
state	string	Required. 2 characters.
postal_code	string	Required. 5-10 digits.
contact_firstname	string	Required.
contact_lastname	string	Required.
phone_number	string	Required. US/CA/PR phone.
email	string	Required. Valid email.
type	string	Required. See customer types.
send_welcome_email	boolean	Optional. Defaults to `true`. Set to `false` to prevent the welcome email when a new customer is created for this order. Ignored when an existing customer is reused (no welcome email is sent in that case). Availability is being rolled out per account; until enabled for your account the welcome email is always sent.

Order Fields

In addition to customer identification, origin, destination, and vehicles:

Field	Type	Notes
first_available_date	string	Optional. Date format `Y-m-d`.
quote_id	string	Optional. Quote nano_id. See Orders with a Quote.
price_option	string	Required when `quote_id` is set. One of: economy, expedited, enclosed, market.
external_id	string	Optional. Max 64 characters. Requires a provider on your account. Must be unique per provider.

Location Fields

Both origin and destination are required objects with the same structure:

Field	Type	Notes
type	string	Required. Enum: auction, body_shop, business, repo, dealer, residence, rental, storage, tow, other, imported, carrier.
name	string	Required.
address	string	Required. Must differ between origin and destination.
city	string	Required.
state	string	Required. 2 characters.
postal_code	string	Required. 5-10 digits.
contact_name	string	Required.
contact_phone	string	Required. US/CA/PR phone.
contact_email	string	Optional.
external_notes	string	Optional. Max 255 characters.

Vehicle Fields

At least one vehicle is required. A maximum of 36 vehicles can be submitted per order.

Field	Type	Notes
vehicle_type	string	Required. Enum: car, motorcycle, van, suv, truck, oversized, other.
year	integer	Required. 4 digits (1900 to current year + 1).
make	string	Required.
model	string	Required.
vin	string	Required. Exactly 17 characters. Must be unique per request.
color	string	Optional. Enum: blue, maroon, yellow, silver, purple, orange, green, gray, pink, tan, brown, black, red, gold, beige, white.
value	numeric	Optional. 0 - 999,999.99.
operable	boolean	Optional.
oversized	boolean	Optional.
gate_pass	URL	Optional. See Orders with Gate Pass.
gate_pass_base64	string	Optional. Mutually exclusive with `gate_pass`.
external_id	string	Optional. Max 64 characters. Requires a provider on your account. Must be unique per provider.

Examples

Using customer_id (bill an external party)

Bill an external party you previously created via POST /api/customers or via the inline customer object. Use the id from the customer creation or order response.

{
  "customer_id": "a1b2c3d4e5f6",
  "first_available_date": "2026-03-01",
  "origin": {
    "type": "dealer",
    "name": "Acme Auto Sales",
    "address": "123 Main Street",
    "city": "Atlanta",
    "state": "GA",
    "postal_code": "30301",
    "contact_name": "John Doe",
    "contact_phone": "+14045551234"
  },
  "destination": {
    "type": "residence",
    "name": "Jane Smith",
    "address": "456 Oak Avenue",
    "city": "Miami",
    "state": "FL",
    "postal_code": "33101",
    "contact_name": "Jane Smith",
    "contact_phone": "+13055559876"
  },
  "vehicles": [
    {
      "vehicle_type": "car",
      "year": 2024,
      "make": "Honda",
      "model": "Accord",
      "vin": "1HGBH41JXMN109186",
      "color": "black",
      "operable": true
    }
  ]
}

Using provider_id (bill yourself)

Bill your own parent account. Pass the provider_id assigned to your account — not an external party's identifier.

{
  "provider_id": "YOUR-ACCOUNT-PROVIDER-ID",
  "first_available_date": "2026-03-01",
  "origin": { ... },
  "destination": { ... },
  "vehicles": [ ... ]
}

Using inline customer object (bill an external party)

Bill an external party and create (or find) that customer in a single request. If a child customer with the given customer.provider_id already exists under your account, it will be reused. Otherwise, a new child customer is created and billed.

{
  "customer": {
    "name": "Acme Auto Sales",
    "provider_id": "YOUR-EXTERNAL-ID-123",
    "address": "123 Main Street",
    "city": "Atlanta",
    "state": "GA",
    "postal_code": "30301",
    "contact_firstname": "John",
    "contact_lastname": "Doe",
    "phone_number": "+14045551234",
    "email": "john@acmeauto.com",
    "type": "independent_dealer",
    "send_welcome_email": false
  },
  "first_available_date": "2026-03-01",
  "origin": {
    "type": "dealer",
    "name": "Acme Auto Sales",
    "address": "123 Main Street",
    "city": "Atlanta",
    "state": "GA",
    "postal_code": "30301",
    "contact_name": "John Doe",
    "contact_phone": "+14045551234"
  },
  "destination": {
    "type": "residence",
    "name": "Jane Smith",
    "address": "456 Oak Avenue",
    "city": "Miami",
    "state": "FL",
    "postal_code": "33101",
    "contact_name": "Jane Smith",
    "contact_phone": "+13055559876"
  },
  "vehicles": [
    {
      "vehicle_type": "car",
      "year": 2024,
      "make": "Honda",
      "model": "Accord",
      "vin": "1HGBH41JXMN109186",
      "color": "black",
      "operable": true
    }
  ]
}

Response (201 Created)

All three methods return the same response structure:

{
  "status": true,
  "status_code": 201,
  "data": {
    "order_id": "f8e7d6c5b4a3",
    "customer_id": "a1b2c3d4e5f6",
    "status": "new",
    "created_at": "2026-02-08T12:00:00Z",
    "updated_at": "2026-02-08T12:00:00Z",
    "origin": {
      "id": "loc-123",
      "name": "Acme Auto Sales",
      "address": "123 Main Street",
      "city": "Atlanta",
      "state": "GA",
      "postal_code": "30301"
    },
    "destination": {
      "id": "loc-456",
      "name": "Jane Smith",
      "address": "456 Oak Avenue",
      "city": "Miami",
      "state": "FL",
      "postal_code": "33101"
    },
    "vehicles": [
      {
        "id": "veh-789",
        "status": "ordered",
        "year": 2024,
        "make": "Honda",
        "model": "Accord",
        "vin": "1HGBH41JXMN109186",
        "color": "black",
        "value": 25000.00,
        "operable": true,
        "oversized": false,
        "tracking_url": "https://...",
        "order_id": "f8e7d6c5b4a3",
        "customer_id": "a1b2c3d4e5f6",
        "origin": {
          "id": "loc-veh-origin",
          "name": "Vehicle Origin Yard",
          "address": "100 Origin St",
          "city": "Atlanta",
          "state": "GA",
          "postal_code": "30301"
        },
        "destination": {
          "id": "loc-veh-destination",
          "name": "Vehicle Destination Lot",
          "address": "200 Dest Ave",
          "city": "Savannah",
          "state": "GA",
          "postal_code": "31401"
        },
        "distance": 412,
        "order_date": "06/15/2026",
        "first_available_date": "06/14/2026",
        "due_date": "07/31/2026",
        "pickup_eta": "05/01/2026",
        "delivery_date": null,
        "estimated_delivery_date": "06/14/2026",
        "transport_fee": 250.5,
        "bill_to": "Acme Auto Sales",
        "load_id": 1001,
        "po_number": "PO-8841",
        "check_in_name": "Westlake"
      }
    ]
  }
}

Each vehicle uses this object. Origin and destination are the vehicle's own locations. Dates use month/day/year, and a missing date is null. estimated_delivery_date is always present. transport_fee is the quoted price. See Listing Vehicles to read these vehicles without requesting every order.

Other Order Endpoints

Method	Endpoint	Description
GET	/api/orders/{order_id}	Get order details by slug.
GET	/api/orders	List all orders (paginated). Each item includes `estimated_delivery_date` when available.
DELETE	/api/orders/{order_id}	Cancel an order.

Next Steps

→ Create an order with a quote to lock in pricing
→ Attach gate passes to vehicles
→ Set up webhooks to track order progress