Orders - Hoard

List orders

Read the seller’s order history, newest first, with the same filters the Hoard dashboard exposes. Each order can optionally embed its line items.

GET /api/orders

This endpoint is mounted at /api/orders, not /api/v1/orders — the /api/v1/orders POST is a separate upload surface (see below). Bearer authentication is supported (Authorization: Bearer YOUR_API_KEY) for AI assistants and integrations.

Line items

By default, each order in the response carries up to 20 line items, sorted by id ascending. The response also includes items_truncated and items_total_count so the caller knows whether they got every item.

?items_per_order=N — change the cap. Clamped to 0..200. 0 omits items entirely (legacy callers that only need order headers).
?items=full — return every line item on every order. Use this when building a packing slip or auditing a refund. Pairs poorly with very wide pages — prefer per_page=10&items=full over per_page=200&items=full.

When items are returned, each item has this shape:

Field	Type	Description
`id`	integer	Line item id.
`product_name`	string	Card or product name.
`product_line`	string	Game (`Magic`, `Pokemon`, `Lorcana`, etc.).
`condition`	string	TCGplayer condition string (`Near Mint`, `Lightly Played`, …).
`quantity`	integer	Units sold.
`unit_price`	string	USD as a string (preserves trailing zeros).
`line_total`	string	`quantity × unit_price`, rounded to two decimals.

Refund, discount, tax, and internal id fields are intentionally omitted from the embedded line-item shape. If you need per-line refund detail, the dashboard exposes it on the individual order page. Order-level refund fields are present on each order header: refund_type (full / partial), refund_origin (who initiated it, e.g. tcgplayer), refund_amt (refunded dollars as a USD string), refund_reason, and refund_note. All are null when the order was not refunded; refund_amt being absent means “not refunded”, distinct from a $0 refund. refund_reason and refund_note are buyer/marketplace-authored free text — on this read surface they are length-bounded and stripped of control / zero-width characters.

Other filters

All standard order filters work — pass any combination:

page (default 1), per_page (default 50, max 200)
sort = date | total | buyer | status | number (default date), direction = asc | desc (default desc)
status — one status, or status[]=Completed&status[]=Refunded for many
search — order number or buyer name (case-insensitive substring)
date_from, date_to — YYYY-MM-DD window on order_date
product_line — restrict to orders containing at least one item in the given game
refund=true — only refunded orders
unfeedbacked=true — only orders with no seller feedback yet
shipping_type = pwe | tracked | expedited
ship_mark=pending — only orders the seller has marked Shipped that have not yet synced back from TCGplayer (the “pushing to TCGplayer” working set). Each order row carries shipped_marked_at (timestamp, null if never marked) and marked_shipped_pending (boolean, true while the optimistic mark is still ahead of the synced status).
pull_session — a pull session id, or one of: active (the open session), none (available to pull — excludes dismissed orders), dismissed (orders excluded from pulls). Each order row includes pull_dismissed_at (timestamp, null when the order is still pullable).

Example response

{
  "orders": [
    {
      "id": 12345,
      "order_number": "ORD-12345",
      "buyer_name": "Alice",
      "order_date": "2026-05-18",
      "order_placed_at": "2026-05-18T14:32:00Z",
      "status": "Completed",
      "product_amt": "24.99",
      "shipping_amt": "0.99",
      "total_amt": "25.98",
      "shipping_type": "pwe",
      "item_count": 2,
      "shipped_marked_at": null,
      "marked_shipped_pending": false,
      "items": [
        {
          "id": 901,
          "product_name": "Lightning Bolt",
          "product_line": "Magic",
          "condition": "Near Mint",
          "quantity": 2,
          "unit_price": "1.50",
          "line_total": "3.00"
        },
        {
          "id": 902,
          "product_name": "Counterspell",
          "product_line": "Magic",
          "condition": "Lightly Played",
          "quantity": 1,
          "unit_price": "21.99",
          "line_total": "21.99"
        }
      ],
      "items_truncated": false,
      "items_total_count": 2
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50,
  "total_pages": 1,
  "status_counts": {"Completed": 1},
  "pull_sessions": []
}

curl example

# Header-only (no line items)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.tryhoard.com/api/orders?items_per_order=0"

# Every line item on every order in the page
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.tryhoard.com/api/orders?per_page=25&items=full"

Upload orders

Upload parsed order data from TCGplayer’s order export. The request is shape-validated synchronously and queued for upsert in a background job — the response is 202 Accepted and the database write happens asynchronously. Orders are upserted by (user_id, order_number) so re-uploading the same orders is safe.

POST /api/v1/orders
Content-Type: application/json

The endpoint accepts both raw JSON and gzip-compressed JSON. For large batches (typically the first full-history upload), gzip is preferred — set Content-Type: application/gzip and gzip the JSON body. The server transparently decompresses gzip and falls back to raw bytes when the body is not gzip-encoded. Request body:

[
  {
    "order_number": "ORD-12345",
    "buyer_name": "John Doe",
    "order_date": "3/27/2026",
    "status": "Completed",
    "product_amt": 24.99,
    "shipping_amt": 0.99,
    "total_amt": 25.98
  }
]

Order object fields

Field	Type	Required	Description
`order_number`	string	Yes	TCGplayer order number. Used as the unique key for upserts.
`buyer_name`	string	No	Buyer’s display name from the order.
`order_date`	string	No	Order date as parsed from TCGplayer CSV (e.g., `"3/27/2026"`).
`status`	string	No	Order status from TCGplayer (e.g., `"Completed"`, `"Cancelled"`).
`product_amt`	number	No	Product subtotal in USD.
`shipping_amt`	number	No	Shipping amount in USD.
`total_amt`	number	No	Total order amount in USD.

Response:

{"status": "accepted", "count": 1}

HTTP status is 202 Accepted — the server has validated the payload shape and enqueued the upsert. The count field reflects the number of orders in the request (not the number of new rows — duplicates are updated in place). If an active Pull session exists, the same upload also checks refreshed orders against Pull eligibility. Orders that are now cancelled, shipped, refunded, or otherwise no longer pullable stay in the session but are marked for review so the tablet queue can warn the puller instead of silently dropping work.

curl example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"order_number":"ORD-12345","buyer_name":"John Doe","order_date":"3/27/2026","status":"Completed","product_amt":24.99,"shipping_amt":0.99,"total_amt":25.98}]' \
  https://www.tryhoard.com/api/v1/orders

