Create Order

Create a single order synchronously, or submit a batch of 1-300 orders for asynchronous processing.

Burq API V2 (Alpha)
Base URL: https://api.burqup.com/v2

---

Overview

Burq offers two ways to create orders. They accept the same order schema — the difference is how the response is delivered.

	POST /v2/orders	POST /v2/orders/create
Operation ID	CreateOrdersV2	CreateBatchOrdersV2
API reference	Create Orders V2	Create Batch Orders V2
Processing	Synchronous	Asynchronous (batch)
Orders per request	1	1-300
Response	201 Created with the full order object	202 Accepted with a batch_id
How you get order IDs	In the response body, immediately	Via webhook when the batch finishes
Route creation	Manual — Step 2: Create Route	Manual - Step 2: Create Route, or automatic with auto_route: true
Batch settings (auto-route, auto-quote, auto-dispatch, vehicle recommendation)	Not supported	Supported. Possibility to create and dispatch with a single API call. See Create and dispatch orders
Best for	Order-by-order flows where you need the order ID right away and no possibility of working with webhooks	High-volume flows where many orders are created at once

If you want a synchronous flow, use POST /v2/orders. It returns the created order in the response, so no webhook handling is required.

Optional: You can enable automatic route creation by setting batch_settings.routing.auto_route: true. When enabled, routes are automatically created from your orders, allowing you to skip Step 2.

This is Step 1 of 5 in the complete delivery flow:

1. Create Orders ← You are here
2. Create Route - Group orders into a multi-stop delivery route (Skip if auto_route: true)
3. Request Quote - Request pricing quotes from available providers
4. Pick Provider - Retrieve and select a provider quote
5. Dispatch - Dispatch the route with the selected provider

---

Prerequisites

Before creating orders, ensure you have:

• A valid Burq API key (see Authentication)
• Pickup and dropoff addresses ready for all orders
• Order details (items, values, etc.) for all orders
• For batch requests: all orders must share the same pickup address
• For batch requestsa webhook subscription configured on your account, so you receive the resulting order IDs

---

Request

Headers

Both endpoints use the same headers.

Header	Value	Required
Content-Type	application/json	Yes
x-api-key	Your API key	Yes

Request Body

The request body contains an orders array with 1-500 order objects. Each order follows the same schema as the single order creation endpoint.

Order Object

Both endpoints accept the same order schema. POST /v2/orders takes a single order object as the request body; POST /v2/orders/create takes an array of them under orders.

Batch Request Body Structure:

• orders (array, required) - Array of 1-300 order objects

Each Order Object Required Fields:

• pickup.address - Address for the pickup location
• pickup.name - Individual or company name of pickup location
• pickup.phone_number - Phone number for driver to contact at pickup
• dropoff.address - Address of dropoff location
• dropoff.name - Individual or company name receiving the order
• dropoff.phone_number - Phone number of dropoff location
• items - List of items to be delivered (array)
  • name - Description of the item
  • quantity - Quantity of the item

Each Order Object Optional Fields:

• external_order_ref - Your external reference identifier
• order_value - Total value of all items in the order (in cents)
• pickup.at - Timestamp for when items should be picked up (ISO8601 format)
• dropoff.at - Timestamp for when items should be delivered (ISO8601 format)
• tip - Tips for the driver
• request_contactless - Whether delivery should be contactless
• request_signature - Whether signature should be collected at dropoff

Request Body Optional Fields:

• webhook_url - HTTPS URL for receiving webhook notifications about batch processing status
• batch_settings - Batch processing settings, including automatic route creation

Batch Settings (batch_settings):

The batch_settings object allows you to configure automatic route creation and routing constraints:

• routing (object) - Routing configuration
  • auto_route (boolean) - If true, automatically creates routes from orders. When enabled, you can skip Step 2: Create Route
  • max_order_value (integer) - Maximum total order value per route. Routes will not be created if the combined order value exceeds this amount
  • max_number_of_orders_per_route (integer) - Maximum number of orders per route. Routes will not be created with more orders than this limit
  • max_route_duration (integer) - Maximum route duration in seconds. Routes will not be created if the estimated duration exceeds this value
  • max_delivery_radius (integer) - Maximum delivery radius in miles/kilometers. Routes will not be created if the delivery radius exceeds this distance

Option 1: Create a Single Order (Synchronous)

Endpoint: POST /v2/orders
Operation ID: CreateOrdersV2
API Reference: Create Orders V2

Example Request

Bash

