On this page
House Plant Dropship · Developer
External Store API
v1Updated November 2026
Send orders straight to HPD fulfillment from your own site, custom storefront, or ERP. Standard JSON endpoints, built-in idempotency, and signed webhooks.
Authentication
Pass your Bearer API key in the header of every request:
Authorization: Bearer hpd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- We issue an API key and a webhook secret during onboarding. They are only displayed once—save them in your secret manager right away.
- Missing, invalid, or malformed keys return 401
{"reason":"unauthorized"}. - HTTPS is mandatory. Unencrypted
http://calls fail instantly with 403{"reason":"https_required"}before key validation. Keep this key secure; it authorizes charges to your payment method. - Order creation is rate-limited per account over a rolling 24-hour window. If you hit 429
{"reason":"daily_limit_exceeded"}, reach out to support to increase your threshold.
Versioning: The API version is scoped in the URL path (/v1). Any breaking updates will launch under a new path like /v2, leaving /v1 untouched.
Onboarding
API integration requires an active House Plant Dropship account. Credentials are set up manually by our team. Before provisioning, you will need to supply:
- A public callback URL — an HTTPS endpoint to receive webhook events. Loopbacks and internal IPs are not accepted.
- A payment method — configured via Stripe (card or ACH) to settle fulfillment charges.
- A billing name and address — printed on your monthly invoice.
Once set up, we will hand off your credentials and confirm your endpoint. If you ever need to rotate your key, contact support. Key rotation takes effect immediately with no overlap period, so make sure to sync the deployment on your end.
Monthly invoice
On the 1st of each month we email a PDF invoice of the previous month's orders to your account email. It lists each order with your external_order_ref, the amount charged, and any cancellations or refunds. Orders are paid as they are placed, so nothing is due.
Going live
There is no separate sandbox environment. Every call to the host above hits production, meaning accepted orders will trigger live fulfillment and charge your account. We recommend placing a small test order first and checking in with your account manager so we can monitor the initial run.
Quick start
Submit an order and fetch its status. The response from POST /orders immediately confirms if the order was accepted and charged—no secondary confirmation step needed. To test authentication without placing an order, call GET /inventory first.
curl -X POST https://api.houseplantdropship.com/v1/orders \
-H "Authorization: Bearer $HPD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"external_order_ref": "RB-1042",
"line_items": [{ "sku": "4_MONSTERA_DELICIOSA", "quantity": 2 }],
"shipping_address": {
"first_name": "Nora", "last_name": "Chen",
"address1": "12 Fern Ct", "city": "Boise",
"province": "ID", "zip": "83702", "country_code": "US"
}
}'
# Check status later using your order reference
curl https://api.houseplantdropship.com/v1/orders/RB-1042 \
-H "Authorization: Bearer $HPD_API_KEY"
Submit an order
Synchronous endpoint. The payload response instantly confirms whether the order was accepted and charged. Safe to retry using the same external_order_ref (see Idempotency & retries).
Request body
Always set Content-Type: application/json. Omitting this header prevents payload parsing and causes requests to fail with 422 invalid_order_ref.
{
"external_order_ref": "RB-1042",
"line_items": [
{ "sku": "4_MONSTERA_DELICIOSA", "quantity": 2 }
],
"shipping_address": {
"first_name": "Nora",
"last_name": "Chen",
"address1": "12 Fern Ct",
"address2": null,
"city": "Boise",
"province": "ID",
"zip": "83702",
"country_code": "US",
"phone": null,
"company": null
}
}
external_order_ref— your order id. Must match^[A-Za-z0-9._-]{1,64}$. This is the key for every later status and cancel call, and for webhook correlation.line_items— one or more{ sku, quantity };quantitymust be ≥ 1.shipping_address—address1,city,zip, andprovinceare required;first_name,last_name,address2,country_code,phone, andcompanyare optional. HPD ships within the U.S. only:zipmust use12345or12345-6789format,provincemust be a valid two-letter U.S. state, territory, or military code, andcountry_codedefaults toUS. A non-U.S. country, malformed ZIP, or missing or invalid state, territory, or military code is rejected with 422unshippable_address.
Response — 201 Created (new order) or 200 OK (re-sent accepted order)
{
"order_id": 84,
"hpd_order_number": "HPD-777777",
"status": "accepted",
"payment": {
"status": "completed",
"amount_cents": 4630,
"method_type": "us_bank_account"
},
"line_items": [
{ "sku": "4_MONSTERA_DELICIOSA", "quantity": 2, "title": "Monstera Deliciosa 4\"" }
]
}
payment.status— Returnscompletedfor settled charges orprocessingfor initiated bank transfers (ACH).processingconfirms success; fulfillment begins immediately without waiting for settlement.payment.amount_cents— Total charge amount in cents. Total cost is combined—we don't separate processing fees.
Order total pricing: We do not offer a separate quote endpoint. Total charges (items, shipping rates, and seasonal cold-pack insulation if needed) are calculated dynamically upon order creation and returned in payment.amount_cents. Catalog figures reflect base product pricing only.
Errors & Edge Cases
Check the error reference for full error lists. Pay close attention to these two scenarios:
- 402
payment_failed— Payment was declined. Update your billing details, then resend the order using the exact same reference ID. - 503
payment_state_unknown— Review the reconciliation instructions below.
payment_state_unknown. This means the payment state is indeterminate and awaiting manual verification. Resending the request is safe and will not double-charge, but it will continue returning 503 until resolved. Contact support and poll GET /orders/:ref instead.Order status
Primary endpoint for order updates. Use this to poll current order state or check status if a webhook is missed.
Response
{
"external_order_ref": "RB-1042",
"order_id": 84,
"hpd_order_number": "HPD-777777",
"status": "OPEN",
"payment": {
"status": "completed",
"amount_cents": 4630,
"method_type": "us_bank_account"
},
"cancellation_status": null,
"tracking": {
"company": "USPS",
"number": "9400...",
"url": "https://tools.usps.com/..."
}
}
Invalid or unmapped references return 404 {"reason":"not_found"}.
Order lifecycle
| Field | Values | Meaning |
|---|---|---|
status |
OPENFULFILLEDCANCELLED |
Order accepted, waiting to be packed. Shipped; details populated in tracking.Cancelled; this reference ID cannot be reused. |
payment.status |
completedprocessing |
Charge settled. Bank transfer (ACH) initiated. Fulfillment proceeds immediately. |
cancellation_status |
nullrequestedacceptedrejected |
No cancellation active. Cancellation request sent to warehouse, pending confirmation. Order successfully cancelled. Cancellation request declined by warehouse. |
tracking |
null{ company, number, url } |
Returns null until shipped, then populates with carrier details and tracking URL. |
Cancel an order
Cancels an order any time before it ships. Unpaid drafts cancel the vendor draft. Paid, unshipped orders are stopped with the fulfillment vendor (ShipStation is the ship authority), then refunded automatically — immediately when the original charge has settled, or when an unsettled bank (ACH) debit settles. Shipped orders cannot be cancelled through the API.
Response
- 200 OK
{"external_order_ref":"RB-1042","cancellation_status":"accepted"}— cancelled (refund issued now, or pending settlement for an unsettled bank payment). Re-POSTing a cancelled ref is idempotent 200. - 409
{"reason":"cannot_cancel","detail":"..."}— already shipped (contact HPD for a return/refund), or a charge is still settling with unknown money state. - 503
{"reason":"refund_pending"}— stopped with the vendor but the refund did not complete; safe to retry (idempotent). Ops can finish viarefunds:resolve. - 404 unknown ref; 502
{"reason":"vendor_unavailable"}if the fulfillment vendor is unreachable — retry later; the order is unchanged.
The order.cancelled webhook fires on paid cancels. Its message states whether the refund was issued now or will follow bank-payment settlement.
Inventory
Returns available stock counts indexed by SKU. We suggest polling every 10–15 minutes.
Response
{ "inventory": { "4_MONSTERA_DELICIOSA": 12, "6_SNAKE_LAURENTII": 3, "4_PALM_PARLOR": 27 } }
Inventory counts mirror cached internal balances and may occasionally lag by a few moments. Live stock checks at order creation remain authoritative, so an order can still return out_of_stock even if inventory previously appeared available.
Catalog
Returns all active SKUs along with titles and base bank-transfer pricing in cents (price_cents). Use this endpoint to build and refresh your local product mappings; run daily or as needed.
Response
{ "catalog": [ { "sku": "4_MONSTERA_DELICIOSA", "title": "Monstera Deliciosa 4\"", "price_cents": 1250, "available_until": null }, { "sku": "4_PALM_PARLOR", "title": "Parlor Palm 4\"", "price_cents": 800, "available_until": null } ] }
price_cents— the per-unit product price in USD cents when paying by bank. Shipping and any automatically added cold-protection items are calculated at order time. Card and bank pricing are explained during onboarding;payment.amount_centsis the actual charged total. Catalog prices are a snapshot, not a locked order quote.available_untilisnullfor almost everything. When HPD plans to stop carrying a SKU it is set to the last date we expect to ship it — wind the listing down before then.- Re-pull the catalog daily. A SKU that is not in the catalog cannot be ordered. The
catalog.updatedwebhook'sdiscontinuedlist is the signal to remove a listing. If a SKU disappears without having been announced, treat it as a pause, not a removal — contact HPD if it is still missing after a day. - A SKU can also become briefly unavailable without being discontinued. It stays in the catalog,
GET /inventoryreports0, and orders for it returnout_of_stock. Treat quantity 0 as "pause the listing", not "delete it" — it may come back. - There is no quote endpoint. You cannot price a basket in advance: the final charged total — products, shipping, and any automatic cold-protection items — is first known when the order is accepted, in
payment.amount_cents. - A SKU absent from the catalog cannot be ordered — submitting it returns
unknown_sku,discontinued_sku, orsku_not_fulfillable. - Pair with GET /inventory for stock quantities; the catalog lists what exists, inventory how many are available.
Idempotency & retries
Every order relies on external_order_ref as its unique idempotency key. Safely retry POST /orders calls using the same reference ID:
- If the initial attempt succeeded, retrying returns the current status (200) without duplicate charges.
- If payment declined (402), update billing and retry the order using the same reference ID to re-trigger payment.
- If payment status was unclear (503), retrying maintains the 503 response until reconciled—it will not cause double charges.
Only reuse reference IDs when retrying identical orders. Cancelled order references cannot be reused (409 order_cancelled)—generate a new reference ID for new requests.
Webhooks
We push real-time order status updates to your callback URL as events occur. Webhooks serve as event triggers, but GET /orders/:ref remains the primary source of truth. Events are delivered at least once, so build your handler to process duplicate payloads gracefully.
Events
| Event | Payload (beyond event) |
|---|---|
order.fulfilled | hpd_order_number, tracking: { company, number, url } |
order.cancelled | hpd_order_number, message |
order.cancellation_rejected | hpd_order_number, message |
catalog.updated | discontinuing: [{sku, available_until}], discontinued: [{sku}], restored: [{sku}] — no external_order_ref |
The three order.* events above also carry external_order_ref to correlate with your order. catalog.updated is sent at most once a night, only when something changed. discontinuing = still orderable, going away on the date. available_until: null in discontinuing means a planned discontinuation was cancelled. discontinued = no longer orderable, remove the listing. restored = a discontinued SKU is orderable again. Any of the three arrays may be empty.
{
"event": "order.fulfilled",
"external_order_ref": "RB-1042",
"hpd_order_number": "HPD-777777",
"tracking": { "company": "USPS", "number": "9400...", "url": "https://..." }
}
Verifying the signature
Every delivery carries an HMAC-SHA256 signature of the raw request body, keyed with your webhook secret (not your API key):
X-HPD-Signature: sha256=<hex HMAC-SHA256(raw_body, webhook_secret)>
Verify it before trusting the payload: compute the HMAC over the exact bytes you received and compare in constant time.
# Ruby
expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", ENV["HPD_WEBHOOK_SECRET"], raw_body)
Rack::Utils.secure_compare(expected, request.headers["X-HPD-Signature"].to_s)
# Python
import hmac, hashlib
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
hmac.compare_digest(expected, request.headers.get("X-HPD-Signature", ""))
// Node
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.get("X-HPD-Signature") || ""));
Retries & reliability
If your endpoint doesn't return a 2xx, HPD retries with exponential backoff over roughly a day, then gives up. Retries resend the identical body, and a delivery can be missed entirely — so reconcile against GET /orders/:ref rather than relying on webhooks alone. Respond 2xx quickly and do the work asynchronously.
Error reference
Every error body carries a reason; most also include a human-readable detail. The 502/503 payment responses instead carry order_id (and payment when money moved). Nothing is persisted or charged for a 422 — those gates run before any order is created.
| HTTP | Reason | Meaning | Your move |
|---|---|---|---|
| 401 | unauthorized | Bad or missing API key | Check the Authorization header |
| 403 | https_required | Plaintext request | Use https:// |
| 422 | invalid_order_ref | Ref fails the format | Use ^[A-Za-z0-9._-]{1,64}$ |
| 422 | invalid_line_items | Missing/empty items or quantity < 1 | Fix the line items |
| 422 | unshippable_address | Missing address1/city/zip | Complete the address |
| 422 | unknown_sku | SKU not in the catalog | Remove or correct the SKU |
| 422 | discontinued_sku | SKU permanently no longer carried | Remove the SKU |
| 422 | sku_not_fulfillable | SKU missing fulfillment data | Contact HPD; don't retry as-is |
| 422 | out_of_stock | Not enough stock, or the SKU is temporarily unavailable | Reduce quantity or wait for restock |
| 422 | shop_not_approved | Account not cleared for intake | Contact HPD |
| 402 | payment_failed | Charge declined | Fix payment method, re-POST same ref |
| 409 | cannot_cancel | Already shipped, or charge settling with unknown money state | Shipped: contact HPD for return/refund. Settling: retry shortly or contact HPD |
| 409 | order_cancelled | Ref belongs to a cancelled order (intake only) | Use a new ref |
| 429 | daily_limit_exceeded | Rolling 24-hour order limit reached | Contact HPD to raise the limit |
| 502 | vendor_unavailable | Fulfillment vendor unreachable | Retry later; a payment block in the body means money moved — don't re-order |
| 503 | refund_pending | Cancel stopped the vendor; refund did not complete | Safe to retry cancel (idempotent); ops may use refunds:resolve |
| 503 | payment_state_unknown | Charge outcome unknown, reconciling | Do not auto-retry. Poll status; contact HPD |
Integration checklist
Everything you need to build on your side:
- A secret store for the API key and webhook secret.
POST /orderswith retry on the sameexternal_order_ref.- A webhook receiver that verifies
X-HPD-Signatureand is idempotent. - A reconciliation poll against
GET /orders/:refas the source of truth.
Questions or credential rotation: contact your HPD integration contact.
For coding agents
Most partners point an AI coding agent at this page. The block below is the whole API in plain text — copy it into your agent, along with your API key from onboarding.
HPD EXTERNAL STORE API — v1 — condensed spec (updated November 2026)
BASE URL
https://api.houseplantdropship.com/v1
JSON in, JSON out. POST bodies require the header Content-Type: application/json;
without it the body is not parsed and the request is rejected 422 invalid_order_ref.
There is no sandbox base URL — every request hits the production system, orders are
real, and an accepted order charges your payment method. Make your first order a
small real one and coordinate it with your HPD contact.
The version is in the path (/v1). A breaking change ships as /v2; /v1 keeps working.
AUTHENTICATION
Header: Authorization: Bearer hpd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
HPD issues the API key and a separate webhook secret during onboarding. Both are
shown once and cannot be recovered — store them in a secret manager immediately.
Rotation invalidates the old key immediately; there is no overlap window.
401 unauthorized missing, malformed, or unknown key
403 https_required plaintext http:// request, refused before the key is read
429 daily_limit_exceeded per-shop rolling 24-hour intake limit, set well above
normal volume — contact HPD to raise it
ENDPOINTS
POST /orders submit an order (synchronous; charges)
GET /orders/:external_order_ref order status (source of truth)
POST /orders/:external_order_ref/cancel cancel before shipping (auto-refund if paid)
GET /inventory available stock by SKU
GET /catalog orderable SKUs + per-unit bank price
POST /orders
Synchronous: the response says whether the order was accepted and paid. There is
no separate confirmation step. Idempotent on external_order_ref.
request:
external_order_ref your order id; must match ^[A-Za-z0-9._-]{1,64}$; the key for
every later status/cancel call and for webhook correlation
line_items one or more { sku, quantity }; quantity must be >= 1
shipping_address first_name, last_name, address1, address2, city, province,
zip, country_code, phone, company
required: address1, city, zip, province — the rest optional
U.S.-only: zip = 12345 or 12345-6789; province = valid
2-letter state/territory/military code; country_code defaults
to US; bad country/zip/province -> 422 unshippable_address
response 201 Created (first time) or 200 OK (re-POST of an accepted order):
{ order_id, hpd_order_number, status: "accepted",
payment: { status, amount_cents, method_type },
line_items: [ { sku, quantity, title } ] }
payment.status is "completed" for a settled charge or "processing" for an
initiated bank (ACH) debit. "processing" IS a success — the order ships on an
initiated debit; do not wait for settlement.
payment.amount_cents is the amount charged. There is never a separate card or
processing "fee" line — pricing is quoted as a single total.
There is no quote endpoint. Shipping and any automatically added cold-protection
items are calculated at order time, so the final charged total (products +
shipping + those items) is first known when the order is accepted, in
payment.amount_cents.
failures: 402 payment_failed — fix the payment method, re-POST the SAME ref.
503 payment_state_unknown — do NOT auto-retry (see ERRORS).
GET /orders/:external_order_ref
Source of truth. Poll it for current state and as the fallback for a missed webhook.
response:
{ external_order_ref, order_id, hpd_order_number, status,
payment: { status, amount_cents, method_type },
cancellation_status,
tracking: { company, number, url } }
order lifecycle values:
status OPEN accepted, awaiting fulfillment
FULFILLED shipped; tracking is populated
CANCELLED cancelled; the ref cannot be reused
payment.status completed charge settled
processing bank (ACH) debit initiated — also a success;
the order ships on an initiated debit
cancellation_status null no cancellation asked for
requested sent to the fulfillment vendor, unanswered
accepted cancelled
rejected the vendor refused the cancellation
tracking null until the order ships, then { company, number, url }
unknown ref -> 404 {"reason":"not_found"}
POST /orders/:external_order_ref/cancel
Cancels an order any time before it ships. Unpaid drafts cancel the vendor
draft. Paid unshipped orders stop at ShipStation via the vendor, then refund
automatically (immediately if settled; on settlement for unsettled ACH).
200 OK {"external_order_ref":"RB-1042","cancellation_status":"accepted"}
(idempotent on re-POST of a cancelled ref)
409 cannot_cancel already shipped, or a charge is settling with unknown state
503 refund_pending vendor stopped; refund pending — safe to retry
404 unknown ref
502 vendor_unavailable — retry later; order unchanged
order.cancelled webhook message says whether the refund issued now or is pending.
GET /inventory
Full snapshot of available stock by SKU. Poll every 10-15 minutes.
{ "inventory": { "4_MONSTERA_DELICIOSA": 12, "6_SNAKE_LAURENTII": 3, "4_PALM_PARLOR": 27 } }
Values can be briefly stale — they mirror an internal cache. The order-time stock
gate is authoritative, so an order may still be rejected out_of_stock even if
inventory looked sufficient.
GET /catalog
Every SKU that has the pricing and weight data intake requires: sku, title, and the
per-unit bank-payment price_cents (weight itself is not exposed). Use it to build
and maintain your SKU mapping; re-poll daily or on demand.
{ "catalog": [ { "sku": "4_MONSTERA_DELICIOSA", "title": "Monstera Deliciosa 4\"",
"price_cents": 1250, "available_until": null },
{ "sku": "4_PALM_PARLOR", "title": "Parlor Palm 4\"",
"price_cents": 800, "available_until": null } ] }
price_cents is the per-unit product price in USD cents when paying by bank. Shipping
and any automatically added cold-protection items are calculated at order time. Card
and bank pricing are explained during onboarding; payment.amount_cents is the actual
charged total. Catalog prices are a snapshot, not a locked order quote.
available_until is null for almost everything; when set, it is the last date HPD
expects to ship that SKU. Re-pull the catalog daily. A SKU that is not in the
catalog cannot be ordered. The catalog.updated webhook's discontinued list is the
signal to remove a listing. If a SKU disappears without having been announced,
treat it as a pause, not a removal — contact HPD if it is still missing after a
day. A SKU can also go briefly unavailable without being discontinued: it stays in
the catalog, GET /inventory reports 0, and orders return out_of_stock. Treat
quantity 0 as "pause the listing", not "delete it" — it may come back.
A SKU absent from the catalog cannot be ordered — submitting it returns
unknown_sku, discontinued_sku, or sku_not_fulfillable.
Pair with GET /inventory for stock quantities: the catalog lists what exists,
inventory how many are available.
IDEMPOTENCY AND RETRIES
external_order_ref is the idempotency key. Retrying POST /orders with the same ref
is always safe:
first attempt charged -> the retry returns the current state (200) and
never charges again
first attempt declined (402) -> the retry re-attempts the charge; use it after
the payment method is fixed
outcome unknown (503) -> the retry stays 503 until HPD reconciles; it
never double-charges
Reuse a ref only for genuine retries of the SAME order. A cancelled ref cannot be
reused (409 order_cancelled); start a new order with a new ref.
WEBHOOKS
HPD POSTs events to your callback URL (HTTPS, public host) as they happen.
Webhooks are an optimization — GET /orders/:ref is the source of truth. Delivery is
at-least-once: the same event may arrive more than once, so make the handler
idempotent.
events (order.* events carry event + external_order_ref, plus):
order.fulfilled hpd_order_number, tracking { company, number, url }
order.cancelled hpd_order_number, message
order.cancellation_rejected hpd_order_number, message
catalog.updated (no external_order_ref) fires at most once a night, only when
something changed:
discontinuing [{sku, available_until}] still orderable, going away on the date
available_until: null means a planned discontinuation was cancelled
discontinued [{sku}] no longer orderable, remove the listing
restored [{sku}] a discontinued SKU is orderable again
(any of the three arrays may be empty)
example body:
{ "event": "order.fulfilled", "external_order_ref": "RB-1042",
"hpd_order_number": "HPD-777777",
"tracking": { "company": "USPS", "number": "9400...", "url": "https://..." } }
signature header:
X-HPD-Signature: sha256=<hex HMAC-SHA256(raw_body, webhook_secret)>
Every delivery is signed over the RAW request body, keyed with the webhook secret
(not the API key). Verify before trusting the payload: compute the HMAC over the
exact bytes received and compare in constant time.
If your endpoint does not return 2xx, HPD retries with exponential backoff over
roughly a day, then gives up. Retries resend the identical body, and a delivery can
be missed entirely — reconcile against GET /orders/:ref rather than relying on
webhooks alone. Respond 2xx quickly and do the work asynchronously.
ERRORS
Every error body carries a reason; most also include a human-readable detail. The
502/503 payment responses instead carry order_id (and payment when money moved).
Nothing is persisted or charged for a 422 — those gates run before any order is
created.
HTTP reason meaning your move
401 unauthorized bad or missing API key check the Authorization header
403 https_required plaintext request use https://
422 invalid_order_ref ref fails the format use ^[A-Za-z0-9._-]{1,64}$
422 invalid_line_items missing/empty items or qty < 1 fix the line items
422 unshippable_address missing address1/city/zip complete the address
422 unknown_sku SKU not in the catalog remove or correct the SKU
422 discontinued_sku SKU permanently no longer carried remove the SKU
422 sku_not_fulfillable SKU missing fulfillment data contact HPD; don't retry as-is
422 out_of_stock not enough stock, or the SKU is temporarily unavailable reduce quantity or wait for restock
422 shop_not_approved account not cleared for intake contact HPD
402 payment_failed charge declined fix payment method, re-POST same ref
409 cannot_cancel already shipped, or charge settling unknown shipped: contact HPD;
settling: retry shortly
409 order_cancelled ref belongs to a cancelled order use a new ref
429 daily_limit_exceeded rolling 24-hour order limit hit contact HPD to raise the limit
502 vendor_unavailable fulfillment vendor unreachable retry later; a payment block in
the body means money moved — don't re-order
503 refund_pending vendor stopped; refund incomplete safe to retry cancel; ops may
use refunds:resolve
503 payment_state_unknown charge outcome unknown, reconciling do NOT auto-retry; poll status;
contact HPD
MONTHLY INVOICE
On the 1st of each month HPD emails a PDF invoice of the previous month's orders
(Pacific time) to your account email: each order's external_order_ref, amount
charged, and any refunds. Orders are paid as placed, so nothing is due. There is
no invoice endpoint.
INTEGRATION CHECKLIST
1. A secret store for the API key and webhook secret.
2. POST /orders with retry on the same external_order_ref.
3. A webhook receiver that verifies X-HPD-Signature and is idempotent.
4. A reconciliation poll against GET /orders/:ref as the source of truth.
Questions or credential rotation: contact your HPD integration contact.

