Developer Support

Can an existing ShipPack user become a developer?

Yes. Register with the existing email and password, then verify the emailed OTP. Developer access is attached to the same eligible identity without creating a duplicate user row.

Why can't I retrieve a lost secret key?

Secret keys are returned only at creation. ShipPack stores a SHA-256 hash and metadata, not the recoverable secret. Create or rotate a key if it is lost.

Does sandbox create a real shipment or charge me?

No. Sandbox creates no operational shipment, charges no wallet, card, or provider, and assigns no driver.

How do I create a production key?

Submit a meaningful reason through the application production-access endpoint. A ShipPack administrator must approve the request before the application can create an sk_live_ key.

Which payment methods are supported?

The current production MVP accepts paymentMethod: wallet when submit is true. Public wallet APIs and card tokenization are not part of the developer API.

What is the API rate limit?

Each application credential is limited to 120 requests per minute.

Which SDKs are available?

The TypeScript SDK source exists at sdks/typescript but is not yet published. Other language SDK packages are deliberately deferred.

Dashboard request is unauthorized

• Use a valid Sanctum user access token.
• Include X-App-Type: developer.
• Confirm the identity completed developer registration and OTP verification.
• Customer, driver, vendor, entity, and other tokens need the developer profile attached before using dashboard routes.

Application-key request is unauthorized

• Send the application secret in Authorization: Bearer SECRET_KEY.
• Confirm the key has not expired or been revoked.
• Confirm its prefix matches the intended environment.
• Do not use a dashboard user token on the server-to-server shipment surface.

Production key creation is rejected

• Confirm the production-access request was approved.
• Provide a meaningful operational reason rather than a placeholder.
• A rejected production request revokes active live keys.

Shipment cannot be found

• Confirm the shipment ID belongs to the application represented by the current key.
• One application cannot access another application's shipment mappings.
• Confirm you are using the same environment in which the shipment was created.

Catalog identifiers are invalid

• Load package sizes and delivery types instead of hard-coding IDs.
• Request delivery options with valid origin and destination coordinates.
• Use the returned packageSizeId and deliveryTypeId values in the create request.

Sandbox simulation is rejected

• The simulation endpoint is sandbox-only.
• Follow PENDING → ASSIGNED → PICKED_UP → IN_TRANSIT → OUT_FOR_DELIVERY → DELIVERED.
• A non-terminal state may transition to FAILED.
• Do not attempt to advance a terminal shipment.

Production values differ from the request

Production callers cannot choose the internal ShipPack user identity. Caller-supplied prices are discarded and operational pricing is resolved by ShipPack.

Webhook endpoint cannot be created

• Use an HTTPS URL.
• Do not use localhost, private, reserved, or locally resolving addresses.
• Confirm public DNS resolves correctly; ShipPack checks DNS again before each delivery.

Signature verification fails

• Use the exact raw request body before JSON parsing or body transformation.
• Sign TIMESTAMP.RAW_REQUEST_BODY with HMAC-SHA256.
• Compare against the complete sha256=HEX_HMAC value using a timing-safe function.
• Reject timestamps outside a five-minute tolerance.
• Confirm you are using the current webhook secret after rotation.

Delivery is repeatedly retried

• Return any HTTP 2xx response quickly, then process asynchronously.
• ShipPack retries after 30 seconds, 2 minutes, 10 minutes, and 30 minutes.
• After five unsuccessful attempts the delivery is marked failed.
• Inspect the saved response and last error, then manually retry a non-delivered attempt.

Duplicate event processing

Deduplicate with the webhook payload id or X-ShipPack-Delivery header. Delivery creation is idempotent, but consumers should still protect their own side effects.