curl -X POST "https://api.burqup.com/v2/orders" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "external_order_ref": "ORDER-001",
  "order_value": 5000,
  "pickup": {
    "address": "123 Main St, New York, NY 10001",
    "name": "Burq Store",
    "phone_number": "[phone]"
  },
  "dropoff": {
    "address": "456 Oak Ave, New York, NY 10002",
    "name": "John Doe",
    "phone_number": "[phone]"
  },
  "items": [
    {
      "name": "Pizza",
      "quantity": 2,
      "unit_price": 100,
      "length": 100,
      "width": 90,
      "height": 80,
      "weight": 200
    }
  ]
}'

---

Response

Success Response (201 Created)

JSON

{
    "id": "o_01kzdnk8tsegc8men1qgdnp123",
    "object": "order",
    "test_mode": true,
    "account_id": "16lk5kkwl9fq1234",
    "platform_account_id": "acct_16lk5kkwl9f12345",
    "pickup": {
        "address": "1-23 Main St, Queens, NY 10001, USA",
        "latitude": 40.762363,
        "longitude": -73.8313912,
        "unit": null,
        "phone_number": "1234567890",
        "name": "Burq Store",
        "contact_email": null,
        "notes": null,
        "store_id": null,
        "at": null,
        "window": null
    },
    "dropoff": {
        "address": "456 Oak Ave, Staten Island, NY 10306, USA",
        "latitude": 40.5604549,
        "longitude": -74.1158896,
        "unit": null,
        "phone_number": "1987654321",
        "name": "John Doe",
        "contact_email": null,
        "notes": null,
        "store_id": null,
        "at": null,
        "window": null
    },
    "external_order_ref": "ORDER-001",
    "external_route_ref": null,
    "external_stop_seq": null,
    "order_value": 5000,
    "tip_amount": 0,
    "created_at": "2026-08-07T08:31:52.665Z",
    "updated_at": "2026-08-07T08:31:52.665Z",
    "order_token": "token",
    "checkout_url": "https://website-checkout.burqup.com?order_token=token",
    "items": [
        {
            "name": "Pizza",
            "quantity": 2,
            "unit_price": 100,
            "description": null,
            "barcode": null,
            "dimensions": {
                "length": 100,
                "width": 90,
                "height": 80,
                "weight": 200,
                "dimension_unit": null,
                "weight_unit": null
            }
        }
    ],
    "dimensions": null,
    "contains_alcohol": false,
    "contactless_requested": false,
    "tsa_certified_driver_requested": false,
    "signature_requested": false,
    "barcode_scan_requested_at_pickup": false,
    "barcode_scan_requested_at_dropoff": false,
    "require_dropoff_photo": false,
    "additional_services": null,
    "vehicle": null,
    "latest_delivery": null,
    "route": null
}

Important:

• The order id is available immediately — store it and move straight to Step 2: Create Route.
• This endpoint does not accept batch_settings, so routes are never created automatically.

---

Option 2: Create Orders in Batch (Asynchronous)

Endpoint: POST /v2/orders/create
Operation ID: CreateBatchOrdersV2
API Reference: Create Batch Orders V2

This endpoint accepts 1-300 orders and queues them for processing. It responds right away with a batch_id; the orders themselves are created in the background, and the resulting order IDs arrive through the webhook configured on your account.

Bash

curl -X POST "https://api.burqup.com/v2/orders/create" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "orders": [
      {
        "external_order_ref": "ORDER-001",
        "order_value": 5000,
        "pickup": {
          "address": "123 Main St, New York, NY 10001",
          "name": "Burq Store",
          "phone_number": "[phone]",
          "at": "2024-01-15T12:00:00Z"
        },
        "dropoff": {
          "address": "456 Oak Ave, New York, NY 10002",
          "name": "John Doe",
          "phone_number": "[phone]",
          "at": "2024-01-15T14:00:00Z"
        },
        "items": [
          {
            "name": "Pizza",
            "quantity": 2,
            "unit_price": 100,
            "length": 100,
            "width": 90,
            "height": 80,
            "weight": 200
          }
        ]
      },
      {
        "external_order_ref": "ORDER-002",
        "order_value": 3000,
        "pickup": {
          "address": "123 Main St, New York, NY 10001",
          "name": "Burq Store",
          "phone_number": "[phone]",
          "at": "2024-01-15T12:00:00Z"
        },
        "dropoff": {
          "address": "789 Pine St, New York, NY 10003",
          "name": "Jane Smith",
          "phone_number": "[phone]",
          "at": "2024-01-15T14:00:00Z"
        },
        "items": [
          {
            "name": "Burger",
            "quantity": 1,
            "size": "medium"
          }
        ]
      }
    ],
    "webhook_url": "https://your-webhook-url.com/batch-status",
    "batch_settings": {
      "routing": {
        "auto_route": true,
        "max_order_value": 2400,
        "max_number_of_orders_per_route": 5,
        "max_route_duration": 28800,
        "max_delivery_radius": 30
      }
    }
  }'

