Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.switchyard.run/llms.txt

Use this file to discover all available pages before exploring further.

​
Placing Orders

This guide covers how orders are created and managed in Switchyard, including manual order creation for testing.

​
Order Sources

Orders can enter Switchyard from multiple sources:
SourceDescription
Goods Mobile AppPrimary source - customers place orders via API
Test OrdersManual creation for testing fulfillment flow
Draft OrdersAdmin-created orders via Switchyard dashboard

​
Creating Test Orders

For testing the fulfillment flow without using the mobile app, you can create test orders directly from the Admin API.

​
Via API

POST /admin/test-orders
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "items": [
    {
      "variant_id": "variant_01ABC123",
      "quantity": 2
    },
    {
      "variant_id": "variant_02XYZ456",
      "quantity": 1
    }
  ],
  "shipping_address": {
    "first_name": "Test",
    "last_name": "Customer",
    "address_1": "123 Test Street",
    "city": "Austin",
    "postal_code": "78701"
  },
  "notes": "Testing sweep fulfillment"
}
Response: 
{
  "success": true,
  "message": "Test order created successfully",
  "order": {
    "id": "order_01ABC123",
    "display_id": 1234,
    "status": "pending",
    "items": [
      {
        "id": "item_01",
        "title": "Organic Bananas",
        "quantity": 2,
        "variant_sku": "BAN-ORG-1LB"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z"
  }
}

​
Request Parameters

FieldTypeRequiredDescription
itemsarrayYesArray of items to include
items[].variant_idstringYesProduct variant ID
items[].quantitynumberYesQuantity to order
customer_idstringNoExisting customer ID (creates test customer if omitted)
shipping_addressobjectNoDelivery address (uses default if omitted)
notesstringNoInternal notes about the test

​
Listing Test Orders

GET /admin/test-orders?limit=20&offset=0
Authorization: Bearer YOUR_TOKEN
Returns only orders marked as test orders.

​
Using Draft Orders

Switchyard’s built-in draft order system provides a full-featured way to create orders:
  1. Go to Orders → Draft Orders in the admin dashboard
  2. Click Create Draft Order
  3. Add customer, items, and shipping details
  4. Complete the draft to create the order
Draft orders go through the complete order flow and are useful for testing end-to-end.

​
Order Flow After Creation

Once an order is created (from any source), it follows the standard fulfillment flow:
  1. Pending - Order received, awaiting processing
  2. Processing - System analyzing sourcing (RFC vs sweep)
  3. Sweep/Picking - Items being sourced
  4. Staged - Order assembled in tote
  5. Delivering - Robot en route
  6. Delivered - Complete
See Order Flow for detailed documentation.

​
Testing Scenarios

Common scenarios to test:

​
RFC-Only Order

Create an order with items that are in RFC stock: 
{
  "items": [
    { "variant_id": "rfc_stocked_item", "quantity": 1 }
  ],
  "notes": "Testing RFC-only fulfillment"
}

​
Sweep Order

Create an order with items that require retailer sourcing: 
{
  "items": [
    { "variant_id": "sweep_only_item", "quantity": 1 }
  ],
  "notes": "Testing sweep fulfillment"
}

​
Hybrid Order

Create an order with both RFC and sweep items: 
{
  "items": [
    { "variant_id": "rfc_item", "quantity": 1 },
    { "variant_id": "sweep_item", "quantity": 1 }
  ],
  "notes": "Testing hybrid fulfillment"
}

​
Cleanup

Test orders are marked with is_test_order: true in metadata and can be filtered/deleted separately from production orders.