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 (49 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
Assets
GET /assets — Get asset endpoint (always returns Invalid asset request)
The bare `/assets` endpoint always returns an `Invalid asset request` error envelope. To fetch a presigned URL for a media asset, use `GET /assets/{file}` (with optional `?path=` query) or `GET /assets/list`.
Auth: xAuthUser + xAuthToken
GET /assets/list — List media assets under a path
Lists files under the named media path. Valid paths are taken from `$sd->path_names`, which seeds with `['media']` and is extended by the comma/`*`-separated `image_media_locations` user option. If `path` is omitted or invalid, a success envelope is returned with an empty media list (or the default path).
Parameters: path (query)
Auth: xAuthUser + xAuthToken
GET /assets/{file} — Get a presigned URL for a named media asset
Like `GET /assets`, but the file name is supplied as the second path segment instead of via `?location=`. The lookup key sent to S3 is `{path}/{file}` where `{path}` defaults from `?path=` (falling back to the empty string). `{file}` is normalized via PHP `basename()`, so directory traversal segments are stripped. Returns a 10-minute presigned URL on success.
Parameters: file (path), path (query)
Auth: xAuthUser + xAuthToken
Profile
GET /profile — Get the authenticated user's profile
Returns the profile of the user identified by the authenticating token. Sensitive columns (UID, UAID, token, secret, cycle, openid, ebayid, amznid, notes) are stripped before the response is returned.
Auth: xAuthUser + xAuthToken
POST /profile/update — Update the authenticated user's profile
Updates the authenticated user's profile. Non-admin callers cannot change `role`, `access`, or request token regeneration; these fields are stripped server-side.
Request body: application/json, application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
POST /profile/update/{userpk} — Update a sub-user's profile (admin only)
Updates the sub-user identified by `userpk` (a sub-user UAID, ≥ 1). Only callers whose role is one of `owner`, `admin`, `support`, or `developer` may target a sub-user this way — for non-admin callers the path segment is ignored and the call updates the caller instead.
Parameters: userpk (path)
Request body: application/json, application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
POST /profile/add — Create a new sub-user (owner/admin only)
Creates a sub-user account under the authenticated owner. Only callers whose role is `owner` or `admin` may create users; any other role returns `User is not allowed to add new users`. The new sub-user inherits the caller's UID as `userid` and gets a default role of `user`.
Request body (required): application/json, application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
POST /profile/username — Change the authenticated user's account username
Renames the authenticated user. The new username must be supplied as `?username=` (query or form).
Parameters: username (query)
Auth: xAuthUser + xAuthToken
POST /profile/manage/{uid} — MaaS admin — manage a customer account
Restricted to MaaS admins (`Helpers::isMaasAdminIn()`). Lets the admin update an arbitrary customer account by UID, or perform one of two side-effect actions selected by the optional fourth path segment:
Parameters: uid (path)
Request body: application/json, application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
GET /profile/users — MaaS admin — list all customer accounts
Restricted to MaaS admins (`Helpers::isMaasAdminIn()`). Returns every owner-level user record visible from the authenticated MaaS admin's database, with password/secret/email-hash/verification-key fields stripped.
Auth: xAuthUser + xAuthToken
Imports
POST /imports/cancel — Cancel an in-progress channel-plugin product import
Resets the named plugin's product-import settings, terminating any in-progress import for that plugin instance. Internally this calls `Plugins\<name>\<name>::resetImport()`, which zeroes `import_products_set_limit` and disables `import_products_set` / `_set_mode`. The request body may be sent as JSON, form data, or query string.
Request body (required): application/json, application/x-www-form-urlencoded
Auth: xAuthUser + xAuthToken
Fitment
POST /fitment/ebay/category — Get eBay vehicle-type feature for a category
Reads the `vehicleType` feature of the supplied eBay category from the cached eBay Taxonomy collection (Mongo `ebay_taxonomies`). Implemented by `Plugins\ebay\Data::getCategoryFeature($id, 'vehicleType', $siteId)`.
Request body (required): application/x-www-form-urlencoded, application/json
Auth: xAuthUser + xAuthToken
POST /fitment/ebay/catalog/{action} — Search the eBay catalog or look up product compatibilities
Two operations are exposed under this path:
Parameters: action (path), instance (query)
Request body (required): application/x-www-form-urlencoded, application/json
Auth: xAuthUser + xAuthToken
POST /fitment/ebay/compatibility/{action} — Look up compatibility data or selectable values
Two operations:
Parameters: action (path)
Request body (required): application/x-www-form-urlencoded, application/json
Auth: xAuthUser + xAuthToken
POST /fitment/ebay/epid — Resolve EPID values for a vehicle / catalog input
Runs `GetEpidValues` with `{ type, input, siteId, result: 'array', ktype }`. Returns an array of EPID matches.
Request body (required): application/x-www-form-urlencoded, application/json
Auth: xAuthUser + xAuthToken
POST /fitment/ebay/ymm — Look up Year/Make/Model fitment values (placeholder)
The framework dispatch in `src/Api.php` whitelists `ymm` as a valid sub-path under `/v1/fitment/ebay/*` but does not provide a concrete handler branch — issuing a `POST /v1/fitment/ebay/ymm` returns the implicit empty handler result.
Request body: application/json
Auth: xAuthUser + xAuthToken