For a large batch, gzip the JSON first:

gzip -c orders.json | curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/gzip" \
  --data-binary @- \
  https://www.tryhoard.com/api/v1/orders

Error responses

Code	Error code	Meaning
422	`invalid_json`	Request body is not valid JSON
422	`invalid_gzip`	`Content-Type` is `application/gzip` but the body is not valid gzip
422	`invalid_payload`	Body is not an array of order hashes, or a row is missing `order_number`
422	`empty_payload`	The orders array is empty
413	`payload_too_large`	Request body exceeds 10 MB on the wire
413	`decompressed_too_large`	Decompressed gzip body exceeds 50 MB
413	`too_many_rows`	More than 50,000 orders in a single request

Notes

Hoard parses TCGplayer’s order export CSV and converts it to this JSON format
First sync sends full order history (from January 2020)
Subsequent syncs send a rolling window of recent orders to keep their status current; older history is sent once and not re-sent every sync
Focused refresh_orders tasks reuse the same upload endpoint after Hoard fetches updated orders
Order upload is non-fatal. If it fails, the inventory sync still completes.
Active Pull sessions keep their snapshot stable; refreshed orders that drift out of eligibility are flagged in the Pull queue.

Upload order refunds

Upload parsed refund rows from TCGplayer’s order export. The request is shape-validated synchronously and queued for upsert in a background job — the response is 202 Accepted and the database write happens asynchronously. Refund rows are upserted by (user_id, order_number), either creating new orders or enriching existing ones with refund metadata.

POST /api/v1/order_refunds
Content-Type: application/json

The endpoint accepts both raw JSON and gzip-compressed JSON. For large batches, set Content-Type: application/gzip and gzip the JSON body. The server transparently decompresses gzip and falls back to raw bytes when the body is not gzip-encoded. Request body:

[
  {
    "order_number": "ORD-12345",
    "buyer_name": "John Doe",
    "product_amt": 24.99,
    "shipping_amt": 0.99,
    "total_amt": 25.98,
    "order_date": "3/27/2026",
    "status": "Refunded",
    "refund_type": "full",
    "refund_origin": "tcgplayer"
  }
]

Response:

{"status": "accepted", "count": 1}

HTTP status is 202 Accepted — the server has validated the payload shape and enqueued the upsert. The count field reflects the number of refund rows in the request.

curl example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"order_number":"ORD-12345","buyer_name":"John Doe","total_amt":25.98,"refund_type":"full","refund_origin":"tcgplayer"}]' \
  https://www.tryhoard.com/api/v1/order_refunds

For a large batch, gzip the JSON first:

gzip -c refunds.json | curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/gzip" \
  --data-binary @- \
  https://www.tryhoard.com/api/v1/order_refunds

Error responses

Code	Error code	Meaning
422	`invalid_json`	Request body is not valid JSON
422	`invalid_gzip`	`Content-Type` is `application/gzip` but the body is not valid gzip
422	`invalid_payload`	Body is not an array of objects, or a row is missing `order_number`
422	`empty_payload`	The refunds array is empty
413	`payload_too_large`	Request body exceeds 10 MB on the wire
413	`decompressed_too_large`	Decompressed gzip body exceeds 50 MB
413	`too_many_rows`	More than 50,000 refund rows in a single request

Upload order line items

Upload parsed line items for existing orders. The request is shape-validated synchronously and queued for upsert in a background job — the response is 202 Accepted and the database write happens asynchronously. Items are upserted by (order_id, sku_id). Items whose order_number has no matching order owned by the user are silently skipped, and multiple sku-less rows per order are allowed.

