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

• 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

• 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

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",
      "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"
      },
      "line_items": [
        {
          "quantity": 1,
          "weight": 123,
          "cube": 33,
          "sku": "item_sku-1",
          "name": "item-description-test"
        }
      ]
    }
  }'

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; 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

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

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 (7-day expiry). Includes POD photos, signatures, damage photos, inspection photos, and more.

Asset Type Reference

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