Get up and running with the Grasshopper API

Before you begin

Grasshopper is a multi-tenant platform. Every carrier (licensee) runs on their own base URL, and your integration connects to their environment, not a shared Grasshopper endpoint. Throughout this guide, {{url}} means the base URL you are working against: https://staging.grasshopperlabs.io while testing, and the carrier's production URL, for example https://carrier-name.grasshopperlabs.io, at go-live.

Production credentials cannot be self-served. The carrier controls your production setup, so collect everything below before go-live.

What you can build

The Grasshopper Shipper Integration lets your system programmatically create and manage orders inside Grasshopper, with full lifecycle visibility from order creation through final delivery. Through a combination of REST APIs and event-driven webhooks, your system can:

• Create final-mile orders via Grasshopper's external APIs
• Track orders and individual line items across their full lifecycle
• Receive real-time updates via webhook events
• Retrieve POD, signatures, and delivery images once orders reach a terminal status

Who this guide is for

Six steps, in order

Every shipper integration follows the same path. Steps 1 and 2 happen inside the Grasshopper UI (carrier-side). Steps 3 through 6 are yours.

1Configure the Shipper in Grasshopper

Before any API integration begins, your company must be created and configured as a shipper inside the Grasshopper UI. This step is performed by the carrier within their Grasshopper environment. You cannot do it through the API; if it has not happened yet, this is the first thing to ask your carrier for.

Information the carrier needs from you

• Primary contact first and last name
• Primary contact email address
• Company name and company address
• Any additional shipper configuration fields required by the carrier's workflow

2Create an API User

Once your shipper exists in Grasshopper, a dedicated user is created under that shipper to handle API authentication. A valid user profile is required before any API access can begin. The credentials are:

• email: used as the username for token generation
• password: used as the secret for authentication

This user can also log in to the shipper UI, which is useful for validating credentials during testing and visually confirming that orders you create via the API actually landed.

3Authenticate

Authentication must be completed before any other API call. Exchange your API user credentials for an access token by sending them as application/x-www-form-urlencoded:

curl --location -g '{{url}}/api/rest/auth' \
  --data-urlencode 'user_name={{username}}' \
  --data-urlencode 'password={{password}}'

// Node.js 18+ (native fetch)
const res = await fetch(`${BASE_URL}/api/rest/auth`, {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({ user_name: USERNAME, password: PASSWORD })
});
const auth = await res.json();

import requests

res = requests.post(
    f"{BASE_URL}/api/rest/auth",
    data={"user_name": USERNAME, "password": PASSWORD},
)
auth = res.json()

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "def50200a1b2c3..."
}

Using the token

• Valid credentials: Grasshopper returns the tokens required for subsequent API requests.
• Invalid credentials: the request is rejected. Do not proceed; verify the username and password by logging in to the shipper UI.
• Token expiry: when a request returns 401 with a previously working token, refresh it via the Refresh token endpoint or re-authenticate, then retry the request.

Full schema and examples: Postman Authentication Docs · Authentication reference

4Create an Order

The Order Creation API creates new final-mile orders in Grasshopper for operational planning, manifest assignment, and downstream delivery execution. The request body wraps everything in a top-level order object.

Required headers

• Content-Type: application/json
• Authorization: {{access_token}} (raw token, no Bearer prefix)

curl --location -g '{{url}}/api/orders' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: {{access_token}}' \
  --data-raw '{
    "order": {
      "retailer": { "identifier": "adouglas" },
      "service_level": "EXP",
      "ref_order_number": "19007365728-EX-M760391-R",
      "customer": {
        "company": "Acme Sleep Co.",
        "address": {
          "address1": "2111 Commerce Way",
          "address2": null,
          "zip": "84663",
          "city": "Springville",
          "state": "UT"
        },
        "phone1": { "number": "1111111111" },
        "phone2": { "number": null },
        "email": "customer@email.com"
      },
      "total_insurance_coverage": 4580,
      "line_items": [
        {
          "quantity": 1,
          "weight": 0,
          "retail_value": 450,
          "cube": null,
          "sku": "7055-50",
          "category": "King Mattress",
          "name": "Classic Hybrid Mattress, King : 11",
          "vendor": "Acme Sleep",
          "freight_info": {
            "is_fob": false,
            "vendor_info": {
              "first_name": "Sam",
              "last_name": "Reeves",
              "address": {
                "address1": "861 Warehouse Pkwy",
                "address2": null,
                "city": "Spring Creek",
                "state": "NV",
                "zip": "89815"
              },
              "phone": "7755550172",
              "email": "pickup@vendor.com"
            }
          },
          "dimensions": {
            "height": 90,
            "width": 50,
            "depth": 80,
            "unit": "inch"
          },
          "tracking_number": null,
          "ref_order_number": "line-item-po-number"
        }
      ],
      "note": ""
    }
  }'

const payload = {
  order: {
    retailer: { identifier: "adouglas" },
    service_level: "EXP",
    ref_order_number: "19007365728-EX-M760391-R",
    customer: {
      company: "Acme Sleep Co.",
      address: { address1: "2111 Commerce Way", address2: null, city: "Springville", state: "UT", zip: "84663" },
      phone1: { number: "1111111111" },
      phone2: { number: null },
      email: "customer@email.com"
    },
    total_insurance_coverage: 4580,
    line_items: [
      {
        quantity: 1,
        weight: 0,
        retail_value: 450,
        cube: null,
        sku: "7055-50",
        category: "King Mattress",
        name: "Classic Hybrid Mattress, King : 11",
        vendor: "Acme Sleep",
        freight_info: {
          is_fob: false,
          vendor_info: {
            first_name: "Sam",
            last_name: "Reeves",
            address: { address1: "861 Warehouse Pkwy", address2: null, city: "Spring Creek", state: "NV", zip: "89815" },
            phone: "7755550172",
            email: "pickup@vendor.com"
          }
        },
        dimensions: { height: 90, width: 50, depth: 80, unit: "inch" },
        tracking_number: null,
        ref_order_number: "line-item-po-number"  // optional
      }
    ],
    note: ""
  }
};

