API Documentation

A single REST API over supplier facility hours. Suppliers publish their operating, receiving, and pickup schedules; shippers and carriers read live availability. Base URL:

https://supplierhours.com

Authentication

Every request needs an API key. Pass it as a bearer token or in the X-API-Key header:

Authorization: Bearer dh_xxxxxxxx...
# or
X-API-Key: dh_xxxxxxxx...

Read keys — issued to shippers and carriers. Can call every GET endpoint.
Write keys — created by suppliers from their dashboard. Can read and write, but strictly scoped to the supplier's own locations. Supplier keys never see other suppliers' data — aggregator-wide access is exclusive to read keys.

Shippers and carriers: request a key by contacting us. Suppliers: generate one under Dashboard → API keys.

Rate limits & plans

Limits are per key and depend on your plan. Over the limit returns 429 Too Many Requests with a Retry-After header. Check your consumption anytime via GET /api/v1/usage.

Plan	Limit	Window
Trial	100 requests	per day
Standard	1,000 requests	per hour
Enterprise	10,000 requests	per hour

Errors

Errors return a JSON body { "error": "message" } with a standard status code:

400 — invalid input (a details field explains what).
401 — missing, invalid, or revoked API key.
403 — valid key without permission for that action.
404 — location not found.
429 — rate limit exceeded.

For shippers & carriers

Read-only endpoints. Find facilities, then check when they're actually open. Start with availability — it does the hours-plus-closures math for you.

GET/api/v1/locationsread scope

List facilities

Search the aggregator for facilities. All filters are optional and combine with AND. Returns up to 200 locations.

Query parameters

city optional — Case-insensitive city match.
region optional — Two-letter state code, e.g. CA.
postalCode optional — Exact ZIP match.
supplierId optional — Restrict to one supplier.
near optional — '<lat>,<lng>' — radius search center. Results sort nearest-first and include distanceMiles.
radius optional — Miles from 'near'. Default 50, max 500.

Example request

curl "https://supplierhours.com/api/v1/locations?region=CA&city=Los%20Angeles" \
  -H "Authorization: Bearer dh_your_read_key"

Example response

{
  "locations": [
    {
      "id": "0f3c…",
      "name": "Los Angeles DC",
      "supplierId": "9a1b…",
      "supplierName": "Acme Foods",
      "addressLine1": "500 Dock St",
      "city": "Los Angeles",
      "region": "CA",
      "postalCode": "90001",
      "country": "US",
      "timezone": "America/Los_Angeles",
      "latitude": 33.97,
      "longitude": -118.24,
      "lastVerifiedAt": "2026-06-20T14:00:00.000Z",
      "stale": false,
      "distanceMiles": 12.4
    }
  ]
}

GET/api/v1/locations/{id}/availabilityread scope

Computed availability (the one you want)

Merges recurring weekly hours with closures into a per-day, per-type open/closed answer. Times are facility-local; the response includes the IANA timezone. Ask for a single day or a window of up to 14.

Query parameters

date required — Start date, YYYY-MM-DD (facility-local).
days optional — How many days to return, 1-14. Default 1.

Example request

curl "https://supplierhours.com/api/v1/locations/0f3c…/availability?date=2026-07-06&days=7" \
  -H "Authorization: Bearer dh_your_read_key"

Example response

{
  "locationId": "0f3c…",
  "timezone": "America/Los_Angeles",
  "lastVerifiedAt": "2026-06-20T14:00:00.000Z",
  "stale": false,
  "days": [
    {
      "date": "2026-07-06",
      "dayOfWeek": 1,
      "operating": { "status": "open",
        "windows": [{ "opensAt": "08:00", "closesAt": "17:00" }] },
      "receiving": { "status": "closed", "reason": "Inventory count" },
      "pickup": { "status": "unavailable" }
    }
  ]
}

GET/api/v1/locations/{id}/hoursread scope

Raw weekly hours

The recurring weekly windows for a facility, before closures are applied. Filter by type to narrow the result. dayOfWeek is 0 (Sunday) through 6 (Saturday).

