# DropHub External API

- [Sandbox quickstart](https://docs.drop-hub.com/quickstart.md): Register a fresh sandbox merchant and reach a shipment-ready state.
- [DropHub External API](https://docs.drop-hub.com/overview.md): Create shipments, follow them to the door, and receive signed events — from your own systems.
- [Environments](https://docs.drop-hub.com/environments.md): Two deployments, two sets of credentials, and the prerequisites for calling either.
- [Authentication](https://docs.drop-hub.com/authentication.md): OAuth 2.0 client credentials, the three scopes, and how tokens behave.
- [Shipments](https://docs.drop-hub.com/shipments.md): Quote a price, create a shipment, and read it back.
- [Tracking](https://docs.drop-hub.com/tracking.md): Live shipment tracking, and public tracking links for recipients.
- [Cancellation](https://docs.drop-hub.com/cancellation.md): Cancel a shipment, and understand when cancellation is refused.
- [Webhooks](https://docs.drop-hub.com/webhooks.md): Subscribe to shipment events, verify signatures, and inspect deliveries.
- [Idempotency and ETags](https://docs.drop-hub.com/idempotency-and-etags.md): Safe retries on creates, and optimistic concurrency on updates.
- [Errors](https://docs.drop-hub.com/errors.md): RFC 9457 problem details, stable machine codes, and what to retry.
- [OAuth 2.0 client-credentials token issuance for machine integrations](https://docs.drop-hub.com/api-reference/authentication/oauth-20-client-credentials-token-issuance-for-machine-integrations.md): Standard RFC 6749 token endpoint. The client authenticates with HTTP Basic (preferred) or body client_id/client_secret parameters and receives a short-lived signed JWT bearer token. Responses use OAuth error semantics and are never stored.
- [Start merchant self-service registration with an email OTP challenge](https://docs.drop-hub.com/api-reference/authentication/start-merchant-self-service-registration-with-an-email-otp-challenge.md): Starts a merchant registration and returns a short-lived opaque upload capability. The capability is valid only for the returned pending registration and is not an account or media credential.
- [List private evidence attached to one pending merchant registration](https://docs.drop-hub.com/api-reference/authentication/list-private-evidence-attached-to-one-pending-merchant-registration.md)
- [Upload or replace one private pending-registration document](https://docs.drop-hub.com/api-reference/authentication/upload-or-replace-one-private-pending-registration-document.md)
- [Delete one document from a pending merchant registration](https://docs.drop-hub.com/api-reference/authentication/delete-one-document-from-a-pending-merchant-registration.md)
- [Start shipping-company self-service registration with an email OTP challenge](https://docs.drop-hub.com/api-reference/authentication/start-shipping-company-self-service-registration-with-an-email-otp-challenge.md): Start shipping-company self-service registration with an email OTP challenge. A shipping company is registered through its own door and recorded in its own table; the two sign-ups do not share a request shape because they do not ask the same questions.
- [Verify the registration OTP and create identity, account and session atomically](https://docs.drop-hub.com/api-reference/authentication/verify-the-registration-otp-and-create-identity-account-and-session-atomically.md): Verify the registration OTP and create identity, account and session atomically.
- [Read this merchant's own Direct API credential](https://docs.drop-hub.com/api-reference/authentication/read-this-merchants-own-direct-api-credential.md): The merchant is its own API client, so the credential is addressed by the session rather than by a client id. A merchant that has never issued one is answered 404.
- [Issue this merchant's Direct API credential](https://docs.drop-hub.com/api-reference/authentication/issue-this-merchants-direct-api-credential.md): One active credential per merchant. A second call while it is active is a conflict. After revocation this same operation cleanly reissues a new client id and one-time secret.
- [Withdraw this merchant's Direct API credential](https://docs.drop-hub.com/api-reference/authentication/withdraw-this-merchants-direct-api-credential.md): Withdraw the credential. Access-policy checks invalidate already-issued bearer tokens immediately.
- [Replace the secret, keeping the old one until it retires](https://docs.drop-hub.com/api-reference/authentication/replace-the-secret-keeping-the-old-one-until-it-retires.md): Rotation keeps an overlap window so a merchant can rotate and redeploy without a gap in which its integration is refused.
- [Idempotently provision this merchant's complete sandbox fixture](https://docs.drop-hub.com/api-reference/sandbox/idempotently-provision-this-merchants-complete-sandbox-fixture.md): Sandbox deployment only. Creates or repairs a tenant-exclusive merchant, internal carrier, coverage, driver, and canonical location fixture. It never accepts hidden identifiers or changes another tenant.
- [Read this merchant's sandbox readiness checklist](https://docs.drop-hub.com/api-reference/sandbox/read-this-merchants-sandbox-readiness-checklist.md)
- [Reset only the calling merchant's sandbox integration fixtures](https://docs.drop-hub.com/api-reference/sandbox/reset-only-the-calling-merchants-sandbox-integration-fixtures.md): Explicitly revokes this tenant's public tracking links and webhook endpoints, repairs its fixture prerequisites, increments the generation, and preserves canonical immutable shipment history. Shared/global platform configuration and other tenants are untouched.
- [Keep the next sandbox shipment before the driver-offer boundary](https://docs.drop-hub.com/api-reference/sandbox/keep-the-next-sandbox-shipment-before-the-driver-offer-boundary.md): Sandbox deployment only. Idempotently arms one tenant-bound hold. The next shipment consumes it atomically and remains PENDING_APPROVAL with no driver offer, allowing the merchant cancellation boundary to be exercised deterministically.
- [Calculate what this merchant is charged for a delivery](https://docs.drop-hub.com/api-reference/external-price-estimates/calculate-what-this-merchant-is-charged-for-a-delivery.md): Calculates authoritative route distance and returns the delivery price agreed with this merchant. DropHub internally verifies an eligible carrier and available driver; merchants never select or receive a carrier identifier. No calculation is persisted.
- [List or reconcile Merchant shipments](https://docs.drop-hub.com/api-reference/external-shipments/list-or-reconcile-merchant-shipments.md): List or reconcile Merchant shipments.
- [Create or replay a canonical Merchant shipment](https://docs.drop-hub.com/api-reference/external-shipments/create-or-replay-a-canonical-merchant-shipment.md): Resolves the authoritative route, internally selects an eligible service and driver, and freezes the merchant commercial terms. Carrier identity and scoring are never merchant inputs. `externalReference` is unique per Merchant company.
- [Get external merchant shipment](https://docs.drop-hub.com/api-reference/external-shipments/get-external-merchant-shipment.md): Get external merchant shipment.
- [Cancel an unassigned shipment](https://docs.drop-hub.com/api-reference/external-shipments/cancel-an-unassigned-shipment.md): Atomic with driver assignment. Once any driver offer/assignment exists this returns 409 SHIPMENT_ALREADY_ASSIGNED.
- [Get the OAuth client's Merchant profile](https://docs.drop-hub.com/api-reference/external-shipments/get-the-oauth-clients-merchant-profile.md): Get the OAuth client's Merchant profile. Results are scoped to the Merchant company bound to the OAuth client.
- [List active and unavailable Merchant branches](https://docs.drop-hub.com/api-reference/external-shipments/list-active-and-unavailable-merchant-branches.md): List active and unavailable Merchant branches. Results are scoped to the Merchant company bound by the OAuth client.
- [List active and unavailable Merchant pickup locations](https://docs.drop-hub.com/api-reference/external-shipments/list-active-and-unavailable-merchant-pickup-locations.md): List active and unavailable Merchant pickup locations. Results are scoped to the Merchant company to the OAuth client.
- [Get v2externalshipments tracking](https://docs.drop-hub.com/api-reference/external-tracking/get-v2externalshipments-tracking.md)
- [Post v2externalshipments tracking links](https://docs.drop-hub.com/api-reference/external-tracking/post-v2externalshipments-tracking-links.md)
- [Delete v2externalshipments tracking links](https://docs.drop-hub.com/api-reference/external-tracking/delete-v2externalshipments-tracking-links.md)
- [List merchant webhook endpoints](https://docs.drop-hub.com/api-reference/webhook-endpoints/list-merchant-webhook-endpoints.md): List merchant webhook endpoints.
- [Create merchant webhook endpoint](https://docs.drop-hub.com/api-reference/webhook-endpoints/create-merchant-webhook-endpoint.md): Returns the signing secret exactly once. Production destinations must be public HTTPS and pass DNS/IP SSRF validation.
- [Get merchant webhook endpoint](https://docs.drop-hub.com/api-reference/webhook-endpoints/get-merchant-webhook-endpoint.md): Get merchant webhook endpoint.
- [Delete merchant webhook endpoint](https://docs.drop-hub.com/api-reference/webhook-endpoints/delete-merchant-webhook-endpoint.md): Delete merchant webhook endpoint.
- [Update merchant webhook endpoint](https://docs.drop-hub.com/api-reference/webhook-endpoints/update-merchant-webhook-endpoint.md): Update merchant webhook endpoint.
- [Rotate merchant webhook secret](https://docs.drop-hub.com/api-reference/webhook-endpoints/rotate-merchant-webhook-secret.md): Returns the new secret once; the former secret remains verifiable only for the configured bounded overlap.
- [Test merchant webhook endpoint](https://docs.drop-hub.com/api-reference/webhook-endpoints/test-merchant-webhook-endpoint.md): Sends a signed connectivity probe using the same hardened HTTP transport; this is not a lifecycle event.
- [List merchant webhook deliveries](https://docs.drop-hub.com/api-reference/webhook-deliveries/list-merchant-webhook-deliveries.md): Delivery is at least once and may be out of order. Deduplicate by event ID and reconcile with sequence and resource version.
- [Get merchant webhook delivery](https://docs.drop-hub.com/api-reference/webhook-deliveries/get-merchant-webhook-delivery.md): Get merchant webhook delivery.
- [Replay merchant webhook delivery](https://docs.drop-hub.com/api-reference/webhook-deliveries/replay-merchant-webhook-delivery.md): Creates a new delivery identity while preserving the original event ID, timestamp, and immutable payload.

## OpenAPI Specs

- [openapi](/openapi.yaml)