SureDone API V1 (v1.0.0)
SureDone REST API v1.
Base URL: https://api.suredone.com/v1
Authentication: Paired X-Auth-User + X-Auth-Token headers. Token is at app.suredone.com/settings/organization/security.
Endpoints (33 operations)
Authentication
POST /auth — Exchange username/password for an API token
POST a JSON (or form-encoded) body with `user` and `pass`. On success the response includes a `token` you can use in the `X-Auth-Token` header for subsequent authenticated calls.
Request body (required): application/json
GET /auth — Validate the supplied API token and return the user profile
Returns the user profile associated with the `X-Auth-User` / `X-Auth-Token` header pair. Useful for confirming that a stored token is still valid and for fetching the user's `role`, `userid`, and `userpk` for routing decisions.
Parameters: apiuser (query)
Auth: xAuthUser + xAuthToken OR xAuthUser + xAuthToken + apiUserQuery
Items
GET /search/items/{query} — Search items by keyword
Returns items matching a free-text keyword query. The path segment is the search term; richer field-scoped queries (e.g. `brand:=msr price:<99`) are supported by URL-encoding them in place of the keyword.
Parameters: query (path)
Auth: xAuthUser + xAuthToken
GET /editor/items — List items with pagination and sorting
Paginated listing of items. Use `page` for pagination, `sort` for sort field, and append `_` to the sort field for descending order (e.g. `name_`). Common sort fields include `id`, `sku`, `guid`, `stock`, `price`, `name`, `title`, `mediacount`, `media`, `size`, `color`, `condition`, `brand`, `style`, `date`, `dateupdated`, `status`, `state`, `category`.
Parameters: page (query), sort (query)
Auth: xAuthUser + xAuthToken
POST /editor/items — Bulk product create/edit/category/media request
Multi-purpose POST endpoint for the product editor. The shape of the body determines the operation:
Parameters: importmedia (query)
Request body (required): application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
POST /editor/items/add — Add a single item
Creates a single product. Required: an `identifier` field (typically `guid`) and a `title`. All other product fields are optional. Use `mediaN` slots or `mediax` (asterisk-delimited URL list) to attach images.
Request body (required): application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
GET /editor/items/edit — Get an item by identifier (GUID or SKU)
Returns the full product record for the item identified by either a `sku` or `guid` query parameter (e.g. `?sku=ABC123`). If neither is supplied the endpoint falls through to the listing handler and returns an ordinal-keyed map of items (same shape as `GET /editor/items`). If a `sku`/`guid` is supplied but no item matches, the response is the metadata-only envelope `{time, type: "items"}`.
Parameters: sku (query), guid (query)
Auth: xAuthUser + xAuthToken
POST /editor/items/edit — Edit a single item
Updates fields on an existing item. Identify the target with `identifier` + the value of that identifier (e.g. `identifier=guid&guid=XYZ`). Any product field may be sent; unspecified fields are left unchanged.
Request body (required): application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
GET /editor/items/edit/{id} — Get an item by numeric ID
Returns the full product record for an item identified by its numeric internal ID. If the supplied `id` does not match any item (including non-numeric strings such as SKUs) the response is the metadata-only envelope `{time, type: "items"}` rather than an HTTP error.
Parameters: id (path)
Auth: xAuthUser + xAuthToken
POST /editor/items/start — Start (list) an item to enabled channels
Triggers a `start` action for the identified item, listing it to enabled marketplaces.
Request body (required): application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
POST /editor/items/end — End an item listing
Ends (removes from sale) the identified item on its currently active channels.
Request body (required): application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
POST /editor/items/relist — Relist an item
Relists (re-creates an active listing for) the identified item.
Request body (required): application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
POST /editor/items/delete — Delete an item
Permanently deletes the identified item from SureDone.
Request body (required): application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
Orders
GET /search/orders/{query} — Search orders
Returns orders matching a SureDone field-scoped query (e.g. `order:ebay shipdate:<2015-07-21`). The path segment must be URL-encoded.
Parameters: query (path)
Auth: xAuthUser + xAuthToken
GET /orders/all — List all orders
Returns all orders matching the (optional) search query, with pagination and sort.
Parameters: q (query), page (query), sort (query)
Auth: xAuthUser + xAuthToken
GET /orders/shipped — List shipped orders
Returns orders in the shipped state, optionally filtered and sorted.
Parameters: q (query), page (query), sort (query)
Auth: xAuthUser + xAuthToken
GET /orders/awaiting — List orders awaiting shipment
Returns orders awaiting shipment, optionally filtered and sorted.
Parameters: q (query), page (query), sort (query)
Auth: xAuthUser + xAuthToken
GET /orders/packing — List packing-slip orders
Returns orders in the packing-slip state, optionally filtered and sorted.
Parameters: q (query), page (query), sort (query)
Auth: xAuthUser + xAuthToken
POST /orders/add — Create a new order
Creates a new order with the supplied line items and shipping/billing details.
Request body (required): application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
POST /orders/edit — Fulfill / update an order
Updates an existing order. Common use is supplying tracking information to fulfill an order (carrier, tracking number, ship date). Any order field may be updated.
Request body (required): application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
GET /orders/edit/{id} — Get a single order
Returns the full record for one order, identified by its SureDone order ID or channel order number.
Parameters: id (path)
Auth: xAuthUser + xAuthToken
GET /orders/invoice/{order} — Get an order invoice
Returns a JSON envelope containing the rendered HTML invoice for a single order, plus a copy of the order record. On lookup failure (unknown order ID) the response is also `application/json` with the standard `{result: failure, message, time}` error envelope and HTTP 200 — callers must inspect the `result` field, not the status.
Parameters: order (path)
Auth: xAuthUser + xAuthToken
Settings
POST /settings — Update account / channel settings
Updates SureDone account-level settings. This endpoint covers every configuration available through the Settings UI, including channel on/off toggles, eBay/Amazon field mappings, eBay templates, business policies, custom user fields, Min/Max stock mappings, and product listing defaults.
Request body (required): application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
Options
GET /options/all — Retrieve all options
Returns every SureDone option/setting for the authenticated account. Useful for one-shot configuration discovery; for routine reads of an individual setting, prefer `GET /options/{username}`.
Auth: xAuthUser + xAuthToken
GET /options/{username} — Retrieve a single option
Returns the current value of a single named option.
Parameters: username (path)
Auth: xAuthUser + xAuthToken
Bulk
POST /bulk — Upload a bulk file
Uploads a CSV (optionally gzipped or zipped) to process as a bulk request. `bulk_file` is the file form field. Use `bulk_name` to set a custom job name and `bulk_email` to specify where to send the completion notification.
Request body (required): multipart/form-data
Auth: xAuthUser + xAuthToken
GET /bulk/results/{bulk_file} — Get bulk file result status
Returns the status of a previously uploaded bulk file and a presigned URL to the result CSV when complete.
Parameters: bulk_file (path)
Auth: xAuthUser + xAuthToken
GET /bulk/results/cancel/{job_id} — Cancel a running bulk job
Cancels a bulk job that is still in progress.
Parameters: job_id (path)
Auth: xAuthUser + xAuthToken
GET /bulk/jobs/{date} — List bulk jobs for a date
Lists every bulk job started on a given date along with status.
Parameters: date (path)
Auth: xAuthUser + xAuthToken
POST /bulk/exports — Start a bulk export
Starts an asynchronous export of items, orders, pages, or categories.
Request body (required): application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
GET /bulk/exports/{bulk_file} — Get bulk export status
Returns the status of a previously requested export and a presigned URL to the export CSV when complete.
Parameters: bulk_file (path)
Auth: xAuthUser + xAuthToken
Taxonomy
POST /taxonomy/ebay — Get eBay category specifics
Returns the required and recommended item specifics for an eBay category, along with allowed values where applicable. Requires the eBay category ID and eBay Site ID.
Request body (required): application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
Logs
POST /logs — Search application logs
Returns log entries for products, orders, settings, and channel operations. Supply one or more search fields to narrow the results.
Request body (required): application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken