{
  "openapi": "3.1.0",
  "info": {
    "title": "SureDone API V1",
    "version": "1.0.0",
    "description": "SureDone REST API v1.\n\n## Authentication\n\nSee the [Authentication guide](https://docs.suredone.com/#description/authentication) in the v3 reference for\ncredentials, a working request, errors, token lifecycle and sub-user headers. The same credentials\napply to v1. The [Authentication endpoints](#tag/authentication) below document `POST /auth` and\n`GET /auth`.\n\n## Unrecognized routes\n\nUnrecognized top-level routes return HTTP `400` with `result: error` and\n`message: Invalid request`. The response does not include an endpoint catalog,\nwhether or not authentication headers are supplied. Clients must not depend\non an `endpoints` field in error responses. Authentication requirements and\nresponses for recognized routes are unchanged.\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."
    },
    {
      "name": "Assets",
      "description": "Account media library — list assets by path, fetch presigned URLs for individual files."
    },
    {
      "name": "Profile",
      "description": "Read/update the authenticated user's profile, manage sub-users, and (MaaS admin only) impersonate or list customer accounts."
    },
    {
      "name": "Imports",
      "description": "Cancel in-progress channel-plugin product imports."
    },
    {
      "name": "Fitment",
      "description": "eBay fitment lookup (category features, catalog search, compatibility, EPID, YMM)."
    }
  ],
  "paths": {
    "/auth": {
      "post": {
        "operationId": "authenticate",
        "summary": "Exchange username/password for an API token",
        "description": "POST form fields `user` and `pass` (or a form field `json` containing\na JSON object with those keys). On success\nthe response includes a `token` you can use in the `X-Auth-Token`\nheader for subsequent authenticated calls.\n\n`X-Auth-User`, `X-Auth-Token` and `?apiuser=` do not supply the\npassword credentials. `X-Auth-Account` can select a sub-user. To check\nan existing token, use `GET /auth` instead. The JSON schema below\ndescribes the object accepted in the form field `json`; a raw JSON\nrequest body is not parsed by this v1 endpoint.\n",
        "tags": [
          "Authentication"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "user": {
                    "type": "string",
                    "description": "Account username or email."
                  },
                  "pass": {
                    "type": "string",
                    "format": "password",
                    "description": "Account password."
                  }
                },
                "required": [
                  "user",
                  "pass"
                ]
              }
            },
            "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": "Password is incorrect"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "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\nUse `<field>:chars<operator><digits>` to compare character counts, for example\n`title:chars>150`, `amzntitle:chars<80`, or `upc:chars!=12`. Supported operators\nare `=`, `!=`, `-=`, `>`, `>=`, `<`, and `<=`; `-=` means `!=`. Use lowercase\n`chars` and a nonnegative whole-number threshold. Conditions combine with\nother filters and OR groups, such as `(title:chars<20 description:chars=0)`.\n\nCounts use the stored value, including spaces and HTML; multibyte characters\ncount once each. Decimal precision is preserved (`29.50` counts as 5,\n`29.5000` as 7), and a stored DATETIME normally counts as 19. Missing rows,\nNULL values, missing JSON keys and JSON null count as 0; the JSON string\n`\"null\"` counts as 4. Core, custom and channel fields are supported, including\nregistered JSON sub-fields. Synthetic fields such as `sku_type`, `kitlinks`\nand `total_stock` retain their existing interpretation. Quoted values such\nas `title:\"chars>150\"` remain literal text searches; malformed or uppercase\nforms retain their existing interpretation. This syntax applies to product\nsearches, including bulk item exports, not order searches.\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": {
      "parameters": [
        {
          "name": "ebay-category-search",
          "in": "query",
          "required": false,
          "description": "Search eBay category suggestions instead of listing or editing products. Uses `siteid` and `instanceid`.",
          "schema": {
            "type": "string"
          },
          "example": "watch band"
        },
        {
          "name": "ebay-specifics-category-id",
          "in": "query",
          "required": false,
          "description": "Look up item specifics for a positive eBay category ID instead of listing or editing products. Uses `ebay-site-id` and `instanceid`.",
          "schema": {
            "type": "string"
          },
          "example": "98624"
        },
        {
          "name": "siteid",
          "in": "query",
          "required": false,
          "description": "eBay site for `ebay-category-search`. Explicit `0` selects US, including\non a non-US account; legacy `1` also resolves to US (`0`). The first\nnonempty value from query then POST form takes precedence. If both are\nmissing or empty, use the selected eBay instance's configured site,\nthen US (`0`) when no site is configured.\n",
          "schema": {
            "type": "string"
          },
          "example": "0"
        },
        {
          "name": "ebay-site-id",
          "in": "query",
          "required": false,
          "description": "eBay site for `ebay-specifics-category-id`, with the same resolution\nas category search: first nonempty query then POST form value, then\nthe selected eBay instance's configured site, then US (`0`). Explicit\n`0` is preserved and legacy `1` resolves to US (`0`).\n",
          "schema": {
            "type": "string"
          },
          "example": "0"
        },
        {
          "name": "instanceid",
          "in": "query",
          "required": false,
          "description": "eBay instance whose configuration is used by category and item-specifics lookups. Defaults to the primary instance.",
          "schema": {
            "type": "integer"
          },
          "example": 2
        }
      ],
      "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\nSupply `ebay-category-search` or `ebay-specifics-category-id` to perform\nthe corresponding eBay lookup instead. Use the same site and instance\nfor both lookups so category IDs and item specifics refer to the same\neBay category tree.\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- `ebay-specifics-category-id=<category-id>` — eBay item-specifics lookup.\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\neBay lookup selectors and site/instance parameters may be supplied in\nthe query or form. Category search uses `siteid`; item specifics uses\n`ebay-site-id`. For either site parameter, a nonempty query value takes\nprecedence over the form, including `0`. An empty query value permits\na nonempty form value; otherwise the selected instance's configured\nsite is used, falling back to US (`0`). Legacy site `1` also means US.\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 the eBay category tree selected by `siteid` and `instanceid`."
                  },
                  "siteid": {
                    "type": "string",
                    "description": "Category-search site. Explicit `0` selects US and legacy `1` maps to US. A nonempty query value takes precedence; missing or empty values fall back to the selected instance's configured site, then US (`0`)."
                  },
                  "ebay-specifics-category-id": {
                    "type": "string",
                    "description": "Positive eBay category ID whose item specifics are requested using `ebay-site-id` and `instanceid`."
                  },
                  "ebay-site-id": {
                    "type": "string",
                    "description": "Item-specifics site, resolved like `siteid`. Explicit `0` selects US; missing or empty query/form values use the selected instance's configured site, then US (`0`). Legacy `1` maps to US."
                  },
                  "instanceid": {
                    "type": "integer",
                    "description": "eBay instance whose configuration is used for both lookups. Defaults to the primary instance."
                  },
                  "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": "Explicit US eBay category search",
                  "value": {
                    "ebay-category-search": "red shoes",
                    "siteid": "0"
                  }
                },
                "ebaySpecifics": {
                  "summary": "Item specifics using the selected instance's configured site",
                  "value": {
                    "ebay-specifics-category-id": "98624",
                    "instanceid": 2
                  }
                },
                "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.\nOptional manual refunds follow the Order canonical refund contract. Form `json`\ncarries structured refunds; `requests` carries header/row batches. Validation\nfailures retain HTTP 200 with result failure. Invalid refund batches create no\ncustomer, address, order or refund rows.\n",
        "tags": [
          "Orders"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "json": {
                    "type": "string",
                    "contentMediaType": "application/json",
                    "description": "Structured order input, preserving exact refund strings and explicit null values.",
                    "contentSchema": {
                      "type": "object",
                      "properties": {
                        "refunds": {
                          "type": [
                            "array",
                            "string",
                            "null"
                          ],
                          "description": "Manual patches or JSON-encoded collection; null and empty collections are no-ops, not deletion.",
                          "items": {
                            "$ref": "#/components/schemas/ManualRefund"
                          }
                        }
                      }
                    }
                  },
                  "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."
                  },
                  "skufield": {
                    "type": "string",
                    "description": "Opt-in line-item matching override naming any mapped product field (e.g. a custom field like `admarksku`; channel JSON sub-fields included). When present, each entry in `items` is matched against that field only — no channel identifiers and no guid fallback; matched entries link to the product (sku rewritten to the product guid), unmatched entries stay unlinked and the order is still created. An unknown field name is rejected with a code 6 error and the order is not created."
                  }
                },
                "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\nwritable field may be updated. Optional manual refunds follow the Order\ncanonical refund contract. Refund validation retains HTTP 200 warning results\nfor addressed updates, including individual `requests` rows; malformed headers\nalso return addressed failures. Foreign IDs and protected metadata are rejected.\nOrdinary legacy errors retain their existing envelopes.\n",
        "tags": [
          "Orders"
        ],
        "security": [
          {
            "xAuthUser": [],
            "xAuthToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "json": {
                    "type": "string",
                    "contentMediaType": "application/json",
                    "description": "Structured order input, preserving exact refund strings and explicit null values.",
                    "contentSchema": {
                      "type": "object",
                      "properties": {
                        "refunds": {
                          "type": [
                            "array",
                            "string",
                            "null"
                          ],
                          "description": "Manual patches or JSON-encoded collection; null and empty collections are no-ops, not deletion.",
                          "items": {
                            "$ref": "#/components/schemas/ManualRefund"
                          }
                        }
                      }
                    }
                  },
                  "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\nAdding or updating a saved Product or Order export through\n`user_interface.products.export.add` or\n`user_interface.orders.export.add` requires full Settings access.\nA sub-account with view-only or denied Settings access receives HTTP\n200 with `result: error` and a permission reason in `message`; the\nsaved export is not changed.\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, except permission denials, which use `message`.\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"
                }
              }
            }
          },
          "503": {
            "description": "The request included a storefront or eBay template mutation, but\ntemplate mutations are temporarily paused or their coordination\nstate could not be verified. No setting or template mutation has\nbegun; retry after the requested delay.\n",
            "headers": {
              "Retry-After": {
                "description": "Number of seconds to wait before retrying the request.",
                "schema": {
                  "type": "integer",
                  "default": 30
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StorefrontTemplateMutationUnavailable"
                },
                "examples": {
                  "paused": {
                    "value": {
                      "result": "error",
                      "error": "storefront_template_mutations_unavailable",
                      "message": "Storefront template changes and executable previews are temporarily paused for a release.",
                      "retry_after": 30
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/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",
                    "description": "Search query for the selected type. Item exports support the same product search syntax as /search/items/{query}, including `title:chars>150` and `description:chars=0` using stored values."
                  },
                  "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`).\nTo match any of several values, send a filter field other than `id`\nas a comma-separated list (`context=amazon,ebay`) or as an array\n(`context[]=amazon&context[]=ebay`); `id` takes a single log id.\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"
                }
              }
            }
          }
        }
      }
    },
    "/assets": {
      "get": {
        "operationId": "getAsset",
        "summary": "Get asset endpoint (always returns Invalid asset request)",
        "description": "The bare `/assets` endpoint always returns an `Invalid asset request`\nerror envelope. To fetch a presigned URL for a media asset, use\n`GET /assets/{file}` (with optional `?path=` query) or `GET /assets/list`.\n\nRequires `media` access at the `view` level (sub-user permission gate).\n",
        "tags": [
          "Assets"
        ],
        "responses": {
          "200": {
            "description": "Always returns the `Invalid asset request` error envelope (this endpoint is a placeholder for the `/assets/{file}` and `/assets/list` operations).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AssetInvalidResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API credentials."
          }
        }
      }
    },
    "/assets/list": {
      "get": {
        "operationId": "listAssets",
        "summary": "List media assets under a path",
        "description": "Lists files under the named media path. Valid paths are taken from\n`$sd->path_names`, which seeds with `['media']` and is extended by the\ncomma/`*`-separated `image_media_locations` user option. If `path` is\nomitted or invalid, a success envelope is returned with an empty\nmedia list (or the default path).\n\nRequires `media` access at the `view` level.\n",
        "tags": [
          "Assets"
        ],
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": false,
            "description": "Media path to list. Must be one of the account's configured\n`image_media_locations` (defaults include `media`). Unknown\npaths cause an `error` result.\n",
            "schema": {
              "type": "string"
            },
            "example": "media"
          }
        ],
        "responses": {
          "200": {
            "description": "List of assets (or empty when path is invalid).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AssetListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API credentials."
          },
          "403": {
            "description": "Caller lacks `media:view` access."
          }
        }
      }
    },
    "/assets/{file}": {
      "get": {
        "operationId": "getAssetByName",
        "summary": "Get a presigned URL for a named media asset",
        "description": "Like `GET /assets`, but the file name is supplied as the second path\nsegment instead of via `?location=`. The lookup key sent to S3 is\n`{path}/{file}` where `{path}` defaults from `?path=` (falling back\nto the empty string). `{file}` is normalized via PHP `basename()`,\nso directory traversal segments are stripped. Returns a 10-minute\npresigned URL on success.\n\nRequires `media` access at the `view` level.\n",
        "tags": [
          "Assets"
        ],
        "parameters": [
          {
            "name": "file",
            "in": "path",
            "required": true,
            "description": "Filename of the asset (no directory components — `basename()` is enforced).",
            "schema": {
              "type": "string"
            },
            "example": "logo.png"
          },
          {
            "name": "path",
            "in": "query",
            "required": false,
            "description": "Media path (folder) the file lives under.",
            "schema": {
              "type": "string"
            },
            "example": "media"
          }
        ],
        "responses": {
          "200": {
            "description": "Presigned URL for the asset (or `error` if S3 returned no object).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AssetItemResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API credentials."
          },
          "403": {
            "description": "Caller lacks `media:view` access."
          }
        }
      }
    },
    "/profile": {
      "get": {
        "operationId": "getProfile",
        "summary": "Get the authenticated user's profile",
        "description": "Returns the profile of the user identified by the authenticating\ntoken. Sensitive columns (UID, UAID, token, secret, cycle, openid,\nebayid, amznid, notes) are stripped before the response is returned.\n",
        "tags": [
          "Profile"
        ],
        "responses": {
          "200": {
            "description": "Profile record (free-form — additional account columns may appear).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfileResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API credentials."
          }
        }
      }
    },
    "/profile/update": {
      "post": {
        "operationId": "updateProfile",
        "summary": "Update the authenticated user's profile",
        "description": "Updates the authenticated user's profile. Non-admin callers cannot\nchange `role`, `access`, or request token regeneration; these fields\nare stripped server-side.\n\nFields are read via `AdminFunctions::apiVars(null, 'add')` from\n`$_POST` or a `json={...}` form field. Each accepted key is prefixed\nwith `sd_` before being passed to `AdminFunctions::processUser`. The\nset below documents the unprefixed form (recommended) — `sd_*` aliases also work.\n",
        "tags": [
          "Profile"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProfileUpdateRequest"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/ProfileUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update result envelope. `result` is `success` on update, `error` otherwise.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API credentials."
          }
        }
      }
    },
    "/profile/update/{userpk}": {
      "post": {
        "operationId": "updateSubuserProfile",
        "summary": "Update a sub-user's profile (admin only)",
        "description": "Updates the sub-user identified by `userpk` (a sub-user UAID, ≥ 1).\nOnly callers whose role is one of `owner`, `admin`, `support`, or\n`developer` may target a sub-user this way — for non-admin callers\nthe path segment is ignored and the call updates the caller instead.\n",
        "tags": [
          "Profile"
        ],
        "parameters": [
          {
            "name": "userpk",
            "in": "path",
            "required": true,
            "description": "Sub-user UAID (from `sd_users_accts`). Must be a positive integer.",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "example": 3815
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProfileUpdateRequest"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/ProfileUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Update result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API credentials."
          }
        }
      }
    },
    "/profile/add": {
      "post": {
        "operationId": "addProfile",
        "summary": "Create a new sub-user (owner/admin only)",
        "description": "Creates a sub-user account under the authenticated owner. Only callers\nwhose role is `owner` or `admin` may create users; any other role\nreturns `User is not allowed to add new users`. The new sub-user\ninherits the caller's UID as `userid` and gets a default role of `user`.\nInvitation creation shares server-side actor and organization limits with\nthe web application. Outstanding invitations, including expired invitations,\ncount toward a configurable organization cap. Existing active members do not\ncount toward that cap. A rejected admission creates no new member.\n",
        "tags": [
          "Profile"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProfileAddRequest"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/ProfileAddRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Add result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API credentials."
          },
          "403": {
            "description": "The internal invitation admission context could not be authorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultMessage"
                }
              }
            }
          },
          "409": {
            "description": "An invitation is already pending or another invitation operation is in progress. Refresh the members list before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultMessage"
                }
              }
            }
          },
          "429": {
            "description": "An invitation creation limit or the outstanding-invitation cap was reached. Retry later or cancel an unused invitation in the application.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultMessage"
                }
              }
            }
          },
          "503": {
            "description": "Invitation security accounting is temporarily unavailable. No new member was created by this rejected admission.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultMessage"
                }
              }
            }
          }
        }
      }
    },
    "/profile/username": {
      "post": {
        "operationId": "changeProfileUsername",
        "summary": "Change the authenticated user's account username",
        "description": "Renames the authenticated user. The new username must be supplied\nas `?username=` (query or form).\n",
        "tags": [
          "Profile"
        ],
        "parameters": [
          {
            "name": "username",
            "in": "query",
            "required": true,
            "description": "New username (slug). Server-side normalized via `Helpers::makeSlug`.",
            "schema": {
              "type": "string"
            },
            "example": "newusername"
          }
        ],
        "responses": {
          "200": {
            "description": "Update result envelope. `result` is `success` on rename, otherwise an `error` with the exception message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API credentials."
          },
          "503": {
            "description": "Storefront template mutations are temporarily paused or their\ncoordination state could not be verified. The username and its\nstorefront routing state were not changed; retry after the\nrequested delay.\n",
            "headers": {
              "Retry-After": {
                "description": "Number of seconds to wait before retrying the request.",
                "schema": {
                  "type": "integer",
                  "default": 30
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StorefrontTemplateMutationUnavailable"
                },
                "examples": {
                  "paused": {
                    "value": {
                      "result": "error",
                      "error": "storefront_template_mutations_unavailable",
                      "message": "Storefront template changes and executable previews are temporarily paused for a release.",
                      "retry_after": 30
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/profile/manage/{uid}": {
      "post": {
        "operationId": "manageMaasUser",
        "summary": "MaaS admin — manage a customer account",
        "description": "Restricted to MaaS admins (`Helpers::isMaasAdminIn()`). Lets the\nadmin update an arbitrary customer account by UID, or perform one\nof two side-effect actions selected by the optional fourth path\nsegment:\n\n- `disable` — calls `AdminFunctions::disableAccount` (downgrades\n  plan, disables sub-users, permanently deletes their data).\n- `migrate` — calls `AdminFunctions::migrateUserWithCreation`\n  to enqueue a Cognito migration job for the customer email.\n",
        "tags": [
          "Profile"
        ],
        "parameters": [
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "description": "Target customer UID. Must be `>= 1000`; smaller values are rejected as invalid.",
            "schema": {
              "type": "integer",
              "minimum": 1000
            },
            "example": 1021
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProfileManageRequest"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/ProfileManageRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result envelope:\n\n- `result: success` with `User <UID> updated successfully` on edit/disable/migrate;\n- `result: error` with `Unauthorized`, `User is invalid`, `Access to user unauthorized`, or the underlying exception message on failure.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API credentials."
          },
          "503": {
            "description": "A requested primary-account status change could alter which\nstorefronts belong to the protected active corpus, but template\nmutations are temporarily paused or their coordination state\ncould not be verified. No account status change began; retry\nafter the requested delay.\n",
            "headers": {
              "Retry-After": {
                "description": "Number of seconds to wait before retrying the request.",
                "schema": {
                  "type": "integer",
                  "default": 30
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StorefrontTemplateMutationUnavailable"
                },
                "examples": {
                  "paused": {
                    "value": {
                      "result": "error",
                      "error": "storefront_template_mutations_unavailable",
                      "message": "Storefront template changes and executable previews are temporarily paused for a release.",
                      "retry_after": 30
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/profile/users": {
      "get": {
        "operationId": "listMaasUsers",
        "summary": "MaaS admin — list all customer accounts",
        "description": "Restricted to MaaS admins (`Helpers::isMaasAdminIn()`). Returns\nevery owner-level user record visible from the authenticated MaaS\nadmin's database, with password/secret/email-hash/verification-key fields stripped.\n",
        "tags": [
          "Profile"
        ],
        "responses": {
          "200": {
            "description": "List of users (success) or `Unauthorized`/`Users not found` error envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfileUsersResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API credentials."
          }
        }
      }
    },
    "/imports/cancel": {
      "post": {
        "operationId": "cancelImport",
        "summary": "Cancel an in-progress channel-plugin product import",
        "description": "Resets the named plugin's product-import settings, terminating any\nin-progress import for that plugin instance. Internally this calls\n`Plugins\\<name>\\<name>::resetImport()`, which zeroes\n`import_products_set_limit` and disables `import_products_set` /\n`_set_mode`. The request body may be sent as JSON, form data, or\nquery string.\n\nAny other path under `/imports/...` returns the `Invalid imports\nendpoint` failure envelope.\n",
        "tags": [
          "Imports"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImportCancelRequest"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/ImportCancelRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cancel result envelope:\n\n- `result: success` with `Import cancelled successfully` on success;\n- `result: failure` with `Plugin name is required`, `Plugin not found`, or `Failed to cancel import: <reason>` on error.\n",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ImportCancelSuccess"
                    },
                    {
                      "$ref": "#/components/schemas/ImportCancelFailure"
                    }
                  ]
                },
                "examples": {
                  "success": {
                    "summary": "Import cancelled",
                    "value": {
                      "result": "success",
                      "message": "Import cancelled successfully"
                    }
                  },
                  "missingName": {
                    "summary": "Missing plugin name",
                    "value": {
                      "result": "failure",
                      "errors": "Plugin name is required"
                    }
                  },
                  "pluginNotFound": {
                    "summary": "Unknown / unconnected plugin",
                    "value": {
                      "result": "failure",
                      "errors": "Plugin not found"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API credentials."
          }
        }
      }
    },
    "/fitment/ebay/category": {
      "post": {
        "operationId": "getEbayFitmentCategoryFeature",
        "summary": "Get eBay vehicle-type feature for a category",
        "description": "Reads the `vehicleType` feature of the supplied eBay category from\nthe cached eBay Taxonomy collection (Mongo `ebay_taxonomies`).\nImplemented by `Plugins\\ebay\\Data::getCategoryFeature($id, 'vehicleType', $siteId)`.\n\n`siteid` defaults to `100` (eBay Motors) if not supplied. The\nlegacy convention `siteid=1` is translated to `0` (US site)\ninternally.\n",
        "tags": [
          "Fitment"
        ],
        "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. Defaults to `100` (eBay Motors).",
                    "default": "100"
                  }
                },
                "required": [
                  "id"
                ]
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "siteid": {
                    "type": "string"
                  }
                },
                "required": [
                  "id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Vehicle-type feature payload (channel-specific structure) or `{ message }` on error.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/fitment/ebay/catalog/{action}": {
      "post": {
        "operationId": "ebayFitmentCatalog",
        "summary": "Search the eBay catalog or look up product compatibilities",
        "description": "Two operations are exposed under this path:\n\n- `search` — keyword search against the eBay catalog. Runs\n  `Sd\\Ebay\\FindProducts` with `{ input: <q>, siteid }`. Returns an\n  array of `{ epid, title }` (or `false` if no `itemSummaries`).\n- `compatibility` — fetch product compatibilities for an EPID\n  (or other catalog product id). Runs `Sd\\Ebay\\GetProductCompatibilities`\n  with `{ epid, type, idType }` (default `idType` = `epid`).\n",
        "tags": [
          "Fitment"
        ],
        "parameters": [
          {
            "name": "action",
            "in": "path",
            "required": true,
            "description": "`search` runs a keyword search against the eBay catalog; `compatibility` looks up product compatibilities by EPID.",
            "schema": {
              "type": "string",
              "enum": [
                "search",
                "compatibility"
              ]
            }
          },
          {
            "name": "instance",
            "in": "query",
            "required": false,
            "description": "eBay instance number (used by the `search` action when initializing the catalog connector). Defaults to 0.",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "q": {
                    "type": "string",
                    "description": "Keyword query (required for `search`)."
                  },
                  "epid": {
                    "type": "string",
                    "description": "eBay catalog product ID (required for `compatibility`)."
                  },
                  "type": {
                    "type": "string",
                    "description": "Optional product type filter (compatibility)."
                  },
                  "idType": {
                    "type": "string",
                    "description": "ID type for `compatibility`. Defaults to `epid`.",
                    "default": "epid"
                  },
                  "siteid": {
                    "type": "string",
                    "description": "eBay Site ID. Defaults to `100`.",
                    "default": "100"
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "q": {
                    "type": "string"
                  },
                  "epid": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  },
                  "idType": {
                    "type": "string"
                  },
                  "siteid": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results or compatibility payload.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "epid": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    {
                      "type": "boolean",
                      "description": "`false` when no results were found."
                    },
                    {
                      "type": "array",
                      "description": "Compatibility entries from `Sd\\Ebay\\GetProductCompatibilities::run()` (or `[]` for invalid EPID).",
                      "items": {
                        "type": "object",
                        "properties": {
                          "data": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "epid": {
                            "oneOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "boolean"
                              }
                            ]
                          },
                          "note": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/fitment/ebay/compatibility/{action}": {
      "post": {
        "operationId": "ebayFitmentCompatibility",
        "summary": "Look up compatibility data or selectable values",
        "description": "Two operations:\n\n- `select` — returns selectable values for a fitment picker. Runs\n  `GetSelectValues` with `{ type, which, data, siteid, engineTrim }`.\n  Valid `which` values include `getEpids`, `getKtypes`, `getyears`\n  and the empty string.\n- any other (e.g. omitted/`values`) — runs `GetYmmValues` with\n  `{ type, input, siteId }`.\n",
        "tags": [
          "Fitment"
        ],
        "parameters": [
          {
            "name": "action",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "`select` for `GetSelectValues`, anything else routes to `GetYmmValues`."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "description": "Fitment type (e.g. vehicle category)."
                  },
                  "which": {
                    "type": "string",
                    "description": "Selector kind for `select` action.",
                    "enum": [
                      "getEpids",
                      "getKtypes",
                      "getyears",
                      ""
                    ]
                  },
                  "data": {
                    "type": "string",
                    "description": "Selector context (current selection)."
                  },
                  "input": {
                    "type": "string",
                    "description": "Input value (non-`select` action — passed to `GetYmmValues`)."
                  },
                  "siteid": {
                    "type": "string",
                    "default": "100"
                  },
                  "engineTrim": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Selector or YMM payload.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/fitment/ebay/epid": {
      "post": {
        "operationId": "ebayFitmentEpid",
        "summary": "Resolve EPID values for a vehicle / catalog input",
        "description": "Runs `GetEpidValues` with `{ type, input, siteId, result: 'array', ktype }`.\nReturns an array of EPID matches.\n",
        "tags": [
          "Fitment"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string"
                  },
                  "input": {
                    "type": "string"
                  },
                  "siteid": {
                    "type": "string",
                    "default": "100"
                  },
                  "ktype": {
                    "type": "string",
                    "description": "Optional KType identifier."
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "EPID lookup payload.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/fitment/ebay/ymm": {
      "post": {
        "operationId": "ebayFitmentYmm",
        "summary": "Look up Year/Make/Model fitment values (placeholder)",
        "description": "The framework dispatch in `src/Api.php` whitelists `ymm` as a valid\nsub-path under `/v1/fitment/ebay/*` but does not provide a concrete\nhandler branch — issuing a `POST /v1/fitment/ebay/ymm` returns the\nimplicit empty handler result.\n\nPrefer `/v1/fitment/ebay/compatibility` (without `action=select`)\nfor Year/Make/Model lookups via `GetYmmValues`.\n",
        "tags": [
          "Fitment"
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "No body is returned. The framework whitelists `ymm` as a valid\nsub-path but has no concrete handler — the dispatcher returns\nwithout invoking `apiRespond`, so the body is empty.\n"
          }
        }
      }
    }
  },
  "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. See the\n[Authentication guide](https://docs.suredone.com/#description/authentication).\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. See the\n[Authentication guide](https://docs.suredone.com/#description/authentication).\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"
        ]
      },
      "StorefrontTemplateMutationUnavailable": {
        "type": "object",
        "description": "Fail-closed response returned before a storefront or eBay template\nmutation begins when the shared mutation pause is active or cannot be\nverified.\n",
        "required": [
          "result",
          "error",
          "message",
          "retry_after"
        ],
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "error": {
            "type": "string",
            "enum": [
              "storefront_template_mutations_unavailable"
            ]
          },
          "message": {
            "type": "string"
          },
          "retry_after": {
            "type": "integer",
            "minimum": 1,
            "default": 30
          }
        }
      },
      "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. Full reads conditionally include read-only\n`refundreferences` and `refundreferencescomplete`. Monetary refunds remain on their recorded\nowner; references never contribute to legacy `returntotal` or `returnitems`.\nNew splits and combines preserve the original refund owner without copying\nits refunds. Existing historical refund rows keep their recorded owners.\nRefund deletion must address its recorded owner and local refund ID;\na reference on a descendant does not grant deletion from that descendant.\nFlattened responses keep references as an array; CSV exports encode that\narray as JSON once and serialize completeness as a boolean.\nThe computed pair is available only when fresh tenant configuration and\nphysical-column metadata prove neither name belongs to an existing custom\norder field. A collision or unproven metadata suppresses both computed\nfields, preserving existing custom-field selectors and output formats.\nExisting custom values under these names are not reference metadata.\nNew custom fields cannot use these two reserved names.\nTo reconcile a mirrored refund collection, read and replace the owning\norder's collection. Use overlap when polling owner `dateupdatedutc`;\ndescendant reference changes do not update descendant timestamps. This\nwriter contract below supplies the canonical mutation guarantees.\nCanonical refunds are owned by the addressed order. A missing refundid appends a new anonymous\nrefund; a positive local refundid edits only that owner's row. Foreign or malformed IDs reject the\naddressed order's entire refund batch before writes. Anonymous append has no replay identity:\nread back after an uncertain outcome instead of blindly retrying it.\n\nThe five amount fields refundtotal, refunditemtotal, refundshippingtotal, refundtaxtotal and\nrefundreturnshipcost accept plain nonnegative decimal strings or JSON null, with at most 14\nsignificant whole and 6 significant fractional digits. JSON numbers, exponents, negative values\nand explicit blank money strings reject. Missing preserves, null clears, and \"0\" records known\nzero. Amounts are not inferred from opaque refunddetails totals or from each other. Currency\nmust match valid explicit owner currency; currency updates cannot relabel an existing normalized\nrefund. The manual return shipping cost uses that same currency.\n\nrefundlines is an optional input-only normalized line list. Its quantity, amount and tax use\nexact nullable decimal strings; itemid must belong to the owner, and providerlineid must be\nnonempty or null. Local item bindings cannot be supplied while creating an idless new order.\nExisting refunditems, refundsku/refundquantity and refunddetails.items retain opaque legacy\nsemantics, including numeric quantities and unknown keys. Do not combine refundlines with an\nold item representation for the same refund event, even through losing aliases. Separate\nnumbered slots or collection rows may use different representations. Established precedence\namong old representations is unchanged. Legacy refunddate ISO/NOW conversion remains supported.\n\nSource identity, raw channel identity, first-recorded date, ancestry and verified binding metadata\nare server-owned. Attempts to assign them reject even in hidden or losing structured aliases.\nOrdinary unrelated order custom fields retain their existing meaning. New flat refund fields\nare unavailable where fresh tenant metadata cannot prove a collision-free namespace; nested\nowned refund values remain separate from custom item values.\n\nNew normalized/enriched creation is disabled by default and requires current storage admission\nand the server gate. Existing owner-bound maintenance remains protected with the gate off.\nPartial/restored storage rejects refund mutation; proven original legacy storage admits only\nvalidated opaque legacy operations. Ordinary requests without refund intent continue normally.\nA whole addressed refund batch is preflighted before mixed order side effects. Refund-only\nchanges do not change stock, shipments, payment or order status. True no-ops do not update\nowner timestamps or send change notifications. Changed owner timestamps and refund writes\ncommit together; notifications run only after durable commit, and delivery errors do not make\na committed anonymous append safe to retry. Mixed non-refund side effects retain their existing\ntransaction boundaries.\n\nReads expose directly owned refunds, sorted by refunddate and local refundid. Canonical money\nis returned as exact nullable strings. Readiness failures preserve legacy reads but make explicit\nunavailable canonical selectors/search predicates fail instead of silently dropping them. Exact\nmoney search supports both AND/OR branches, for example refundtotal:=0; empty equality tests\nunknown SQL NULL, separately from zero. Poll owner dateupdatedutc with overlap and include\narchived orders when polling refunddateadded. Ancestor references never add money to descendants.\nFlattened multi-refund columns retain a slot for every sorted refund, including null and trailing\nnull; CSV encodes these arrays as JSON once.\n\nFor file transport only, an ordinary empty flat CSV cell means absent/no-change after custom\nnamespace and raw protected-field validation. It does not conflict with a nonblank refundlines\ncell. \"0\", whitespace, nonempty JSON strings and explicit keys inside structured refund JSON\n(including null, [] and empty string) keep their presence. Use structured refund JSON for an\nexplicit nullable amount clear; there is no magic CSV null token. Blank-only refund cells are a\nsuccessful no-op. JSON/API/Automation inputs do not use CSV blank elision.\n",
        "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"
          },
          "refunds": {
            "type": "array",
            "readOnly": true,
            "items": {
              "$ref": "#/components/schemas/OwnedRefund"
            }
          },
          "refundreferences": {
            "$ref": "#/components/schemas/RefundReferences"
          },
          "refundreferencescomplete": {
            "$ref": "#/components/schemas/RefundReferencesComplete"
          }
        },
        "required": [
          "order"
        ],
        "additionalProperties": true
      },
      "RefundAmount": {
        "type": [
          "string",
          "null"
        ],
        "pattern": "^[0-9]+(?:\\.[0-9]+)?$",
        "description": "Exact nonnegative decimal; 14 significant whole and 6 significant fractional digits maximum. Null is unknown and zero is known zero. Readers remove insignificant zeros.",
        "examples": [
          "0",
          "1.23",
          "99999999999999.999999",
          null
        ]
      },
      "NormalizedRefundLine": {
        "description": "Explicit normalized refund line; it does not change legacy opaque item aliases.",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "itemid": {
            "type": [
              "integer",
              "string"
            ],
            "description": "Positive local item ID bound to the addressed existing owner."
          },
          "providerlineid": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 512
          },
          "sku": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 100
          },
          "title": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 500
          },
          "quantity": {
            "$ref": "#/components/schemas/RefundAmount"
          },
          "amount": {
            "$ref": "#/components/schemas/RefundAmount"
          },
          "tax": {
            "$ref": "#/components/schemas/RefundAmount"
          }
        }
      },
      "ManualRefund": {
        "type": "object",
        "description": "Public manual patch. Missing ID appends; existing positive ID addresses only the same owner. Server identity and protected detail metadata are forbidden.",
        "properties": {
          "refundid": {
            "type": [
              "integer",
              "string"
            ]
          },
          "refunddate": {
            "type": "string"
          },
          "refunddetails": {
            "description": "Opaque legacy data; structured server-owned identity aliases are rejected before precedence or merge."
          },
          "refundtotal": {
            "$ref": "#/components/schemas/RefundAmount"
          },
          "refunditemtotal": {
            "$ref": "#/components/schemas/RefundAmount"
          },
          "refundshippingtotal": {
            "$ref": "#/components/schemas/RefundAmount"
          },
          "refundtaxtotal": {
            "$ref": "#/components/schemas/RefundAmount"
          },
          "refundreturnshipcost": {
            "$ref": "#/components/schemas/RefundAmount"
          },
          "refundcurrency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Validation context matching owner currency; cannot clear or re-denominate money."
          },
          "refundtype": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "refund",
              null
            ]
          },
          "refundlines": {
            "type": [
              "array",
              "string"
            ],
            "writeOnly": true,
            "description": "Normalized line list, supplied directly or as a JSON-encoded array of the same objects.",
            "items": {
              "$ref": "#/components/schemas/NormalizedRefundLine"
            },
            "contentMediaType": "application/json",
            "contentSchema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/NormalizedRefundLine"
              }
            }
          },
          "refunditems": {
            "description": "Legacy opaque item representation, not normalized refundlines."
          },
          "refundsku": {
            "description": "Legacy opaque SKU representation."
          },
          "refundquantity": {
            "description": "Legacy quantity representation, retaining numeric compatibility."
          }
        }
      },
      "OwnedRefund": {
        "type": "object",
        "readOnly": true,
        "description": "Directly owned refund only; canonical source keys are not projected as public fields. Opaque historical refunddetails is not redacted. Canonical fields require proven full storage readiness.",
        "properties": {
          "refundid": {
            "type": "string"
          },
          "refunddate": {
            "type": "string"
          },
          "refunddetails": {
            "description": "Existing opaque legacy details and retained server-protected metadata."
          },
          "refundtotal": {
            "$ref": "#/components/schemas/RefundAmount"
          },
          "refunditemtotal": {
            "$ref": "#/components/schemas/RefundAmount"
          },
          "refundshippingtotal": {
            "$ref": "#/components/schemas/RefundAmount"
          },
          "refundtaxtotal": {
            "$ref": "#/components/schemas/RefundAmount"
          },
          "refundreturnshipcost": {
            "$ref": "#/components/schemas/RefundAmount"
          },
          "refundcurrency": {
            "type": [
              "string",
              "null"
            ]
          },
          "refundtype": {
            "type": [
              "string",
              "null"
            ]
          },
          "refunddateadded": {
            "type": [
              "string",
              "null"
            ],
            "description": "Immutable first-recorded time; historical null is preserved."
          },
          "refundchannelid": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512,
            "description": "Trusted raw channel identity, never a public write or unique identity by itself."
          }
        }
      },
      "RefundReferences": {
        "type": "array",
        "readOnly": true,
        "description": "When the computed namespace is available: nonmonetary pointers to refunds\nowned by known ancestor orders, including\nintermediate split/combine orders. The current order's own refunds are\nexcluded. Each (refundoid, refundid) pair occurs once, sorted by refundoid\nthen refundid. Read the owner to retrieve its refund; do not add reference\nvalues to order totals or allocate refund money or quantities to a child.\n",
        "items": {
          "type": "object",
          "required": [
            "refundid",
            "refundoid"
          ],
          "properties": {
            "refundid": {
              "type": "integer",
              "description": "Local refund ID on the owning order.",
              "example": 42
            },
            "refundoid": {
              "type": "integer",
              "description": "Numeric OID of the order that owns the refund.",
              "example": 1001
            }
          }
        }
      },
      "RefundReferencesComplete": {
        "type": "boolean",
        "readOnly": true,
        "description": "When the computed namespace is available: whether bounded traversal\ncovered the complete locally recorded ancestry.\nFalse means history is unknown, unavailable, missing, cyclic, or beyond a\ntraversal limit; known references may still be returned. An empty array\nwith false does not establish that no ancestor has refunds. True does not\ncertify complete marketplace ingestion, financial ownership, or item\nallocation. Reads retain the existing read-replica consistency semantics.\n",
        "example": false
      },
      "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",
            "description": "The identifier column detected in the uploaded file — one of `id`, `sku`, `guid`, or a\nconfigured custom identifier. This names the column your rows are addressed by; it is not a\nrecord id and not a job id. To act on the job itself, use `job_id`.\n",
            "example": "guid"
          },
          "job_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Identifier of the bulk processing job created for this upload. Pass it to\n`/bulk/results/cancel/{job_id}` to cancel the job, and use it to correlate the upload with\nits entry in the bulk jobs listing.\n\n`null` when no job was created: the upload was submitted as a preview, or bulk processing is\nnot enabled for the account. Treat a null value as \"nothing to poll or cancel\" rather than\npassing it on.\n",
            "example": "66d2f1a4c3b28e0012ab34cd"
          },
          "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. Permission denials use `message`; field errors use `errors`.",
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ]
          },
          "message": {
            "type": "string",
            "description": "Permission-denial reason when the caller cannot perform the settings update.",
            "example": "You do not have permission to access this page. Please contact your system administrator."
          },
          "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"
        ]
      },
      "AssetListResponse": {
        "type": "object",
        "description": "Response from `GET /v1/assets/list`. When the requested path is invalid, `result` is `error` and `media` is an empty placeholder.",
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ]
          },
          "media": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "description": "Public-base URL for the media path (CDN-aware).",
                "example": "https://assets.suredone.com/"
              },
              "path": {
                "type": "string",
                "description": "The path that was listed.",
                "example": "media"
              },
              "upath": {
                "type": "string",
                "description": "Fully-qualified S3 prefix (account-scoped) for the listing.",
                "example": "1021/media/"
              },
              "media": {
                "type": "array",
                "description": "S3 keys (relative to bucket root) under the listed path.",
                "items": {
                  "type": "string"
                },
                "example": [
                  "1021/media/logo.png",
                  "1021/media/banner.jpg"
                ]
              }
            }
          }
        },
        "required": [
          "result",
          "media"
        ]
      },
      "AssetItemResponse": {
        "type": "object",
        "description": "Response for `GET /v1/assets/{file}` and `GET /v1/assets` (with `?location=`). The `media.url` field is a 10-minute S3 presigned URL, or `null` when the object does not exist.",
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ]
          },
          "media": {
            "type": "object",
            "properties": {
              "url": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "10-minute presigned S3 URL, or `null` if the object does not exist."
              },
              "path": {
                "type": "string",
                "description": "Joined `{path}/{file}` lookup key (server-built)."
              },
              "media": {
                "type": "array",
                "description": "Always empty for the single-file form.",
                "items": {
                  "type": "string"
                },
                "example": []
              }
            }
          }
        },
        "required": [
          "result",
          "media"
        ]
      },
      "AssetInvalidResponse": {
        "type": "object",
        "description": "Fallback envelope returned by `GET /v1/assets` with no file selector and no `?location=`.",
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "message": {
            "type": "string",
            "example": "Invalid asset request"
          }
        },
        "required": [
          "result",
          "message"
        ]
      },
      "ProfileResponse": {
        "type": "object",
        "description": "Profile envelope returned by `GET /v1/profile`. Built from\n`AdminFunctions::getUser`, then stripped of sensitive columns\n(UID/UAID/token/secret/cycle/openid/ebayid/amznid/notes).\n",
        "properties": {
          "userid": {
            "type": "integer",
            "description": "Authenticating user's UID. Always present.",
            "example": 1021
          },
          "username": {
            "type": "string",
            "example": "examplecompany"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "owner@example.com"
          },
          "name": {
            "type": "string",
            "description": "Display name (`user_display` / `acct_display`).",
            "example": "Example Owner"
          },
          "role": {
            "type": "string",
            "example": "owner"
          },
          "status": {
            "type": "string",
            "example": "active"
          },
          "plan": {
            "type": "string",
            "example": "STANDARD"
          }
        },
        "required": [
          "userid"
        ],
        "additionalProperties": true
      },
      "ProfileUpdateRequest": {
        "type": "object",
        "description": "Body for `POST /v1/profile/update[/{userpk}]`. Fields are accepted\neither with the documented unprefixed key (when sent via JSON or\n`?key=...` query) or with the legacy `sd_*` prefix. Only fields\nwhose unprefixed key is listed below are persisted — everything\nelse is ignored by `AdminFunctions::processUser`. Role, access,\nand token generation are stripped server-side for non-admin callers.\n",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "New email address. Validated and sha1-hashed server-side."
          },
          "user": {
            "type": "string",
            "description": "New username (slug). Ignored when targeting a sub-user or when called by API."
          },
          "role": {
            "type": "string",
            "description": "Role for the target user. Only admins may change this.",
            "enum": [
              "owner",
              "admin",
              "support",
              "developer",
              "user"
            ]
          },
          "status": {
            "type": "string",
            "description": "Account/sub-user status.",
            "enum": [
              "active",
              "suspend",
              "disable"
            ]
          },
          "pass": {
            "type": "string",
            "format": "password",
            "description": "New password (7–100 characters)."
          },
          "generatetoken": {
            "type": "boolean",
            "description": "When truthy, rotates the API token. Admin-only."
          },
          "access": {
            "type": "object",
            "description": "Sub-user permission map. Admin-only."
          },
          "avatar": {
            "type": "string",
            "description": "Avatar URL."
          },
          "name": {
            "type": "string",
            "description": "Display name."
          },
          "bio": {
            "type": "string",
            "description": "User bio (HTML, purified via HTMLPurifier with restricted tags)."
          },
          "notes": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "ProfileAddRequest": {
        "description": "Body for `POST /v1/profile/add`. Same field set as `ProfileUpdateRequest`, but `email` is required and `role` defaults to `user`.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ProfileUpdateRequest"
          },
          {
            "type": "object",
            "required": [
              "email"
            ]
          }
        ]
      },
      "ProfileManageRequest": {
        "description": "Body for `POST /v1/profile/manage/{uid}`. Adds the `status` override that MaaS admins may set on the target account.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ProfileUpdateRequest"
          },
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "description": "When present, forwarded as the customer's new status.",
                "enum": [
                  "active",
                  "suspend",
                  "disable"
                ]
              }
            }
          }
        ]
      },
      "ProfileUsersResponse": {
        "type": "object",
        "description": "Response from `GET /v1/profile/users`. `users` is keyed by ordinal\n(`1`, `2`, ...) and each value contains the de-prefixed customer\nrecord.\n",
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ]
          },
          "message": {
            "type": "string"
          },
          "users": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "uid": {
                  "type": "integer"
                },
                "username": {
                  "type": "string"
                },
                "email": {
                  "type": "string",
                  "format": "email"
                },
                "role": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "plan": {
                  "type": "string"
                },
                "token": {
                  "type": "string"
                },
                "last_login_time": {
                  "type": "string",
                  "format": "date-time"
                }
              },
              "additionalProperties": true
            }
          }
        },
        "required": [
          "result",
          "message"
        ]
      },
      "ResultMessage": {
        "type": "object",
        "description": "Standard `result` + `message` envelope used by profile mutations.",
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ]
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "result",
          "message"
        ]
      },
      "ImportCancelRequest": {
        "type": "object",
        "description": "Body for `POST /v1/imports/cancel`. May be supplied as JSON, form data, or query string.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Plugin slug. Supported plugins (per `Plugins\\Data::getPlugin`):\n`amzn`, `shopify`, `walmart`, `etsy`, `magentotwo`, `google`,\n`facebook`, `miva`, `lightspeedevo`. `ebay` is NOT supported by\nthis endpoint (no top-level `Plugins\\ebay\\ebay` class exists).\n"
          },
          "instance": {
            "type": "integer",
            "description": "Plugin instance number. Valid values are `0` (primary instance) or\nintegers `>= 2` for additional instances. The value `1` is rejected\nby `Helpers::getInstanceInt` with `Invalid instance 1`.\n",
            "minimum": 0,
            "example": 0
          }
        },
        "required": [
          "name"
        ]
      },
      "ImportCancelSuccess": {
        "type": "object",
        "description": "Success envelope from `POST /v1/imports/cancel`.",
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "success"
            ]
          },
          "message": {
            "type": "string",
            "example": "Import cancelled successfully"
          }
        },
        "required": [
          "result",
          "message"
        ]
      },
      "ImportCancelFailure": {
        "type": "object",
        "description": "Failure envelope from `POST /v1/imports/cancel`.",
        "properties": {
          "result": {
            "type": "string",
            "enum": [
              "failure"
            ]
          },
          "errors": {
            "type": "string"
          }
        },
        "required": [
          "result",
          "errors"
        ]
      }
    }
  }
}