Talk to an Expert
Create order - Grasshopper Labs API
DocsOrdersCreate order
Orders

Create order

Push a new order into Grasshopper for fulfillment. Returns the created order with its assigned order_id.

POST /api/orders/

Body parameters

ref_order_number
string Required
Your internal PO or reference number. Must be unique within your shipper scope.
service_level
string Required
Service level code. See Service levels.
wgrocparocprocthrcurbb2bblnkexpprcl
customer
object Required
Consignee details. Must include first_name, last_name, address.
customer.first_name
string Required
Customer's first name.
customer.last_name
string Required
Customer's last name.
customer.email
string Optional
Customer's email. Used for scheduling notifications.
customer.phone1
object Optional
Primary phone. Object with number and type.
customer.address
object Required
Address object: address1, address2, city, state, zip.
line_items
array Required
Array of items. Must have at least one line item.
line_items[].sku
string Required
Item SKU.
line_items[].name
string Required
Item description.
line_items[].quantity
integer Required
Quantity. Must be ≥ 1.
line_items[].weight
number Required
Item weight in pounds.
line_items[].cube
number Optional
Item volume in cubic feet.
line_items[].vendor
string Optional
Vendor / manufacturer name.
line_items[].freight_info
object Optional
Freight details (FOB flag, vendor info, pickup location).

Example

curl -X POST https://{licensee-url}/api/orders/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref_order_number": "PO-12345",
    "service_level": "wg",
    "customer": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone1": { "number": "5551234567", "type": 0 },
      "address": {
        "address1": "123 Main St",
        "city": "Austin",
        "state": "TX",
        "zip": "78701"
      }
    },
    "line_items": [{
      "sku": "SOFA-001",
      "name": "3-Seat Sofa",
      "quantity": 1,
      "weight": 150,
      "cube": 35,
      "vendor": "Acme Furniture"
    }]
  }'
const res = await fetch('https://{licensee-url}/api/orders/', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    ref_order_number: 'PO-12345',
    service_level: 'wg',
    customer: { /* ... */ },
    line_items: [{ /* ... */ }]
  })
});
const order = await res.json();
import requests

order = requests.post(
    'https://{licensee-url}/api/orders/',
    headers={'Authorization': f'Bearer {token}'},
    json={
        'ref_order_number': 'PO-12345',
        'service_level': 'wg',
        'customer': { # ... },
        'line_items': [{ # ... }]
    }
).json()
// HTTP 201 Created
{
  "order_id": "22200041771",
  "ref_order_number": "PO-12345",
  "status": 2,
  "service_level": "wg",
  "created_at": "2026-05-12T14:38:43.969Z",
  "customer": { /* ... */ },
  "line_items": [
    {
      "item_id": "22200041771-1",
      "sku": "SOFA-001",
      "status": 2
    }
  ]
}
Try it out
Response will appear here

Errors

Statuserror.codeCause
400missing_required_fieldA required field was omitted. See error.field.
422invalid_service_levelThe service_level code is not recognized.
422invalid_zipThe ZIP code is not in your coverage area.
409duplicate_ref_order_numberAn order with this ref_order_number already exists.
← Previous
List orders