Skip to content
Please don't forget to add WINTER SHIPPING PROTECTION to your orders if average daytime temps drop below 50°F
Please don't forget to add WINTER SHIPPING PROTECTION to your orders if average daytime temps drop below 50°F
On this page

House Plant Dropship · Developer

External Store API

v1

Updated 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.

Base URL https://api.houseplantdropship.com/v1

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:

  1. A public callback URL — an HTTPS endpoint to receive webhook events. Loopbacks and internal IPs are not accepted.
  2. A payment method — configured via Stripe (card or ACH) to settle fulfillment charges.
  3. 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"
POST /orders

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 }; quantity must be ≥ 1.
  • shipping_address — address1, city, zip, and province are required; first_name, last_name, address2, country_code, phone, and company are optional. HPD ships within the U.S. only: zip must use 12345 or 12345-6789 format, province must be a valid two-letter U.S. state, territory, or military code, and country_code defaults to US. A non-U.S. country, malformed ZIP, or missing or invalid state, territory, or military code is rejected with 422 unshippable_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 — Returns completed for settled charges or processing for initiated bank transfers (ACH). processing confirms 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.
Do not automatically retry a 503 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.
GET /orders/:external_order_ref

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

FieldValuesMeaning
status OPEN
FULFILLED
CANCELLED
Order accepted, waiting to be packed.
Shipped; details populated in tracking.
Cancelled; this reference ID cannot be reused.
payment.status completed
processing
Charge settled.
Bank transfer (ACH) initiated. Fulfillment proceeds immediately.
cancellation_status null
requested
accepted
rejected
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.
POST /orders/:external_order_ref/cancel

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 via refunds: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.

GET /inventory

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.

GET /catalog

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_cents is the actual charged total. Catalog prices are a snapshot, not a locked order quote.
  • available_until is null for 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.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 become briefly unavailable without being discontinued. It stays in the catalog, GET /inventory reports 0, and orders for it return out_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, or sku_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

EventPayload (beyond event)
order.fulfilledhpd_order_number, tracking: { company, number, url }
order.cancelledhpd_order_number, message
order.cancellation_rejectedhpd_order_number, message
catalog.updateddiscontinuing: [{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.

HTTPReasonMeaningYour move
401unauthorizedBad or missing API keyCheck the Authorization header
403https_requiredPlaintext requestUse https://
422invalid_order_refRef fails the formatUse ^[A-Za-z0-9._-]{1,64}$
422invalid_line_itemsMissing/empty items or quantity < 1Fix the line items
422unshippable_addressMissing address1/city/zipComplete the address
422unknown_skuSKU not in the catalogRemove or correct the SKU
422discontinued_skuSKU permanently no longer carriedRemove the SKU
422sku_not_fulfillableSKU missing fulfillment dataContact HPD; don't retry as-is
422out_of_stockNot enough stock, or the SKU is temporarily unavailableReduce quantity or wait for restock
422shop_not_approvedAccount not cleared for intakeContact HPD
402payment_failedCharge declinedFix payment method, re-POST same ref
409cannot_cancelAlready shipped, or charge settling with unknown money stateShipped: contact HPD for return/refund. Settling: retry shortly or contact HPD
409order_cancelledRef belongs to a cancelled order (intake only)Use a new ref
429daily_limit_exceededRolling 24-hour order limit reachedContact HPD to raise the limit
502vendor_unavailableFulfillment vendor unreachableRetry later; a payment block in the body means money moved — don't re-order
503refund_pendingCancel stopped the vendor; refund did not completeSafe to retry cancel (idempotent); ops may use refunds:resolve
503payment_state_unknownCharge outcome unknown, reconcilingDo not auto-retry. Poll status; contact HPD

Integration checklist

Everything you need to build on your side:

  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.

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.

Plain-text API spec
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.