Query parameters

type optional — operating | receiving | pickup. Omit for all three.

Example request

curl "https://supplierhours.com/api/v1/locations/0f3c…/hours?type=receiving" \
  -H "Authorization: Bearer dh_your_read_key"

Example response

{
  "locationId": "0f3c…",
  "hours": [
    { "type": "receiving", "dayOfWeek": 1,
      "opensAt": "06:00:00", "closesAt": "11:00:00" },
    { "type": "operating", "dayOfWeek": 1,
      "opensAt": "08:00:00", "closesAt": "17:00:00" }
  ]
}

GET/api/v1/locations/{id}/closuresread scope

List closures

Blackout date ranges for a facility. A null type means the whole facility is closed; a specific type means only that function is down.

Query parameters

from optional — Only return closures ending on or after this date (YYYY-MM-DD).

Example request

curl "https://supplierhours.com/api/v1/locations/0f3c…/closures?from=2026-07-01" \
  -H "Authorization: Bearer dh_your_read_key"

Example response

{
  "locationId": "0f3c…",
  "closures": [
    { "id": "7d2e…", "type": null,
      "startsOn": "2026-12-25", "endsOn": "2026-12-25",
      "reason": "Christmas" }
  ]
}

GET/api/v1/usageread scope

Your usage and limits

Self-service usage visibility for the calling key: billing tier, current rate-limit window consumption, and a 7-day history of usage windows.

Example request

curl "https://supplierhours.com/api/v1/usage" \
  -H "Authorization: Bearer dh_your_key"

Example response

{
  "keyPrefix": "dh_a1b2c3d4",
  "scope": "read",
  "tier": "standard",
  "currentWindow": {
    "limit": 1000, "used": 42, "remaining": 958,
    "resetAt": "2026-07-06T15:00:00.000Z"
  },
  "history": [
    { "windowStart": "2026-07-06T14:00:00.000Z", "count": 42 }
  ]
}

For suppliers

Write endpoints for publishing your hours programmatically instead of through the dashboard. Use a write-scoped key; you can only modify locations your company owns. The same key works on the read endpoints above, but returns only your own locations — for aggregator-wide data, you need a consumer read key.

PUT/api/v1/locations/{id}/hourswrite scope

Replace weekly hours

Full replacement of all windows for ONE hours type. Send the complete set each time (the endpoint is idempotent — it deletes then reinserts). The key must belong to the supplier that owns the location. Times are HH:MM, 24-hour, facility-local.

Request body

{
  "type": "receiving",
  "windows": [
    { "dayOfWeek": 1, "opensAt": "06:00", "closesAt": "11:00" },
    { "dayOfWeek": 1, "opensAt": "13:00", "closesAt": "16:00" }
  ]
}

Example request

curl -X PUT "https://supplierhours.com/api/v1/locations/0f3c…/hours" \
  -H "Authorization: Bearer dh_your_write_key" \
  -H "Content-Type: application/json" \
  -d '{"type":"receiving","windows":[{"dayOfWeek":1,"opensAt":"06:00","closesAt":"11:00"}]}'

Example response

{ "ok": true, "type": "receiving", "count": 2 }

POST/api/v1/locations/{id}/closureswrite scope

Add a closure

Add a blackout date range. Omit type (or send null) to close the entire facility; set a type to close only that function. The key must belong to the supplier that owns the location.

Request body

{
  "type": null,
  "startsOn": "2026-12-25",
  "endsOn": "2026-12-25",
  "reason": "Christmas"
}

Example request

curl -X POST "https://supplierhours.com/api/v1/locations/0f3c…/closures" \
  -H "Authorization: Bearer dh_your_write_key" \
  -H "Content-Type: application/json" \
  -d '{"startsOn":"2026-12-25","endsOn":"2026-12-25","reason":"Christmas"}'

Example response

{
  "closure": {
    "id": "7d2e…", "locationId": "0f3c…", "type": null,
    "startsOn": "2026-12-25", "endsOn": "2026-12-25", "reason": "Christmas"
  }
}