# Quickstart

This walkthrough takes you from zero to a delivered (simulated) order on Envoi's staging environment in about 15 minutes. Envoi is a same-day/next-day parcel delivery carrier in Canada; you integrate by creating orders through the REST API and tracking them via the package journey or webhooks. Everything below runs against staging (`https://api.staging.yourenvoi.com`) with a staging API key, so nothing here touches real deliveries. All examples use the canonical docs dataset: retailer "Maple & Main", fulfillment location `MapleMain-GTA-1` (id `118`), order `MM-10042`.

## 1. Get a staging API key

1. Sign in to the staging Parcel Dashboard at `https://app.staging.yourenvoi.com` with an **admin** user.
2. Go to **Settings → Generate API Token**.
3. Copy the key immediately — it is shown only once. Keys are UUIDs, and staging keys are separate from production keys.

If you don't have a staging (test) account yet, email marcello@envoinow.com to have one set up.

Export the key for the rest of this guide:

```bash
export ENVOI_API_KEY="00000000-0000-4000-8000-000000000000"
```

See [Authentication](authentication.md) for header details, rotation, and key limits.

## 2. Validate an address (serviceability + rate)

Check that the destination postal code is inside your fulfillment location's service area, and get a rate:

```bash
curl -X POST "https://api.staging.yourenvoi.com/public/service-areas/ca/validate" \
  -H "Access-Token: $ENVOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "postalCode": "M2K 0A6",
    "fulfillmentLocationName": "MapleMain-GTA-1",
    "sendRate": true,
    "weight": 1.4,
    "length": 30,
    "width": 25,
    "height": 12
  }'
```

```json
{
  "message": "success",
  "data": {
    "isSupported": true,
    "rate": 9.99,
    "taxes": 1.3,
    "estimatedDeliveryDate": "2026-07-22"
  }
}
```

See [Validate & Rate](../api/service-areas/validate.md) for all options.

## 3. Create an order

`fulfillmentLocationId` says where the parcel ships from — `118` is the same **MapleMain-GTA-1** location you rate-shopped in step 2. Find your own ids with [Service Area Lookups](../api/service-areas/lookup.md): list your service areas, then read the `id` field of that area's fulfillment locations. The location's name is still accepted as the legacy `childUserName`.

```bash
curl -X POST "https://api.staging.yourenvoi.com/public/orders" \
  -H "Access-Token: $ENVOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "MM-10042",
    "recipient": "Avery Chen",
    "addressLine1": "27 Rean Drive",
    "addressLine2": "Unit 1203 - Buzzer 1203",
    "city": "North York",
    "province": "ON",
    "postalCode": "M2K 0A6",
    "country": "Canada",
    "phone": "4165550123",
    "email": "avery.chen@example.com",
    "fulfillmentLocationId": 118,
    "date": "2026-07-22",
    "barcodeForScan": "MNM4T7K9QW2XCV8R",
    "trackingCode": "MNM00100042CA",
    "note": "Please leave at the concierge desk. Call on arrival.",
    "addressType": "APARTMENT",
    "dropoffLocation": "CONCIERGE",
    "accessCode": "#1203 on the intercom",
    "business": false,
    "signatureRequired": false,
    "sizeCategory": "M",
    "weight": 1.4,
    "length": 30,
    "width": 25,
    "height": 12,
    "customFields": {
      "customField1": {
        "label": "SKU",
        "value": "MM-TOTE-CANVAS-NAT"
      },
      "customField2": {
        "label": "Description",
        "value": "Canvas tote bag, natural"
      }
    }
  }'
```

The response is the serialized order object (no envelope). The parts you'll use most:

```json
{
  "id": "1345901",
  "number": "MM-10042",
  "status": "DELIVERY_SCHEDULED",
  "envoiTrackingCode": "3f2c9a4e-6b1d-4e8a-9c3f-7d5e8a2b1c4d",
  "trackingCode": "MNM00100042CA",
  "shippingLabelUrl": "https://api.yourenvoi.com/files/labels/1345901.pdf",
  "latitude": 43.7664518,
  "longitude": -79.4106783
}
```

- `id` — Envoi's numeric order ID; use it in `/public/orders/:id` calls.
- `envoiTrackingCode` — drives the public tracking page: `https://app.yourenvoi.com/tracking/3f2c9a4e-6b1d-4e8a-9c3f-7d5e8a2b1c4d`.
- `shippingLabelUrl` — the PDF label is returned right in the create response; there is no separate label endpoint. See [Shipping Labels](../api/labels.md).
- `status` — starts at `DELIVERY_SCHEDULED`.

Full request/response bodies and every field: [Create an Order](../api/orders/create.md).

## 4. Fetch the order back

```bash
curl "https://api.staging.yourenvoi.com/public/orders/1345901" \
  -H "Access-Token: $ENVOI_API_KEY"
```

This returns the order directly (no envelope), including a `packageJourney` array with one `DELIVERY_SCHEDULED` event. You can also pass a tracking code instead of the numeric ID — see [Get, Update, Cancel](../api/orders/get-update-cancel.md).

## 5. Simulate a delivery journey (staging only)

Staging exposes a simulation endpoint that plays a realistic package journey onto a test order. Simulate a failed first attempt, a second attempt, and a return-to-sender:

```bash
curl -X POST "https://api.staging.yourenvoi.com/public/shipment-tracking/simulate" \
  -H "Access-Token: $ENVOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 1345901,
    "scenario": "MULTI_ATTEMPT_RTS"
  }'
```

This endpoint does not exist in production. Scenarios and custom event scripts are documented in [Simulate Tracking Events](../api/tracking/simulate.md).

## 6. Re-fetch and inspect the package journey

```bash
curl "https://api.staging.yourenvoi.com/public/orders/1345901?includePackageJourney=true" \
  -H "Access-Token: $ENVOI_API_KEY"
```

The order's `packageJourney` now contains the simulated events (`PICKED_UP_FROM_STORE`, `SORTED_AT_WAREHOUSE`, `ATTEMPTING_DELIVERY`, `SKIPPED`, and so on), each with `statusUpdatedAt` (UTC), `localTimestamp`, `localUtcOffset`, and `location`. Status meanings and reason codes: [Statuses & Reason Codes](../api/tracking/statuses.md).

## 7. Next steps

- [Webhooks Overview](../webhooks/overview.md) — push tracking events to your endpoint instead of polling.
- [Choose Your Pathway](choose-your-pathway.md) — pick the right integration model (direct API, rate-shop integrator, SFTP, Shopify, 3PL).
- [Postman Collection](../tools/postman.md) — run this entire flow from Postman.
- [Environments](environments.md) — what changes when you go to production.