Get up and running with the Grasshopper API in six steps.

Before any API integration begins, the shipper must be created and configured inside the Grasshopper UI. This step is performed by the carrier within their Grasshopper environment.

Required Information

The carrier will collect and configure the following:

• Primary contact first name
• Primary contact last name
• Primary contact email address
• Company name
• Company address
• Any additional retailer configuration fields required by the carrier workflow

Once the shipper exists in Grasshopper, create a dedicated user under that shipper's users to handle API authentication. A valid user profile is required before any API access can begin.

Required Credentials

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

What else this user can do

The API user profile behaves exactly like any other Grasshopper user. It can also:

• Log in to the shipper UI when needed
• Validate credentials during testing
• Trigger password resets (sent to the email above)

Authentication must be completed before any API access begins. Use the API user credentials created in Step 2 to obtain an access token.

Request

Send credentials as application/x-www-form-urlencoded:

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

Behavior

• Valid credentials: Grasshopper returns the authentication tokens required for subsequent API requests
• Invalid credentials: the request is rejected and the integration must not proceed with additional API calls

The Order Creation API allows retailers to create new final-mile orders in Grasshopper for operational planning, manifest assignment, and downstream delivery execution.

Required Headers

• Content-Type: application/json
• Authorization: {{access_token}}

Example Request

curl --location -g '{{url}}/api/orders' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: {{access_token}}' \
  --data-raw '{
    "order": {
      "retailer": { "identifier": "gh3test" },
      "service_level": "WG",
      "ref_order_number": "1123456",
      "sales_order_number": "<optional>",
      "freight_tracking_number": "<optional>",
      "customer": {
        "first_name": "Ori",
        "last_name": "Anavim",
        "address": {
          "address1": "123 Main",
          "city": "Charlotte",
          "state": "NC",
          "zip": "28277"
        },
        "phone1": { "number": "987-858-8558" },
        "email": "ori@email.com"
      },
      "total_insurance_coverage": 0,
      "line_items": [
        {
          "quantity": 1,
          "weight": 123,
          "cube": 33,
          "sku": "item_sku-1",
          "tracking_number": "item_serial-1234",
          "serial_number": "item_serial-1234",
          "category": "Misc",
          "name": "item-description-test",
          "vendor": "vendor-name-123",
          "freight_info": { "is_fob": true, "vendor_info": {} }
        }
      ],
      "note": "sample order note"
    }
  }'

Behavior

• A valid authenticated request creates a new final-mile order in Grasshopper
• The order becomes available for manifest assignment, lifecycle tracking, and delivery
• Items submitted under line_items participate in lifecycle tracking alongside the order

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

Order vs. Item Status

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

Order-Level Events

Event	Description
order_created	Order created in Grasshopper
order_complete_stop	Order completed (Delivered / Rejected / Delivery Failed / Damaged)
order_updated	Order information has been updated
order_status_changed	Order status was changed
tracking_changed	Tracking entry was added
notes_added	Note was added to the order
notes_updated	Note was updated
delivery_changed	Delivery date was changed
pickup_date_schedule_changed	Pickup date was changed
expected_arrival_changed	Expected arrival was changed
order_estimated_arrival_changed	Estimated arrival time changed
customer_information_changed	Customer information changed on the order
service_level_changed	Service level changed
asset_added	Image was added to the order
asset_removed	Image was removed from the order
arrive_on_site	Driver team arrived at the consignee

Item-Level Events

Event	Description
item_status_changed	Line item status was changed
item_damaged	Individual line item was marked as damaged
item_added	Item was added
item_removed	Item was removed
item_updated	Item was updated
item_rejected	Individual line item was rejected
item_failed_delux	Item did not pass deluxe process

Subscribing to Webhooks

To register a webhook subscription, provide:

• Topic name — one of the supported topics above
• Method — POST, PUT, or PATCH
• URL — your endpoint that will receive the event payload

Payload Structure

Webhook payloads contain two top-level sections:

• msg_info — metadata about the webhook delivery (event context, message info)
• order — the Grasshopper order data relevant to the event, including order info, delivery, customer, retailer, line_items, tracking, assets, notes, and item-level tracking

Webhook Resources

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

Terminal Statuses

An order is considered terminal when no further operational updates are expected:

Successful completion    Failure outcome    Other terminal state

Download POD

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

Response Codes

• 200 OK — POD file returned as binary stream
• 404 — POD not found or not yet available
• 403 — Unauthorized access
• 400 — Invalid request

Download Images & Related Assets

Returns all images and related assets associated with an order: POD photos, signatures, damage photos, inspection photos, and more. Assets come back as URLs (7-day expiry), not binary files.

Sample Response

{
  "status": "ok",
  "data": [
    {
      "id": "6489cfd7977ae68383fd6b9f",
      "original_file_name": "signature.png",
      "key": "orders/22200039622/1-06142023-103359565.png",
      "type": 1,
      "file_type": "image/png",
      "date": "2023-06-14T14:33:59.731Z",
      "url": "https://dlr-imgs.s3.amazonaws.com/orders/...",
      "user": {
        "first_name": "Ces",
        "last_name": "Driver",
        "full_name": "Ces Driver"
      }
    }
  ]
}

Asset Type Reference

The type field on each asset identifies what it is. The most common types:

ID	Type
0	General
1	Signature [Accept]
2	Signature [Reject]
4	Delivery Location
5	Damage Product
7	Accept Product
11	Item Inspection
13	Bill of Lading
25	Arrive on Site
26	eSignature POD

Full list of 38 asset types available in the Postman documentation.