POST /api/v1/order_items
Content-Type: application/json

The endpoint accepts both raw JSON and gzip-compressed JSON. The same gzip fallback rules as /api/v1/orders apply. Request body:

[
  {
    "order_number": "ORD-12345",
    "product_name": "Lightning Bolt",
    "product_line": "Magic",
    "condition": "Near Mint",
    "set_name": "Alpha",
    "rarity": "C",
    "quantity": 2,
    "sku_id": 12345,
    "main_photo_url": "https://example.com/bolt.jpg"
  }
]

Response:

{"status": "accepted", "count": 1}

curl example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"order_number":"ORD-12345","product_name":"Lightning Bolt","sku_id":12345,"quantity":2}]' \
  https://www.tryhoard.com/api/v1/order_items

For a large batch, gzip the JSON first:

gzip -c items.json | curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/gzip" \
  --data-binary @- \
  https://www.tryhoard.com/api/v1/order_items

Error responses

Code	Error code	Meaning
422	`invalid_json`	Request body is not valid JSON
422	`invalid_gzip`	`Content-Type` is `application/gzip` but the body is not valid gzip
422	`invalid_payload`	Body is not an array of objects
422	`empty_payload`	The items array is empty
413	`payload_too_large`	Request body exceeds 10 MB on the wire
413	`decompressed_too_large`	Decompressed gzip body exceeds 50 MB
413	`too_many_rows`	More than 50,000 line items in a single request

Upload order shipping

Upload shipping enrichment (carrier, address, tracking, weight) for existing orders. The request is shape-validated synchronously and queued for a bulk SQL update in a background job — the response is 202 Accepted and the database write happens asynchronously. Updates are keyed on (user_id, order_number); unknown order numbers are silently skipped.

POST /api/v1/orders/shipping
Content-Type: application/json

The endpoint accepts both raw JSON and gzip-compressed JSON. The same gzip fallback rules as /api/v1/orders apply. Request body:

[
  {
    "order_number": "ORD-12345",
    "shipping_method": "USPS First Class",
    "city": "Portland",
    "state": "OR",
    "postal_code": "97201",
    "tracking_number": "9400111899223100001234",
    "item_count": 3,
    "product_weight": 0.5
  }
]

Response:

{"status": "accepted", "count": 1}

curl example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"order_number":"ORD-12345","shipping_method":"USPS First Class","city":"Portland","state":"OR","postal_code":"97201","tracking_number":"9400111899223100001234"}]' \
  https://www.tryhoard.com/api/v1/orders/shipping

For a large batch, gzip the JSON first:

gzip -c shipping.json | curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/gzip" \
  --data-binary @- \
  https://www.tryhoard.com/api/v1/orders/shipping

Error responses

Code	Error code	Meaning
422	`invalid_json`	Request body is not valid JSON
422	`invalid_gzip`	`Content-Type` is `application/gzip` but the body is not valid gzip
422	`invalid_payload`	Body is not an array of objects, or a row is missing `order_number`
422	`empty_payload`	The shipping array is empty
413	`payload_too_large`	Request body exceeds 10 MB on the wire
413	`decompressed_too_large`	Decompressed gzip body exceeds 50 MB
413	`too_many_rows`	More than 50,000 shipping rows in a single request

Upload seller feedback

Upload seller feedback ratings scraped from TCGplayer. Matches each item to an existing order by order_number and stores the rating and comment. Items with no matching order or ratings outside 1–5 are silently skipped.

POST /api/v1/order_feedbacks
Content-Type: application/json

Request body:

[
  {
    "order_number": "ORD-12345",
    "rating": 5,
    "comment": "Fast shipping, great packaging!"
  }
]

Feedback object fields

Field	Type	Required	Description
`order_number`	string	Yes	TCGplayer order number to attach feedback to. Must match an existing order.
`rating`	integer	Yes	Seller rating from 1 (lowest) to 5 (highest).
`comment`	string	No	Optional buyer comment.

Response:

{"status": "ok", "updated": 1}

The updated field is the number of orders that had feedback written to them.

curl example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"order_number":"ORD-12345","rating":5,"comment":"Great seller!"}]' \
  https://www.tryhoard.com/api/v1/order_feedbacks

Error responses

Code	Error code	Meaning
422	`invalid_json`	Request body is not valid JSON
422	`empty_payload`	The feedback array is empty

​List orders

​Line items

​Other filters

​Example response

​curl example

​Upload orders

​Order object fields

​curl example

​Error responses

​Notes

​Upload order refunds

​curl example

​Error responses

​Upload order line items

​curl example

​Error responses

​Upload order shipping

​curl example

​Error responses

​Upload seller feedback

​Feedback object fields

​curl example

​Error responses

List orders

Line items

Other filters

Example response

curl example

Upload orders

Order object fields

curl example

Error responses

Notes

Upload order refunds

curl example

Error responses

Upload order line items

curl example

Error responses

Upload order shipping

curl example

Error responses

Upload seller feedback

Feedback object fields

curl example

Error responses