{
  "openapi": "3.1.0",
  "info": {
    "title": "SureDone API V1",
    "version": "1.0.0",
    "description": "SureDone REST API v1.\n\nAuthentication uses paired `X-Auth-User` and `X-Auth-Token` headers. The API\nUsername and Token are available at\nhttps://app.suredone.com/settings/organization/security.\n\nThe `POST /auth` endpoint also accepts an `?apiuser=` query parameter for\nsub-account / partner lookups.\n\n## Throttling (released 2022-12-09)\n\nEvery request is throttled with the following basic schema:\n\n- `read`: 300 requests per minute for `GET`, `TRACE`, `CONNECT` and related calls\n- `write`: 60 requests per minute for `POST`, `PATCH`, `PUT` and `DELETE` calls\n- `options`: 300 requests per minute for `OPTIONS` (for apps and UI integrations)\n\nWhen the throttle is hit, the API returns HTTP `429` with these response headers:\n\n- `X-Rate-Limit-Limit` (e.g. `300`)\n- `X-Rate-Limit-Remaining` (e.g. `295`)\n- `X-Rate-Limit-Reset` (e.g. `1666020201`)\n- `X-Rate-Limit-Type` (e.g. `read`)\n"
  },
  "servers": [
    {
      "url": "https://api.suredone.com/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "xAuthUser": [],
      "xAuthToken": []
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "Validate API credentials and obtain a session token."
    },
    {
      "name": "Items",
      "description": "Product (item) CRUD, search, and lifecycle operations."
    },
    {
      "name": "Orders",
      "description": "Order retrieval, creation, search, and fulfillment."
    },
    {
      "name": "Settings",
      "description": "Account-level configuration via the settings endpoint."
    },
    {
      "name": "Options",
      "description": "Read individual option values or all options for the account."
    },
    {
      "name": "Bulk",
      "description": "Bulk file upload, export, job status, and cancellation."
    },
    {
      "name": "Taxonomy",
      "description": "Marketplace category and item-specifics search."
    },
    {
      "name": "Logs",
      "description": "Application logging queries for products, orders, and channels."
    }
  ],
  "paths": {
    "/auth": {
      "post": {
        "operationId": "authenticate",
        "summary": "Exchange username/password for an API token",
        "description": "POST a JSON (or form-encoded) body with `user` and `pass`. On success\nthe response includes a `token` you can use in the `X-Auth-Token`\nheader for subsequent authenticated calls.\n\nThis endpoint authenticates from the request body alone. `X-Auth-User`\n/ `X-Auth-Token` headers and the `?apiuser=` query parameter, if\npresent, are ignored. To check or refresh an existing token, use\n`GET /auth` instead.\n",
        "tags": [
          "Authentication"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user": {
                    "type": "string",
                    "description": "Account username (typically the account email)."
                  },
                  "pass": {
                    "type": "string",
                    "format": "password",
                    "description": "Account password."
                  }
                },
                "required": [
                  "user",
                  "pass"
                ]
              },
              "examples": {
                "login": {
                  "summary": "Standard login",
                  "value": {
                    "user": "demo@suredone.com",
                    "pass": "s3cret"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Always 200. The `result` field discriminates: `success` returns the\nauthenticated user with a `token`; `failure` returns a `message`\nexplaining why (missing/invalid credentials).\n",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "Success envelope.",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "success"
                          ]
                        },
                        "token": {
                          "type": "string",
                          "description": "API token for the `X-Auth-Token` header."
                        },
                        "userid": {
                          "type": "string"
                        },
                        "userpk": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "role": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "result",
                        "token",
                        "userid"
                      ]
                    },
                    {
                      "type": "object",
                      "description": "Failure envelope (e.g. missing credentials, invalid password).",
                      "properties": {
                        "result": {
                          "type": "string",
                          "enum": [
                            "failure"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "result",
                        "message"
                      ]
                    }
                  ]
                },
                "examples": {
                  "success": {
                    "summary": "Successful authentication",
                    "value": {
                      "result": "success",
                      "token": "EXAMPLE000000000000000000000token",
                      "userid": "1021",
                      "userpk": "1923",
                      "email": "demo@suredone.com",
                      "role": "admin"
                    }
                  },
                  "missingCredentials": {
                    "summary": "Missing user or pass in body",
                    "value": {
                      "result": "failure",
                      "message": "Username or password is empty"
                    }
                  },
                  "invalidPassword": {
                    "summary": "Wrong password",
                    "value": {
                      "result": "failure",
                      "message": "Invalid password"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "operationId": "validateToken",
        "summary": "Validate the supplied API token and return the user profile",
        "description": "Returns the user profile associated with the `X-Auth-User` /\n`X-Auth-Token` header pair. Useful for confirming that a stored token\nis still valid and for fetching the user's `role`, `userid`, and\n`userpk` for routing decisions.\n\nSystem administrators (`userid: 1`) may additionally pass\n`?apiuser=<uid>` to read the profile of another user; for non-admin\ncallers the parameter is silently ignored and the caller's own profile\nis returned.\n",
        "tags": [
          "Authentication"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          },
          {
            "xAuthUser": [],
            "xAuthToken": [],
            "apiUserQuery": []
          }
        ],
        "parameters": [
          {
            "name": "apiuser",
            "in": "query",
            "required": false,
            "description": "Target UID for admin (`userid: 1`) impersonation. Ignored for non-admin callers.",
            "schema": {
              "type": "string"
            },
            "example": "1021"
          }
        ],
        "responses": {
          "200": {
            "description": "Token is valid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "string",
                      "enum": [
                        "success"
                      ]
                    },
                    "userid": {
                      "type": "string"
                    },
                    "userpk": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "username": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "display": {
                      "type": "string"
                    },
                    "role": {
                      "type": "string"
                    },
                    "time": {
                      "type": "string",
                      "description": "Current server time at validation."
                    },
                    "created": {
                      "type": "string"
                    },
                    "lastlogin": {
                      "type": "string"
                    },
                    "verified": {
                      "type": "string"
                    },
                    "token": {
                      "type": "string"
                    },
                    "cycle": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "plan": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "crmid": {
                      "type": "string"
                    },
                    "agree": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "result",
                    "userid",
                    "userpk",
                    "email",
                    "role",
                    "token"
                  ]
                },
                "examples": {
                  "success": {
                    "value": {
                      "result": "success",
                      "userid": "1021",
                      "userpk": "1923",
                      "email": "demo@suredone.com",
                      "username": null,
                      "display": "Demo User",
                      "role": "admin",
                      "time": "2026-05-20 12:34:56",
                      "created": "2018-02-14 19:06:28",
                      "lastlogin": "2018-02-14 19:06:28",
                      "verified": "18a2a9c04d2852a56e2dc6a16ad2ecc045813c43",
                      "token": "EXAMPLE000000000000000000000token",
                      "cycle": null,
                      "plan": null,
                      "crmid": "",
                      "agree": "0"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid": {
                    "value": {
                      "result": "error",
                      "message": "Invalid Token"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/search/items/{query}": {
      "get": {
        "operationId": "searchItemsByKeyword",
        "summary": "Search items by keyword",
        "description": "Returns items matching a free-text keyword query. The path segment is\nthe search term; richer field-scoped queries (e.g. `brand:=msr price:<99`)\nare supported by URL-encoding them in place of the keyword.\n",
        "tags": [
          "Items"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "query",
            "in": "path",
            "required": true,
            "description": "Search term, optionally using SureDone field-scoped query syntax.",
            "schema": {
              "type": "string"
            },
            "example": "apple"
          }
        ],
        "responses": {
          "200": {
            "description": "Search results keyed by ordinal position with `all` and `time` summary fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemSearchResponse"
                },
                "examples": {
                  "results": {
                    "value": {
                      "1": {
                        "id": "99982",
                        "sku": "3616-Apple-XL",
                        "guid": "3616-Apple-XL",
                        "title": "LAT Junior Fit Fine Jersey Longer Length T-Shirt, Apple, X-Large",
                        "price": "4.97",
                        "stock": "0"
                      },
                      "type": "items",
                      "all": 302,
                      "time": "2015-06-25 13:11:48"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/search/orders/{query}": {
      "get": {
        "operationId": "searchOrders",
        "summary": "Search orders",
        "description": "Returns orders matching a SureDone field-scoped query\n(e.g. `order:ebay shipdate:<2015-07-21`). The path segment must be\nURL-encoded.\n",
        "tags": [
          "Orders"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "query",
            "in": "path",
            "required": true,
            "description": "Field-scoped order search query.",
            "schema": {
              "type": "string"
            },
            "example": "order:ebay shipdate:<2015-07-21"
          }
        ],
        "responses": {
          "200": {
            "description": "Order search results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/editor/items": {
      "get": {
        "operationId": "listItems",
        "summary": "List items with pagination and sorting",
        "description": "Paginated listing of items. Use `page` for pagination, `sort` for sort\nfield, and append `_` to the sort field for descending order\n(e.g. `name_`). Common sort fields include `id`, `sku`, `guid`,\n`stock`, `price`, `name`, `title`, `mediacount`, `media`, `size`,\n`color`, `condition`, `brand`, `style`, `date`, `dateupdated`,\n`status`, `state`, `category`.\n",
        "tags": [
          "Items"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number.",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "example": 1
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort field. Append `_` for descending sort.",
            "schema": {
              "type": "string"
            },
            "example": "name"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of items keyed by ordinal position.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemSearchResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "bulkProductRequest",
        "summary": "Bulk product create/edit/category/media request",
        "description": "Multi-purpose POST endpoint for the product editor. The shape of the\nbody determines the operation:\n\n- `requests=[[...]]` — bulk add/edit with a header row plus data rows.\n- `ebay-category-search=<query>` — eBay category keyword search.\n- `action=edit&identifier=<id>&...&mediaN=<url>` — set media URLs on\n  a single product. Add `?importmedia=true` to download and host the\n  URLs instead of referencing them in place.\n\nResponses for bulk requests return per-row status entries keyed by\nordinal position alongside top-level `result`, `time`, and `actions`\nfields.\n",
        "tags": [
          "Items"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "importmedia",
            "in": "query",
            "required": false,
            "description": "When `true`, instructs SureDone to download referenced media URLs into its CDN.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "requests": {
                    "type": "string",
                    "description": "JSON-encoded array-of-arrays. First row is header, subsequent rows are data."
                  },
                  "action": {
                    "type": "string",
                    "description": "Action verb (`add`, `edit`, `start`, `end`, `relist`, `delete`)."
                  },
                  "identifier": {
                    "type": "string",
                    "description": "Field used as the row identifier (e.g. `guid`, `sku`)."
                  },
                  "guid": {
                    "type": "string"
                  },
                  "ebay-category-search": {
                    "type": "string",
                    "description": "Keyword search across eBay category tree."
                  },
                  "media1": {
                    "type": "string",
                    "description": "Image URL or local file reference for media slot 1."
                  }
                }
              },
              "examples": {
                "bulkAdd": {
                  "summary": "Bulk add via requests array",
                  "value": {
                    "requests": "[[\"action=add\",\"guid\",\"stock\",\"price\",\"title\"],[\"add\",\"TEST001\",1,9.99,\"Product 1\"],[\"add\",\"TEST002\",3,19.99,\"Product 2\"]]"
                  }
                },
                "ebayCategorySearch": {
                  "summary": "eBay category search",
                  "value": {
                    "ebay-category-search": "red shoes"
                  }
                },
                "setMedia": {
                  "summary": "Set media URLs on an existing item",
                  "value": {
                    "action": "edit",
                    "identifier": "guid",
                    "guid": "TEST001",
                    "media1": "https://assets.suredone.com/v6/logos/suredone-icon-164x164.png"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per-row result entries plus top-level summary.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkActionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/editor/items/add": {
      "post": {
        "operationId": "addItem",
        "summary": "Add a single item",
        "description": "Creates a single product. Required: an `identifier` field (typically\n`guid`) and a `title`. All other product fields are optional. Use\n`mediaN` slots or `mediax` (asterisk-delimited URL list) to attach\nimages.\n",
        "tags": [
          "Items"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "identifier": {
                    "type": "string",
                    "description": "Field used as the unique identifier (commonly `guid`)."
                  },
                  "guid": {
                    "type": "string"
                  },
                  "sku": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string",
                    "description": "Required for product creation."
                  },
                  "price": {
                    "type": "string"
                  },
                  "stock": {
                    "type": "string"
                  },
                  "brand": {
                    "type": "string"
                  },
                  "media1": {
                    "type": "string"
                  },
                  "mediax": {
                    "type": "string",
                    "description": "Asterisk-delimited list of additional image URLs."
                  }
                },
                "required": [
                  "identifier",
                  "title"
                ]
              },
              "examples": {
                "minimal": {
                  "summary": "Minimum required fields",
                  "value": {
                    "identifier": "guid",
                    "guid": "xxxtestxxx",
                    "title": "test product xxx",
                    "price": "99"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Single-action response with per-row status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleActionResponse"
                },
                "examples": {
                  "success": {
                    "value": {
                      "1": {
                        "result": "success",
                        "action": "add",
                        "identifier": "xxxtestxxx"
                      },
                      "result": "success",
                      "type": "items",
                      "id": "guid",
                      "time": "2015-07-20 18:31:37",
                      "actions": 1
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/editor/items/edit": {
      "get": {
        "operationId": "getItemByIdentifier",
        "summary": "Get an item by identifier (GUID or SKU)",
        "description": "Returns the full product record for the item identified by either a\n`sku` or `guid` query parameter (e.g. `?sku=ABC123`). If neither is\nsupplied the endpoint falls through to the listing handler and returns\nan ordinal-keyed map of items (same shape as `GET /editor/items`). If a\n`sku`/`guid` is supplied but no item matches, the response is the\nmetadata-only envelope `{time, type: \"items\"}`.\n",
        "tags": [
          "Items"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "sku",
            "in": "query",
            "required": false,
            "description": "SKU to look up. Mutually exclusive with `guid`.",
            "schema": {
              "type": "string"
            },
            "example": "ABC123"
          },
          {
            "name": "guid",
            "in": "query",
            "required": false,
            "description": "GUID to look up. Mutually exclusive with `sku`.",
            "schema": {
              "type": "string"
            },
            "example": "xxxtestxxx"
          }
        ],
        "responses": {
          "200": {
            "description": "One of three shapes: a flat `Item` record (when `sku`/`guid` matches),\nan empty-result envelope `{time, type: \"items\"}` (when supplied\n`sku`/`guid` does not match), or an ordinal-keyed listing map\n(when no lookup parameter was supplied).\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemLookupResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "editItem",
        "summary": "Edit a single item",
        "description": "Updates fields on an existing item. Identify the target with\n`identifier` + the value of that identifier (e.g. `identifier=guid&guid=XYZ`).\nAny product field may be sent; unspecified fields are left unchanged.\n\nAlso accepts setting product-level eBay item specifics\n(`ebayitemspecifics<fieldname>=<value>`), a product-level eBay template\n(`ebaytemplate=<template>.htm`), or other product-scoped overrides.\n",
        "tags": [
          "Items"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "identifier": {
                    "type": "string"
                  },
                  "guid": {
                    "type": "string"
                  },
                  "sku": {
                    "type": "string"
                  },
                  "price": {
                    "type": "string"
                  },
                  "brand": {
                    "type": "string"
                  },
                  "ebaytemplate": {
                    "type": "string",
                    "description": "Name of a previously uploaded eBay template file."
                  }
                },
                "required": [
                  "identifier"
                ]
              },
              "examples": {
                "priceBrand": {
                  "summary": "Update price and brand",
                  "value": {
                    "identifier": "guid",
                    "guid": "xxxtestxxx",
                    "price": "89.99",
                    "brand": "Nike"
                  }
                },
                "ebayItemSpecifics": {
                  "summary": "Set product-level eBay item specifics",
                  "value": {
                    "identifier": "guid",
                    "guid": "TEST",
                    "ebayitemspecificsregionoforigin": "Asia"
                  }
                },
                "productTemplate": {
                  "summary": "Apply a product-level eBay template",
                  "value": {
                    "identifier": "guid",
                    "guid": "TEST",
                    "ebaytemplate": "ebay-template.htm"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Edit result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleActionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/editor/items/edit/{id}": {
      "get": {
        "operationId": "getItemById",
        "summary": "Get an item by numeric ID",
        "description": "Returns the full product record for an item identified by its numeric\ninternal ID. If the supplied `id` does not match any item (including\nnon-numeric strings such as SKUs) the response is the metadata-only\nenvelope `{time, type: \"items\"}` rather than an HTTP error.\n",
        "tags": [
          "Items"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Numeric internal item ID.",
            "schema": {
              "type": "integer"
            },
            "example": 1
          }
        ],
        "responses": {
          "200": {
            "description": "Either a flat `Item` record (match) or an empty-result envelope\n`{time, type: \"items\"}` (no match). HTTP status is 200 in both\ncases; callers should check for the `id` (or `sku`) field to\ndistinguish a real item from the empty envelope.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemLookupByIdResponse"
                }
              }
            }
          }
        }
      }
    },
    "/editor/items/start": {
      "post": {
        "operationId": "startItem",
        "summary": "Start (list) an item to enabled channels",
        "description": "Triggers a `start` action for the identified item, listing it to enabled marketplaces.",
        "tags": [
          "Items"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "identifier": {
                    "type": "string"
                  },
                  "guid": {
                    "type": "string"
                  },
                  "price": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  }
                },
                "required": [
                  "identifier"
                ]
              },
              "examples": {
                "start": {
                  "value": {
                    "identifier": "guid",
                    "guid": "xxxtestxxx",
                    "price": "199.9",
                    "title": "Product XXX"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Start result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleActionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/editor/items/end": {
      "post": {
        "operationId": "endItem",
        "summary": "End an item listing",
        "description": "Ends (removes from sale) the identified item on its currently active channels.",
        "tags": [
          "Items"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "identifier": {
                    "type": "string"
                  },
                  "guid": {
                    "type": "string"
                  }
                },
                "required": [
                  "identifier"
                ]
              },
              "examples": {
                "end": {
                  "value": {
                    "identifier": "guid",
                    "guid": "xxxtestxxx"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "End result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleActionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/editor/items/relist": {
      "post": {
        "operationId": "relistItem",
        "summary": "Relist an item",
        "description": "Relists (re-creates an active listing for) the identified item.",
        "tags": [
          "Items"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "identifier": {
                    "type": "string"
                  },
                  "guid": {
                    "type": "string"
                  }
                },
                "required": [
                  "identifier"
                ]
              },
              "examples": {
                "relist": {
                  "value": {
                    "identifier": "guid",
                    "guid": "xxxtestxxx"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Relist result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleActionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/editor/items/delete": {
      "post": {
        "operationId": "deleteItem",
        "summary": "Delete an item",
        "description": "Permanently deletes the identified item from SureDone.",
        "tags": [
          "Items"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "identifier": {
                    "type": "string"
                  },
                  "guid": {
                    "type": "string"
                  }
                },
                "required": [
                  "identifier"
                ]
              },
              "examples": {
                "delete": {
                  "value": {
                    "identifier": "guid",
                    "guid": "xxxtestxxx"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Delete result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleActionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/orders/all": {
      "get": {
        "operationId": "listAllOrders",
        "summary": "List all orders",
        "description": "Returns all orders matching the (optional) search query, with pagination and sort.",
        "tags": [
          "Orders"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Field-scoped search query (e.g. `shipcarrier:=fedex`).",
            "schema": {
              "type": "string"
            },
            "example": "shipcarrier:=fedex"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort field. Append `_` for descending sort.",
            "schema": {
              "type": "string"
            },
            "example": "shipcarrier"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of orders.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/orders/shipped": {
      "get": {
        "operationId": "listShippedOrders",
        "summary": "List shipped orders",
        "description": "Returns orders in the shipped state, optionally filtered and sorted.",
        "tags": [
          "Orders"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Field-scoped search query.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort field. Append `_` for descending sort.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of shipped orders.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/orders/awaiting": {
      "get": {
        "operationId": "listAwaitingOrders",
        "summary": "List orders awaiting shipment",
        "description": "Returns orders awaiting shipment, optionally filtered and sorted.",
        "tags": [
          "Orders"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Field-scoped search query.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort field. Append `_` for descending sort.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of awaiting-shipment orders.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/orders/packing": {
      "get": {
        "operationId": "listPackingOrders",
        "summary": "List packing-slip orders",
        "description": "Returns orders in the packing-slip state, optionally filtered and sorted.",
        "tags": [
          "Orders"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Field-scoped search query.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort field. Append `_` for descending sort.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of orders with packing-slip state, including a\nrendered HTML packing slip. When there are no matching orders the\ninner `orders` map is replaced by a metadata-only object\n(`{type: \"orders\", all: 0, time: \"...\"}`); when there are\nmatches it is an ordinal-keyed map of order records with an `all`\ncount. Callers should branch on `orders.type === \"orders\"` (no\nmatches) vs `orders.all > 0` (matches).\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackingResponse"
                }
              }
            }
          }
        }
      }
    },
    "/orders/add": {
      "post": {
        "operationId": "addOrder",
        "summary": "Create a new order",
        "description": "Creates a new order with the supplied line items and shipping/billing details.",
        "tags": [
          "Orders"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "order": {
                    "type": "string",
                    "description": "Channel order number / unique order identifier."
                  },
                  "total": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "items": {
                    "type": "string",
                    "description": "Asterisk-delimited list of GUIDs or SKUs."
                  },
                  "qtys": {
                    "type": "string",
                    "description": "Asterisk-delimited list of quantities aligned with `items`."
                  },
                  "scountry": {
                    "type": "string"
                  },
                  "sfirstname": {
                    "type": "string"
                  },
                  "slastname": {
                    "type": "string"
                  },
                  "sold": {
                    "type": "string",
                    "description": "Set to `true` to decrement inventory on import."
                  }
                },
                "required": [
                  "order"
                ]
              },
              "examples": {
                "create": {
                  "value": {
                    "order": "SD13097689151690",
                    "total": "601",
                    "email": "john@testdomain.com",
                    "scountry": "US",
                    "sfirstname": "john",
                    "slastname": "smith",
                    "items": "xxxtestxxx",
                    "qtys": "1",
                    "sold": "true"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order creation result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderActionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/orders/edit": {
      "post": {
        "operationId": "fulfillOrder",
        "summary": "Fulfill / update an order",
        "description": "Updates an existing order. Common use is supplying tracking information\nto fulfill an order (carrier, tracking number, ship date). Any order\nfield may be updated.\n",
        "tags": [
          "Orders"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "order": {
                    "type": "string"
                  },
                  "shipcarrier": {
                    "type": "string"
                  },
                  "shiptracking": {
                    "type": "string"
                  },
                  "shipdate": {
                    "type": "string",
                    "description": "ISO-style timestamp (URL-encoded space allowed)."
                  }
                },
                "required": [
                  "order"
                ]
              },
              "examples": {
                "fulfill": {
                  "value": {
                    "order": "SD13097689151690",
                    "shipcarrier": "UPS",
                    "shiptracking": "1Z9999999999999999",
                    "shipdate": "2020-08-30 00:54:20"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order fulfillment result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderActionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/orders/edit/{id}": {
      "get": {
        "operationId": "getOrderById",
        "summary": "Get a single order",
        "description": "Returns the full record for one order, identified by its SureDone order ID or channel order number.",
        "tags": [
          "Orders"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Order ID (SureDone-issued or channel-supplied).",
            "schema": {
              "type": "string"
            },
            "example": "SD13097689151690"
          }
        ],
        "responses": {
          "200": {
            "description": "Single-order record.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/orders/invoice/{order}": {
      "get": {
        "operationId": "getOrderInvoice",
        "summary": "Get an order invoice",
        "description": "Returns a JSON envelope containing the rendered HTML invoice for a\nsingle order, plus a copy of the order record. On lookup failure\n(unknown order ID) the response is also `application/json` with the\nstandard `{result: failure, message, time}` error envelope and\nHTTP 200 — callers must inspect the `result` field, not the status.\n",
        "tags": [
          "Orders"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "order",
            "in": "path",
            "required": true,
            "description": "Order ID.",
            "schema": {
              "type": "string"
            },
            "example": "SD13097689151690"
          }
        ],
        "responses": {
          "200": {
            "description": "Invoice envelope. On success, `orders` is a map of ordinal\nposition to `Order` plus an `all` count and `html` carries the\nrendered HTML invoice. On lookup failure, `result` is `failure`\nand `message` describes the problem.\n",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/InvoiceResponse"
                    },
                    {
                      "$ref": "#/components/schemas/InvoiceErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "success": {
                    "summary": "Invoice for an existing order",
                    "value": {
                      "orders": {
                        "1": {
                          "oid": "1",
                          "order": "SD13097689151690",
                          "email": "customer@example.com"
                        },
                        "all": "1"
                      },
                      "html": "<html>...rendered invoice...</html>",
                      "time": "2026-05-20 00:22:14"
                    }
                  },
                  "notFound": {
                    "summary": "Unknown order ID",
                    "value": {
                      "result": "failure",
                      "message": "Invalid Order Number",
                      "time": "2026-05-20 00:22:14"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/settings": {
      "post": {
        "operationId": "updateSettings",
        "summary": "Update account / channel settings",
        "description": "Updates SureDone account-level settings. This endpoint covers every\nconfiguration available through the Settings UI, including channel\non/off toggles, eBay/Amazon field mappings, eBay templates, business\npolicies, custom user fields, Min/Max stock mappings, and product\nlisting defaults.\n\nThe response `result` is `success` or `error`. On `error`, the\n`errors` field is an object keyed by field name with a per-field error\ndescription.\n",
        "tags": [
          "Settings"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "description": "Free-form settings payload. Any setting name accepted by the Settings UI may be sent here.",
                "additionalProperties": true
              },
              "examples": {
                "ebayBusinessPoliciesRefresh": {
                  "summary": "Refresh eBay Business Policies",
                  "value": {
                    "ebay-profiles-refresh": "true",
                    "instanceid": "2"
                  }
                },
                "disableChannels": {
                  "summary": "Disable eBay and Amazon integrations",
                  "value": {
                    "site_ebayconnect": "off",
                    "site_amznconnect": "off"
                  }
                },
                "createCustomFields": {
                  "summary": "Bulk-create custom user fields",
                  "value": {
                    "user_field_names_addname[]": "test1",
                    "user_field_names_addtype": "varchar",
                    "user_field_names_addlength": "200",
                    "user_field_names_addbulk": "true"
                  }
                },
                "setEbayTemplate": {
                  "summary": "Set the default eBay template",
                  "value": {
                    "ebay_templates": "ebay-template.htm"
                  }
                },
                "setMinMaxStock": {
                  "summary": "Set Min/Max stock mappings for eBay and Amazon",
                  "value": {
                    "ebay_minstock": "minstock",
                    "ebay_maxstock": "maxstock",
                    "amzn_minstock": "minstock",
                    "amzn_maxstock": "maxstock"
                  }
                },
                "minimumListingOptions": {
                  "summary": "Minimum eBay listing configuration",
                  "value": {
                    "business_country": "US",
                    "business_zip": "10010",
                    "ebay_siteid": "1",
                    "ebay_listtype": "FixedPriceItem",
                    "ebay_listtime": "GTC"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Settings update result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettingsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/options/all": {
      "get": {
        "operationId": "getAllOptions",
        "summary": "Retrieve all options",
        "description": "Returns every SureDone option/setting for the authenticated account.\nUseful for one-shot configuration discovery; for routine reads of an\nindividual setting, prefer `GET /options/{username}`.\n",
        "tags": [
          "Options"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Map of every option name to its current value.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "All options keyed by option name. `result` is always present.",
                  "properties": {
                    "result": {
                      "type": "string",
                      "example": "success"
                    },
                    "site_user": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "result"
                  ],
                  "additionalProperties": true
                },
                "examples": {
                  "example": {
                    "value": {
                      "result": "success",
                      "site_user": "testapixxx",
                      "site_live": "{\"site\":\"off\",\"live\":\"off\"}",
                      "site_domain": ""
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/options/{username}": {
      "get": {
        "operationId": "getOption",
        "summary": "Retrieve a single option",
        "description": "Returns the current value of a single named option.",
        "tags": [
          "Options"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "username",
            "in": "path",
            "required": true,
            "description": "Option name to retrieve (e.g. `site_user`).",
            "schema": {
              "type": "string"
            },
            "example": "site_user"
          }
        ],
        "responses": {
          "200": {
            "description": "Single-option payload.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "result"
                  ],
                  "additionalProperties": true
                },
                "examples": {
                  "example": {
                    "value": {
                      "result": "success",
                      "site_user": "testapixxx"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/bulk": {
      "post": {
        "operationId": "bulkFileUpload",
        "summary": "Upload a bulk file",
        "description": "Uploads a CSV (optionally gzipped or zipped) to process as a bulk\nrequest. `bulk_file` is the file form field. Use `bulk_name` to set a\ncustom job name and `bulk_email` to specify where to send the\ncompletion notification.\n\nCompressed file uploads (`.gz`, `.csv.gz`, `.zip`) are automatically\ndecompressed before processing.\n",
        "tags": [
          "Bulk"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "bulk_file": {
                    "type": "string",
                    "format": "binary",
                    "description": "CSV file (optionally compressed)."
                  },
                  "bulk_name": {
                    "type": "string",
                    "description": "Optional custom name for the bulk job."
                  },
                  "bulk_email": {
                    "type": "string",
                    "format": "email",
                    "description": "Optional address to email on completion."
                  }
                },
                "required": [
                  "bulk_file"
                ]
              },
              "examples": {
                "upload": {
                  "summary": "Upload `test-upload.csv` with a custom job name",
                  "value": {
                    "bulk_file": "(binary file payload — multipart/form-data)",
                    "bulk_name": "test-upload"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkUploadResponse"
                }
              }
            }
          }
        }
      }
    },
    "/bulk/results/{bulk_file}": {
      "get": {
        "operationId": "getBulkResultStatus",
        "summary": "Get bulk file result status",
        "description": "Returns the status of a previously uploaded bulk file and a presigned URL to the result CSV when complete.",
        "tags": [
          "Bulk"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "bulk_file",
            "in": "path",
            "required": true,
            "description": "Bulk result filename returned from the upload.",
            "schema": {
              "type": "string"
            },
            "example": "20161014-121734-1-bulk-results.csv"
          }
        ],
        "responses": {
          "200": {
            "description": "Bulk job status payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkStatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/bulk/results/cancel/{job_id}": {
      "get": {
        "operationId": "cancelBulkJob",
        "summary": "Cancel a running bulk job",
        "description": "Cancels a bulk job that is still in progress.",
        "tags": [
          "Bulk"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "description": "Bulk job identifier.",
            "schema": {
              "type": "string"
            },
            "example": "20161014-121734-1"
          }
        ],
        "responses": {
          "200": {
            "description": "Cancellation result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimpleResultResponse"
                },
                "examples": {
                  "cancelled": {
                    "value": {
                      "result": "success",
                      "message": "Cancelled job 20161014-121734-1"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/bulk/jobs/{date}": {
      "get": {
        "operationId": "getBulkJobsForDate",
        "summary": "List bulk jobs for a date",
        "description": "Lists every bulk job started on a given date along with status.",
        "tags": [
          "Bulk"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "date",
            "in": "path",
            "required": true,
            "description": "Date to list jobs for, in `YYYY-MM-DD` format.",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2023-05-16"
          }
        ],
        "responses": {
          "200": {
            "description": "Bulk job listing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "jobs": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "result"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/bulk/exports": {
      "post": {
        "operationId": "bulkFileExport",
        "summary": "Start a bulk export",
        "description": "Starts an asynchronous export of items, orders, pages, or categories.\n\n- `q` — optional search query used to curate the export.\n- `type` — one of `items`, `orders`, `pages`, `categories`.\n- `mode` — `include` (only export the named fields) or `remove`\n  (export everything except the named fields).\n- `fields` — comma-delimited list (or array) of field names tied to `mode`.\n- `export_name` — optional file name for the result.\n- `export_email` — optional address to email on completion.\n- `lineitem` — for `orders` type, whether to export per-line-item rows.\n- `compressed` — when `true`, the result file is gzip-compressed (`.csv.gz`).\n",
        "tags": [
          "Bulk"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "q": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "items",
                      "orders",
                      "pages",
                      "categories"
                    ]
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "include",
                      "remove"
                    ]
                  },
                  "fields": {
                    "type": "string",
                    "description": "Comma-delimited field names, or an array."
                  },
                  "export_name": {
                    "type": "string"
                  },
                  "export_email": {
                    "type": "string",
                    "format": "email"
                  },
                  "lineitem": {
                    "type": "string"
                  },
                  "compressed": {
                    "type": "string",
                    "enum": [
                      "true",
                      "false"
                    ]
                  }
                },
                "required": [
                  "type"
                ]
              },
              "examples": {
                "priceFilter": {
                  "value": {
                    "q": "price:>999",
                    "type": "items",
                    "mode": "include",
                    "fields": "guid,title,price",
                    "export_name": "mylist",
                    "compressed": "false"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Export accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkUploadResponse"
                }
              }
            }
          }
        }
      }
    },
    "/bulk/exports/{bulk_file}": {
      "get": {
        "operationId": "getBulkExportStatus",
        "summary": "Get bulk export status",
        "description": "Returns the status of a previously requested export and a presigned URL to the export CSV when complete.",
        "tags": [
          "Bulk"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "parameters": [
          {
            "name": "bulk_file",
            "in": "path",
            "required": true,
            "description": "Export filename returned from the export request.",
            "schema": {
              "type": "string"
            },
            "example": "124811-1104-products-mylist-export.csv"
          }
        ],
        "responses": {
          "200": {
            "description": "Bulk export status payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkStatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/taxonomy/ebay": {
      "post": {
        "operationId": "getEbaySpecifics",
        "summary": "Get eBay category specifics",
        "description": "Returns the required and recommended item specifics for an eBay\ncategory, along with allowed values where applicable. Requires the\neBay category ID and eBay Site ID.\n\nField-mapping state for each specific is returned in `match`:\n`both` (mapped + DB field), `label` (DB field but unmapped),\n`field` (mapped but no DB field — legacy), `neither`.\n",
        "tags": [
          "Taxonomy"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "eBay category ID."
                  },
                  "siteid": {
                    "type": "string",
                    "description": "eBay Site ID (e.g. `0` or `1` for eBay US)."
                  },
                  "instanceid": {
                    "type": "string",
                    "description": "Optional eBay marketplace instance ID."
                  }
                },
                "required": [
                  "id",
                  "siteid"
                ]
              },
              "examples": {
                "lookup": {
                  "value": {
                    "id": "33713",
                    "siteid": "100"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Category specifics payload.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "display_name": {
                      "type": "string"
                    },
                    "parent_id": {
                      "type": "string"
                    },
                    "parent_name": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "required": [
                    "result"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/logs": {
      "post": {
        "operationId": "searchLogs",
        "summary": "Search application logs",
        "description": "Returns log entries for products, orders, settings, and channel\noperations. Supply one or more search fields to narrow the results.\n\nFilterable fields include `identifier`, `context` (channel name),\n`integration`, `instance`, `request_id`, `id`, `channel_id`, `action`,\n`operation`, `method`, `type`, `result`, `job_id`. Time windows are\nset with `timestamp_start` and `timestamp_end` (`Y-m-d H:i:s`).\n\nPagination is controlled by `start` (offset) and `records` (1-50,\ndefault 20).\n\nThe response includes `found` (total result count, capped at 1001),\n`found_more_logs` (boolean indicating whether more results exist\nbeyond 1001), `start`, `records`, and the result `logs` keyed by\nordinal position.\n",
        "tags": [
          "Logs"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "context": {
                    "type": "string",
                    "description": "Channel name (e.g. `amazon`, `ebay`)."
                  },
                  "identifier": {
                    "type": "string"
                  },
                  "integration": {
                    "type": "string"
                  },
                  "instance": {
                    "type": "string"
                  },
                  "request_id": {
                    "type": "string"
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "add",
                      "edit",
                      "relist",
                      "end",
                      "delete",
                      "start",
                      "sold",
                      "skip",
                      "import",
                      "export",
                      "acknowledge",
                      "tracking"
                    ]
                  },
                  "operation": {
                    "type": "string"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "api",
                      "ui",
                      "bulk",
                      "auto",
                      "sync"
                    ]
                  },
                  "type": {
                    "type": "string"
                  },
                  "result": {
                    "type": "string"
                  },
                  "job_id": {
                    "type": "string"
                  },
                  "channel_id": {
                    "type": "string"
                  },
                  "timestamp_start": {
                    "type": "string"
                  },
                  "timestamp_end": {
                    "type": "string"
                  },
                  "start": {
                    "type": "integer"
                  },
                  "records": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50
                  }
                }
              },
              "examples": {
                "amazonWindow": {
                  "summary": "Recent Amazon log entries",
                  "value": {
                    "context": "amazon",
                    "timestamp_start": "2016-08-20 00:00:01",
                    "timestamp_end": "2016-08-22 00:00:01",
                    "records": 10
                  }
                },
                "amazonErrors": {
                  "summary": "Amazon error log entries",
                  "value": {
                    "context": "amazon",
                    "result": "error",
                    "timestamp_start": "2016-09-08 00:00:01",
                    "timestamp_end": "2016-09-10 00:00:01",
                    "log_level": "3",
                    "records": 10
                  }
                },
                "amazonAsins": {
                  "summary": "Amazon ASIN retrieval log entries",
                  "value": {
                    "context": "suredone",
                    "integration": "amazon-asins",
                    "timestamp_start": "2016-09-08 00:00:01",
                    "timestamp_end": "2016-09-10 00:00:01",
                    "log_level": "3",
                    "records": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Log search results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogSearchResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "xAuthUser": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Auth-User",
        "description": "Paired with `X-Auth-Token`. Both headers must be sent together; this\nscheme entry covers the username header. Token values are available\nat https://app.suredone.com/settings/organization/security.\n"
      },
      "xAuthToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Auth-Token",
        "description": "Paired with `X-Auth-User`. Both headers must be sent together; this\nscheme entry covers the token header.\n"
      },
      "apiUserQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "apiuser",
        "description": "Numeric UID used by the system-admin (`userid: 1`) impersonation path on\n`GET /auth`. When the authenticating actor is the system admin, adding\n`?apiuser=<uid>` causes the response to describe the target user's\naccount instead of the admin's. Non-admin callers may pass the\nparameter, but it is silently ignored. The parameter has no effect on\n`POST /auth`. Verified live 2026-05-20.\n"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Standard error envelope (`result: error`) with a human-readable message.",
        "properties": {
          "result": {
            "type": "string",
            "example": "error"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "result",
          "message"
        ]
      },
      "Item": {
        "type": "object",
        "description": "SureDone product record. Every account has a base set of fields plus\nany custom fields the account has added; only the most common are\nlisted below. Unknown fields are tolerated.\n",
        "properties": {
          "id": {
            "type": "string"
          },
          "sku": {
            "type": "string"
          },
          "guid": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "price": {
            "type": "string"
          },
          "stock": {
            "type": "string"
          },
          "brand": {
            "type": "string"
          },
          "condition": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "media": {
            "type": "string"
          },
          "media1": {
            "type": "string"
          },
          "mediacount": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "date": {
            "type": "string"
          },
          "dateupdated": {
            "type": "string"
          },
          "ebayid": {
            "type": "string"
          },
          "amznsku": {
            "type": "string"
          },
          "amznasin": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "guid"
        ],
        "additionalProperties": true
      },
      "ItemSearchResponse": {
        "type": "object",
        "description": "Map of ordinal position (`\"1\"`, `\"2\"`, ...) to `Item`, with summary\nfields `type`, `all`, and `time` at the top level.\n",
        "properties": {
          "type": {
            "type": "string",
            "example": "items"
          },
          "all": {
            "type": "integer",
            "description": "Total number of matching items across all pages."
          },
          "time": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "all",
          "time"
        ],
        "additionalProperties": true
      },
      "ItemLookupEmpty": {
        "type": "object",
        "description": "Empty-result envelope returned by `/editor/items/edit[/{id}]` when the\nsupplied identifier does not match any item. HTTP status is still 200;\ncallers should detect this shape by the absence of an `id`/`sku` field\nand the presence of `type: \"items\"`.\n",
        "properties": {
          "time": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "items"
            ]
          }
        },
        "required": [
          "time",
          "type"
        ]
      },
      "ItemLookupResponse": {
        "description": "Polymorphic response from `GET /editor/items/edit`. One of:\na flat `Item` record (when `sku`/`guid` matched), the empty-result\nenvelope (when supplied but did not match), or the ordinal-keyed\nlisting map (when no lookup query was supplied).\n",
        "oneOf": [
          {
            "$ref": "#/components/schemas/Item"
          },
          {
            "$ref": "#/components/schemas/ItemLookupEmpty"
          },
          {
            "$ref": "#/components/schemas/ItemSearchResponse"
          }
        ]
      },
      "ItemLookupByIdResponse": {
        "description": "Polymorphic response from `GET /editor/items/edit/{id}`. Either a\nflat `Item` record (match) or the empty-result envelope (no match).\n",
        "oneOf": [
          {
            "$ref": "#/components/schemas/Item"
          },
          {
            "$ref": "#/components/schemas/ItemLookupEmpty"
          }
        ]
      },
      "Order": {
        "type": "object",
        "description": "SureDone order record.",
        "properties": {
          "oid": {
            "type": "string"
          },
          "order": {
            "type": "string"
          },
          "date": {
            "type": "string"
          },
          "dateupdated": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "total": {
            "type": "string"
          },
          "itemtotal": {
            "type": "string"
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "description": "Customer email; may be null for channel orders where the marketplace does not forward an email (e.g. eBay payment-only orders)."
          },
          "shipcarrier": {
            "type": "string"
          },
          "shiptracking": {
            "type": "string"
          },
          "shipdate": {
            "type": "string"
          },
          "items": {
            "type": "string"
          },
          "qtys": {
            "type": "string"
          }
        },
        "required": [
          "order"
        ],
        "additionalProperties": true
      },
      "OrderSearchResponse": {
        "type": "object",
        "description": "Map of ordinal position (`\"1\"`, `\"2\"`, ...) to `Order` plus summary\nfields. The packing-slip variant wraps the orders map in an `orders`\nproperty and includes a rendered `html` packing slip.\n",
        "properties": {
          "all": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "time": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "orders": {
            "type": "object",
            "description": "For the packing-slip variant, wraps the order map.",
            "additionalProperties": {
              "$ref": "#/components/schemas/Order"
            }
          },
          "html": {
            "type": "string",
            "description": "Rendered HTML packing slip (packing-slip variant only)."
          }
        },
        "additionalProperties": {
          "$ref": "#/components/schemas/Order"
        }
      },
      "PackingResponse": {
        "type": "object",
        "description": "Response envelope for `GET /orders/packing`. The inner `orders` object\nhas two shapes: when matches exist it is an ordinal-keyed map of order\nrecords plus an `all` count (the \"populated\" shape); when there are no\nmatches it is an inline metadata object `{type, all, time}` with `all`\nequal to `0`. The outer `html` field is always present and contains the\nrendered packing-slip markup. See the `orders` `oneOf` for the two\nshapes.\n",
        "properties": {
          "orders": {
            "description": "Either a map of ordinal position (`\"1\"`, `\"2\"`, ...) to `Order`\nwith an `all` total count (populated case), or the empty-result\nenvelope `{type: \"orders\", all: 0, time: \"...\"}`.\n",
            "oneOf": [
              {
                "type": "object",
                "title": "PackingOrdersPopulated",
                "description": "Map of ordinal position to `Order`, with an `all` count.",
                "properties": {
                  "all": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "integer"
                      }
                    ]
                  }
                },
                "additionalProperties": {
                  "$ref": "#/components/schemas/Order"
                }
              },
              {
                "type": "object",
                "title": "PackingOrdersEmpty",
                "description": "Metadata envelope returned when no orders match.",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "orders"
                    ]
                  },
                  "all": {
                    "type": "integer",
                    "enum": [
                      0
                    ]
                  },
                  "time": {
                    "type": "string"
                  }
                },
                "required": [
                  "type",
                  "all",
                  "time"
                ]
              }
            ]
          },
          "html": {
            "type": "string",
            "description": "Rendered HTML packing slip."
          },
          "time": {
            "type": "string"
          }
        },
        "required": [
          "orders",
          "html",
          "time"
        ]
      },
      "InvoiceResponse": {
        "type": "object",
        "description": "Success-case invoice envelope. `orders` carries the order record\n(keyed by ordinal position plus an `all` count); `html` is the\nrendered invoice markup.\n",
        "properties": {
          "orders": {
            "type": "object",
            "description": "Map of ordinal position to `Order`, with an `all` count.",
            "properties": {
              "all": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "integer"
                  }
                ]
              }
            },
            "additionalProperties": {
              "$ref": "#/components/schemas/Order"
            }
          },
          "html": {
            "type": "string",
            "description": "Rendered HTML invoice."
          },
          "time": {
            "type": "string"
          }
        },
        "required": [
          "orders",
          "html",
          "time"
        ]
      },
      "InvoiceErrorResponse": {
        "type": "object",
        "description": "Error envelope returned by the invoice endpoint when the order ID\ncannot be resolved. HTTP status is still 200 — callers must check\n`result`.\n",
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "failure"
            ]
          },
          "message": {
            "type": "string"
          },
          "time": {
            "type": "string"
          }
        },
        "required": [
          "result",
          "message",
          "time"
        ]
      },
      "SingleActionResponse": {
        "type": "object",
        "description": "Per-row status (keyed at `\"1\"`) with a top-level summary.",
        "properties": {
          "result": {
            "type": "string"
          },
          "message": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "time": {
            "type": "string"
          },
          "actions": {
            "type": "integer"
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "result",
          "time"
        ],
        "additionalProperties": true
      },
      "BulkActionResponse": {
        "type": "object",
        "description": "Map of ordinal row position (`\"1\"`, `\"2\"`, ...) to a per-row result\nobject plus a top-level summary (`result`, `message`, `time`,\n`actions`).\n",
        "properties": {
          "result": {
            "type": "string"
          },
          "message": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "type": "string"
          },
          "time": {
            "type": "string"
          },
          "actions": {
            "type": "integer"
          }
        },
        "required": [
          "result",
          "time",
          "actions"
        ],
        "additionalProperties": true
      },
      "OrderActionResponse": {
        "type": "object",
        "description": "Response envelope for order create / fulfill calls.",
        "properties": {
          "result": {
            "type": "string"
          },
          "message": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "order": {
            "type": "string"
          },
          "time": {
            "type": "string"
          }
        },
        "required": [
          "result",
          "time"
        ]
      },
      "BulkUploadResponse": {
        "type": "object",
        "description": "Response envelope returned when a bulk upload or export job is accepted.",
        "properties": {
          "result": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "request_file": {
            "type": "string"
          },
          "result_file": {
            "type": "string"
          },
          "export_file": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "time": {
            "type": "string"
          },
          "actions": {
            "type": "integer"
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "result",
          "time"
        ]
      },
      "BulkStatusResponse": {
        "type": "object",
        "description": "Status payload for a bulk job. While the job is still running the\nresponse carries `result: \"failure\"` (with a \"has not completed\" message)\nand `url: false` (literal boolean `false`, not a string). Once the job\ncompletes successfully, `result: \"success\"` and `url` becomes a presigned\nS3 URL string. Callers should branch on `result === \"success\"` rather\nthan on the presence/type of `url` alone.\n",
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "success",
              "failure"
            ]
          },
          "message": {
            "type": "string"
          },
          "url": {
            "description": "Presigned URL to the result CSV (string) once `result == \"success\"`.\nBoolean `false` while the job is still processing or has failed.\n",
            "oneOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "boolean",
                "enum": [
                  false
                ]
              }
            ]
          }
        },
        "required": [
          "result",
          "message"
        ]
      },
      "SimpleResultResponse": {
        "type": "object",
        "description": "Minimal result envelope with `result` and `message`.",
        "properties": {
          "result": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "result",
          "message"
        ]
      },
      "SettingsResponse": {
        "type": "object",
        "description": "Result envelope for settings updates. On `error`, the `errors` map is populated.",
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ]
          },
          "errors": {
            "type": "object",
            "description": "Map of field name to per-field error description.",
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "required": [
          "result"
        ]
      },
      "LogEntry": {
        "type": "object",
        "description": "A single SureDone log record (product, order, channel, etc.).",
        "properties": {
          "id": {
            "type": "string"
          },
          "sd_user_id": {
            "type": "string"
          },
          "log_level": {
            "type": "integer"
          },
          "message": {
            "type": "string"
          },
          "timestamp": {
            "type": "string"
          },
          "context": {
            "type": "string"
          },
          "result": {
            "type": "string"
          },
          "operation": {
            "type": "string"
          },
          "action": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "identifier": {
            "type": "string"
          },
          "job_id": {
            "type": "string"
          },
          "sd_acct_id": {
            "type": "integer"
          },
          "integration": {
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "instance": {
            "type": "integer"
          },
          "channel_id": {
            "type": "string"
          },
          "field_data": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "timestamp"
        ]
      },
      "LogSearchResponse": {
        "type": "object",
        "description": "Response envelope for `POST /logs` searches. `logs` holds the result set keyed by ordinal position.",
        "properties": {
          "result": {
            "type": "string"
          },
          "found": {
            "type": "integer"
          },
          "found_more_logs": {
            "type": "boolean"
          },
          "sort": {
            "type": "string"
          },
          "start": {
            "type": "integer"
          },
          "records": {
            "type": "string"
          },
          "logs": {
            "type": "object",
            "description": "Map of ordinal position (`\"0\"`, `\"1\"`, ...) to a `LogEntry`.",
            "additionalProperties": {
              "$ref": "#/components/schemas/LogEntry"
            }
          }
        },
        "required": [
          "result",
          "found"
        ]
      }
    }
  }
}