# Partner API Changelog

User-facing changelog for the ShedCloud Partner API (`/partner/v1`) and its
official SDKs. Newest first. Every entry here is also rendered on the
[/partner/reference](https://go.shedcloud.com/partner/reference#changelog) page.

The API is **additive-only within v1**: new endpoints, fields, and query
parameters may appear at any time, but existing fields are never renamed,
retyped, or removed. See "Versioning" in the reference for the full policy.

SDK versions: `@shedcloud/partner-api` (npm),
`github.com/Corland-Partners-LLC/shedcloud-gomod/partnerapi` (Go),
`shedcloud-partner-api` (PyPI), `shedcloud/partner-api` (Composer), and
`shedcloud-partner_api` (RubyGems) are released in lockstep with API additions —
the SDK version that first supports each change is noted per entry.

---

## 2026-07-13

- **Official SDKs — Python, PHP, and Ruby.** First-party clients now ship for
  Python (`shedcloud-partner-api` on PyPI), PHP (`shedcloud/partner-api` on
  Composer), and Ruby (`shedcloud-partner_api` on RubyGems), with full parity
  to the existing Node and Go SDKs. Reference guide, llms.txt, and
  `/partner/reference.md` updated with install links and examples.
- **B2B agreements (read-only).** New endpoints under
  `GET /partner/v1/agreements` (list), `GET /partner/v1/agreements/{id}`,
  `GET /partner/v1/agreements/active`, and
  `GET /partner/v1/agreements/{id}/state-legal[/{state}]`. Scope
  `partner-api.agreements.read`. Acceptance evidence and internal actor ids
  are never exposed. RTO quotes/orders now include `rto.agreementId` on the
  linked B2B agreement. SDK support in the next npm/Go release.
- **Machine/AI-readable docs.** The documentation is now published in
  machine-friendly formats at stable public paths: `/llms.txt` (and
  `/partner/llms.txt`) — an [llms.txt](https://llmstxt.org) index for AI
  agents; `/partner/reference.md` — the full API reference as one Markdown
  file; `/partner/openapi.json` / `/partner/openapi.yaml` — the raw OpenAPI
  spec; `/partner/changelog.md` — this changelog as Markdown. No API-surface
  changes.
- **User writes.** `POST /partner/v1/users` creates a company user through
  the portal's own pipeline: profile, RBAC role (`roleId`), location
  assignments (`locationIds` or `allLocations`), and the invitation email
  (default on). Existing ShedCloud accounts are linked by email instead of
  duplicated (`409` when already a member); the Cognito login is created at
  the user's first sign-in via the invite. Accepts `Idempotency-Key`.
  `PATCH /partner/v1/users/{id}` updates profile/role/locations and `active`
  (per-company enable/disable; the owner is protected).
  `GET /partner/v1/roles` (under `users.read`) lists assignable RBAC roles.
  New scope: `partner-api.users.write`. (SDKs: npm 0.5.0, Go v0.5.0)
- **Payment writes.** `POST /partner/v1/orders/{id}/payments` records a
  manual payment (`cash | check | financed | manual`) through the portal's
  own pipeline — payment record, order-balance ledger recalc, audit, and an
  automatic `payment.created` event; status is always `paid`. Card/ACH are
  rejected (Stripe owns those). Accepts `Idempotency-Key`.
  `POST /partner/v1/orders/{id}/payment-links` creates a Stripe Checkout
  session (requires the company's Stripe integration with payments enabled)
  and returns `{url, sessionId, expiresAt, emailSent}`; the customer
  payment-link email sends by default (`sendEmail: false` to skip). New
  scope: `partner-api.payments.write`. (SDKs: npm 0.5.0, Go v0.5.0)
- **Work order creation.** `POST /partner/v1/work-orders` — portal
  building-wizard parity: status starts in `Customer Care`, the number is
  allocated automatically, friendly enums map to the internal build-type
  flags (`purchaseType`: new-build · existing-physical-inventory · general ·
  stock; `workOrderType`: made-to-order · lot-stock · rental-return ·
  immediate-sale · template; `deliveryType`: delivery-from-factory ·
  built-on-site · delivered-from-dealer · delivered-from-lot-stock). Optional
  `sizeId` attaches the product (creating the manufacturing BOM unless the
  unit is pre-existing physical inventory); serial numbers are enforced
  unique (`409`). Accepts `Idempotency-Key`. Scope:
  `partner-api.work-orders.write`. (SDKs: npm 0.5.0, Go v0.5.0)
- **Order creation.** `POST /partner/v1/orders` — full order creation:
  customer (existing `customerId` or inline auto-create), location, base
  product (`productId` + optional `sizeId`), upgrade lines, pricing header,
  delivery address, and an optional **configurator payload**
  (`selectedCategories` verbatim, or flat siding/trim/roof attributes). Runs
  the portal's own pipeline (order number, detail rows, configurator link,
  status log, ledger, audit, CRM). New orders start in `Unsubmitted`.
  Accepts `Idempotency-Key`. Scope: `partner-api.orders.write`.
  (SDKs: npm 0.5.0, Go v0.5.0)
- **Line-item writes.** `POST /partner/v1/{quotes|orders}/{id}/line-items`
  (add an upgrade line, idempotent on `lineKey`) and
  `DELETE .../line-items/{lineId}` (the base product line is protected).
  Header pricing is not recalculated — PATCH pricing fields after changing
  lines. Scopes: the parent's write scope.
  (SDKs: npm 0.5.0, Go v0.5.0)
- **Product writes.** `POST /partner/v1/products` (finished catalog products,
  optional `lineId` line linking), `PATCH /partner/v1/products/{id}`
  (allowlisted fields), and `POST /partner/v1/products/{id}/sizes` (size
  children carrying real width/length/price). Creates accept
  `Idempotency-Key`. Scope: `partner-api.products.write`.
  (SDKs: npm 0.5.0, Go v0.5.0)
- **Domains.** New read resource for white-label storefront subdomains:
  `GET /partner/v1/domains` and `GET /partner/v1/locations/{id}/domains`,
  exposing per-location assignments (hide prices, product/size mappings) and
  the new **Default For Store** flag (`defaultForStore`), filterable via
  `?defaultForStore=true`. Scope: `partner-api.domains.read`.
  (SDKs: npm 0.5.0, Go v0.5.0)
- **Default For Store flag.** Locations can mark one domain as their primary
  storefront from the portal's *Domains* tab; the server enforces at most one
  default per location.
- **Changelog and versioning policy published.** This changelog is now part of
  the reference page, together with the documented additive-only versioning
  policy and official SDK quickstarts.

## 2026-07-12

- **API key scope management.** Company admins can edit the scopes of an
  existing credential from *Settings → Company → Developer API* without
  rotating the secret.

## 2026-07-11

- **Events feed and webhooks.** `GET /partner/v1/events` (poll-based feed),
  webhook subscriptions with signed deliveries, delivery inspection via
  `GET /partner/v1/webhook-deliveries`, and manual redelivery with
  `POST /partner/v1/events/{id}/redeliver`. Scope: `partner-api.events.read`.
- **External references.** Attach your own system's ids to sales entities and
  work orders (`externalReferences` on PATCH; merge semantics, `null` deletes
  a key).
- **Optimistic concurrency.** Get-one responses carry `ETag`; `If-Match` on
  PATCH turns writes conditional (`409` on version mismatch).
- **New read resources.** Payments (`/payments`, `/orders/{id}/payments`),
  documents (`/documents`, `/documents/{id}/download`), users (`/users`),
  stock templates (`/stock-templates`), order contract PDF
  (`/orders/{id}/contract`), status history and line items sub-resources.
- **Configurator sessions.** `POST /partner/v1/configurator-sessions` mints
  single-use launch URLs into the Structura 3D configurator.
- **Customer merge.** `POST /partner/v1/customers/{id}/merge` folds a
  duplicate customer into a survivor with full relink and lineage stamps.

## 2026-07-10

- **Lot stock exterior attributes.** Each lot-stock unit now returns an
  `attributes` object — siding, siding color, trim color, roof material, roof
  color — matching the work-order detail page. Custom colors surface as
  `Custom Color - #HEX`. (SDKs: npm 0.3.0, Go v0.3.0)
- **Lot stock defaults to ALL.** `GET /partner/v1/lot-stock` no longer filters
  to `Lot Stock` by default; pass `purchaseType` to filter (case-insensitive,
  hyphens/underscores accepted, e.g. `lot-stock`).
- **Products: finished products only + images.** `GET /partner/v1/products`
  now returns only finished catalog products (raw materials and kits excluded)
  and each product carries `images` — public gallery URLs.
- **Lead creation.** `POST /partner/v1/leads` with automatic salesperson
  routing. Scope: `partner-api.leads.write`.
- **Quote → order conversion.** `POST /partner/v1/quotes/{id}/convert`.
  Scope: `partner-api.orders.write`.
- **Idempotency keys.** All create endpoints accept `Idempotency-Key`
  (24-hour replay window, `Idempotency-Replayed: true` on replays).
- **Store hours on locations.** `LocationItem.storeHours` — weekly schedule
  keyed by day (`mon`..`sun`).

## 2026-07-09

- **Initial public release of the Partner API.** Company-scoped credentials
  (API keys + OAuth2 client credentials), scoped authorization, rate limiting,
  and response caching.
- **Resources at launch:** lot stock, leads, quotes, orders, work orders
  (list/get + PATCH + status transitions), locations, customers, products
  (list/get/create/update where applicable), in-stock quote creation
  (`POST /partner/v1/quotes`).
- **Official SDKs:** `@shedcloud/partner-api` on npm and the Go module
  `shedcloud-gomod/partnerapi`.