​
Developer overview

Hilt gives developers a clean way to automate the same merchant workflow the dashboard already runs. If you want one working flow tonight, start with Developer quickstart. If you want the broader model first, stay here.

​
What Hilt is good at

Hilt works best when you want one system to own:
  • hosted checkout
  • payment state
  • memberships and recurring operations
  • receipt proof
  • support context
  • webhook event delivery
That means your own backend does not need to rebuild the merchant operating trail after payment.

​
The fastest reliable implementation path

The practical build order is:
  1. launch one real product in the dashboard or create the equivalent product from code
  2. create an API key
  3. install the SDK or import Postman
  4. add a webhook endpoint
  5. test the Hilt contract in sandbox
  6. finish with one tiny live payment
That gives you:
  • one working product
  • one working integration
  • one real merchant trail to compare against

​
What your backend should own

Your backend is usually the right place for:
  • product creation or updates when needed
  • signed buyer handoff link generation
  • webhook consumers for longer-running automation
  • active checkout polling while the buyer is still waiting
  • your own correlation between users and Hilt ids

​
What Hilt should own

Hilt should remain the source of truth for:
  • payment settlement state
  • membership state
  • renewal intelligence
  • receipt proof
  • support case history

​
Start from a real merchant workspace

The cleanest integrations start from a real merchant workspace rather than a purely synthetic setup:
  1. launch the first flow in the dashboard
  2. create the API key for that workspace
  3. automate the same product and checkout flow from your backend
  4. compare the API trail against what the merchant sees in the app
That keeps the integration aligned with the live commercial object the merchant already understands.

​
Use the right auth surface

For merchant-only routes, Hilt accepts either a merchant session token or an API key.
SurfaceTypical authBest use
Public checkout payload and buyer session startno authBuyer-facing hosted checkout
Merchant backend or bot automationX-Hilt-KeyServer-to-server integrations
Dashboard-session toolingAuthorization: Bearer JWT_TOKENMerchant browser workflows and session-assisted tools
Practical rule:
  • use X-Hilt-Key for almost all backend work
  • use Authorization: Bearer JWT_TOKEN for webhook endpoint management

​
Public contract at a glance

AreaWhat you do thereMain routes
ProductsCreate, update, archive, and inspect merchant offers/v1/products
Hosted checkoutRead buyer payloads and start buyer sessions/v1/products/p/{slug}, /connect, /resolve-handoff
PaymentsConfirm and read payment state/v1/pay/confirm, /v1/payments/{payment_id}
WebhooksReceive signed outbound Hilt events/v1/webhooks*
MembershipsRead access state and run follow-up actions/v1/memberships*
ReceiptsRead proof and public verification links/v1/receipts, /v1/receipt/{id}
SupportOpen and manage issue threads tied to the payment trail/v1/support/tickets*
TestingRun contract-level sandbox sessions before one tiny live payment/v1/testing*

​
The ids worth keeping

These are the ids worth persisting in your own system:
  • product_id
  • slug
  • payment_id
  • membership_id
  • receipt_id
  • ticket_id
The most important one is payment_id. It is the clean join between:
  • checkout state
  • payment status
  • memberships
  • receipts
  • support tickets
  • webhook timelines

​
Reference and tooling

Hilt publishes the public merchant contract in several forms:
  • OpenAPI spec: https://api.hilt.so/v1/openapi.json
  • Swagger UI: https://api.hilt.so/v1/docs
  • Redoc: https://api.hilt.so/v1/redoc
  • TypeScript SDK: npm install @hiltpay/sdk
  • TypeScript SDK source: https://github.com/Hiltpay/hilt-sdk-js
  • Python SDK: pip install hilt-sdk
  • Python SDK source: https://github.com/Hiltpay/hilt-sdk-python
  • Developer assets repo: https://github.com/Hiltpay/hilt-developer-assets
Use the GitHub developer-assets repo when you want public mirrors of:
  • OpenAPI snapshots
  • Postman imports
  • example webhook payloads
Use the live Hilt API surfaces when you want the canonical contract.

​
Rate limits

Hilt returns standard rate-limit headers on API responses:
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset
  • Retry-After on 429
Current defaults are:
  • unauthenticated public buyer routes: 120 requests per minute
  • Free: 60 requests per minute
  • Starter: 120 requests per minute
  • Growth: 300 requests per minute
  • Scale: 900 requests per minute
  • Enterprise: custom or effectively unlimited by contract

​
When to use the dashboard, API, SDK, Postman, or CLI

SurfaceBest for
DashboardFirst launch, checkout branding, commercial setup, daily merchant operations
APIBackend automation, bots, signed handoff links, payment-state reads, webhook consumers, ledger lookups
SDKsFaster typed integration in TypeScript or Python
PostmanFast request inspection and contract exploration without writing code
CLIRepeatable support workflows, terminal lookups, and lightweight scripts

​
Go deeper