EasyPod Partner API

Exchange your apiKey + secret for a 24-hour bearer token. The JWT carries your dealer id; every subsequent call is auto-scoped to your dealer's shops.

Posted to Identity (https://id.customhub.io), not the API host.

Re-exchange when the token nears expiry — there's no separate refresh-token flow in v1.

Page through every active model in the catalog. Use search to filter by model name or code.

Each row carries a dealer-specific pricing summary — the lowest ("from") price across the model's variations on your price list. Full per-variation pricing is on GET /models/{id}.

The top-level listPrice / price fields are tenant-wide defaults and are often 0 — read your real numbers from pricing. Each from* value is the cheapest across the model's variations on your price list; pricing is null only when none of the model's variations are priced for your account.

Returns the full model with every orderable variation SKU, all images, supported placements, and product copy (material, care, sizing, …).

Use variations[].sku in items[].sku on POST /orders, and placements[].code in designs[].placement.

Every variation carries your exact pricing (blank cost, handling fee, unit/list price) and every placement lists its printMethods with your exact per-placement print charge — enough to compute the full item cost without quoting: blankCost + printMethods[].price (per printed placement) + handlingFee.

Placements have a stable code (width1..width5, width7, width8, plus gang_sheet) and a human label — the tenant's configured placement title (e.g. Front, Pocket, Back, Left Sleeve, Right Sleeve). In designs[].placement you may send either the code or that label (case-insensitive) — both resolve to the same placement. Real-world meaning varies per garment, so pick a placement by its dimensions and the position you see in the mockup.

Computing your cost — an item's all-in production cost is variations[].pricing.blankCost + the printMethods[].price of each placement you print + handlingFee. Example above: blank 5.68 + one front DTF print 2.50 = 8.18. These are the same numbers the order engine bills at approval, so you can seed your cost table straight from the catalog. priceSource tells you how firm the number is: dealer (an explicit price for that placement + method), dealer_default (the placement's default), dealer_location_fallback (cheapest configured method at that placement), or global (tenant-wide fallback). Shipping is quoted separately — see POST /orders/quote.

Returns the same computedCost shape that POST /orders returns, without persisting an order, reserving an externalOrderId, ingesting designs, or running the wallet headroom check.

Use it to show your customer the total at checkout before committing.

Quoting does not check your wallet. Neither does POST /orders — orders are always accepted as ApprovalPending, and an underfunded order waits there until the wallet covers it. Check headroom via GET /api/v1/balance.

Submit a new order. Returns the locked cost breakdown so you can show your customer the total before approval.

Idempotency: externalOrderId doubles as the per-dealer idempotency key. Retrying a successful create with the same id + identical body returns the original response; a different body for that id returns 409 EXTERNAL_ORDER_ID_CONFLICT. A create that failed (4xx/5xx, no order created) is not cached — fix the problem and retry with the same externalOrderId.

Design files — we download from your URL, validate format (PNG/JPEG only in v1), and re-host on our storage. The URL must be HTTPS and publicly reachable at submit time. Max 100 MB.

Bring Your Own Label — include shippingLabel (requires the orders_selfship scope) to ship with your own pre-purchased label (see the BYOL example tab above). You provide a URL to your already-hosted label file in labelUrl — there is no binary file upload. We download the label at submit, convert it to a 4x6 PNG and host it ourselves, so the URL only has to be reachable at submit time (PDF, PNG or JPEG, HTTPS, ≤500 chars, ≤25 MB; ZPL is not accepted). If we can't fetch or convert it, the order is rejected with a LABEL_* error and you can retry with the same externalOrderId. Any carrier is accepted (it is free-text — e.g. UniUni). EasyPod skips buying a carrier label and charges $0 postage (the box/handling fee still applies, since we still produce and pack the order).

Returns the full order with its owning shop (shopId + shopName), current addresses, items (with their re-hosted design URLs and any submitted proof URLs), all shipments, the locked cost breakdown, rejection details (if applicable), and a sanitized event log.

Each item carries options[] — its resolved {name, value} option rows (Size, Color) in display order — and personalization, the buyer's personalization text from a marketplace listing (e.g. Etsy), or null. These matter most for orders imported from a connected store rather than created through this API.

Page through your orders. Filter by status, by since (createdAt ≥), by your own externalOrderId for lookup after a network retry, or by shopId to list one shop's orders. Each row carries the owning shopId + shopName.

Cancels an order only while it is in ApprovalPending — i.e. before an admin has approved it.

Idempotent: cancelling an already-cancelled order returns the current state with 200. After admin approval, contact your account team.

Add designs to an existing item while the order is still ApprovalPending. A design whose placement is already used replaces the existing one.

The order cost is recomputed and returned (placements are priced independently). This does not re-check wallet balance — the order already cleared that at create. Send at most one design per placement; after admin approval you get 409 ORDER_NOT_MUTABLE.

Discover valid placement codes and their supported print methods via GET /api/v1/models/{id} — each placement lists maxWidthInches/maxHeightInches and a printMethods[] array.

Returns every shop you own, earliest first. The one with isDefault: true is used when an order omits shopId.

Create a shop to group orders. The first shop you create (or the one auto-provisioned on your first order) becomes your default. Max 100 shops per dealer.

Errors: 422 SHOP_NAME_REQUIRED, 422 INVALID_CURRENCY, 422 SHOP_LIMIT_REACHED (100-shop cap), 403 FORBIDDEN (no linked dealer).

Update a shop's display name. Returns the updated shop.

404 SHOP_NOT_FOUND if the id isn't one of your shops.

Soft-deletes a shop. Orders already placed in it are unaffected. If it was your default, the next-earliest shop becomes the new default. You must always keep at least one shop.

422 CANNOT_DELETE_LAST_SHOP if it's your only shop; 404 SHOP_NOT_FOUND if the id isn't one of your shops.

Returns the caller dealer's current balance, credit limit, and remaining headroom. Order creation never rejects for balance: an order your wallet can't cover is still accepted as ApprovalPending and is held there until it's funded. Call this to know in advance whether an order will be approvable.

balance > 0 means the dealer owes that amount; balance < 0 means there is credit on file.headroom = creditLimit − balance.