Important:

• All orders in the batch must have the same pickup address to be grouped into a route
• If auto_route: true is set, routes will be automatically created and you can skip Step 2: Create Route

Response

Success Response (202 Accepted)

JSON

{
  "batch_id": "batch_abc123",
  "object": "batch",
  "status": "queued",
  "orders_count": 2,
  "created_at": "2024-01-15T10:00:00Z"
}

Important:

• This endpoint returns immediately with a batch_id
• Order creation happens asynchronously
• You'll receive a webhook notification when orders are created (if webhook_url is provided)
• Order IDs will be included in the webhook payload or can be retrieved using the batch ID

Response Fields

Field	Type	Description
batch_id	string	Unique batch identifier - Use this to track batch status
object	string	Always "batch"
status	string	Batch status (initial status is "queued")
orders_count	integer	Number of orders in the batch
created_at	string	Timestamp when the batch was created (ISO8601 format)

Getting Order IDs and Route IDs

Batch order creation is asynchronous, so the order IDs (and route IDs, if auto_route is enabled) are delivered through the webhook subscription configured on your Burq account. There is no webhook_url field on the request — Burq sends the events to the webhook endpoint registered for your account, so make sure one is configured and subscribed to the batch.* events before submitting a batch.

Batch Webhook Events

Event	When it fires
batch.order_creation_started	Batch processing has begun
batch.order_creation_complete	All orders were processed; payload includes the created order IDs
batch.order_creation_failed	Every order in the batch failed
batch.route_creation_started	Route creation has begun (only when auto_route: true)
batch.route_creation_complete	Routes were created; payload includes the route IDs
batch.route_creation_failed	Route creation failed

---

Example batch.order_creation_complete Payload

JSON

{
  "object": "event",
  "type": "batch.order_creation_complete",
  "data": {
    "batch_id": "batch_abc123",
    "object": "batch_status",
    "status": "completed",
    "metrics": {
      "submitted": 2,
      "created": 2,
      "failed": 0
    },
    "order_ids": ["ord_abc123", "ord_def456"]
  }
}

Batch Size Limits

• Minimum: 1 order per batch
• Maximum: 300 orders per batch

For routes with more than 300 orders, create multiple batches and combine the order IDs from all batches when creating the route.

---

Error Handling

Common errors when creating batch orders:

• invalid_orders_count - The orders array must contain between 1 and 500 orders
• invalid_webhook_url - The webhook_url must be a valid URL
• webhook_url_not_https - The webhook_url must use HTTPS protocol
• Missing required fields - Ensure all required fields are provided for each order
• Invalid addresses - Verify pickup and dropoff addresses are valid
• Invalid item size - Use one of: small, medium, large, xlarge
• Authentication errors - Verify your API key is correct

See Error Handling for detailed error information.

---

Best Practices

1. Use external_order_ref - Track orders in your system with your own reference
2. Same pickup address - Ensure all orders in a batch share the same pickup address
3. Configure webhooks - Use webhook_url to receive order IDs automatically when batch processing completes
4. Use auto_route - Enable auto_route: true to automatically create routes and skip manual route creation
5. Set routing constraints - Configure max_order_value, max_number_of_orders_per_route, max_route_duration, and max_delivery_radius to control route grouping
6. Accurate item sizes - Correct sizes help with pricing and provider matching
7. Set pickup/dropoff times - Provide realistic timing for better route optimization
8. Batch size - Create batches of reasonable size (e.g., 10-100 orders) for better processing efficiency
9. Save order IDs - Store order IDs from webhook notifications (needed if not using auto_route)
10. Handle async processing - Account for the asynchronous nature of batch processing in your workflow

---

Next Step

Once you have created a batch of orders:

If auto_route: true is enabled (default option if missing):

• Routes are automatically created during batch processing
• You can skip Step 2: Create Route
• Proceed directly to Step 3: Request Quote using the route IDs from your webhook notification

If auto_route: false:

• You need to manually create routes
• Ensure you have:
  1. Received the order IDs (via webhook or polling)
  2. Verified all orders share the same pickup address
• Proceed to:

Step 2: Create Route - Group your orders into a multi-stop delivery route

Note: If not using auto_route, you must have the order IDs before proceeding to Step 2. Ensure your webhook handler is ready or implement polling to retrieve order IDs after batch processing completes.

---

Related Documentation

• Authentication - Learn how to authenticate API requests
• Error Handling - Error codes and handling
• Create and dispatch orders with a single API call

---

← Back to Main Documentation | Next: Create Route →