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

Machine-readable spec: /openapi.json (OpenAPI 3.1 — generate an SDK)

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",
          "appointmentRequired": false }] },
      "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. A window of 00:00–23:59 means open 24 hours that day.

Request body

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

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","appointmentRequired":true}]}'

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"
  }
}

Website widget (free)

Show a facility's live hours on your own website — open/closed badge, weekly schedule, and upcoming closures, always in sync with what you publish here. No API key needed. Paste this where you want the card to appear (the snippet with your location's ID is on each location page in the dashboard):

<div data-supplierhours="YOUR_LOCATION_ID"></div>
<script src="https://supplierhours.com/widget.js" async></script>

Optional: add data-type="operating", receiving, or pickupto show a single schedule type. The widget is self-contained and won't conflict with your site's styles.

OpenAPI spec & SDKs

The full API is described in an OpenAPI 3.1 document at https://supplierhours.com/openapi.json. Import it into Postman/Insomnia, or generate a typed client:

# TypeScript types + fetch client
npx openapi-typescript https://supplierhours.com/openapi.json -o supplierhours.d.ts

# Full client in another language (Python example)
npx @openapitools/openapi-generator-cli generate \
  -i https://supplierhours.com/openapi.json -g python -o ./supplierhours-client

The spec is versioned with the API — breaking changes will ship as a new version, never silently.