const res = await fetch(`${BASE_URL}/api/orders`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": accessToken  // raw token, no Bearer prefix
  },
  body: JSON.stringify(payload)
});
const created = await res.json();

import requests

payload = {
    "order": {
        "retailer": {"identifier": "adouglas"},
        "service_level": "EXP",
        "ref_order_number": "19007365728-EX-M760391-R",
        "customer": {
            "company": "Acme Sleep Co.",
            "address": {"address1": "2111 Commerce Way", "address2": None, "city": "Springville", "state": "UT", "zip": "84663"},
            "phone1": {"number": "1111111111"},
            "phone2": {"number": None},
            "email": "customer@email.com",
        },
        "total_insurance_coverage": 4580,
        "line_items": [
            {
                "quantity": 1,
                "weight": 0,
                "retail_value": 450,
                "cube": None,
                "sku": "7055-50",
                "category": "King Mattress",
                "name": "Classic Hybrid Mattress, King : 11",
                "vendor": "Acme Sleep",
                "freight_info": {
                    "is_fob": False,
                    "vendor_info": {
                        "first_name": "Sam",
                        "last_name": "Reeves",
                        "address": {"address1": "861 Warehouse Pkwy", "address2": None, "city": "Spring Creek", "state": "NV", "zip": "89815"},
                        "phone": "7755550172",
                        "email": "pickup@vendor.com",
                    },
                },
                "dimensions": {"height": 90, "width": 50, "depth": 80, "unit": "inch"},
                "tracking_number": None,
                "ref_order_number": "line-item-po-number",  # optional
            }
        ],
        "note": "",
    }
}

res = requests.post(
    f"{BASE_URL}/api/orders",
    json=payload,
    headers={"Authorization": ACCESS_TOKEN},  # raw token, no Bearer prefix
)
created = res.json()

The example uses service_level: "EXP". All 13 service level codes, including White Glove, Threshold, and Curbside, are listed in the service levels reference.

Field reference

Every field in the create-order body. Nullable fields may be sent as null; optional fields may be omitted entirely. Each line item gets its own independent lifecycle and status (see Step 5).

Freight scope: what is_fob controls

The freight_info.is_fob flag on each line item tells the carrier how much of the journey they are responsible for. This is set per item, not per order, so a single order can mix both modes.

Full schema and live examples: POST Create New Order [Final Mile Only]

5Receive Lifecycle Webhooks

How registration works

Webhook subscriptions are configured by the carrier inside the Grasshopper UI. There is no self-serve subscription API. To get connected, send your carrier three things for each subscription:

Order vs. item status

Grasshopper tracks status at two levels and emits webhook events at both, so your system always has an accurate picture of where each order and each item is in its lifecycle:

• Item-level status: each individual line item has its own independent lifecycle
• Order-level status: an aggregated view; the order reflects the least advanced state across its items

Order-level events

All 23 supported topics are listed below. The same list with payload details lives on the Webhook Topics page.

Item-level events

Building your receiver

• Respond fast with a 2xx. Acknowledge receipt immediately, then process the event asynchronously. Slow responses look like failures and trigger retries.
• Be idempotent. Events are asynchronous, may be retried, and may arrive more than once for the same lifecycle change. Deduplicate on the event content plus your ref_order_number.
• Tolerate out-of-order delivery. Do not assume events arrive in lifecycle sequence. When in doubt, re-fetch the order via Retrieve order for current state.
• Tolerate unknown fields. Payloads may gain fields over time; parse defensively.

For full setup details, payload structure, and testing, see the Webhooks Overview · Payload · Topics · Testing

6Retrieve POD & Delivery Assets

Once an order reaches a terminal status, you can retrieve final delivery artifacts including Proof of Delivery (POD), signatures, and delivery images.

Terminal statuses

Download POD

Returns the POD document as a binary file stream. Use after the order reaches a terminal status, typically DELIVERED.

Download images & related assets

Returns all images and related assets as URLs. Includes POD photos, signatures, damage photos, inspection photos, and more.

Asset type reference

Errors & troubleshooting

The API uses standard HTTP status codes. The failures below account for nearly every stuck integration:

Full error semantics: Errors reference

Go-live checklist

Run this end to end in staging before requesting production access. Every item maps to a step above.

• Staging account created at staging.grasshopperlabs.io; authentication returns tokens (Step 3)
• Test order created via API and visible in the shipper UI (Step 4)
• ref_order_number deduplication enforced on your side (Step 4)
• order_created webhook received and reconciled against your OMS (Step 5)
• Receiver returns 2xx quickly, processes asynchronously, and handles duplicate events (Step 5)
• Terminal-status flow tested: POD downloaded, images retrieved and persisted before the 7-day URL expiry (Step 6)
• Token expiry and 401 recovery tested (Step 3)
• Production base URL, credentials, and webhook registrations confirmed with your carrier

Resources

Stuck on something this guide does not cover? Email support@grasshopperlabs.io or submit a ticket.