# Shirtplatform Webservices API

> REST API for the Shirtplatform print-on-demand platform: authenticate, browse and configure
> products, place and track orders, upload motives, and manage fulfilment. All resources live under
> the base URL `https://api.shirtplatform.com/webservices/rest`, are secured with HTTP Basic Auth on
> `/auth` (then an `x-auth-token` header), and speak XML or JSON (Jettison-wrapped) on
> `application/xml` and `application/json`.

## Workflows

Standalone, step-by-step call sequences written for programmatic (LLM-agent) consumption. Each
step names the HTTP method and full path, shows Jettison-format JSON, and states which response
fields feed later steps.

- [Authenticate and use a session token](workflow-authenticate.md): obtain an `x-auth-token` via
  `/auth` (HTTP Basic) and send it on every subsequent request; session semantics.
- [Manage a product for sale](workflow-manage-products.md): make an existing product sellable
  — assign views, colors, and sizes, add print-technology setups (Kornit/General/Brother/Media/Color),
  assign categories, and add localized texts.
- [Use the current session order](workflow-session-order.md): start an order bound to your HTTP
  session, read it back without its id, adopt an existing order as the session order, merge items
  from another order into it, then commit / cancel / send it to production.
- [Manage orders](workflow-manage-orders.md): the full order lifecycle — browse orders, create one
  (CreatorSE deferred create preferred, or plain create then add items via OrderedProduct), update
  its uniqueId, commit it, send it to production, cancel it, and delete it.
- [Create a design — build, preview, order a CreatorSE design](workflow-create-design.md): assemble a
  CreatorSE.Design payload, render a preview image (`GET designedProducts/preview`, Base64 design), and
  add it to an order as a custom-designed ordered product (`POST orderedProducts/usingCreatorSE`).
- [Add an item to an order — the ordered-product creation modes](workflow-add-ordered-product.md):
  decision guide across the ways to add an ordered product — from a base catalog product
  (`POST orderedProducts/usingBaseProduct/{productId}`), a designed template
  (`POST orderedProducts/usingTemplateProduct/{designedTemplateProductId}`), a custom CreatorSE design
  (`POST orderedProducts/usingCreatorSE`), or a passthrough warehouse item carried in the deferred
  `POST orders/usingCreatorSE` payload.
- [Embed the Creator widget](workflow-embed-creator-widget.md): embed Shirtplatform's in-browser
  product designer — fetch the embedding snippet (`GET creator/snippet`), inject the mount div and
  preloader script, configure via query params and/or the `creatorApiInitializeCallback(configure)`
  hook, drive the widget through its JavaScript API (`shirtplatform.creator*.api.*`), and receive the
  persisted ordered-product ids via `addToBasketCallback`. Legacy but functional snippet-based path;
  other integration methods are covered separately by shirtplatform support.
- [Manage filters — build a reusable saved filter and apply it](workflow-manage-filters.md): create a
  server-stored filter (`POST /filters` with an expression tree of AND/OR/between/in/is-null criteria
  and a sort order), read the assigned `filterId`, then apply it to any paginated list endpoint via
  `?filterId=` (e.g. `GET .../products?filterId=`); list/get/update/delete saved filters. The Filter
  resource is user-scoped and flat (`/rest/filters`, not account/shop-scoped).
- [Manage motives — browse, upload, use](workflow-manage-motives.md): browse the shop motive catalog and
  read a motive's image/metadata, create a catalog motive and attach its bitmap, let an end customer
  upload a motive into their private library, manage a motive's localizations/categories/tags/print
  technologies, then reference a motive id from a design when creating an ordered product.
- [Webhooks — subscribe and handle events](workflow-webhooks.md): register a webhook subscription for
  an order event, list/get/update/delete it, trigger a test delivery, and verify the
  `x-shirtplatform-hmac-sha256` signature on incoming event payloads.
- [Shipping — discover carriers, providers, and countries](workflow-manage-shipping.md): read the
  account's shipping modules and the providers each supports, the shop's carriers (compact and
  expanded with zones/destinations/prices), and the account's destination countries with their tax
  and currency configuration.
- [Account and shops — read your account and its shops](workflow-manage-account.md): read your
  account (general settings and identifiers) and list/read the shops under it to resolve the
  `accountId`/`shopId` every other workflow needs; account/shop administration is back-office-only.

## Reference — entry points

- [API overview](index.html): landing page, resource groups, and global conventions.
- [Quick start guides](guides.html): human-oriented introduction (auth, media types, linking and
  expansion, filters, ordering, motives, webhooks).
- [Data types](data-types.html): index of every request/response DTO; each type has its own
  `data-types/{Type}.html` page with the XML and JSON shape.

## Reference — resources

- [Authentication](resource_Authentication.html): `/auth` — obtain and inspect a session token.
- [Product](resource_Product.html): products and their structure (views/colors/sizes), print
  technologies, categories, localizations, prices, and SKUs.
- [SharedProduct](resource_SharedProduct.html): products shared into a shop.
- [OrderedProduct](resource_OrderedProduct.html): products added to an order.
- [DesignedProduct](resource_DesignedProduct.html): designed products and previews.
- [Order](resource_Order.html): create, commit, and track orders.
- [OrderCsvImport](resource_OrderCsvImport.html): bulk order import via CSV.
- [Motive](resource_Motive.html): motive catalog.
- [UserMotive](resource_UserMotive.html): end-user motive uploads.
- [Filter](resource_Filter.html): reusable product/motive/order filters.
- [Shop](resource_Shop.html): shops under an account.
- [Account](resource_Account.html): account details.
- [Carrier](resource_Carrier.html): carriers, zones, and shipping prices.
- [ShippingModule](resource_ShippingModule.html): shipping module configuration.
- [Country](resource_Country.html): supported countries.
- [Webhook](resource_Webhook.html): register and manage webhooks.