Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Added a self-service account endpoint to the Seller API
Damian Legawiecedb4bbdda95f
diff --git a/docs/api-reference/seller.yaml b/docs/api-reference/seller.yamlindex 236f53b971..fd41966380 100644--- a/docs/api-reference/seller.yaml+++ b/docs/api-reference/seller.yaml@@ -91,6 +91,7 @@ paths:full_name: Jan Cummeratacreated_at: '2026-01-15T12:00:00.000Z'avatar_url:+ selected_locale:sellers:- id: sel_UkLWZg9DAJname: Seller 1@@ -157,6 +158,7 @@ paths:full_name: Magdalen Hayescreated_at: '2026-01-15T12:00:00.000Z'avatar_url:+ selected_locale:sellers:- id: sel_UkLWZg9DAJname: Seller 3@@ -202,512 +204,326 @@ paths:kind: passwordschema:"$ref": "#/components/schemas/AuthProvidersResponse"- "/api/v3/seller/auth/invitations/{id}/lookup":- parameters:- - name: id- in: path- description: Invitation ID from the emailed link- required: true- schema:- type: string+ "/api/v3/seller/balances":get:- summary: Look up an invitation+ summary: List balancestags:- - Authentication+ - Earnings+ security:+ - bearer_auth: []description: |- Reads an invitation from the emailed link, before anyone signs in.-- The acceptance page needs the invited address to decide whether it is- asking someone to set a new password or to confirm one they already have.+ Where this seller stands with the marketplace, one row per currency+ they have earned or been paid in: what they have earned (settled+ transfers, refund reversals included), what has reached them, what the+ marketplace still owes, and earnings the payout provider has not yet+ confirmed.- Unauthenticated — the ID and token in the emailed link are the- credential. A wrong token is indistinguishable from an unknown- invitation: both answer `404`, so the endpoint cannot be used to- enumerate. An invitation onto the store's own staff rather than a seller- answers `404` here too.+ Computed from the ledger rather than stored, so the rows carry no id+ and there is nothing to page.parameters:- - name: token- in: query+ - name: X-Spree-Seller-Id+ in: headerrequired: true- description: The token from the emailed linkschema:type: stringresponses:'200':- description: invitation found- content:- application/json:- example:- id: inv_UkLWZg9DAJ- email: [email protected]- created_at: '2026-01-15T12:00:00.000Z'- expires_at: '2026-01-29T12:00:00.000Z'- accepted_at:- status: pending- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=RgGhNP1euUCS75Nc3V1Y7YQF"- schema:- "$ref": "#/components/schemas/Invitation"- '404':- description: wrong token, or an invitation that can no longer be accepted+ description: balances listedcontent:application/json:example:- error:- code: record_not_found- message: Invitation not found, expired, or already accepted.+ data:+ - currency: USD+ settlement_currency: USD+ converted: false+ earned: '40.0'+ display_earned: "$40.00"+ payable: '40.0'+ display_payable: "$40.00"+ paid: '15.0'+ display_paid: "$15.00"+ balance: '25.0'+ display_balance: "$25.00"+ pending: '0.0'+ display_pending: "$0.00"schema:- "$ref": "#/components/schemas/ErrorResponse"- "/api/v3/seller/auth/invitations/{id}/accept":+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Balance"+ required:+ - data+ "/api/v3/seller/orders/{order_id}/claims":parameters:- - name: id+ - name: order_idin: path- description: Invitation ID from the emailed link+ description: Prefixed order IDrequired: trueschema:type: string- post:- summary: Accept an invitation+ get:+ summary: List claimstags:- - Authentication- description: |- Accepts the invitation and returns a signed-in seller session, so the new- member lands in the panel rather than on a login form.-- The email is never taken from the request — it always comes from the- invitation, which is what stops the link being redirected to another- address.-- `password` is required when no account exists for the invited address, in- which case it sets one. When an account already exists, the same field is- how the person proves the account is theirs.+ - Claims+ security:+ - bearer_auth: []+ description: Problems reported on one of this seller's orders.parameters:- - name: token- in: query+ - name: X-Spree-Seller-Id+ in: headerrequired: true- description: The token from the emailed linkschema:type: stringresponses:'200':- description: invitation accepted, session issued- content:- application/json:- example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjRmYzVlNzBmLWU1ODAtNDExNi1hOWU5LTBjNDliMGExYjMxNCIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.H0mJ1zDqTi6mNs_BZBRTJ77OMsWAqeUXvQM09YPLefs- user:- id: adm_gbHJdmfrXB- email: [email protected]- first_name: Robin- last_name: Ellis- full_name: Robin Ellis- created_at: '2026-01-15T12:00:00.000Z'- avatar_url:- sellers:- - id: sel_UkLWZg9DAJ- name: Seller 44- status: approved- schema:- "$ref": "#/components/schemas/AuthResponse"- '404':- description: wrong token, or an invitation that can no longer be accepted+ description: claims listedcontent:application/json:- example:- error:- code: record_not_found- message: Invitation not found, expired, or already accepted.schema:- "$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- properties:- password:- type: string- example: password123- password_confirmation:- type: string- example: password123- first_name:- type: string- example: Robin- last_name:- type: string- example: Ellis- "/api/v3/seller/auth/password_resets":+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Claim"+ required:+ - datapost:- summary: Request password reset+ summary: Open a claimtags:- - Authentication+ - Claims+ security:+ - bearer_auth: []description: |- Requests a password reset email for a seller.-- Unauthenticated. Always answers `202`, whether or not the address- belongs to a seller, so this cannot be used to discover which accounts- exist. A store staff member who runs no seller is treated as no match:- they have no seller panel to be sent to.+ Reports that something went wrong with a delivery, to be put right+ without necessarily asking for the goods back.- `redirect_url` is where the emailed link should point, with the reset- token appended as a `token` query param. It is honoured only when it- matches one of the store's allowed origins; otherwise it is silently- ignored and the server resolves the seller panel origin itself. The- email is delivered by Spree via the- `seller_user.password_reset_requested` event, which is never forwarded- to webhook endpoints.- parameters: []+ A replacement variant, if one is offered, comes from this seller's own+ catalogue — a rival's is not theirs to promise.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: stringresponses:- '202':- description: reset requested+ '201':+ description: claim openedcontent:application/json:- example:- message: If an account exists for that email, password reset instructions- have been sent.+ schema:+ "$ref": "#/components/schemas/Claim"requestBody:content:application/json:schema:type: objectproperties:- email:+ items:+ type: array+ items:+ type: object+ properties:+ line_item_id:+ type: string+ quantity:+ type: integer+ description:+ type: string+ nullable: true+ send_replacement:+ type: boolean+ replacement_variant_id:+ type: string+ nullable: true+ refund_amount:+ type: string+ nullable: true+ required:+ - line_item_id+ - quantity+ reason_id:type: string- format: email- example: [email protected]- redirect_url:+ nullable: true+ memo:type: string- example: https://sellers.your-store.com/reset-password- description: Must match an allowed origin of the store; ignored- otherwise.+ nullable: truerequired:- "/api/v3/seller/auth/password_resets/{id}":+ - items+ "/api/v3/seller/orders/{order_id}/claims/{id}/approve":+ parameters:+ - name: order_id+ in: path+ required: true+ schema:+ type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringpatch:- summary: Reset password+ summary: Approve a claimtags:- - Authentication- description: |- Spends a password reset token (the `token` query param from the emailed- link), sets the new password and signs the seller in: the response- carries a seller JWT and the rotatable refresh token is set in an- HttpOnly cookie, so they land in the panel rather than on a login form.-- The token is single-use, and resetting revokes every other session the- account holds. A token whose seller membership has since been revoked is- refused exactly as an expired one.+ - Claims+ security:+ - bearer_auth: []+ description: Accepts that the claim is good.parameters:- - name: id- in: path- description: The reset token from the emailed link+ - name: X-Spree-Seller-Id+ in: headerrequired: trueschema:type: stringresponses:'200':- description: password reset+ description: claim approvedcontent:application/json:- example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImJjMDM3NTNhLTEzN2MtNGM1Zi1hMzM2LWUzMjBlZTNiMjQ5YyIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.EASrzbGpJVyAl10SJyzs8na68Wmvedkm7G66wTBq_0k- user:- id: adm_UkLWZg9DAJ- email: [email protected]- first_name: Ariana- last_name: Wiza- full_name: Ariana Wiza- created_at: '2026-01-15T12:00:00.000Z'- avatar_url:- sellers:- - id: sel_UkLWZg9DAJ- name: Seller 78- status: approvedschema:- "$ref": "#/components/schemas/AuthResponse"- '422':- description: invalid or expired token+ "$ref": "#/components/schemas/Claim"+ "/api/v3/seller/orders/{order_id}/claims/{id}/resolve":+ parameters:+ - name: order_id+ in: path+ required: true+ schema:+ type: string+ - name: id+ in: path+ required: true+ schema:+ type: string+ patch:+ summary: Resolve a claim+ tags:+ - Claims+ security:+ - bearer_auth: []+ description: |+ Puts the claim right: money back, a replacement shipment, or both.++ A refund is bounded by this order's share of the payment, so one+ seller can never settle out of a sibling's money.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: claim resolvedcontent:application/json:- example:- error:- code: password_reset_token_invalid- message: Password reset token is invalid or has expired.schema:- "$ref": "#/components/schemas/ErrorResponse"+ "$ref": "#/components/schemas/Claim"requestBody:content:application/json:schema:type: objectproperties:- password:+ resolution:type: string- example: new-password-123- password_confirmation:+ enum:+ - refund+ - replacement+ - refund_and_replacement+ refund_method:type: string- example: new-password-123+ enum:+ - original_payment+ - store_credit+ amount:+ type: string+ nullable: true+ replacement_line_item_ids:+ type: array+ items:+ type: stringrequired:- - password- - password_confirmation- "/api/v3/seller/me":+ - resolution+ "/api/v3/seller/orders/{order_id}/claims/{id}/deny":+ parameters:+ - name: order_id+ in: path+ required: true+ schema:+ type: string+ - name: id+ in: path+ required: true+ schema:+ type: string+ patch:+ summary: Deny a claim+ tags:+ - Claims+ security:+ - bearer_auth: []+ description: Turns the claim down.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: claim denied+ content:+ application/json:+ schema:+ "$ref": "#/components/schemas/Claim"+ "/api/v3/seller/claim_reasons":get:- summary: Current user+ summary: List claim reasonstags:- - Account+ - Claimssecurity:- bearer_auth: []description: |- The signed-in user, the sellers they may act for, and what they may do on- the selected one.+ What can go wrong with a delivery, as the marketplace defines it.- This is the one authenticated endpoint that answers without- `X-Spree-Seller-Id` — it is what tells the panel which seller to name.- Sending the header narrows `permission_keys` and `permissions` to that- seller; without it both are empty, because capability is per seller and- there is no answer spanning all of them.+ Read-only: a seller picks from the operator's vocabulary.parameters:- name: X-Spree-Seller-Idin: header- required: false- description: The seller to report capability for. Omit to list sellers without- narrowing permissions.+ required: trueschema:type: stringresponses:'200':- description: current user returned+ description: reasons listedcontent:application/json:example:- user:- id: adm_UkLWZg9DAJ- email: [email protected]- first_name: Nadia- last_name: Effertz- full_name: Nadia Effertz- created_at: '2026-01-15T12:00:00.000Z'- avatar_url:- sellers:- - id: sel_UkLWZg9DAJ- name: Seller 53- slug: seller-53- status: approved- permissions:- - allow: true- actions:- - read- subjects:- - Spree::Country- has_conditions: false- - allow: true- actions:- - read- subjects:- - Spree::State- has_conditions: false- - allow: true- actions:- - read- subjects:- - Spree::Store- has_conditions: true- - allow: true- actions:- - read- - admin- subjects:- - Spree::Product- has_conditions: false- - allow: true- actions:- - read- - admin- subjects:- - Spree::Variant- has_conditions: false- - allow: true- actions:- - read- - admin- subjects:- - Spree::OptionType- has_conditions: false- - allow: true- actions:- - read- - admin- subjects:- - Spree::OptionValue- has_conditions: false- - allow: true- actions:- - read- - admin- subjects:- - Spree::Price- has_conditions: false- - allow: true- actions:- - read- - admin- subjects:- - Spree::PriceList- has_conditions: false- - allow: true- actions:- - read- - admin- subjects:- - Spree::PriceRule- has_conditions: false- - allow: true- actions:- - read- - admin- subjects:- - Spree::Catalog- has_conditions: false- - allow: true- actions:- - read- - admin- subjects:- - Spree::CatalogProduct- has_conditions: false- - allow: true- actions:- - read- - admin- subjects:- - Spree::CatalogAssignment- has_conditions: false- - allow: true- actions:- - read- - admin- subjects:- - Spree::CustomField- has_conditions: false- - allow: true- actions:- - read- - admin- subjects:- - Spree::DigitalAsset- has_conditions: false- - allow: true- actions:- - read- - admin- subjects:- - Spree::Import- has_conditions: false- - allow: true- actions:- - read- - admin- subjects:- - Spree::ImportRow- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::Product- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::Variant- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::OptionType- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::OptionValue- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::Price- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::PriceList- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::PriceRule- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::Catalog- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::CatalogProduct- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::CatalogAssignment- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::CustomField- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::DigitalAsset- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::Import- has_conditions: false- - allow: true- actions:- - manage- subjects:- - Spree::ImportRow- has_conditions: false- permission_keys:- - read_products- - write_products- schema:- "$ref": "#/components/schemas/SellerMeResponse"- '401':- description: missing or invalid token- content:- application/json:- example:- error:- code: authentication_required- message: Authentication required+ data:+ - id: clr_UkLWZg9DAJ+ name: Arrived damaged+ active: true+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:schema:- "$ref": "#/components/schemas/ErrorResponse"+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Reason"+ required:+ - data"/api/v3/seller/countries":get:summary: List countries@@ -12989,27 +12805,27 @@ paths:required:- data- meta- "/api/v3/seller/onboarding":- get:- summary: Get onboarding checklist+ "/api/v3/seller/direct_uploads":+ post:+ summary: Create a direct uploadtags:- - Onboarding+ - Uploadssecurity:- bearer_auth: []description: |- What this marketplace asks of the seller before it will admit them.+ Presigns an upload target for a file the seller is about to send.- Singular: the checklist is always the acting seller's. Every answer is- computed server-side by the same evaluator the operator's own view uses,- so the panel and the operator can never show different progress.+ Three steps: post the file's metadata here, `PUT` the bytes to the+ returned `direct_upload.url` with the headers it names, then send the+ returned `signed_id` wherever the file belongs — as a requirement+ submission's `file`, or as `logo`, `square_logo` or `cover_photo` on the+ profile.- `progress` counts optional requirements too — it is how far along the- checklist is, not how close to approval. Read `blocking` on each- requirement for that.+ The blob is attached to nothing at this point. The endpoint that consumes+ the `signed_id` is the one that checks ownership.- Each requirement's `id` is what a submission is posted against. A- marketplace that asks for nothing returns an empty list, which is a- complete answer rather than a missing one.+ `checksum` is the file's MD5 digest, base64-encoded — the storage service+ verifies the upload against it.parameters:- name: X-Spree-Seller-Idin: header@@ -13017,43 +12833,62 @@ paths:schema:type: stringresponses:- '200':- description: checklist returned- content:- application/json:- example:- status: approved- progress:- done: 0- total: 0- requirements: []- schema:- "$ref": "#/components/schemas/SellerOnboardingResponse"- '403':- description: no seller named, or not a member of it+ '201':+ description: upload target createdcontent:application/json:example:- error:- code: access_denied- message: You do not have access to this seller.+ direct_upload:+ url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJuem5oOGdra3VxendvbDc1ODBxNHNwZmpmMjVxIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--98397ef4b61ccb9056997559e739cf48aed9b4f0+ headers:+ Content-Type: application/pdf+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8689a8a2636cd26ac1081498c4c5d7b905fcd0eeschema:- "$ref": "#/components/schemas/ErrorResponse"- "/api/v3/seller/onboarding/submit_for_review":- post:- summary: Submit for review+ "$ref": "#/components/schemas/DirectUploadResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ blob:+ type: object+ properties:+ filename:+ type: string+ example: registration.pdf+ byte_size:+ type: integer+ example: 51234+ checksum:+ type: string+ description: Base64-encoded MD5 digest of the file+ example: rL0Y20zC+Fzt72VPzMSk2A==+ content_type:+ type: string+ example: application/pdf+ required:+ - filename+ - byte_size+ - checksum+ - content_type+ required:+ - blob+ "/api/v3/seller/orders/{order_id}/exchanges":+ parameters:+ - name: order_id+ in: path+ description: Prefixed order ID+ required: true+ schema:+ type: string+ get:+ summary: List exchangestags:- - Onboarding+ - Exchangessecurity:- bearer_auth: []- description: |- Says the seller is ready, moving them from `onboarding` to- `ready_for_review`.-- Refused with `422` when something required is still outstanding — the- message names the blocking requirements, and the seller's status is- unchanged. Returns the same payload as the checklist so the panel can- re-render from one response.+ description: Goods swapped for different ones on one of this seller's orders.parameters:- name: X-Spree-Seller-Idin: header@@ -13062,55 +12897,137 @@ paths:type: stringresponses:'200':- description: submitted for review+ description: exchanges listedcontent:application/json:- example:- status: ready_for_review- progress:- done: 0- total: 0- requirements: []schema:- "$ref": "#/components/schemas/SellerOnboardingResponse"- '422':- description: something required is still outstanding+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Exchange"+ required:+ - data+ post:+ summary: Open an exchange+ tags:+ - Exchanges+ security:+ - bearer_auth: []+ description: |+ Swaps goods for different ones.++ The replacement comes from this seller's own catalogue: it is stock+ they will send, so a variant belonging to another seller is not theirs+ to promise and reads as missing.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '201':+ description: exchange openedcontent:application/json:- example:- error:- code: processing_error- message: Requirements Accept terms is not completeschema:- "$ref": "#/components/schemas/ErrorResponse"- "/api/v3/seller/requirements/{requirement_id}/submissions":+ "$ref": "#/components/schemas/Exchange"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ items:+ type: array+ items:+ type: object+ properties:+ fulfillment_item_id:+ type: string+ new_variant_id:+ type: string+ quantity:+ type: integer+ required:+ - fulfillment_item_id+ - new_variant_id+ - quantity+ reason_id:+ type: string+ nullable: true+ stock_location_id:+ type: string+ nullable: true+ memo:+ type: string+ nullable: true+ required:+ - items+ "/api/v3/seller/orders/{order_id}/exchanges/{id}/fulfill":parameters:- - name: requirement_id+ - name: order_id+ in: path+ required: true+ schema:+ type: string+ - name: idin: path- description: Requirement ID, as returned by `GET /api/v3/seller/onboarding`required: trueschema:type: string+ patch:+ summary: Send the replacement+ tags:+ - Exchanges+ security:+ - bearer_auth: []+ description: |+ Sends the replacement goods, settling any price difference at the same+ time — which is why it takes a refund method.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: replacement sent+ content:+ application/json:+ schema:+ "$ref": "#/components/schemas/Exchange"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ refund_method:+ type: string+ enum:+ - original_payment+ - store_credit+ "/api/v3/seller/exports":post:- summary: Submit against a requirement+ summary: Create an exporttags:- - Onboarding+ - Exportssecurity:- bearer_auth: []description: |- What the seller says about one requirement: an attestation they tick, a- document they upload, a reference they paste.-- Create only. A submission records what was said and when, so a seller who- needs to correct something submits again rather than editing, and the- latest one counts.+ Queues a CSV of this seller's own records.- `file` is **not** a multipart upload — it is the `signed_id` returned by- `POST /api/v3/seller/direct_uploads`, so the bytes are already in storage- by the time this runs.+ Only datasets that can be narrowed to a single seller are offered, so+ an export can never contain another seller's rows however it is+ filtered. The seller and the store come from the request context+ whatever the payload says.- An attestation is accepted on the spot; a requirement the operator- reviews comes back `pending`.+ Generation runs in the background: poll `GET /api/v3/seller/exports/{id}`+ until `done` is true, then fetch `download_url`.parameters:- name: X-Spree-Seller-Idin: header@@ -13119,30 +13036,31 @@ paths:type: stringresponses:'201':- description: submission recorded+ description: export queuedcontent:application/json:example:- id: selsub_UkLWZg9DAJ- status: accepted- note: Confirmed.- review_note:- reference:- reviewed_at: '2026-01-15T12:00:00.000Z'+ id: exp_UkLWZg9DAJ+ number: EF1001+ format: csvcreated_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'- file_url:- file_name:+ type: orders+ user_id: adm_UkLWZg9DAJ+ done: false+ filename:+ byte_size:+ download_url:schema:- "$ref": "#/components/schemas/RequirementSubmission"- '404':- description: a requirement belonging to another marketplace+ "$ref": "#/components/schemas/Export"+ '422':+ description: type cannot be scoped to one sellercontent:application/json:example:error:- code: record_not_found- message: Seller requirement not found+ code: validation_error+ message: 'Unsupported export type. Supported types: orders, products'schema:"$ref": "#/components/schemas/ErrorResponse"requestBody:@@ -13151,37 +13069,47 @@ paths:schema:type: objectproperties:- note:+ type:type: string- description: Anything the seller wants to say alongside the submission- reference:+ enum:+ - orders+ - products+ description: Which dataset to export.+ record_selection:type: string- description: A reference number or external identifier, for requirements- that ask for one- file:+ enum:+ - filtered+ - all+ description: "`filtered` (default) honours `search_params`; `all`+ exports everything this seller owns."+ search_params:+ type: object+ description: Ransack predicates, the same shape the list endpoints+ take. Ignored when `record_selection` is `all`.+ additionalProperties: true+ results_url:type: string- description: A direct-upload `signed_id`, for requirements that- ask for a document- "/api/v3/seller/requirement_submissions/{id}/download":+ description: Panel URL the export-done email links back to. Honoured+ only when it matches one of the store's allowed origins.+ required:+ - type+ "/api/v3/seller/exports/{id}":parameters:- name: idin: path- description: Submission ID+ description: Export IDrequired: trueschema:type: stringget:- summary: Download a submitted document+ summary: Get an exporttags:- - Onboarding+ - Exportssecurity:- bearer_auth: []description: |- Streams the file attached to one of this seller's submissions.-- Served through the API rather than from a storage URL on purpose: these- are identity and registration documents, so every read is authorized- against the acting seller. Another seller's submission answers `404`.+ Reads one of this seller's exports. Poll this until `done` is true,+ then fetch `download_url`.parameters:- name: X-Spree-Seller-Idin: header@@ -13189,63 +13117,162 @@ paths:schema:type: stringresponses:+ '200':+ description: export found+ content:+ application/json:+ example:+ id: exp_UkLWZg9DAJ+ number: EF1001+ format: csv+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ type: orders+ user_id: adm_UkLWZg9DAJ+ done: false+ filename:+ byte_size:+ download_url:+ schema:+ "$ref": "#/components/schemas/Export"'404':- description: another seller's submission+ description: another seller's exportcontent:application/json:example:error:code: record_not_found- message: Seller requirement submission not found- application/octet-stream:+ message: Export not foundschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/seller/policies":+ "/api/v3/seller/exports/{id}/download":+ parameters:+ - name: id+ in: path+ description: Export ID+ required: true+ schema:+ type: stringget:- summary: List policies+ summary: Download an exporttags:- - Policies+ - Exportssecurity:- bearer_auth: []description: |- This seller's own policy documents.+ Streams the finished CSV.- Rooted in the acting seller, so the marketplace operator's store- policies and every other seller's are invisible here. A seller starts- with none: what they are expected to publish is decided by the- marketplace's onboarding checklist.+ The bytes are served by this endpoint rather than through a redirect,+ so the seller's own session authorizes every download.parameters:- name: X-Spree-Seller-Idin: headerrequired: trueschema:type: string- - name: page- in: query- required: false- description: Page number- schema:- type: integer- - name: limit- in: query- required: false- description: Records per page (max 100)+ responses:+ '422':+ description: export is still being written+ content:+ application/json:+ example:+ error:+ code: export_not_ready+ message: Export is not ready yet+ text/csv:+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ '404':+ description: another seller's export+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Export not found+ text/csv:+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/seller/orders/{order_id}/fulfillments":+ parameters:+ - name: order_id+ in: path+ description: Prefixed order ID+ required: true+ schema:+ type: string+ get:+ summary: List fulfillments+ tags:+ - Fulfillments+ security:+ - bearer_auth: []+ description: |+ The parcels this seller owes on one order.++ Reached through the order, which is itself fetched through the acting+ seller — so a fulfillment on somebody else's order is unreachable+ whatever ids are sent.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: trueschema:- type: integer+ type: stringresponses:'200':- description: policies listed+ description: fulfillments listedcontent:application/json:example:data:- - id: pol_uw2YK1rnl0- name: Returns Policy- slug: returns-policy- body: Send anything back within 30 days.- body_html: "<p>Send anything back within 30 days.</p>"- updated_at: '2026-01-15T12:00:00.000Z'+ - id: ful_UkLWZg9DAJ+ number: R1001-F1+ status: unfulfilled+ tracking: U10000+ tracking_url:+ fulfilled_at:+ delivered_at:created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ fulfillment_type: shipping+ delivery_method_name: UPS Ground 81+ stock_location_name: Vernie Lehner+ stock_location_id: sloc_UkLWZg9DAJ+ fulfillment_items:+ - id: fi_UkLWZg9DAJ+ quantity: 1+ line_item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ name: Product 1869315+ sku: SKU-252+ options_text: ''+ selected_delivery_rate_id: dr_gbHJdmfrXB+ delivery_rates:+ - id: dr_gbHJdmfrXB+ name: UPS Ground 81+ selected: true+ cost: '10.0'+ total: '10.0'+ carrier:+ service_level:+ estimated_delivery_date:+ display_cost: "$10.00"+ display_total: "$10.00"+ deliveries:+ - id: dlv_UkLWZg9DAJ+ tracking_number: U10000+ carrier:+ carrier_name:+ service:+ status: pending+ tracking_url:+ estimated_delivery_at:+ delivered_at:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ shipping_label_id:+ labels: []meta:page: 1limit: 25@@ -13262,24 +13289,38 @@ paths:data:type: arrayitems:- "$ref": "#/components/schemas/Policy"- meta:- "$ref": "#/components/schemas/PaginationMeta"+ "$ref": "#/components/schemas/Fulfillment"required:- data- - meta- post:- summary: Create a policy+ "/api/v3/seller/orders/{order_id}/fulfillments/{id}/fulfill":+ parameters:+ - name: order_id+ in: path+ description: Prefixed order ID+ required: true+ schema:+ type: string+ - name: id+ in: path+ description: Prefixed fulfillment ID+ required: true+ schema:+ type: string+ patch:+ summary: Fulfill (ship) a parceltags:- - Policies+ - Fulfillmentssecurity:- bearer_auth: []description: |- Publishes one of this seller's policies. `body` accepts HTML and is- sanitized before it is stored.+ Marks the parcel shipped.- When the marketplace requires a named policy, use that exact name —- the onboarding check matches on it.+ This is the same workflow the marketplace operator runs, so the+ customer's dispatch email, the label purchase and any extension hooks+ happen exactly as they would had the operator shipped it.++ `items` narrows the dispatch to part of what the fulfillment holds; the+ remainder splits onto a new one. Omit it to ship the lot.parameters:- name: X-Spree-Seller-Idin: header@@ -13287,52 +13328,113 @@ paths:schema:type: stringresponses:- '201':- description: policy created+ '200':+ description: parcel shippedcontent:application/json:example:- id: pol_OIJLhNcSbf- name: Shipping Policy- slug: shipping-policy- body: Orders leave the workshop within two working days.- body_html: "<p>Orders leave the workshop within two working days.</p>"- updated_at: '2026-01-15T12:00:00.000Z'+ id: ful_UkLWZg9DAJ+ number: R1001-F1+ status: fulfilled+ tracking: TRACK-1+ tracking_url:+ fulfilled_at: '2026-01-15T12:00:00.000Z'+ delivered_at:created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ fulfillment_type: shipping+ delivery_method_name: UPS Ground 82+ stock_location_name: Mirta Herman+ stock_location_id: sloc_UkLWZg9DAJ+ fulfillment_items:+ - id: fi_UkLWZg9DAJ+ quantity: 1+ line_item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ name: Product 187961+ sku: SKU-253+ options_text: ''+ selected_delivery_rate_id: dr_gbHJdmfrXB+ delivery_rates:+ - id: dr_gbHJdmfrXB+ name: UPS Ground 82+ selected: true+ cost: '10.0'+ total: '10.0'+ carrier:+ service_level:+ estimated_delivery_date:+ display_cost: "$10.00"+ display_total: "$10.00"+ deliveries:+ - id: dlv_UkLWZg9DAJ+ tracking_number: TRACK-1+ carrier:+ carrier_name:+ service:+ status: pending+ tracking_url:+ estimated_delivery_at:+ delivered_at:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ shipping_label_id:+ labels: []schema:- "$ref": "#/components/schemas/Policy"+ "$ref": "#/components/schemas/Fulfillment"requestBody:content:application/json:schema:type: objectproperties:- name:- type: string- example: Shipping Policy- slug:+ tracking:type: string- example: shipping-policy- body:+ description: Carrier tracking number+ tracking_carrier:type: string- example: "<p>Orders leave the workshop within two working days.</p>"- required:- - name- "/api/v3/seller/policies/{id}":+ description: Carrier name+ notify_customer:+ type: boolean+ description: Send the dispatch email (default true)+ items:+ type: array+ description: Ship only these lines; the rest split onto a new fulfillment+ items:+ type: object+ properties:+ item_id:+ type: string+ description: Prefixed line item ID+ quantity:+ type: integer+ required:+ - item_id+ - quantity+ "/api/v3/seller/orders/{order_id}/fulfillments/{id}":parameters:+ - name: order_id+ in: path+ required: true+ schema:+ type: string- name: idin: pathrequired: true- description: Policy prefixed ID or slugschema:type: string- get:- summary: Get a policy+ patch:+ summary: Update trackingtags:- - Policies+ - Fulfillmentssecurity:- bearer_auth: []- description: Returns one of this seller's policies, by prefixed ID or slug.+ description: |+ Adds or corrects the tracking number and its carrier.++ Deliberately narrow: where a parcel ships from and which service+ carries it are the marketplace's arrangements, so they are not+ editable here.parameters:- name: X-Spree-Seller-Idin: header@@ -13341,76 +13443,92 @@ paths:type: stringresponses:'200':- description: policy found+ description: tracking recordedcontent:application/json:example:- id: pol_uw2YK1rnl0- name: Returns Policy- slug: returns-policy- body: Send anything back within 30 days.- body_html: "<p>Send anything back within 30 days.</p>"- updated_at: '2026-01-15T12:00:00.000Z'+ id: ful_UkLWZg9DAJ+ number: R1001-F1+ status: unfulfilled+ tracking: TRACK-2+ tracking_url: https://www.ups.com/track?tracknum=TRACK-2+ fulfilled_at:+ delivered_at:created_at: '2026-01-15T12:00:00.000Z'- schema:- "$ref": "#/components/schemas/Policy"- '404':- description: policy not found- content:- application/json:- example:- error:- code: record_not_found- message: Policy not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- patch:- summary: Update a policy- tags:- - Policies- security:- - bearer_auth: []- description: Rewrites one of this seller's policies.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: policy updated- content:- application/json:- example:- id: pol_uw2YK1rnl0- name: Returns Policy- slug: returns-policy- body: Send anything back within 60 days.- body_html: "<p>Send anything back within 60 days.</p>"updated_at: '2026-01-15T12:00:00.000Z'- created_at: '2026-01-15T12:00:00.000Z'+ fulfillment_type: shipping+ delivery_method_name: UPS Ground 83+ stock_location_name: Eugena Schultz+ stock_location_id: sloc_UkLWZg9DAJ+ fulfillment_items:+ - id: fi_UkLWZg9DAJ+ quantity: 1+ line_item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ name: Product 1883170+ sku: SKU-254+ options_text: ''+ selected_delivery_rate_id: dr_gbHJdmfrXB+ delivery_rates:+ - id: dr_gbHJdmfrXB+ name: UPS Ground 83+ selected: true+ cost: '10.0'+ total: '10.0'+ carrier:+ service_level:+ estimated_delivery_date:+ display_cost: "$10.00"+ display_total: "$10.00"+ deliveries:+ - id: dlv_UkLWZg9DAJ+ tracking_number: TRACK-2+ carrier: ups+ carrier_name: UPS+ service:+ status: pending+ tracking_url: https://www.ups.com/track?tracknum=TRACK-2+ estimated_delivery_at:+ delivered_at:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ shipping_label_id:+ labels: []schema:- "$ref": "#/components/schemas/Policy"+ "$ref": "#/components/schemas/Fulfillment"requestBody:content:application/json:schema:type: objectproperties:- name:- type: string- slug:+ tracking:type: string- body:+ nullable: true+ tracking_carrier:type: string- delete:- summary: Delete a policy+ nullable: true+ "/api/v3/seller/orders/{order_id}/fulfillments/{id}/cancel":+ parameters:+ - name: order_id+ in: path+ required: true+ schema:+ type: string+ - name: id+ in: path+ required: true+ schema:+ type: string+ patch:+ summary: Cancel a parceltags:- - Policies+ - Fulfillmentssecurity:- bearer_auth: []- description: Withdraws one of this seller's policies.+ description: |+ A parcel this seller is not going to send after all. The goods go back+ on the shelf and the carrier is stood down.parameters:- name: X-Spree-Seller-Idin: header@@ -13418,236 +13536,329 @@ paths:schema:type: stringresponses:- '204':- description: policy deleted- "/api/v3/seller/product_types":+ '200':+ description: parcel canceled+ content:+ application/json:+ example:+ id: ful_UkLWZg9DAJ+ number: R1001-F1+ status: canceled+ tracking: U10000+ tracking_url:+ fulfilled_at:+ delivered_at:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ fulfillment_type: shipping+ delivery_method_name: UPS Ground 84+ stock_location_name: Karyn Moore+ stock_location_id: sloc_UkLWZg9DAJ+ fulfillment_items:+ - id: fi_UkLWZg9DAJ+ quantity: 1+ line_item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ name: Product 1897276+ sku: SKU-255+ options_text: ''+ selected_delivery_rate_id: dr_gbHJdmfrXB+ delivery_rates:+ - id: dr_gbHJdmfrXB+ name: UPS Ground 84+ selected: true+ cost: '10.0'+ total: '10.0'+ carrier:+ service_level:+ estimated_delivery_date:+ display_cost: "$10.00"+ display_total: "$10.00"+ deliveries:+ - id: dlv_UkLWZg9DAJ+ tracking_number: U10000+ carrier:+ carrier_name:+ service:+ status: pending+ tracking_url:+ estimated_delivery_at:+ delivered_at:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ shipping_label_id:+ labels: []+ schema:+ "$ref": "#/components/schemas/Fulfillment"+ "/api/v3/seller/tracking_carriers":get:- summary: List product types+ summary: List tracking carrierstags:- - Product Types+ - Fulfillmentssecurity:- bearer_auth: []description: |- The product types a seller may list a product against.-- Read only. A type is the template that hands a product its option types- and its delivery profile, so a seller picks one when listing; defining- types is the marketplace's. Send the chosen `id` as `product_type_id`- on the product.+ The carriers a tracking number can be pinned to, from the registry —+ so a carrier an extension adds appears without a client change.parameters:- name: X-Spree-Seller-Idin: headerrequired: trueschema:type: string- - name: page- in: query- required: false- description: Page number- schema:- type: integer- - name: limit- in: query- required: false- description: Records per page (max 100)- schema:- type: integerresponses:'200':- description: product types listed+ description: carriers listedcontent:application/json:example:data:- - id: pt_UkLWZg9DAJ- name: Apparel- option_type_labels: []- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:+ - id: australia_post+ name: Australia Post+ - id: canada_post+ name: Canada Post+ - id: chronopost+ name: Chronopost+ - id: colissimo+ name: Colissimo+ - id: dhl+ name: DHL Express+ - id: dpd+ name: DPD+ - id: deutsche_post+ name: Deutsche Post DHL+ - id: evri+ name: Evri+ - id: fedex+ name: FedEx+ - id: gls+ name: GLS+ - id: inpost+ name: InPost+ - id: poczta_polska+ name: Poczta Polska+ - id: postnl+ name: PostNL+ - id: royal_mail+ name: Royal Mail+ - id: ups+ name: UPS+ - id: usps+ name: USPSschema:type: objectproperties:data:type: arrayitems:- "$ref": "#/components/schemas/ProductType"- meta:- "$ref": "#/components/schemas/PaginationMeta"- required:- - data- - meta- "/api/v3/seller/product_types/{id}":+ type: object+ properties:+ id:+ type: string+ name:+ type: string+ required:+ - id+ - name+ required:+ - data+ "/api/v3/seller/auth/invitations/{id}/lookup":+ parameters:+ - name: id+ in: path+ description: Invitation ID from the emailed link+ required: true+ schema:+ type: stringget:- summary: Get a product type+ summary: Look up an invitationtags:- - Product Types- security:- - bearer_auth: []+ - Authentication+ description: |+ Reads an invitation from the emailed link, before anyone signs in.++ The acceptance page needs the invited address to decide whether it is+ asking someone to set a new password or to confirm one they already have.++ Unauthenticated — the ID and token in the emailed link are the+ credential. A wrong token is indistinguishable from an unknown+ invitation: both answer `404`, so the endpoint cannot be used to+ enumerate. An invitation onto the store's own staff rather than a seller+ answers `404` here too.parameters:- - name: X-Spree-Seller-Id- in: header+ - name: token+ in: queryrequired: true+ description: The token from the emailed linkschema:type: string- - name: id- in: path+ responses:+ '200':+ description: invitation found+ content:+ application/json:+ example:+ id: inv_UkLWZg9DAJ+ email: [email protected]+ created_at: '2026-01-15T12:00:00.000Z'+ expires_at: '2026-01-29T12:00:00.000Z'+ accepted_at:+ status: pending+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=RgGhNP1euUCS75Nc3V1Y7YQF"+ schema:+ "$ref": "#/components/schemas/Invitation"+ '404':+ description: wrong token, or an invitation that can no longer be accepted+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Invitation not found, expired, or already accepted.+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/seller/auth/invitations/{id}/accept":+ parameters:+ - name: id+ in: path+ description: Invitation ID from the emailed link+ required: true+ schema:+ type: string+ post:+ summary: Accept an invitation+ tags:+ - Authentication+ description: |+ Accepts the invitation and returns a signed-in seller session, so the new+ member lands in the panel rather than on a login form.++ The email is never taken from the request — it always comes from the+ invitation, which is what stops the link being redirected to another+ address.++ `password` is required when no account exists for the invited address, in+ which case it sets one. When an account already exists, the same field is+ how the person proves the account is theirs.+ parameters:+ - name: token+ in: queryrequired: true- description: Product type ID+ description: The token from the emailed linkschema:type: stringresponses:'200':- description: product type found+ description: invitation accepted, session issuedcontent:application/json:example:- id: pt_UkLWZg9DAJ- name: Apparel- option_type_labels: []+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjRmYzVlNzBmLWU1ODAtNDExNi1hOWU5LTBjNDliMGExYjMxNCIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.H0mJ1zDqTi6mNs_BZBRTJ77OMsWAqeUXvQM09YPLefs+ user:+ id: adm_gbHJdmfrXB+ email: [email protected]+ first_name: Robin+ last_name: Ellis+ full_name: Robin Ellis+ created_at: '2026-01-15T12:00:00.000Z'+ avatar_url:+ selected_locale:+ sellers:+ - id: sel_UkLWZg9DAJ+ name: Seller 44+ status: approvedschema:- "$ref": "#/components/schemas/ProductType"- "/api/v3/seller/products":+ "$ref": "#/components/schemas/AuthResponse"+ '404':+ description: wrong token, or an invitation that can no longer be accepted+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Invitation not found, expired, or already accepted.+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ password:+ type: string+ example: password123+ password_confirmation:+ type: string+ example: password123+ first_name:+ type: string+ example: Robin+ last_name:+ type: string+ example: Ellis+ "/api/v3/seller/invitations":get:- summary: List products+ summary: List pending invitationstags:- - Products+ - Teamsecurity:- bearer_auth: []description: |- The seller's own catalog — the products they own outright.+ Offers nobody has accepted yet, newest first.- Every call is rooted in the acting seller server-side, so this can never- return another seller's product or one the marketplace operator sells- first-party.+ Pending only — an accepted invitation is a team member, and shows up on+ `GET /api/v3/seller/team` instead.++ Sending an invitation lives on `team`, because that is hiring. Chasing or+ withdrawing one is bookkeeping on the offer itself, so it lives here.parameters:- name: X-Spree-Seller-Idin: headerrequired: trueschema:type: string- - name: page- in: query- required: false- description: Page number- schema:- type: integer- - name: limit- in: query- required: false- description: Records per page (max 100)- schema:- type: integer- - name: sort- in: query- required: false- description: Sort field; prefix with `-` for descending- schema:- type: stringresponses:'200':- description: products listed+ description: invitations listedcontent:application/json:example:data:- - id: prod_UkLWZg9DAJ- name: Product 2053250- slug: product-2053250- meta_title:- meta_description:- meta_keywords:- variant_count: 1- available_on:- preorder_ships_at:- purchasable: true- preorder: false- in_stock: false- backorderable: true- available: true- description: Maiores ut qui dolores ab autem. Architecto quos sequi- minus debitis tempora molestiae. Quasi officiis minus voluptatum- eveniet incidunt. Nisi laboriosam a aliquam eveniet occaecati- ducimus. Provident quo amet nostrum sed assumenda cum odio. Distinctio- perferendis quasi nisi exercitationem veritatis minima esse. In- velit at corporis nobis. Voluptate mollitia nam pariatur enim.- Recusandae necessitatibus earum deserunt sapiente eveniet quidem- unde. Consectetur ab perspiciatis veniam dolor tempora. Omnis- odit autem quae repellat. Delectus corrupti ea nisi reiciendis- atque iure a molestias. Repellendus laboriosam sint molestias- debitis in. Minima omnis accusantium modi accusamus doloribus- fugit. Accusamus autem sequi perferendis saepe quos perspiciatis.- description_html: |-- Maiores ut qui dolores ab autem. Architecto quos sequi minus debitis tempora molestiae. Quasi officiis minus voluptatum eveniet incidunt. Nisi laboriosam a aliquam eveniet occaecati ducimus. Provident quo amet nostrum sed assumenda cum odio.- Distinctio perferendis quasi nisi exercitationem veritatis minima esse. In velit at corporis nobis. Voluptate mollitia nam pariatur enim. Recusandae necessitatibus earum deserunt sapiente eveniet quidem unde.- Consectetur ab perspiciatis veniam dolor tempora. Omnis odit autem quae repellat. Delectus corrupti ea nisi reiciendis atque iure a molestias.- Repellendus laboriosam sint molestias debitis in. Minima omnis accusantium modi accusamus doloribus fugit. Accusamus autem sequi perferendis saepe quos perspiciatis.- default_variant_id: variant_UkLWZg9DAJ- buy_box_variant_id: variant_UkLWZg9DAJ- thumbnail_url:- tags: []- price:- id: price_UkLWZg9DAJ- amount: '19.99'- amount_in_cents: 1999- compare_at_amount:- compare_at_amount_in_cents:- currency: USD- display_amount: "$19.99"- display_compare_at_amount:- price_list_id:- original_price:- seller_id: sel_UkLWZg9DAJ- status: active- metadata: {}+ - id: inv_UkLWZg9DAJ+ email: [email protected]created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- product_type_id:- delivery_profile_id: fp_UkLWZg9DAJ- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:+ expires_at: '2026-01-29T12:00:00.000Z'+ accepted_at:+ status: pending+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=gybGAXxVP79yKWNTZLAC94ui"schema:type: objectproperties:data:type: arrayitems:- "$ref": "#/components/schemas/Product"- meta:- "$ref": "#/components/schemas/PaginationMeta"+ "$ref": "#/components/schemas/Invitation"required:- data- - meta- post:- summary: Create a product+ "/api/v3/seller/invitations/{id}/resend":+ parameters:+ - name: id+ in: path+ description: Invitation ID+ required: true+ schema:+ type: string+ patch:+ summary: Resend an invitationtags:- - Products+ - Teamsecurity:- bearer_auth: []description: |- Creates a product owned by the acting seller.-- The seller and the store are taken from the request context whatever the- payload says, so a product cannot be created against another seller.-- The operator's own settings — tax category, delivery profile and whether- the product is promotionable — are not writable here; they belong to the- marketplace, not the seller.+ Sends the invitation email again, for a colleague who never got the first+ one. An invitation whose window has closed is refused rather than+ re-sent.parameters:- name: X-Spree-Seller-Idin: header@@ -13655,141 +13866,45 @@ paths:schema:type: stringresponses:- '201':- description: product created+ '200':+ description: invitation resentcontent:application/json:example:- id: prod_gbHJdmfrXB- name: Hand-thrown mug- slug: hand-thrown-mug- meta_title:- meta_description:- meta_keywords:- variant_count: 0- available_on:- preorder_ships_at:- purchasable: false- preorder: false- in_stock: false- backorderable: false- available: false- description:- description_html:- default_variant_id: variant_gbHJdmfrXB- buy_box_variant_id: variant_gbHJdmfrXB- thumbnail_url:- tags: []- price:- id: price_gbHJdmfrXB- amount: '24.0'- amount_in_cents: 2400- compare_at_amount:- compare_at_amount_in_cents:- currency: USD- display_amount: "$24.00"- display_compare_at_amount:- price_list_id:- original_price:- seller_id: sel_UkLWZg9DAJ- status: draft- metadata: {}+ id: inv_UkLWZg9DAJ+ email: [email protected]created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- product_type_id:- delivery_profile_id: fp_UkLWZg9DAJ+ expires_at: '2026-01-29T12:00:00.000Z'+ accepted_at:+ status: pending+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=3uJFfKUSiHtnc9TGAXMJUXsB"schema:- "$ref": "#/components/schemas/Product"- '422':- description: validation failed+ "$ref": "#/components/schemas/Invitation"+ '404':+ description: another seller's invitationcontent:application/json:example:error:- code: validation_error- message: Name can't be blank- details:- name:- - can't be blank+ code: record_not_found+ message: Invitation not foundschema:"$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- properties:- name:- type: string- example: Hand-thrown mug- description:- type: string- slug:- type: string- example: hand-thrown-mug- status:- type: string- example: draft- meta_title:- type: string- meta_description:- type: string- meta_keywords:- type: string- product_type_id:- type: string- example: ptype_abc123- tags:- type: array- items:- type: string- example:- - ceramics- - handmade- category_ids:- type: array- items:- type: string- example:- - cat_abc123- metadata:- type: object- additionalProperties: true- prices:- type: array- items:- type: object- properties:- amount:- type: string- example: '24.00'- compare_at_amount:- type: string- example: '30.00'- currency:- type: string- example: USD- required:- - name- "/api/v3/seller/products/{id}":+ "/api/v3/seller/invitations/{id}":parameters:- name: idin: path- description: Product ID+ description: Invitation IDrequired: trueschema:type: string- get:- summary: Get a product+ delete:+ summary: Revoke an invitationtags:- - Products+ - Teamsecurity:- bearer_auth: []- description: |- A product the acting seller owns.-- An id belonging to another seller answers `404`, not `403` — the seller- is not told the record exists.+ description: Withdraws an offer that has not been accepted.parameters:- name: X-Spree-Seller-Idin: header@@ -13797,1078 +13912,387 @@ paths:schema:type: stringresponses:- '200':- description: product returned- content:- application/json:- example:- id: prod_UkLWZg9DAJ- name: Product 2086710- slug: product-2086710- meta_title:- meta_description:- meta_keywords:- variant_count: 1- available_on:- preorder_ships_at:- purchasable: true- preorder: false- in_stock: false- backorderable: true- available: true- description: Aliquid voluptate laudantium necessitatibus quidem eaque.- Sapiente at autem eveniet exercitationem odio in dolores. Laborum- accusantium nulla autem tempora qui inventore assumenda molestiae.- Quisquam voluptas delectus ipsum totam ab incidunt. Sunt excepturi- eius provident unde neque in. Earum pariatur enim odit delectus- accusamus recusandae. Dolorem eligendi debitis iste voluptate laboriosam- ab. Ab aut suscipit illo occaecati. Dolores libero cupiditate provident- at itaque temporibus. Adipisci iste beatae quibusdam perferendis- ea blanditiis saepe facilis.- description_html: |-- Aliquid voluptate laudantium necessitatibus quidem eaque. Sapiente at autem eveniet exercitationem odio in dolores. Laborum accusantium nulla autem tempora qui inventore assumenda molestiae. Quisquam voluptas delectus ipsum totam ab incidunt. Sunt excepturi eius provident unde neque in.- Earum pariatur enim odit delectus accusamus recusandae. Dolorem eligendi debitis iste voluptate laboriosam ab. Ab aut suscipit illo occaecati. Dolores libero cupiditate provident at itaque temporibus. Adipisci iste beatae quibusdam perferendis ea blanditiis saepe facilis.- default_variant_id: variant_UkLWZg9DAJ- buy_box_variant_id: variant_UkLWZg9DAJ- thumbnail_url:- tags: []- price:- id: price_UkLWZg9DAJ- amount: '19.99'- amount_in_cents: 1999- compare_at_amount:- compare_at_amount_in_cents:- currency: USD- display_amount: "$19.99"- display_compare_at_amount:- price_list_id:- original_price:- seller_id: sel_UkLWZg9DAJ- status: active- metadata: {}- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- product_type_id:- delivery_profile_id: fp_UkLWZg9DAJ- schema:- "$ref": "#/components/schemas/Product"+ '204':+ description: invitation revoked'404':- description: another seller's product+ description: another seller's invitationcontent:application/json:example:error:code: record_not_found- message: Product not found+ message: Invitation not foundschema:"$ref": "#/components/schemas/ErrorResponse"- patch:- summary: Update a product+ "/api/v3/seller/me":+ get:+ summary: Current usertags:- - Products+ - Accountsecurity:- bearer_auth: []- description: Edits a product the acting seller owns.+ description: |+ The signed-in user, the sellers they may act for, and what they may do on+ the selected one.++ This is the one authenticated endpoint that answers without+ `X-Spree-Seller-Id` — it is what tells the panel which seller to name.+ Sending the header narrows `permission_keys` and `permissions` to that+ seller; without it both are empty, because capability is per seller and+ there is no answer spanning all of them.parameters:- name: X-Spree-Seller-Idin: header- required: true+ required: false+ description: The seller to report capability for. Omit to list sellers without+ narrowing permissions.schema:type: stringresponses:'200':- description: product updated+ description: current user returnedcontent:application/json:example:- id: prod_UkLWZg9DAJ- name: Hand-thrown mug, large- slug: product-2118212- meta_title:- meta_description:- meta_keywords:- variant_count: 1- available_on:- preorder_ships_at:- purchasable: true- preorder: false- in_stock: false- backorderable: true- available: true- description: Vel minima recusandae iure deserunt non. Corrupti soluta- pariatur recusandae saepe eveniet. Sequi deserunt fugiat architecto- animi. Eum facilis veniam a consequatur minus. Dolor iure facilis- repellendus tenetur. Nobis harum perferendis ab maiores labore eius- eum quo.- description_html: |-- Vel minima recusandae iure deserunt non. Corrupti soluta pariatur recusandae saepe eveniet. Sequi deserunt fugiat architecto animi.- Eum facilis veniam a consequatur minus. Dolor iure facilis repellendus tenetur. Nobis harum perferendis ab maiores labore eius eum quo.- default_variant_id: variant_UkLWZg9DAJ- buy_box_variant_id: variant_UkLWZg9DAJ- thumbnail_url:- tags: []- price:- id: price_UkLWZg9DAJ- amount: '19.99'- amount_in_cents: 1999- compare_at_amount:- compare_at_amount_in_cents:- currency: USD- display_amount: "$19.99"- display_compare_at_amount:- price_list_id:- original_price:- seller_id: sel_UkLWZg9DAJ- status: active- metadata: {}- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- product_type_id:- delivery_profile_id: fp_UkLWZg9DAJ- schema:- "$ref": "#/components/schemas/Product"- requestBody:- content:- application/json:- schema:- type: object- properties:- name:- type: string- example: Hand-thrown mug, large- description:- type: string- slug:- type: string- status:- type: string- example: active- tags:- type: array- items:- type: string- category_ids:- type: array- items:- type: string- metadata:- type: object- additionalProperties: true- delete:- summary: Delete a product- tags:- - Products- security:- - bearer_auth: []- description: Deletes a product the acting seller owns.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '204':- description: product deleted- "/api/v3/seller/profile":- get:- summary: Get profile- tags:- - Profile- security:- - bearer_auth: []- description: |- The seller's own record.-- Singular by nature: the seller in play is always the one named by- `X-Spree-Seller-Id`, never an id in the path — so a seller cannot address- another seller here even by guessing one.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: profile returned- content:- application/json:- example:- id: sel_UkLWZg9DAJ- name: Seller 98- slug: seller-98- about: ''- about_html: ''- logo_url:- square_logo_url:- cover_photo_url:- preferred_timezone: UTC- status: approved- legal_name:- registration_number:- contact_email:- billing_email:- tax_remittance: seller- payouts_schedule_interval:- holiday_mode_until:- terms_accepted_at: '2026-01-15T12:00:00.000Z'- created_at: '2026-01-15T12:00:00.000Z'- minimum_payout_amount:- on_holiday: false- sellable: true- default_currency: USD- supported_currencies:- - USD- - EUR- - GBP- products_count: 0- schema:- "$ref": "#/components/schemas/Profile"- '403':- description: no seller named, or not a member of it- content:- application/json:- example:- error:- code: access_denied- message: You do not have access to this seller.- schema:- "$ref": "#/components/schemas/ErrorResponse"- patch:- summary: Update profile- tags:- - Profile- security:- - bearer_auth: []- description: |- Edits presentation, contact details and addresses.-- Readable but **not** writable, by design: `status` — the lifecycle belongs- to the marketplace operator's workflows — the settlement terms, and- `slug`, since a seller renaming their own storefront address would break- every link pointing at it.-- `accept_terms: true` stamps the moment the seller accepted the- marketplace's terms, which is what the matching onboarding requirement- reads. One-way — sending `false` does not unmake the stamp.-- `custom_fields` is narrowed server-side to the definitions this- marketplace's onboarding actually asks this seller for; a field nothing- asked for is ignored rather than written.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: profile updated- content:- application/json:- example:- id: sel_UkLWZg9DAJ- name: Acme Supplies- slug: seller-100- about: ''- about_html: ''- logo_url:- square_logo_url:- cover_photo_url:- preferred_timezone: UTC- status: approved- legal_name:- registration_number:- contact_email: [email protected]- billing_email:- tax_remittance: seller- payouts_schedule_interval:- holiday_mode_until:- terms_accepted_at: '2026-01-15T12:00:00.000Z'- created_at: '2026-01-15T12:00:00.000Z'- minimum_payout_amount:- on_holiday: false- sellable: true- default_currency: USD- supported_currencies:- - USD- - EUR- - GBP- products_count: 0- schema:- "$ref": "#/components/schemas/Profile"- '422':- description: validation failed- content:- application/json:- example:- error:- code: validation_error- message: Name can't be blank- details:- name:- - can't be blank- schema:- "$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- properties:- name:- type: string- example: Acme Supplies- contact_email:- type: string- format: email- nullable: true- example: [email protected]- billing_email:- type: string- format: email- nullable: true- example: [email protected]- about:- type: string- nullable: true- description: Sanitized HTML — the seller's public description- legal_name:- type: string- nullable: true- description: The business a commission invoice is made out to- registration_number:- type: string- nullable: true- logo:- type: string- nullable: true- description: ActiveStorage signed id; `null` removes the attachment- square_logo:- type: string- nullable: true- cover_photo:- type: string- nullable: true- accept_terms:- type: boolean- description: Stamps acceptance of the marketplace terms- billing_address:- type: object- additionalProperties: true- custom_fields:- type: array- items:- type: object- properties:- custom_field_definition_id:- type: string- example: cfd_abc123- value:- description: Any JSON value the definition accepts- "/api/v3/seller/stock_locations":- get:- summary: List stock locations- tags:- - Stock Locations- security:- - bearer_auth: []- description: |- Where this seller keeps stock, and so where their returns are sent.-- Rooted in the acting seller, so the marketplace operator's own warehouses- never appear here.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- - name: page- in: query- required: false- description: Page number- schema:- type: integer- - name: limit- in: query- required: false- description: Records per page (max 100)- schema:- type: integer- - name: sort- in: query- required: false- description: Sort field; prefix with `-` for descending- schema:- type: string- responses:- '200':- description: stock locations listed- content:- application/json:- example:- data:- - id: sloc_UkLWZg9DAJ- name: Lesha Stroman- address1: 1600 Pennsylvania Ave NW- city: Washington- zipcode: '20500'- country_code: US- country_name: United States- state_code: AL- state_text: AL- pickup_ready_in_minutes:- pickup_instructions:- address2:- state_name:- phone: "(202) 456-1111"- company:- active: true- default: false- kind: warehouse- returns_enabled: true- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/StockLocation"- meta:- "$ref": "#/components/schemas/PaginationMeta"- required:- - data- - meta- post:- summary: Create a stock location- tags:- - Stock Locations- security:- - bearer_auth: []- description: |- Adds a place this seller ships from.-- The seller and the store come from the request context whatever the- payload says.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '201':- description: stock location created- content:- application/json:- example:- id: sloc_gbHJdmfrXB- name: Main warehouse- address1:- city: Portland- zipcode:- country_code: US- country_name: United States- state_code:- state_text:- pickup_ready_in_minutes:- pickup_instructions:- address2:- state_name:- phone:- company:- active: true- default: false- kind: warehouse- returns_enabled: true- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- schema:- "$ref": "#/components/schemas/StockLocation"- '422':- description: validation failed- content:- application/json:- example:- error:- code: validation_error- message: Name can't be blank- details:- name:- - can't be blank- schema:- "$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- properties:- name:- type: string- example: Main warehouse- company:- type: string- nullable: true- address1:- type: string- nullable: true- example: 1 Kiln Lane- address2:- type: string- nullable: true- city:- type: string- nullable: true- example: Portland- zipcode:- type: string- nullable: true- example: '97205'- country_code:- type: string- nullable: true- example: US- state_code:- type: string- nullable: true- example: OR- state_name:- type: string- nullable: true- phone:- type: string- nullable: true- active:- type: boolean- description: Set `false` to retire a location — there is no delete- default:- type: boolean- kind:- type: string- example: warehouse- required:- - name- "/api/v3/seller/stock_locations/{id}":- parameters:- - name: id- in: path- description: Stock location ID- required: true- schema:- type: string- get:- summary: Get a stock location- tags:- - Stock Locations- security:- - bearer_auth: []- description: |- A stock location the acting seller owns. An id belonging to another- seller — or to the marketplace operator — answers `404`.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: stock location returned- content:- application/json:- example:- id: sloc_UkLWZg9DAJ- name: Marsha Turner- address1: 1600 Pennsylvania Ave NW- city: Washington- zipcode: '20500'- country_code: US- country_name: United States- state_code: AL- state_text: AL- pickup_ready_in_minutes:- pickup_instructions:- address2:- state_name:- phone: "(202) 456-1111"- company:- active: true- default: false- kind: warehouse- returns_enabled: true- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- schema:- "$ref": "#/components/schemas/StockLocation"- '404':- description: another seller's stock location- content:- application/json:- example:- error:- code: record_not_found- message: Stock location not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- patch:- summary: Update a stock location- tags:- - Stock Locations- security:- - bearer_auth: []- description: |- Edits a stock location the acting seller owns.-- There is no delete: a location holds stock levels and is named on- historical fulfillments, so a seller retires one by setting `active` to- `false`.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: stock location updated- content:- application/json:- example:- id: sloc_UkLWZg9DAJ- name: Kiln Lane warehouse- address1: 1600 Pennsylvania Ave NW- city: Washington- zipcode: '20500'- country_code: US- country_name: United States- state_code: AL- state_text: AL- pickup_ready_in_minutes:- pickup_instructions:- address2:- state_name:- phone: "(202) 456-1111"- company:- active: true- default: false- kind: warehouse- returns_enabled: true- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- schema:- "$ref": "#/components/schemas/StockLocation"- requestBody:- content:- application/json:- schema:- type: object- properties:- name:- type: string- example: Main warehouse- address1:- type: string- nullable: true- city:- type: string- nullable: true- zipcode:- type: string- nullable: true- country_code:- type: string- nullable: true- state_code:- type: string- nullable: true- phone:- type: string- nullable: true- active:- type: boolean- default:- type: boolean- "/api/v3/seller/invitations":- get:- summary: List pending invitations- tags:- - Team- security:- - bearer_auth: []- description: |- Offers nobody has accepted yet, newest first.-- Pending only — an accepted invitation is a team member, and shows up on- `GET /api/v3/seller/team` instead.-- Sending an invitation lives on `team`, because that is hiring. Chasing or- withdrawing one is bookkeeping on the offer itself, so it lives here.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: invitations listed- content:- application/json:- example:- data:- - id: inv_UkLWZg9DAJ- email: [email protected]- created_at: '2026-01-15T12:00:00.000Z'- expires_at: '2026-01-29T12:00:00.000Z'- accepted_at:- status: pending- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=gybGAXxVP79yKWNTZLAC94ui"- schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Invitation"- required:- - data- "/api/v3/seller/invitations/{id}/resend":- parameters:- - name: id- in: path- description: Invitation ID- required: true- schema:- type: string- patch:- summary: Resend an invitation- tags:- - Team- security:- - bearer_auth: []- description: |- Sends the invitation email again, for a colleague who never got the first- one. An invitation whose window has closed is refused rather than- re-sent.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: invitation resent- content:- application/json:- example:- id: inv_UkLWZg9DAJ- email: [email protected]- created_at: '2026-01-15T12:00:00.000Z'- expires_at: '2026-01-29T12:00:00.000Z'- accepted_at:- status: pending- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=3uJFfKUSiHtnc9TGAXMJUXsB"- schema:- "$ref": "#/components/schemas/Invitation"- '404':- description: another seller's invitation- content:- application/json:- example:- error:- code: record_not_found- message: Invitation not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- "/api/v3/seller/invitations/{id}":- parameters:- - name: id- in: path- description: Invitation ID- required: true- schema:- type: string- delete:- summary: Revoke an invitation- tags:- - Team- security:- - bearer_auth: []- description: Withdraws an offer that has not been accepted.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '204':- description: invitation revoked- '404':- description: another seller's invitation- content:- application/json:- example:- error:- code: record_not_found- message: Invitation not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- "/api/v3/seller/team":- get:- summary: List team members- tags:- - Team- security:- - bearer_auth: []- description: |- The people who run this seller.-- Rooted at the acting seller throughout, so a seller only ever sees their- own team. Unpaginated — a seller's team is small by nature.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: team members listed- content:- application/json:- example:- data:- - id: adm_UkLWZg9DAJ- email: [email protected]- first_name: Bill- last_name: Towne- full_name: Bill Towne+ user:+ id: adm_UkLWZg9DAJ+ email: [email protected]+ first_name: Nadia+ last_name: Effertz+ full_name: Nadia Effertzcreated_at: '2026-01-15T12:00:00.000Z'avatar_url:+ selected_locale:+ sellers:+ - id: sel_UkLWZg9DAJ+ name: Seller 53+ slug: seller-53+ status: approved+ permissions:+ - allow: true+ actions:+ - read+ subjects:+ - Spree::Country+ has_conditions: false+ - allow: true+ actions:+ - read+ subjects:+ - Spree::State+ has_conditions: false+ - allow: true+ actions:+ - read+ subjects:+ - Spree::Store+ has_conditions: true+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::Product+ has_conditions: false+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::Variant+ has_conditions: false+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::OptionType+ has_conditions: false+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::OptionValue+ has_conditions: false+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::Price+ has_conditions: false+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::PriceList+ has_conditions: false+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::PriceRule+ has_conditions: false+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::Catalog+ has_conditions: false+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::CatalogProduct+ has_conditions: false+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::CatalogAssignment+ has_conditions: false+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::CustomField+ has_conditions: false+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::DigitalAsset+ has_conditions: false+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::Import+ has_conditions: false+ - allow: true+ actions:+ - read+ - admin+ subjects:+ - Spree::ImportRow+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::Product+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::Variant+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::OptionType+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::OptionValue+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::Price+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::PriceList+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::PriceRule+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::Catalog+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::CatalogProduct+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::CatalogAssignment+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::CustomField+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::DigitalAsset+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::Import+ has_conditions: false+ - allow: true+ actions:+ - manage+ subjects:+ - Spree::ImportRow+ has_conditions: false+ permission_keys:+ - read_products+ - write_productsschema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/TeamMember"- required:- - data- post:- summary: Invite a team member- tags:- - Team- security:- - bearer_auth: []- description: |- Invites a colleague onto this seller's team. They join when they accept,- on the same invitation rail — and the same email — the marketplace- operator's own invitations use.-- Hiring is not a lifecycle transition: a trading seller's status is- untouched by taking someone on.-- The role is not a parameter. Every member holds the seller's own seeded- role, which already carries the whole seller vocabulary.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '201':- description: invitation sent- content:- application/json:- example:- id: inv_UkLWZg9DAJ- email: [email protected]- created_at: '2026-01-15T12:00:00.000Z'- expires_at: '2026-01-29T12:00:00.000Z'- accepted_at:- status: pending- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=3K6BfBtHGFeQgToPE45qUDWE"- schema:- "$ref": "#/components/schemas/Invitation"- '422':- description: validation failed+ "$ref": "#/components/schemas/SellerMeResponse"+ '401':+ description: missing or invalid tokencontent:application/json:example:error:- code: validation_error- message: Email is invalid and Email can't be blank- details:- email:- - is invalid- - can't be blank+ code: authentication_required+ message: Authentication requiredschema:"$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- properties:- email:- type: string- format: email- example: [email protected]- required:- "/api/v3/seller/team/{id}":- parameters:- - name: id- in: path- description: Team member (user) ID- required: true- schema:- type: string- delete:- summary: Remove a team member+ patch:+ summary: Update your accounttags:- - Team+ - Accountsecurity:- bearer_auth: []description: |- Revokes a member's access, removing every role they hold on this seller.+ Edits the signed-in person's own account — the name and photo their team+ sees, and the language their panel displays.- The team can never reach zero: emptying it would leave a seller nobody- can sign in to, and only the marketplace operator could put someone back.- The last remaining member is refused with `422`.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string+ This is the person, not the business: the seller they act for is+ `PATCH /profile`. Like `GET /me` it answers without+ `X-Spree-Seller-Id`, because the account is the same whichever seller+ they are acting for.++ `avatar` takes an ActiveStorage direct-upload signed id to set the+ photo, or `null` to remove it; omit it to leave the current one alone.+ `email` is identity-bound and cannot be changed here.+ parameters: []responses:- '204':- description: member removed- '422':- description: cannot remove the last remaining member+ '200':+ description: account updatedcontent:application/json:example:- error:- code: processing_error- message: A seller needs at least one team member. Invite someone- else before removing this one.+ user:+ id: adm_UkLWZg9DAJ+ email: [email protected]+ first_name: Ada+ last_name: Lovelace+ full_name: Ada Lovelace+ created_at: '2026-01-15T12:00:00.000Z'+ avatar_url:+ selected_locale:+ sellers:+ - id: sel_UkLWZg9DAJ+ name: Seller 55+ slug: seller-55+ status: approved+ permissions: []+ permission_keys: []schema:- "$ref": "#/components/schemas/ErrorResponse"- '404':- description: not a member of this seller+ "$ref": "#/components/schemas/SellerMeResponse"+ '422':+ description: the photo is not a web imagecontent:application/json:example:error:- code: record_not_found- message: Admin user not found+ code: validation_error+ message: Avatar has an invalid content type (authorized content+ types are PNG, JPG, GIF, WEBP)+ details:+ avatar:+ - has an invalid content type (authorized content types are PNG,+ JPG, GIF, WEBP)schema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/seller/direct_uploads":- post:- summary: Create a direct upload- tags:- - Uploads- security:- - bearer_auth: []- description: |- Presigns an upload target for a file the seller is about to send.-- Three steps: post the file's metadata here, `PUT` the bytes to the- returned `direct_upload.url` with the headers it names, then send the- returned `signed_id` wherever the file belongs — as a requirement- submission's `file`, or as `logo`, `square_logo` or `cover_photo` on the- profile.-- The blob is attached to nothing at this point. The endpoint that consumes- the `signed_id` is the one that checks ownership.-- `checksum` is the file's MD5 digest, base64-encoded — the storage service- verifies the upload against it.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '201':- description: upload target created+ '401':+ description: missing or invalid tokencontent:application/json:example:- direct_upload:- url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJuem5oOGdra3VxendvbDc1ODBxNHNwZmpmMjVxIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--84b12e983ef99a420e514d015b34f26a6a0716bb- headers:- Content-Type: application/pdf- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac+ error:+ code: authentication_required+ message: Authentication requiredschema:- "$ref": "#/components/schemas/DirectUploadResponse"+ "$ref": "#/components/schemas/ErrorResponse"requestBody:content:application/json:schema:type: objectproperties:- blob:- type: object- properties:- filename:- type: string- example: registration.pdf- byte_size:- type: integer- example: 51234- checksum:- type: string- description: Base64-encoded MD5 digest of the file- example: rL0Y20zC+Fzt72VPzMSk2A==- content_type:- type: string- example: application/pdf- required:- - filename- - byte_size- - checksum- - content_type- required:- - blob- "/api/v3/seller/balances":+ first_name:+ type: string+ example: Ada+ last_name:+ type: string+ example: Lovelace+ selected_locale:+ type: string+ example: de+ description: Panel display language, as a code the panel ships.+ avatar:+ type: string+ nullable: true+ description: Direct-upload signed id, or `null` to remove the photo.+ "/api/v3/seller/onboarding":get:- summary: List balances+ summary: Get onboarding checklisttags:- - Earnings+ - Onboardingsecurity:- bearer_auth: []description: |- Where this seller stands with the marketplace, one row per currency- they have earned or been paid in: what they have earned (settled- transfers, refund reversals included), what has reached them, what the- marketplace still owes, and earnings the payout provider has not yet- confirmed.+ What this marketplace asks of the seller before it will admit them.- Computed from the ledger rather than stored, so the rows carry no id- and there is nothing to page.+ Singular: the checklist is always the acting seller's. Every answer is+ computed server-side by the same evaluator the operator's own view uses,+ so the panel and the operator can never show different progress.++ `progress` counts optional requirements too — it is how far along the+ checklist is, not how close to approval. Read `blocking` on each+ requirement for that.++ Each requirement's `id` is what a submission is posted against. A+ marketplace that asks for nothing returns an empty list, which is a+ complete answer rather than a missing one.parameters:- name: X-Spree-Seller-Idin: header@@ -14877,105 +14301,42 @@ paths:type: stringresponses:'200':- description: balances listed+ description: checklist returnedcontent:application/json:example:- data:- - currency: USD- settlement_currency: USD- converted: false- earned: '40.0'- display_earned: "$40.00"- payable: '40.0'- display_payable: "$40.00"- paid: '15.0'- display_paid: "$15.00"- balance: '25.0'- display_balance: "$25.00"- pending: '0.0'- display_pending: "$0.00"+ status: approved+ progress:+ done: 0+ total: 0+ requirements: []schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Balance"- required:- - data- "/api/v3/seller/orders/{order_id}/claims":- parameters:- - name: order_id- in: path- description: Prefixed order ID- required: true- schema:- type: string- get:- summary: List claims- tags:- - Claims- security:- - bearer_auth: []- description: Problems reported on one of this seller's orders.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: claims listed+ "$ref": "#/components/schemas/SellerOnboardingResponse"+ '403':+ description: no seller named, or not a member of itcontent:application/json:example:- data:- - id: claim_UkLWZg9DAJ- number: CLM1001- status: open- resolution:- order_id: or_UkLWZg9DAJ- reason_id:- refund_total: '0.0'- display_refund_total: "$0.00"- approved_at:- resolved_at:- denied_at:- canceled_at:- memo:- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:+ error:+ code: access_denied+ message: You do not have access to this seller.schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Claim"- required:- - data+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/seller/onboarding/submit_for_review":post:- summary: Open a claim+ summary: Submit for reviewtags:- - Claims+ - Onboardingsecurity:- bearer_auth: []description: |- Reports that something went wrong with a delivery, to be put right- without necessarily asking for the goods back.+ Says the seller is ready, moving them from `onboarding` to+ `ready_for_review`.- A replacement variant, if one is offered, comes from this seller's own- catalogue — a rival's is not theirs to promise.+ Refused with `422` when something required is still outstanding — the+ message names the blocking requirements, and the seller's status is+ unchanged. Returns the same payload as the checklist so the panel can+ re-render from one response.parameters:- name: X-Spree-Seller-Idin: header@@ -14983,204 +14344,265 @@ paths:schema:type: stringresponses:- '201':- description: claim opened+ '200':+ description: submitted for reviewcontent:application/json:example:- id: claim_UkLWZg9DAJ- number: CLM1001- status: open- resolution:- order_id: or_UkLWZg9DAJ- reason_id:- refund_total: '0.0'- display_refund_total: "$0.00"- approved_at:- resolved_at:- denied_at:- canceled_at:- memo:+ status: ready_for_review+ progress:+ done: 0+ total: 0+ requirements: []schema:- "$ref": "#/components/schemas/Claim"- requestBody:- content:- application/json:- schema:- type: object- properties:- items:- type: array- items:- type: object- properties:- line_item_id:- type: string- quantity:- type: integer- description:- type: string- nullable: true- send_replacement:- type: boolean- replacement_variant_id:- type: string- nullable: true- refund_amount:- type: string- nullable: true- required:- - line_item_id- - quantity- reason_id:- type: string- nullable: true- memo:- type: string- nullable: true- required:- - items- "/api/v3/seller/orders/{order_id}/claims/{id}/approve":- parameters:- - name: order_id- in: path- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: string- patch:- summary: Approve a claim+ "$ref": "#/components/schemas/SellerOnboardingResponse"+ '422':+ description: something required is still outstanding+ content:+ application/json:+ example:+ error:+ code: processing_error+ message: Requirements Accept terms is not complete+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/seller/orders":+ get:+ summary: List orderstags:- - Claims+ - Orderssecurity:- bearer_auth: []- description: Accepts that the claim is good.+ description: |+ What this seller has sold.++ On a marketplace a basket spanning several sellers is split into one+ order each, so these are the seller's own orders rather than a filtered+ view of somebody else's — another seller's order is never reachable,+ whatever id is sent.++ Checkouts still in flight are left out: until one completes it is+ nobody's order.parameters:- name: X-Spree-Seller-Idin: headerrequired: trueschema:type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Records per page (max 100)+ schema:+ type: integer+ - name: sort+ in: query+ required: false+ description: Sort field; prefix with `-` for descending+ schema:+ type: stringresponses:'200':- description: claim approved+ description: orders listedcontent:application/json:example:- id: claim_UkLWZg9DAJ- number: CLM1001- status: approved- resolution:- order_id: or_UkLWZg9DAJ- reason_id:- refund_total: '0.0'- display_refund_total: "$0.00"- approved_at: '2026-01-15T12:00:00Z'- resolved_at:- denied_at:- canceled_at:- memo:+ data:+ - id: or_UkLWZg9DAJ+ number: R1001+ customer_note:+ currency: USD+ total_quantity: 1+ status: placed+ fulfillment_status:+ payment_status:+ completed_at: '2026-01-15T12:00:00.000Z'+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ internal_note:+ internal_note_html:+ item_total: '10.0'+ display_item_total: "$10.00"+ delivery_total: '100.0'+ display_delivery_total: "$100.00"+ discount_total: '0.0'+ display_discount_total: "$0.00"+ adjustment_total: '0.0'+ display_adjustment_total: "$0.00"+ included_tax_total: '0.0'+ display_included_tax_total: "$0.00"+ additional_tax_total: '0.0'+ display_additional_tax_total: "$0.00"+ tax_total: '0.0'+ display_tax_total: "$0.00"+ total: '110.0'+ display_total: "$110.00"+ payment_total: '0.0'+ display_payment_total: "$0.00"+ amount_due: '110.0'+ display_amount_due: "$110.00"+ commission_amount_total: '0.0'+ display_commission_amount_total: "$0.00"+ commission_tax_total: '0.0'+ display_commission_tax_total: "$0.00"+ commission_total: '0.0'+ display_commission_total: "$0.00"+ canceled_at:+ cancel_reason_name:+ cancel_note:+ items:+ - id: li_UkLWZg9DAJ+ name: Product 19195+ options_text: ''+ quantity: 1+ currency: USD+ price: '10.0'+ display_price: "$10.00"+ total: '10.0'+ display_total: "$10.00"+ variant_id: variant_UkLWZg9DAJ+ sku: SKU-257+ thumbnail_url:+ fulfillments:+ - id: ful_UkLWZg9DAJ+ number: R1001-F1+ status: unfulfilled+ tracking: U10000+ tracking_url:+ fulfilled_at:+ delivered_at:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ fulfillment_type: shipping+ delivery_method_name: UPS Ground 86+ stock_location_name: Roseline Roberts+ stock_location_id: sloc_UkLWZg9DAJ+ fulfillment_items:+ - id: fi_UkLWZg9DAJ+ quantity: 1+ line_item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ name: Product 19195+ sku: SKU-257+ options_text: ''+ selected_delivery_rate_id: dr_gbHJdmfrXB+ delivery_rates:+ - id: dr_gbHJdmfrXB+ name: UPS Ground 86+ selected: true+ cost: '10.0'+ total: '10.0'+ carrier:+ service_level:+ estimated_delivery_date:+ display_cost: "$10.00"+ display_total: "$10.00"+ deliveries:+ - id: dlv_UkLWZg9DAJ+ tracking_number: U10000+ carrier:+ carrier_name:+ service:+ status: pending+ tracking_url:+ estimated_delivery_at:+ delivered_at:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ shipping_label_id:+ labels: []+ shipping_address:+ id: addr_gbHJdmfrXB+ label:+ first_name: John+ last_name: Doe+ full_name: John Doe+ address1: 167 Lovely Street+ address2: Northwest+ postal_code: '10118'+ city: New York+ phone: 555-555-0199+ company: Company+ country_name: United States+ country_code: US+ state_text: NY+ state_code: NY+ quick_checkout: false+ is_default_billing: false+ is_default_shipping: false+ state_abbr: NY+ country_iso: US+ state_name: New York+ billing_address:+ id: addr_UkLWZg9DAJ+ label:+ first_name: John+ last_name: Doe+ full_name: John Doe+ address1: 166 Lovely Street+ address2: Northwest+ postal_code: '10118'+ city: New York+ phone: 555-555-0199+ company: Company+ country_name: United States+ country_code: US+ state_text: NY+ state_code: NY+ quick_checkout: false+ is_default_billing: false+ is_default_shipping: false+ state_abbr: NY+ country_iso: US+ state_name: New York+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:schema:- "$ref": "#/components/schemas/Claim"- "/api/v3/seller/orders/{order_id}/claims/{id}/resolve":+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Order"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ "/api/v3/seller/orders/{id}":parameters:- - name: order_id- in: path- required: true- schema:- type: string- name: idin: path+ description: Prefixed order IDrequired: trueschema:type: string- patch:- summary: Resolve a claim+ get:+ summary: Get an ordertags:- - Claims+ - Orderssecurity:- bearer_auth: []description: |- Puts the claim right: money back, a replacement shipment, or both.+ One order, as the seller needs it to pack and post the parcel: the+ lines with their SKUs, where it ships to, and a fulfillment per parcel.- A refund is bounded by this order's share of the payment, so one- seller can never settle out of a sibling's money.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: claim resolved- content:- application/json:- example:- id: claim_UkLWZg9DAJ- number: CLM1001- status: resolved- resolution: refund- order_id: or_UkLWZg9DAJ- reason_id:- refund_total: '0.0'- display_refund_total: "$0.00"- approved_at: '2026-01-15T12:00:00Z'- resolved_at: '2026-01-15T12:00:00Z'- denied_at:- canceled_at:- memo:- schema:- "$ref": "#/components/schemas/Claim"- requestBody:- content:- application/json:- schema:- type: object- properties:- resolution:- type: string- enum:- - refund- - replacement- - refund_and_replacement- refund_method:- type: string- enum:- - original_payment- - store_credit- amount:- type: string- nullable: true- replacement_line_item_ids:- type: array- items:- type: string- required:- - resolution- "/api/v3/seller/orders/{order_id}/claims/{id}/deny":- parameters:- - name: order_id- in: path- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: string- patch:- summary: Deny a claim- tags:- - Claims- security:- - bearer_auth: []- description: Turns the claim down.+ How the customer paid the marketplace is deliberately absent — that is+ between the buyer and the operator.parameters:- name: X-Spree-Seller-Idin: header@@ -15189,143 +14611,195 @@ paths:type: stringresponses:'200':- description: claim denied+ description: order foundcontent:application/json:example:- id: claim_UkLWZg9DAJ- number: CLM1001- status: denied- resolution:- order_id: or_UkLWZg9DAJ- reason_id:- refund_total: '0.0'- display_refund_total: "$0.00"- approved_at:- resolved_at:- denied_at: '2026-01-15T12:00:00Z'+ id: or_UkLWZg9DAJ+ number: R1001+ customer_note:+ currency: USD+ total_quantity: 1+ status: placed+ fulfillment_status:+ payment_status:+ completed_at: '2026-01-15T12:00:00.000Z'+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ internal_note:+ internal_note_html:+ item_total: '10.0'+ display_item_total: "$10.00"+ delivery_total: '100.0'+ display_delivery_total: "$100.00"+ discount_total: '0.0'+ display_discount_total: "$0.00"+ adjustment_total: '0.0'+ display_adjustment_total: "$0.00"+ included_tax_total: '0.0'+ display_included_tax_total: "$0.00"+ additional_tax_total: '0.0'+ display_additional_tax_total: "$0.00"+ tax_total: '0.0'+ display_tax_total: "$0.00"+ total: '110.0'+ display_total: "$110.00"+ payment_total: '0.0'+ display_payment_total: "$0.00"+ amount_due: '110.0'+ display_amount_due: "$110.00"+ commission_amount_total: '0.0'+ display_commission_amount_total: "$0.00"+ commission_tax_total: '0.0'+ display_commission_tax_total: "$0.00"+ commission_total: '0.0'+ display_commission_total: "$0.00"canceled_at:- memo:+ cancel_reason_name:+ cancel_note:+ items:+ - id: li_UkLWZg9DAJ+ name: Product 1929755+ options_text: ''+ quantity: 1+ currency: USD+ price: '10.0'+ display_price: "$10.00"+ total: '10.0'+ display_total: "$10.00"+ variant_id: variant_UkLWZg9DAJ+ sku: SKU-258+ thumbnail_url:+ fulfillments:+ - id: ful_UkLWZg9DAJ+ number: R1001-F1+ status: unfulfilled+ tracking: U10000+ tracking_url:+ fulfilled_at:+ delivered_at:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ fulfillment_type: shipping+ delivery_method_name: UPS Ground 87+ stock_location_name: Woodrow Hand+ stock_location_id: sloc_UkLWZg9DAJ+ fulfillment_items:+ - id: fi_UkLWZg9DAJ+ quantity: 1+ line_item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ name: Product 1929755+ sku: SKU-258+ options_text: ''+ selected_delivery_rate_id: dr_gbHJdmfrXB+ delivery_rates:+ - id: dr_gbHJdmfrXB+ name: UPS Ground 87+ selected: true+ cost: '10.0'+ total: '10.0'+ carrier:+ service_level:+ estimated_delivery_date:+ display_cost: "$10.00"+ display_total: "$10.00"+ deliveries:+ - id: dlv_UkLWZg9DAJ+ tracking_number: U10000+ carrier:+ carrier_name:+ service:+ status: pending+ tracking_url:+ estimated_delivery_at:+ delivered_at:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ shipping_label_id:+ labels: []+ shipping_address:+ id: addr_gbHJdmfrXB+ label:+ first_name: John+ last_name: Doe+ full_name: John Doe+ address1: 169 Lovely Street+ address2: Northwest+ postal_code: '10118'+ city: New York+ phone: 555-555-0199+ company: Company+ country_name: United States+ country_code: US+ state_text: NY+ state_code: NY+ quick_checkout: false+ is_default_billing: false+ is_default_shipping: false+ state_abbr: NY+ country_iso: US+ state_name: New York+ billing_address:+ id: addr_UkLWZg9DAJ+ label:+ first_name: John+ last_name: Doe+ full_name: John Doe+ address1: 168 Lovely Street+ address2: Northwest+ postal_code: '10118'+ city: New York+ phone: 555-555-0199+ company: Company+ country_name: United States+ country_code: US+ state_text: NY+ state_code: NY+ quick_checkout: false+ is_default_billing: false+ is_default_shipping: false+ state_abbr: NY+ country_iso: US+ state_name: New Yorkschema:- "$ref": "#/components/schemas/Claim"- "/api/v3/seller/claim_reasons":- get:- summary: List claim reasons- tags:- - Claims- security:- - bearer_auth: []- description: |- What can go wrong with a delivery, as the marketplace defines it.-- Read-only: a seller picks from the operator's vocabulary.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: reasons listed+ "$ref": "#/components/schemas/Order"+ '404':+ description: another seller's ordercontent:application/json:example:- data:- - id: clr_UkLWZg9DAJ- name: Arrived damaged- active: true- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:+ error:+ code: order_not_found+ message: Order not foundschema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Reason"- required:- - data- "/api/v3/seller/orders/{order_id}/exchanges":+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/seller/orders/{id}/cancel":parameters:- - name: order_id+ - name: idin: pathdescription: Prefixed order IDrequired: trueschema:type: string- get:- summary: List exchanges- tags:- - Exchanges- security:- - bearer_auth: []- description: Goods swapped for different ones on one of this seller's orders.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: exchanges listed- content:- application/json:- example:- data:- - id: exch_UkLWZg9DAJ- number: EX1001- status: requested- order_id: or_UkLWZg9DAJ- reason_id:- price_difference: '9.99'- display_price_difference: "$9.99"- approved_at:- received_at:- fulfilled_at:- canceled_at:- memo:- stock_location_id: sloc_UkLWZg9DAJ- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Exchange"- required:- - data- post:- summary: Open an exchange+ patch:+ summary: Cancel an ordertags:- - Exchanges+ - Orderssecurity:- bearer_auth: []description: |- Swaps goods for different ones.+ Withdraws from an order this seller cannot fulfil, naming a reason from+ the marketplace's own list.- The replacement comes from this seller's own catalogue: it is stock- they will send, so a variant belonging to another seller is not theirs- to promise and reads as missing.+ The goods go back on the shelf and the payment authorization is+ released either way. `refund_payments` also hands back what the buyer+ paid for these goods — a seller is merchant of record for their own+ child order, and on a split checkout only that order's share of the+ group's payment is settled.++ There is no `refund_amount`: withdrawing from the whole order returns+ what that order was paid, and a partial figure is a return.parameters:- name: X-Spree-Seller-Idin: header@@ -15333,134 +14807,55 @@ paths:schema:type: stringresponses:- '201':- description: exchange opened+ '200':+ description: order canceledcontent:application/json:- example:- id: exch_UkLWZg9DAJ- number: EX1001- status: requested- order_id: or_UkLWZg9DAJ- reason_id:- price_difference: '9.99'- display_price_difference: "$9.99"- approved_at:- received_at:- fulfilled_at:- canceled_at:- memo:- stock_location_id: sloc_UkLWZg9DAJschema:- "$ref": "#/components/schemas/Exchange"+ "$ref": "#/components/schemas/Order"requestBody:content:application/json:schema:type: objectproperties:- items:- type: array- items:- type: object- properties:- fulfillment_item_id:- type: string- new_variant_id:- type: string- quantity:- type: integer- required:- - fulfillment_item_id- - new_variant_id- - quantity- reason_id:- type: string- nullable: true- stock_location_id:+ cancel_reason_id:type: stringnullable: true- memo:+ description: A reason from GET /order_cancellation_reasons+ cancel_note:type: stringnullable: true- required:- - items- "/api/v3/seller/orders/{order_id}/exchanges/{id}/fulfill":+ description: Free text beside the reason+ refund_payments:+ type: boolean+ description: Hand back what the buyer paid for this order's goods+ notify_customer:+ type: boolean+ description: Email the customer about the cancellation+ "/api/v3/seller/orders/{id}/address":parameters:- - name: order_id- in: path- required: true- schema:- type: string- name: idin: path+ description: Prefixed order IDrequired: trueschema:type: stringpatch:- summary: Send the replacement- tags:- - Exchanges- security:- - bearer_auth: []- description: |- Sends the replacement goods, settling any price difference at the same- time — which is why it takes a refund method.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: replacement sent- content:- application/json:- example:- id: exch_UkLWZg9DAJ- number: EX1001- status: fulfilled- order_id: or_UkLWZg9DAJ- reason_id:- price_difference: '9.99'- display_price_difference: "$9.99"- approved_at: '2026-01-15T12:00:00Z'- received_at: '2026-01-15T12:00:00Z'- fulfilled_at: '2026-01-15T12:00:00Z'- canceled_at:- memo:- stock_location_id: sloc_UkLWZg9DAJ- schema:- "$ref": "#/components/schemas/Exchange"- requestBody:- content:- application/json:- schema:- type: object- properties:- refund_method:- type: string- enum:- - original_payment- - store_credit- "/api/v3/seller/exports":- post:- summary: Create an export+ summary: Correct an order addresstags:- - Exports+ - Orderssecurity:- bearer_auth: []description: |- Queues a CSV of this seller's own records.+ Corrects where the goods go or who the invoice names.- Only datasets that can be narrowed to a single seller are offered, so- an export can never contain another seller's rows however it is- filtered. The seller and the store come from the request context- whatever the payload says.+ The seller is merchant of record for their own child order, so a+ delivery address the buyer got wrong is theirs to fix. Send only the+ lines that change — the rest of the address is carried over.- Generation runs in the background: poll `GET /api/v3/seller/exports/{id}`- until `done` is true, then fetch `download_url`.+ This is the only write against the order itself besides cancelling:+ nothing else about it, its totals included, is the seller's to change.parameters:- name: X-Spree-Seller-Idin: header@@ -15468,81 +14863,266 @@ paths:schema:type: stringresponses:- '201':- description: export queued+ '200':+ description: address correctedcontent:application/json:example:- id: exp_UkLWZg9DAJ- number: EF1001- format: csv+ id: or_UkLWZg9DAJ+ number: R1001+ customer_note:+ currency: USD+ total_quantity: 1+ status: placed+ fulfillment_status:+ payment_status:+ completed_at: '2026-01-15T12:00:00.000Z'created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'- type: orders- user_id: adm_UkLWZg9DAJ- done: false- filename:- byte_size:- download_url:+ internal_note:+ internal_note_html:+ item_total: '10.0'+ display_item_total: "$10.00"+ delivery_total: '100.0'+ display_delivery_total: "$100.00"+ discount_total: '0.0'+ display_discount_total: "$0.00"+ adjustment_total: '0.0'+ display_adjustment_total: "$0.00"+ included_tax_total: '0.0'+ display_included_tax_total: "$0.00"+ additional_tax_total: '0.0'+ display_additional_tax_total: "$0.00"+ tax_total: '0.0'+ display_tax_total: "$0.00"+ total: '110.0'+ display_total: "$110.00"+ payment_total: '0.0'+ display_payment_total: "$0.00"+ amount_due: '110.0'+ display_amount_due: "$110.00"+ commission_amount_total: '0.0'+ display_commission_amount_total: "$0.00"+ commission_tax_total: '0.0'+ display_commission_tax_total: "$0.00"+ commission_total: '0.0'+ display_commission_total: "$0.00"+ canceled_at:+ cancel_reason_name:+ cancel_note:+ items:+ - id: li_UkLWZg9DAJ+ name: Product 1965038+ options_text: ''+ quantity: 1+ currency: USD+ price: '10.0'+ display_price: "$10.00"+ total: '10.0'+ display_total: "$10.00"+ variant_id: variant_UkLWZg9DAJ+ sku: SKU-262+ thumbnail_url:+ fulfillments:+ - id: ful_UkLWZg9DAJ+ number: R1001-F1+ status: unfulfilled+ tracking: U10000+ tracking_url:+ fulfilled_at:+ delivered_at:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ fulfillment_type: shipping+ delivery_method_name: UPS Ground 91+ stock_location_name: Rudy Mosciski+ stock_location_id: sloc_UkLWZg9DAJ+ fulfillment_items:+ - id: fi_UkLWZg9DAJ+ quantity: 1+ line_item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ name: Product 1965038+ sku: SKU-262+ options_text: ''+ selected_delivery_rate_id: dr_gbHJdmfrXB+ delivery_rates:+ - id: dr_gbHJdmfrXB+ name: UPS Ground 91+ selected: true+ cost: '10.0'+ total: '10.0'+ carrier:+ service_level:+ estimated_delivery_date:+ display_cost: "$10.00"+ display_total: "$10.00"+ deliveries:+ - id: dlv_UkLWZg9DAJ+ tracking_number: U10000+ carrier:+ carrier_name:+ service:+ status: pending+ tracking_url:+ estimated_delivery_at:+ delivered_at:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ shipping_label_id:+ labels: []+ shipping_address:+ id: addr_EfhxLZ9ck8+ label:+ first_name: John+ last_name: Doe+ full_name: John Doe+ address1: 9 Corrected Way+ address2: Northwest+ postal_code: '10118'+ city: Fixedton+ phone: 555-555-0199+ company: Company+ country_name: United States+ country_code: US+ state_text: NY+ state_code: NY+ quick_checkout: false+ is_default_billing: false+ is_default_shipping: true+ state_abbr: NY+ country_iso: US+ state_name: New York+ billing_address:+ id: addr_UkLWZg9DAJ+ label:+ first_name: John+ last_name: Doe+ full_name: John Doe+ address1: 176 Lovely Street+ address2: Northwest+ postal_code: '10118'+ city: New York+ phone: 555-555-0199+ company: Company+ country_name: United States+ country_code: US+ state_text: NY+ state_code: NY+ quick_checkout: false+ is_default_billing: false+ is_default_shipping: false+ state_abbr: NY+ country_iso: US+ state_name: New Yorkschema:- "$ref": "#/components/schemas/Export"+ "$ref": "#/components/schemas/Order"'422':- description: type cannot be scoped to one seller+ description: neither address namedcontent:application/json:example:error:code: validation_error- message: 'Unsupported export type. Supported types: orders, products'- schema:- "$ref": "#/components/schemas/ErrorResponse"+ message: shipping_address or billing_address is required+ details:+ base:+ - shipping_address or billing_address is requiredrequestBody:content:application/json:schema:type: objectproperties:- type:- type: string- enum:- - orders- - products- description: Which dataset to export.- record_selection:- type: string- enum:- - filtered- - all- description: "`filtered` (default) honours `search_params`; `all`- exports everything this seller owns."- search_params:+ shipping_address:type: object- description: Ransack predicates, the same shape the list endpoints- take. Ignored when `record_selection` is `all`.- additionalProperties: true- results_url:- type: string- description: Panel URL the export-done email links back to. Honoured- only when it matches one of the store's allowed origins.- required:- - type- "/api/v3/seller/exports/{id}":+ description: Only the lines that change; the rest is carried over+ properties:+ first_name:+ type: string+ last_name:+ type: string+ company:+ type: string+ nullable: true+ address1:+ type: string+ address2:+ type: string+ nullable: true+ city:+ type: string+ postal_code:+ type: string+ country_code:+ type: string+ state_code:+ type: string+ nullable: true+ state_name:+ type: string+ nullable: true+ phone:+ type: string+ nullable: true+ label:+ type: string+ nullable: true+ billing_address:+ type: object+ description: Only the lines that change; the rest is carried over+ properties:+ first_name:+ type: string+ last_name:+ type: string+ company:+ type: string+ nullable: true+ address1:+ type: string+ address2:+ type: string+ nullable: true+ city:+ type: string+ postal_code:+ type: string+ country_code:+ type: string+ state_code:+ type: string+ nullable: true+ state_name:+ type: string+ nullable: true+ phone:+ type: string+ nullable: true+ label:+ type: string+ nullable: true+ required: true+ "/api/v3/seller/orders/{order_id}/notes":parameters:- - name: id+ - name: order_idin: path- description: Export ID+ description: Prefixed order IDrequired: trueschema:type: stringget:- summary: Get an export+ summary: Get order notestags:- - Exports+ - Orderssecurity:- bearer_auth: []description: |- Reads one of this seller's exports. Poll this until `done` is true,- then fetch `download_url`.+ The instructions the buyer left, and the seller's own working note.++ A marketplace basket splits into one order per seller, so the internal+ note here is this seller's alone rather than the operator's note about+ the whole sale.parameters:- name: X-Spree-Seller-Idin: header@@ -15551,101 +15131,171 @@ paths:type: stringresponses:'200':- description: export found+ description: notescontent:application/json:example:- id: exp_UkLWZg9DAJ- number: EF1001- format: csv+ id: or_UkLWZg9DAJ+ number: R1001+ customer_note:+ currency: USD+ total_quantity: 1+ status: placed+ fulfillment_status:+ payment_status:+ completed_at: '2026-01-15T12:00:00.000Z'created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'- type: orders- user_id: adm_UkLWZg9DAJ- done: false- filename:- byte_size:- download_url:- schema:- "$ref": "#/components/schemas/Export"- '404':- description: another seller's export- content:- application/json:- example:- error:- code: record_not_found- message: Export not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- "/api/v3/seller/exports/{id}/download":- parameters:- - name: id- in: path- description: Export ID- required: true- schema:- type: string- get:- summary: Download an export- tags:- - Exports- security:- - bearer_auth: []- description: |- Streams the finished CSV.-- The bytes are served by this endpoint rather than through a redirect,- so the seller's own session authorizes every download.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '422':- description: export is still being written- content:- application/json:- example:- error:- code: export_not_ready- message: Export is not ready yet- text/csv:- schema:- "$ref": "#/components/schemas/ErrorResponse"- '404':- description: another seller's export- content:- application/json:- example:- error:- code: record_not_found- message: Export not found- text/csv:- schema:- "$ref": "#/components/schemas/ErrorResponse"- "/api/v3/seller/orders/{order_id}/fulfillments":- parameters:- - name: order_id- in: path- description: Prefixed order ID- required: true- schema:- type: string- get:- summary: List fulfillments+ internal_note:+ internal_note_html:+ item_total: '10.0'+ display_item_total: "$10.00"+ delivery_total: '100.0'+ display_delivery_total: "$100.00"+ discount_total: '0.0'+ display_discount_total: "$0.00"+ adjustment_total: '0.0'+ display_adjustment_total: "$0.00"+ included_tax_total: '0.0'+ display_included_tax_total: "$0.00"+ additional_tax_total: '0.0'+ display_additional_tax_total: "$0.00"+ tax_total: '0.0'+ display_tax_total: "$0.00"+ total: '110.0'+ display_total: "$110.00"+ payment_total: '0.0'+ display_payment_total: "$0.00"+ amount_due: '110.0'+ display_amount_due: "$110.00"+ commission_amount_total: '0.0'+ display_commission_amount_total: "$0.00"+ commission_tax_total: '0.0'+ display_commission_tax_total: "$0.00"+ commission_total: '0.0'+ display_commission_total: "$0.00"+ canceled_at:+ cancel_reason_name:+ cancel_note:+ items:+ - id: li_UkLWZg9DAJ+ name: Product 1983962+ options_text: ''+ quantity: 1+ currency: USD+ price: '10.0'+ display_price: "$10.00"+ total: '10.0'+ display_total: "$10.00"+ variant_id: variant_UkLWZg9DAJ+ sku: SKU-264+ thumbnail_url:+ fulfillments:+ - id: ful_UkLWZg9DAJ+ number: R1001-F1+ status: unfulfilled+ tracking: U10000+ tracking_url:+ fulfilled_at:+ delivered_at:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ fulfillment_type: shipping+ delivery_method_name: UPS Ground 93+ stock_location_name: Kecia Pollich+ stock_location_id: sloc_UkLWZg9DAJ+ fulfillment_items:+ - id: fi_UkLWZg9DAJ+ quantity: 1+ line_item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ name: Product 1983962+ sku: SKU-264+ options_text: ''+ selected_delivery_rate_id: dr_gbHJdmfrXB+ delivery_rates:+ - id: dr_gbHJdmfrXB+ name: UPS Ground 93+ selected: true+ cost: '10.0'+ total: '10.0'+ carrier:+ service_level:+ estimated_delivery_date:+ display_cost: "$10.00"+ display_total: "$10.00"+ deliveries:+ - id: dlv_UkLWZg9DAJ+ tracking_number: U10000+ carrier:+ carrier_name:+ service:+ status: pending+ tracking_url:+ estimated_delivery_at:+ delivered_at:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ shipping_label_id:+ labels: []+ shipping_address:+ id: addr_gbHJdmfrXB+ label:+ first_name: John+ last_name: Doe+ full_name: John Doe+ address1: 181 Lovely Street+ address2: Northwest+ postal_code: '10118'+ city: New York+ phone: 555-555-0199+ company: Company+ country_name: United States+ country_code: US+ state_text: NY+ state_code: NY+ quick_checkout: false+ is_default_billing: false+ is_default_shipping: false+ state_abbr: NY+ country_iso: US+ state_name: New York+ billing_address:+ id: addr_UkLWZg9DAJ+ label:+ first_name: John+ last_name: Doe+ full_name: John Doe+ address1: 180 Lovely Street+ address2: Northwest+ postal_code: '10118'+ city: New York+ phone: 555-555-0199+ company: Company+ country_name: United States+ country_code: US+ state_text: NY+ state_code: NY+ quick_checkout: false+ is_default_billing: false+ is_default_shipping: false+ state_abbr: NY+ country_iso: US+ state_name: New York+ schema:+ "$ref": "#/components/schemas/Order"+ patch:+ summary: Update order notestags:- - Fulfillments+ - Orderssecurity:- bearer_auth: []description: |- The parcels this seller owes on one order.+ Send only the note that changes: an absent key leaves the other alone,+ while an empty string clears it.- Reached through the order, which is itself fetched through the acting- seller — so a fulfillment on somebody else's order is unreachable- whatever ids are sent.+ `internal_note` accepts HTML and is sanitized on save;+ `internal_note_html` reads it back.parameters:- name: X-Spree-Seller-Idin: header@@ -15654,11 +15304,66 @@ paths:type: stringresponses:'200':- description: fulfillments listed+ description: notes updatedcontent:application/json:example:- data:+ id: or_UkLWZg9DAJ+ number: R1001+ customer_note:+ currency: USD+ total_quantity: 1+ status: placed+ fulfillment_status:+ payment_status:+ completed_at: '2026-01-15T12:00:00.000Z'+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ internal_note: Packed with the fragile insert.+ internal_note_html: "<p>Packed with the fragile insert.</p>"+ item_total: '10.0'+ display_item_total: "$10.00"+ delivery_total: '100.0'+ display_delivery_total: "$100.00"+ discount_total: '0.0'+ display_discount_total: "$0.00"+ adjustment_total: '0.0'+ display_adjustment_total: "$0.00"+ included_tax_total: '0.0'+ display_included_tax_total: "$0.00"+ additional_tax_total: '0.0'+ display_additional_tax_total: "$0.00"+ tax_total: '0.0'+ display_tax_total: "$0.00"+ total: '110.0'+ display_total: "$110.00"+ payment_total: '0.0'+ display_payment_total: "$0.00"+ amount_due: '110.0'+ display_amount_due: "$110.00"+ commission_amount_total: '0.0'+ display_commission_amount_total: "$0.00"+ commission_tax_total: '0.0'+ display_commission_tax_total: "$0.00"+ commission_total: '0.0'+ display_commission_total: "$0.00"+ canceled_at:+ cancel_reason_name:+ cancel_note:+ items:+ - id: li_UkLWZg9DAJ+ name: Product 1995749+ options_text: ''+ quantity: 1+ currency: USD+ price: '10.0'+ display_price: "$10.00"+ total: '10.0'+ display_total: "$10.00"+ variant_id: variant_UkLWZg9DAJ+ sku: SKU-265+ thumbnail_url:+ fulfillments:- id: ful_UkLWZg9DAJnumber: R1001-F1status: unfulfilled@@ -15669,21 +15374,21 @@ paths:created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'fulfillment_type: shipping- delivery_method_name: UPS Ground 81- stock_location_name: Vernie Lehner+ delivery_method_name: UPS Ground 94+ stock_location_name: Ophelia Hartmannstock_location_id: sloc_UkLWZg9DAJfulfillment_items:- id: fi_UkLWZg9DAJquantity: 1line_item_id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJ- name: Product 1869315- sku: SKU-252+ name: Product 1995749+ sku: SKU-265options_text: ''selected_delivery_rate_id: dr_gbHJdmfrXBdelivery_rates:- id: dr_gbHJdmfrXB- name: UPS Ground 81+ name: UPS Ground 94selected: truecost: '10.0'total: '10.0'@@ -15706,14 +15411,218 @@ paths:updated_at: '2026-01-15T12:00:00.000Z'shipping_label_id:labels: []+ shipping_address:+ id: addr_gbHJdmfrXB+ label:+ first_name: John+ last_name: Doe+ full_name: John Doe+ address1: 183 Lovely Street+ address2: Northwest+ postal_code: '10118'+ city: New York+ phone: 555-555-0199+ company: Company+ country_name: United States+ country_code: US+ state_text: NY+ state_code: NY+ quick_checkout: false+ is_default_billing: false+ is_default_shipping: false+ state_abbr: NY+ country_iso: US+ state_name: New York+ billing_address:+ id: addr_UkLWZg9DAJ+ label:+ first_name: John+ last_name: Doe+ full_name: John Doe+ address1: 182 Lovely Street+ address2: Northwest+ postal_code: '10118'+ city: New York+ phone: 555-555-0199+ company: Company+ country_name: United States+ country_code: US+ state_text: NY+ state_code: NY+ quick_checkout: false+ is_default_billing: false+ is_default_shipping: false+ state_abbr: NY+ country_iso: US+ state_name: New York+ schema:+ "$ref": "#/components/schemas/Order"+ '422':+ description: neither note named+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: customer_note or internal_note is required+ details:+ base:+ - customer_note or internal_note is required+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ customer_note:+ type: string+ nullable: true+ description: What the buyer asked for+ internal_note:+ type: string+ nullable: true+ description: The seller's own working note, as HTML+ required: true+ "/api/v3/seller/order_cancellation_reasons":+ get:+ summary: List order cancellation reasons+ tags:+ - Orders+ security:+ - bearer_auth: []+ description: |+ Why an order was called off, as the marketplace defines it.++ Read-only: a seller picks one when cancelling, and the operator decides+ what the list holds. Retired reasons are left out.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: reasons listed+ content:+ application/json:+ example:+ data:+ - id: ocr_UkLWZg9DAJ+ name: Out of stock+ active: true+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Reason"+ required:+ - data+ "/api/v3/seller/package_types":+ get:+ summary: List package types+ tags:+ - Package Types+ security:+ - bearer_auth: []+ description: |+ What this seller packs their goods into: the boxes their parcels ship+ in, the cartons their products are packed into, the pallets a+ wholesale order leaves on.++ The list carries the marketplace's own packaging alongside the+ seller's, so a seller can pack into the operator's standard cartons+ rather than measuring them again. Those rows report `editable: false`+ and are refused by every write.++ The row marked `default` is the box this seller's parcels are quoted+ with — its size and weight are added to every rate.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ - name: owner+ in: query+ required: false+ schema:+ type: string+ enum:+ - mine+ description: Narrows the list to the seller's own packaging, leaving out the+ marketplace's shared rows+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Records per page (max 100)+ schema:+ type: integer+ responses:+ '200':+ description: package types listed+ content:+ application/json:+ example:+ data:+ - id: pkgtype_UkLWZg9DAJ+ name: Standard mailer+ kind: box+ length: '30.0'+ width: '20.0'+ height: '15.0'+ weight: '0.4'+ max_weight:+ default: true+ metadata: {}+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ dimensions_unit: cm+ weight_unit: kg+ volume: '0.009'+ editable: true+ - id: pkgtype_gbHJdmfrXB+ name: Marketplace carton+ kind: carton+ length: '40.0'+ width: '30.0'+ height: '25.0'+ weight:+ max_weight: '20.0'+ default: false+ metadata: {}+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ dimensions_unit: cm+ weight_unit: kg+ volume: '0.03'+ editable: falsemeta:page: 1limit: 25- count: 1+ count: 2pages: 1from: 1- to: 1- in: 1+ to: 2+ in: 2previous:next:schema:@@ -15722,38 +15631,23 @@ paths:data:type: arrayitems:- "$ref": "#/components/schemas/Fulfillment"+ "$ref": "#/components/schemas/PackageType"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"required:- data- "/api/v3/seller/orders/{order_id}/fulfillments/{id}/fulfill":- parameters:- - name: order_id- in: path- description: Prefixed order ID- required: true- schema:- type: string- - name: id- in: path- description: Prefixed fulfillment ID- required: true- schema:- type: string- patch:- summary: Fulfill (ship) a parcel+ - meta+ post:+ summary: Create a package typetags:- - Fulfillments+ - Package Typessecurity:- bearer_auth: []description: |- Marks the parcel shipped.-- This is the same workflow the marketplace operator runs, so the- customer's dispatch email, the label purchase and any extension hooks- happen exactly as they would had the operator shipped it.-- `items` narrows the dispatch to part of what the fulfillment holds; the- remainder splits onto a new one. Omit it to ship the lot.+ Records a piece of the seller's own packaging. Marking it `default`+ makes it the box their parcels are quoted with, and demotes whichever+ of their rows held the flag before — the marketplace's default is a+ different owner's row and is left alone.parameters:- name: X-Spree-Seller-Idin: header@@ -15761,207 +15655,106 @@ paths:schema:type: stringresponses:- '200':- description: parcel shipped+ '201':+ description: package type createdcontent:application/json:example:- id: ful_UkLWZg9DAJ- number: R1001-F1- status: fulfilled- tracking: TRACK-1- tracking_url:- fulfilled_at: '2026-01-15T12:00:00.000Z'- delivered_at:+ id: pkgtype_EfhxLZ9ck8+ name: Large mailer+ kind: box+ length: '40.0'+ width: '30.0'+ height: '20.0'+ weight: '0.6'+ max_weight:+ default: false+ metadata: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'- fulfillment_type: shipping- delivery_method_name: UPS Ground 82- stock_location_name: Mirta Herman- stock_location_id: sloc_UkLWZg9DAJ- fulfillment_items:- - id: fi_UkLWZg9DAJ- quantity: 1- line_item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- name: Product 187961- sku: SKU-253- options_text: ''- selected_delivery_rate_id: dr_gbHJdmfrXB- delivery_rates:- - id: dr_gbHJdmfrXB- name: UPS Ground 82- selected: true- cost: '10.0'- total: '10.0'- carrier:- service_level:- estimated_delivery_date:- display_cost: "$10.00"- display_total: "$10.00"- deliveries:- - id: dlv_UkLWZg9DAJ- tracking_number: TRACK-1- carrier:- carrier_name:- service:- status: pending- tracking_url:- estimated_delivery_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- shipping_label_id:- labels: []+ dimensions_unit: cm+ weight_unit: kg+ volume: '0.024'+ editable: trueschema:- "$ref": "#/components/schemas/Fulfillment"- requestBody:- content:- application/json:- schema:- type: object- properties:- tracking:- type: string- description: Carrier tracking number- tracking_carrier:- type: string- description: Carrier name- notify_customer:- type: boolean- description: Send the dispatch email (default true)- items:- type: array- description: Ship only these lines; the rest split onto a new fulfillment- items:- type: object- properties:- item_id:- type: string- description: Prefixed line item ID- quantity:- type: integer- required:- - item_id- - quantity- "/api/v3/seller/orders/{order_id}/fulfillments/{id}":- parameters:- - name: order_id- in: path- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: string- patch:- summary: Update tracking- tags:- - Fulfillments- security:- - bearer_auth: []- description: |- Adds or corrects the tracking number and its carrier.-- Deliberately narrow: where a parcel ships from and which service- carries it are the marketplace's arrangements, so they are not- editable here.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: tracking recorded+ "$ref": "#/components/schemas/PackageType"+ '422':+ description: validation errorcontent:application/json:example:- id: ful_UkLWZg9DAJ- number: R1001-F1- status: unfulfilled- tracking: TRACK-2- tracking_url: https://www.ups.com/track?tracknum=TRACK-2- fulfilled_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- fulfillment_type: shipping- delivery_method_name: UPS Ground 83- stock_location_name: Eugena Schultz- stock_location_id: sloc_UkLWZg9DAJ- fulfillment_items:- - id: fi_UkLWZg9DAJ- quantity: 1- line_item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- name: Product 1883170- sku: SKU-254- options_text: ''- selected_delivery_rate_id: dr_gbHJdmfrXB- delivery_rates:- - id: dr_gbHJdmfrXB- name: UPS Ground 83- selected: true- cost: '10.0'- total: '10.0'- carrier:- service_level:- estimated_delivery_date:- display_cost: "$10.00"- display_total: "$10.00"- deliveries:- - id: dlv_UkLWZg9DAJ- tracking_number: TRACK-2- carrier: ups- carrier_name: UPS- service:- status: pending- tracking_url: https://www.ups.com/track?tracknum=TRACK-2- estimated_delivery_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- shipping_label_id:- labels: []+ error:+ code: validation_error+ message: Kind is not included in the list+ details:+ kind:+ - is not included in the listschema:- "$ref": "#/components/schemas/Fulfillment"+ "$ref": "#/components/schemas/ErrorResponse"requestBody:content:application/json:schema:type: objectproperties:- tracking:+ name:+ type: string+ kind:type: string+ enum:+ - box+ - envelope+ - carton+ - pallet+ - container+ length:+ type: numbernullable: true- tracking_carrier:+ width:+ type: number+ nullable: true+ height:+ type: number+ nullable: true+ dimensions_unit:type: stringnullable: true- "/api/v3/seller/orders/{order_id}/fulfillments/{id}/cancel":+ weight:+ type: number+ nullable: true+ description: The empty package's own weight, added to every quote+ max_weight:+ type: number+ nullable: true+ weight_unit:+ type: string+ nullable: true+ default:+ type: boolean+ metadata:+ type: object+ nullable: true+ required:+ - name+ - kind+ required: true+ "/api/v3/seller/package_types/{id}":parameters:- - name: order_id- in: path- required: true- schema:- type: string- name: idin: pathrequired: true+ description: Package type IDschema:type: string- patch:- summary: Cancel a parcel+ get:+ summary: Get a package typetags:- - Fulfillments+ - Package Typessecurity:- bearer_auth: []description: |- A parcel this seller is not going to send after all. The goods go back- on the shelf and the carrier is stood down.+ Returns one package type by prefixed ID — the seller's own, or a+ marketplace row they may pack into.parameters:- name: X-Spree-Seller-Idin: header@@ -15970,69 +15763,47 @@ paths:type: stringresponses:'200':- description: parcel canceled+ description: package type foundcontent:application/json:example:- id: ful_UkLWZg9DAJ- number: R1001-F1- status: canceled- tracking: U10000- tracking_url:- fulfilled_at:- delivered_at:+ id: pkgtype_UkLWZg9DAJ+ name: Standard mailer+ kind: box+ length: '30.0'+ width: '20.0'+ height: '15.0'+ weight: '0.4'+ max_weight:+ default: true+ metadata: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'- fulfillment_type: shipping- delivery_method_name: UPS Ground 84- stock_location_name: Karyn Moore- stock_location_id: sloc_UkLWZg9DAJ- fulfillment_items:- - id: fi_UkLWZg9DAJ- quantity: 1- line_item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- name: Product 1897276- sku: SKU-255- options_text: ''- selected_delivery_rate_id: dr_gbHJdmfrXB- delivery_rates:- - id: dr_gbHJdmfrXB- name: UPS Ground 84- selected: true- cost: '10.0'- total: '10.0'- carrier:- service_level:- estimated_delivery_date:- display_cost: "$10.00"- display_total: "$10.00"- deliveries:- - id: dlv_UkLWZg9DAJ- tracking_number: U10000- carrier:- carrier_name:- service:- status: pending- tracking_url:- estimated_delivery_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- shipping_label_id:- labels: []+ dimensions_unit: cm+ weight_unit: kg+ volume: '0.009'+ editable: trueschema:- "$ref": "#/components/schemas/Fulfillment"- "/api/v3/seller/tracking_carriers":- get:- summary: List tracking carriers+ "$ref": "#/components/schemas/PackageType"+ '404':+ description: package type not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Package type not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update a package typetags:- - Fulfillments+ - Package Typessecurity:- bearer_auth: []description: |- The carriers a tracking number can be pinned to, from the registry —- so a carrier an extension adds appears without a client change.+ Changes the seller's own packaging. A marketplace row is not theirs to+ edit and answers 404.parameters:- name: X-Spree-Seller-Idin: header@@ -16041,494 +15812,306 @@ paths:type: stringresponses:'200':- description: carriers listed+ description: package type updatedcontent:application/json:example:- data:- - id: australia_post- name: Australia Post- - id: canada_post- name: Canada Post- - id: chronopost- name: Chronopost- - id: colissimo- name: Colissimo- - id: dhl- name: DHL Express- - id: dpd- name: DPD- - id: deutsche_post- name: Deutsche Post DHL- - id: evri- name: Evri- - id: fedex- name: FedEx- - id: gls- name: GLS- - id: inpost- name: InPost- - id: poczta_polska- name: Poczta Polska- - id: postnl- name: PostNL- - id: royal_mail- name: Royal Mail- - id: ups- name: UPS- - id: usps- name: USPS+ id: pkgtype_UkLWZg9DAJ+ name: Standard mailer+ kind: box+ length: '30.0'+ width: '20.0'+ height: '15.0'+ weight: '0.4'+ max_weight: '25.0'+ default: true+ metadata: {}+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ dimensions_unit: cm+ weight_unit: kg+ volume: '0.009'+ editable: trueschema:- type: object- properties:- data:- type: array- items:- type: object- properties:- id:- type: string- name:- type: string- required:- - id- - name- required:- - data- "/api/v3/seller/orders":- get:- summary: List orders+ "$ref": "#/components/schemas/PackageType"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ kind:+ type: string+ enum:+ - box+ - envelope+ - carton+ - pallet+ - container+ length:+ type: number+ nullable: true+ width:+ type: number+ nullable: true+ height:+ type: number+ nullable: true+ dimensions_unit:+ type: string+ nullable: true+ weight:+ type: number+ nullable: true+ max_weight:+ type: number+ nullable: true+ weight_unit:+ type: string+ nullable: true+ default:+ type: boolean+ metadata:+ type: object+ nullable: true+ required: true+ delete:+ summary: Delete a package typetags:- - Orders+ - Package Typessecurity:- bearer_auth: []description: |- What this seller has sold.-- On a marketplace a basket spanning several sellers is split into one- order each, so these are the seller's own orders rather than a filtered- view of somebody else's — another seller's order is never reachable,- whatever id is sent.-- Checkouts still in flight are left out: until one completes it is- nobody's order.+ Retires one of the seller's own package types. The default box is+ refused — name another default first, or every parcel silently falls+ back to the marketplace's box.parameters:- name: X-Spree-Seller-Idin: headerrequired: trueschema:type: string- - name: page- in: query- required: false- description: Page number- schema:- type: integer- - name: limit- in: query- required: false- description: Records per page (max 100)- schema:- type: integer- - name: sort- in: query- required: false- description: Sort field; prefix with `-` for descending- schema:- type: stringresponses:- '200':- description: orders listed+ '204':+ description: package type deleted+ "/api/v3/seller/auth/password_resets":+ post:+ summary: Request password reset+ tags:+ - Authentication+ description: |+ Requests a password reset email for a seller.++ Unauthenticated. Always answers `202`, whether or not the address+ belongs to a seller, so this cannot be used to discover which accounts+ exist. A store staff member who runs no seller is treated as no match:+ they have no seller panel to be sent to.++ `redirect_url` is where the emailed link should point, with the reset+ token appended as a `token` query param. It is honoured only when it+ matches one of the store's allowed origins; otherwise it is silently+ ignored and the server resolves the seller panel origin itself. The+ email is delivered by Spree via the+ `seller_user.password_reset_requested` event, which is never forwarded+ to webhook endpoints.+ parameters: []+ responses:+ '202':+ description: reset requestedcontent:application/json:example:- data:- - id: or_UkLWZg9DAJ- number: R1001- customer_note:- currency: USD- total_quantity: 1- status: placed- fulfillment_status:- payment_status:- completed_at: '2026-01-15T12:00:00.000Z'- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- internal_note:- internal_note_html:- item_total: '10.0'- display_item_total: "$10.00"- delivery_total: '100.0'- display_delivery_total: "$100.00"- discount_total: '0.0'- display_discount_total: "$0.00"- adjustment_total: '0.0'- display_adjustment_total: "$0.00"- included_tax_total: '0.0'- display_included_tax_total: "$0.00"- additional_tax_total: '0.0'- display_additional_tax_total: "$0.00"- tax_total: '0.0'- display_tax_total: "$0.00"- total: '110.0'- display_total: "$110.00"- payment_total: '0.0'- display_payment_total: "$0.00"- amount_due: '110.0'- display_amount_due: "$110.00"- commission_amount_total: '0.0'- display_commission_amount_total: "$0.00"- commission_tax_total: '0.0'- display_commission_tax_total: "$0.00"- commission_total: '0.0'- display_commission_total: "$0.00"- canceled_at:- cancel_reason_name:- cancel_note:- items:- - id: li_UkLWZg9DAJ- name: Product 19195- options_text: ''- quantity: 1- currency: USD- price: '10.0'- display_price: "$10.00"- total: '10.0'- display_total: "$10.00"- variant_id: variant_UkLWZg9DAJ- sku: SKU-257- thumbnail_url:- fulfillments:- - id: ful_UkLWZg9DAJ- number: R1001-F1- status: unfulfilled- tracking: U10000- tracking_url:- fulfilled_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- fulfillment_type: shipping- delivery_method_name: UPS Ground 86- stock_location_name: Roseline Roberts- stock_location_id: sloc_UkLWZg9DAJ- fulfillment_items:- - id: fi_UkLWZg9DAJ- quantity: 1- line_item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- name: Product 19195- sku: SKU-257- options_text: ''- selected_delivery_rate_id: dr_gbHJdmfrXB- delivery_rates:- - id: dr_gbHJdmfrXB- name: UPS Ground 86- selected: true- cost: '10.0'- total: '10.0'- carrier:- service_level:- estimated_delivery_date:- display_cost: "$10.00"- display_total: "$10.00"- deliveries:- - id: dlv_UkLWZg9DAJ- tracking_number: U10000- carrier:- carrier_name:- service:- status: pending- tracking_url:- estimated_delivery_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- shipping_label_id:- labels: []- shipping_address:- id: addr_gbHJdmfrXB- label:- first_name: John- last_name: Doe- full_name: John Doe- address1: 167 Lovely Street- address2: Northwest- postal_code: '10118'- city: New York- phone: 555-555-0199- company: Company- country_name: United States- country_code: US- state_text: NY- state_code: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_abbr: NY- country_iso: US- state_name: New York- billing_address:- id: addr_UkLWZg9DAJ- label:- first_name: John- last_name: Doe- full_name: John Doe- address1: 166 Lovely Street- address2: Northwest- postal_code: '10118'- city: New York- phone: 555-555-0199- company: Company- country_name: United States- country_code: US- state_text: NY- state_code: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_abbr: NY- country_iso: US- state_name: New York- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Order"- meta:- "$ref": "#/components/schemas/PaginationMeta"- required:- - data- - meta- "/api/v3/seller/orders/{id}":- parameters:- - name: id- in: path- description: Prefixed order ID- required: true- schema:- type: string- get:- summary: Get an order+ message: If an account exists for that email, password reset instructions+ have been sent.+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ email:+ type: string+ format: email+ example: [email protected]+ redirect_url:+ type: string+ example: https://sellers.your-store.com/reset-password+ description: Must match an allowed origin of the store; ignored+ otherwise.+ required:+ "/api/v3/seller/auth/password_resets/{id}":+ patch:+ summary: Reset passwordtags:- - Orders- security:- - bearer_auth: []+ - Authenticationdescription: |- One order, as the seller needs it to pack and post the parcel: the- lines with their SKUs, where it ships to, and a fulfillment per parcel.+ Spends a password reset token (the `token` query param from the emailed+ link), sets the new password and signs the seller in: the response+ carries a seller JWT and the rotatable refresh token is set in an+ HttpOnly cookie, so they land in the panel rather than on a login form.- How the customer paid the marketplace is deliberately absent — that is- between the buyer and the operator.+ The token is single-use, and resetting revokes every other session the+ account holds. A token whose seller membership has since been revoked is+ refused exactly as an expired one.parameters:- - name: X-Spree-Seller-Id- in: header+ - name: id+ in: path+ description: The reset token from the emailed linkrequired: trueschema:type: stringresponses:'200':- description: order found+ description: password resetcontent:application/json:example:- id: or_UkLWZg9DAJ- number: R1001- customer_note:- currency: USD- total_quantity: 1- status: placed- fulfillment_status:- payment_status:- completed_at: '2026-01-15T12:00:00.000Z'- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- internal_note:- internal_note_html:- item_total: '10.0'- display_item_total: "$10.00"- delivery_total: '100.0'- display_delivery_total: "$100.00"- discount_total: '0.0'- display_discount_total: "$0.00"- adjustment_total: '0.0'- display_adjustment_total: "$0.00"- included_tax_total: '0.0'- display_included_tax_total: "$0.00"- additional_tax_total: '0.0'- display_additional_tax_total: "$0.00"- tax_total: '0.0'- display_tax_total: "$0.00"- total: '110.0'- display_total: "$110.00"- payment_total: '0.0'- display_payment_total: "$0.00"- amount_due: '110.0'- display_amount_due: "$110.00"- commission_amount_total: '0.0'- display_commission_amount_total: "$0.00"- commission_tax_total: '0.0'- display_commission_tax_total: "$0.00"- commission_total: '0.0'- display_commission_total: "$0.00"- canceled_at:- cancel_reason_name:- cancel_note:- items:- - id: li_UkLWZg9DAJ- name: Product 1929755- options_text: ''- quantity: 1- currency: USD- price: '10.0'- display_price: "$10.00"- total: '10.0'- display_total: "$10.00"- variant_id: variant_UkLWZg9DAJ- sku: SKU-258- thumbnail_url:- fulfillments:- - id: ful_UkLWZg9DAJ- number: R1001-F1- status: unfulfilled- tracking: U10000- tracking_url:- fulfilled_at:- delivered_at:+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImJjMDM3NTNhLTEzN2MtNGM1Zi1hMzM2LWUzMjBlZTNiMjQ5YyIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.EASrzbGpJVyAl10SJyzs8na68Wmvedkm7G66wTBq_0k+ user:+ id: adm_UkLWZg9DAJ+ email: [email protected]+ first_name: Ariana+ last_name: Wiza+ full_name: Ariana Wizacreated_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- fulfillment_type: shipping- delivery_method_name: UPS Ground 87- stock_location_name: Woodrow Hand- stock_location_id: sloc_UkLWZg9DAJ- fulfillment_items:- - id: fi_UkLWZg9DAJ- quantity: 1- line_item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- name: Product 1929755- sku: SKU-258- options_text: ''- selected_delivery_rate_id: dr_gbHJdmfrXB- delivery_rates:- - id: dr_gbHJdmfrXB- name: UPS Ground 87- selected: true- cost: '10.0'- total: '10.0'- carrier:- service_level:- estimated_delivery_date:- display_cost: "$10.00"- display_total: "$10.00"- deliveries:- - id: dlv_UkLWZg9DAJ- tracking_number: U10000- carrier:- carrier_name:- service:- status: pending- tracking_url:- estimated_delivery_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- shipping_label_id:- labels: []- shipping_address:- id: addr_gbHJdmfrXB- label:- first_name: John- last_name: Doe- full_name: John Doe- address1: 169 Lovely Street- address2: Northwest- postal_code: '10118'- city: New York- phone: 555-555-0199- company: Company- country_name: United States- country_code: US- state_text: NY- state_code: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_abbr: NY- country_iso: US- state_name: New York- billing_address:- id: addr_UkLWZg9DAJ- label:- first_name: John- last_name: Doe- full_name: John Doe- address1: 168 Lovely Street- address2: Northwest- postal_code: '10118'- city: New York- phone: 555-555-0199- company: Company- country_name: United States- country_code: US- state_text: NY- state_code: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_abbr: NY- country_iso: US- state_name: New York+ avatar_url:+ selected_locale:+ sellers:+ - id: sel_UkLWZg9DAJ+ name: Seller 80+ status: approvedschema:- "$ref": "#/components/schemas/Order"- '404':- description: another seller's order+ "$ref": "#/components/schemas/AuthResponse"+ '422':+ description: invalid or expired token+ content:+ application/json:+ example:+ error:+ code: password_reset_token_invalid+ message: Password reset token is invalid or has expired.+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ password:+ type: string+ example: new-password-123+ password_confirmation:+ type: string+ example: new-password-123+ required:+ - password+ - password_confirmation+ "/api/v3/seller/payouts":+ get:+ summary: List payouts+ tags:+ - Earnings+ security:+ - bearer_auth: []+ description: |+ Settlements to this seller: each one batches the transfers that had+ accumulated since the last, on the seller's payout schedule. `pending`+ and `processing` rows are owed; `completed` ones reached the seller's+ bank. `transfers_count` says how many earnings a settlement covers —+ list them with `GET /api/v3/seller/transfers?q[payout_id_eq]=…`.++ Read-only: a payout is created by the marketplace's sweep and+ confirmed by the payout provider or the operator.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Records per page (max 100)+ schema:+ type: integer+ - name: q[status_eq]+ in: query+ required: false+ schema:+ type: string+ enum:+ - pending+ - processing+ - completed+ - failed+ - unresolved+ responses:+ '200':+ description: payouts listedcontent:application/json:example:- error:- code: order_not_found- message: Order not found+ data:+ - id: vpo_UkLWZg9DAJ+ status: pending+ currency: USD+ provider: Spree::PayoutProvider::System+ reference:+ period_start:+ period_end:+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ amount: '120.0'+ display_amount: "$120.00"+ transfers_count: 1+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:schema:- "$ref": "#/components/schemas/ErrorResponse"- "/api/v3/seller/orders/{id}/cancel":+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Payout"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ "/api/v3/seller/payouts/{id}":parameters:- name: idin: path- description: Prefixed order IDrequired: true+ description: Payout prefixed IDschema:type: string- patch:- summary: Cancel an order+ get:+ summary: Get a payouttags:- - Orders+ - Earningssecurity:- bearer_auth: []- description: |- Withdraws from an order this seller cannot fulfil, naming a reason from- the marketplace's own list.-- The goods go back on the shelf and the payment authorization is- released either way. `refund_payments` also hands back what the buyer- paid for these goods — a seller is merchant of record for their own- child order, and on a split checkout only that order's share of the- group's payment is settled.-- There is no `refund_amount`: withdrawing from the whole order returns- what that order was paid, and a partial figure is a return.+ description: One of this seller's settlements. Another seller's is not found,+ whatever id is sent.parameters:- name: X-Spree-Seller-Idin: header@@ -16537,642 +16120,482 @@ paths:type: stringresponses:'200':- description: order canceled+ description: payout foundcontent:application/json:example:- id: or_UkLWZg9DAJ- number: R1001- customer_note:+ id: vpo_UkLWZg9DAJ+ status: pendingcurrency: USD- total_quantity: 1- status: canceled- fulfillment_status: canceled- payment_status: none- completed_at: '2026-01-15T12:00:00.000Z'+ provider: Spree::PayoutProvider::System+ reference:+ period_start:+ period_end:created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'- internal_note:- internal_note_html:- item_total: '10.0'- display_item_total: "$10.00"- delivery_total: '100.0'- display_delivery_total: "$100.00"- discount_total: '0.0'- display_discount_total: "$0.00"- adjustment_total: '0.0'- display_adjustment_total: "$0.00"- included_tax_total: '0.0'- display_included_tax_total: "$0.00"- additional_tax_total: '0.0'- display_additional_tax_total: "$0.00"- tax_total: '0.0'- display_tax_total: "$0.00"- total: '110.0'- display_total: "$110.00"- payment_total: '0.0'- display_payment_total: "$0.00"- amount_due: "-0.0"- display_amount_due: "$0.00"- commission_amount_total: '0.0'- display_commission_amount_total: "$0.00"- commission_tax_total: '0.0'- display_commission_tax_total: "$0.00"- commission_total: '0.0'- display_commission_total: "$0.00"- canceled_at: '2026-01-15T12:00:00Z'- cancel_reason_name:- cancel_note:- items:- - id: li_UkLWZg9DAJ- name: Product 1956554- options_text: ''- quantity: 1- currency: USD- price: '10.0'- display_price: "$10.00"- total: '10.0'- display_total: "$10.00"- variant_id: variant_UkLWZg9DAJ- sku: SKU-261- thumbnail_url:- fulfillments:- - id: ful_UkLWZg9DAJ- number: R1001-F1- status: canceled- tracking: U10000- tracking_url:- fulfilled_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- fulfillment_type: shipping- delivery_method_name: UPS Ground 90- stock_location_name: Ricky Kutch- stock_location_id: sloc_UkLWZg9DAJ- fulfillment_items:- - id: fi_UkLWZg9DAJ- quantity: 1- line_item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- name: Product 1956554- sku: SKU-261- options_text: ''- selected_delivery_rate_id: dr_gbHJdmfrXB- delivery_rates:- - id: dr_gbHJdmfrXB- name: UPS Ground 90- selected: true- cost: '10.0'- total: '10.0'- carrier:- service_level:- estimated_delivery_date:- display_cost: "$10.00"- display_total: "$10.00"- deliveries:- - id: dlv_UkLWZg9DAJ- tracking_number: U10000- carrier:- carrier_name:- service:- status: pending- tracking_url:- estimated_delivery_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- shipping_label_id:- labels: []- shipping_address:- id: addr_gbHJdmfrXB- label:- first_name: John- last_name: Doe- full_name: John Doe- address1: 175 Lovely Street- address2: Northwest- postal_code: '10118'- city: New York- phone: 555-555-0199- company: Company- country_name: United States- country_code: US- state_text: NY- state_code: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_abbr: NY- country_iso: US- state_name: New York- billing_address:- id: addr_UkLWZg9DAJ- label:- first_name: John- last_name: Doe- full_name: John Doe- address1: 174 Lovely Street- address2: Northwest- postal_code: '10118'- city: New York- phone: 555-555-0199- company: Company- country_name: United States- country_code: US- state_text: NY- state_code: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_abbr: NY- country_iso: US- state_name: New York+ amount: '120.0'+ display_amount: "$120.00"+ transfers_count: 1schema:- "$ref": "#/components/schemas/Order"- requestBody:- content:- application/json:- schema:- type: object- properties:- cancel_reason_id:- type: string- nullable: true- description: A reason from GET /order_cancellation_reasons- cancel_note:- type: string- nullable: true- description: Free text beside the reason- refund_payments:- type: boolean- description: Hand back what the buyer paid for this order's goods- notify_customer:- type: boolean- description: Email the customer about the cancellation- "/api/v3/seller/orders/{id}/address":- parameters:- - name: id- in: path- description: Prefixed order ID- required: true- schema:- type: string- patch:- summary: Correct an order address+ "$ref": "#/components/schemas/Payout"+ '404':+ description: payout not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Seller payout not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/seller/policies":+ get:+ summary: List policiestags:- - Orders+ - Policiessecurity:- bearer_auth: []description: |- Corrects where the goods go or who the invoice names.-- The seller is merchant of record for their own child order, so a- delivery address the buyer got wrong is theirs to fix. Send only the- lines that change — the rest of the address is carried over.+ This seller's own policy documents.- This is the only write against the order itself besides cancelling:- nothing else about it, its totals included, is the seller's to change.+ Rooted in the acting seller, so the marketplace operator's store+ policies and every other seller's are invisible here. A seller starts+ with none: what they are expected to publish is decided by the+ marketplace's onboarding checklist.parameters:- name: X-Spree-Seller-Idin: headerrequired: trueschema:type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Records per page (max 100)+ schema:+ type: integerresponses:'200':- description: address corrected+ description: policies listedcontent:application/json:example:- id: or_UkLWZg9DAJ- number: R1001- customer_note:- currency: USD- total_quantity: 1- status: placed- fulfillment_status:- payment_status:- completed_at: '2026-01-15T12:00:00.000Z'- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- internal_note:- internal_note_html:- item_total: '10.0'- display_item_total: "$10.00"- delivery_total: '100.0'- display_delivery_total: "$100.00"- discount_total: '0.0'- display_discount_total: "$0.00"- adjustment_total: '0.0'- display_adjustment_total: "$0.00"- included_tax_total: '0.0'- display_included_tax_total: "$0.00"- additional_tax_total: '0.0'- display_additional_tax_total: "$0.00"- tax_total: '0.0'- display_tax_total: "$0.00"- total: '110.0'- display_total: "$110.00"- payment_total: '0.0'- display_payment_total: "$0.00"- amount_due: '110.0'- display_amount_due: "$110.00"- commission_amount_total: '0.0'- display_commission_amount_total: "$0.00"- commission_tax_total: '0.0'- display_commission_tax_total: "$0.00"- commission_total: '0.0'- display_commission_total: "$0.00"- canceled_at:- cancel_reason_name:- cancel_note:- items:- - id: li_UkLWZg9DAJ- name: Product 1965038- options_text: ''- quantity: 1- currency: USD- price: '10.0'- display_price: "$10.00"- total: '10.0'- display_total: "$10.00"- variant_id: variant_UkLWZg9DAJ- sku: SKU-262- thumbnail_url:- fulfillments:- - id: ful_UkLWZg9DAJ- number: R1001-F1- status: unfulfilled- tracking: U10000- tracking_url:- fulfilled_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'+ data:+ - id: pol_uw2YK1rnl0+ name: Returns Policy+ slug: returns-policy+ body: Send anything back within 30 days.+ body_html: "<p>Send anything back within 30 days.</p>"updated_at: '2026-01-15T12:00:00.000Z'- fulfillment_type: shipping- delivery_method_name: UPS Ground 91- stock_location_name: Rudy Mosciski- stock_location_id: sloc_UkLWZg9DAJ- fulfillment_items:- - id: fi_UkLWZg9DAJ- quantity: 1- line_item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- name: Product 1965038- sku: SKU-262- options_text: ''- selected_delivery_rate_id: dr_gbHJdmfrXB- delivery_rates:- - id: dr_gbHJdmfrXB- name: UPS Ground 91- selected: true- cost: '10.0'- total: '10.0'- carrier:- service_level:- estimated_delivery_date:- display_cost: "$10.00"- display_total: "$10.00"- deliveries:- - id: dlv_UkLWZg9DAJ- tracking_number: U10000- carrier:- carrier_name:- service:- status: pending- tracking_url:- estimated_delivery_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- shipping_label_id:- labels: []- shipping_address:- id: addr_EfhxLZ9ck8- label:- first_name: John- last_name: Doe- full_name: John Doe- address1: 9 Corrected Way- address2: Northwest- postal_code: '10118'- city: Fixedton- phone: 555-555-0199- company: Company- country_name: United States- country_code: US- state_text: NY- state_code: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: true- state_abbr: NY- country_iso: US- state_name: New York- billing_address:- id: addr_UkLWZg9DAJ- label:- first_name: John- last_name: Doe- full_name: John Doe- address1: 176 Lovely Street- address2: Northwest- postal_code: '10118'- city: New York- phone: 555-555-0199- company: Company- country_name: United States- country_code: US- state_text: NY- state_code: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_abbr: NY- country_iso: US- state_name: New York+ created_at: '2026-01-15T12:00:00.000Z'+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Policy"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ post:+ summary: Create a policy+ tags:+ - Policies+ security:+ - bearer_auth: []+ description: |+ Publishes one of this seller's policies. `body` accepts HTML and is+ sanitized before it is stored.++ When the marketplace requires a named policy, use that exact name —+ the onboarding check matches on it.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '201':+ description: policy created+ content:+ application/json:+ example:+ id: pol_OIJLhNcSbf+ name: Shipping Policy+ slug: shipping-policy+ body: Orders leave the workshop within two working days.+ body_html: "<p>Orders leave the workshop within two working days.</p>"+ updated_at: '2026-01-15T12:00:00.000Z'+ created_at: '2026-01-15T12:00:00.000Z'+ schema:+ "$ref": "#/components/schemas/Policy"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ example: Shipping Policy+ slug:+ type: string+ example: shipping-policy+ body:+ type: string+ example: "<p>Orders leave the workshop within two working days.</p>"+ required:+ - name+ "/api/v3/seller/policies/{id}":+ parameters:+ - name: id+ in: path+ required: true+ description: Policy prefixed ID or slug+ schema:+ type: string+ get:+ summary: Get a policy+ tags:+ - Policies+ security:+ - bearer_auth: []+ description: Returns one of this seller's policies, by prefixed ID or slug.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: policy found+ content:+ application/json:+ example:+ id: pol_uw2YK1rnl0+ name: Returns Policy+ slug: returns-policy+ body: Send anything back within 30 days.+ body_html: "<p>Send anything back within 30 days.</p>"+ updated_at: '2026-01-15T12:00:00.000Z'+ created_at: '2026-01-15T12:00:00.000Z'schema:- "$ref": "#/components/schemas/Order"- '422':- description: neither address named+ "$ref": "#/components/schemas/Policy"+ '404':+ description: policy not foundcontent:application/json:example:error:- code: validation_error- message: shipping_address or billing_address is required- details:- base:- - shipping_address or billing_address is required+ code: record_not_found+ message: Policy not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update a policy+ tags:+ - Policies+ security:+ - bearer_auth: []+ description: Rewrites one of this seller's policies.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: policy updated+ content:+ application/json:+ example:+ id: pol_uw2YK1rnl0+ name: Returns Policy+ slug: returns-policy+ body: Send anything back within 60 days.+ body_html: "<p>Send anything back within 60 days.</p>"+ updated_at: '2026-01-15T12:00:00.000Z'+ created_at: '2026-01-15T12:00:00.000Z'+ schema:+ "$ref": "#/components/schemas/Policy"requestBody:content:application/json:schema:type: objectproperties:- shipping_address:- type: object- description: Only the lines that change; the rest is carried over- properties:- first_name:- type: string- last_name:- type: string- company:- type: string- nullable: true- address1:- type: string- address2:- type: string- nullable: true- city:- type: string- postal_code:- type: string- country_code:- type: string- state_code:- type: string- nullable: true- state_name:- type: string- nullable: true- phone:- type: string- nullable: true- label:- type: string- nullable: true- billing_address:- type: object- description: Only the lines that change; the rest is carried over- properties:- first_name:- type: string- last_name:- type: string- company:- type: string- nullable: true- address1:- type: string- address2:- type: string- nullable: true- city:- type: string- postal_code:- type: string- country_code:- type: string- state_code:- type: string- nullable: true- state_name:- type: string- nullable: true- phone:- type: string- nullable: true- label:- type: string- nullable: true+ name:+ type: string+ slug:+ type: string+ body:+ type: string+ delete:+ summary: Delete a policy+ tags:+ - Policies+ security:+ - bearer_auth: []+ description: Withdraws one of this seller's policies.+ parameters:+ - name: X-Spree-Seller-Id+ in: headerrequired: true- "/api/v3/seller/orders/{order_id}/notes":- parameters:- - name: order_id- in: path- description: Prefixed order ID- required: true- schema:- type: string+ schema:+ type: string+ responses:+ '204':+ description: policy deleted+ "/api/v3/seller/product_types":+ get:+ summary: List product types+ tags:+ - Product Types+ security:+ - bearer_auth: []+ description: |+ The product types a seller may list a product against.++ Read only. A type is the template that hands a product its option types+ and its delivery profile, so a seller picks one when listing; defining+ types is the marketplace's. Send the chosen `id` as `product_type_id`+ on the product.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Records per page (max 100)+ schema:+ type: integer+ responses:+ '200':+ description: product types listed+ content:+ application/json:+ example:+ data:+ - id: pt_UkLWZg9DAJ+ name: Apparel+ option_type_labels: []+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/ProductType"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ "/api/v3/seller/product_types/{id}":+ get:+ summary: Get a product type+ tags:+ - Product Types+ security:+ - bearer_auth: []+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Product type ID+ schema:+ type: string+ responses:+ '200':+ description: product type found+ content:+ application/json:+ example:+ id: pt_UkLWZg9DAJ+ name: Apparel+ option_type_labels: []+ schema:+ "$ref": "#/components/schemas/ProductType"+ "/api/v3/seller/products":get:- summary: Get order notes+ summary: List productstags:- - Orders+ - Productssecurity:- bearer_auth: []description: |- The instructions the buyer left, and the seller's own working note.+ The seller's own catalog — the products they own outright.- A marketplace basket splits into one order per seller, so the internal- note here is this seller's alone rather than the operator's note about- the whole sale.+ Every call is rooted in the acting seller server-side, so this can never+ return another seller's product or one the marketplace operator sells+ first-party.parameters:- name: X-Spree-Seller-Idin: headerrequired: trueschema:type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Records per page (max 100)+ schema:+ type: integer+ - name: sort+ in: query+ required: false+ description: Sort field; prefix with `-` for descending+ schema:+ type: stringresponses:'200':- description: notes+ description: products listedcontent:application/json:example:- id: or_UkLWZg9DAJ- number: R1001- customer_note:- currency: USD- total_quantity: 1- status: placed- fulfillment_status:- payment_status:- completed_at: '2026-01-15T12:00:00.000Z'- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- internal_note:- internal_note_html:- item_total: '10.0'- display_item_total: "$10.00"- delivery_total: '100.0'- display_delivery_total: "$100.00"- discount_total: '0.0'- display_discount_total: "$0.00"- adjustment_total: '0.0'- display_adjustment_total: "$0.00"- included_tax_total: '0.0'- display_included_tax_total: "$0.00"- additional_tax_total: '0.0'- display_additional_tax_total: "$0.00"- tax_total: '0.0'- display_tax_total: "$0.00"- total: '110.0'- display_total: "$110.00"- payment_total: '0.0'- display_payment_total: "$0.00"- amount_due: '110.0'- display_amount_due: "$110.00"- commission_amount_total: '0.0'- display_commission_amount_total: "$0.00"- commission_tax_total: '0.0'- display_commission_tax_total: "$0.00"- commission_total: '0.0'- display_commission_total: "$0.00"- canceled_at:- cancel_reason_name:- cancel_note:- items:- - id: li_UkLWZg9DAJ- name: Product 1983962- options_text: ''- quantity: 1- currency: USD- price: '10.0'- display_price: "$10.00"- total: '10.0'- display_total: "$10.00"- variant_id: variant_UkLWZg9DAJ- sku: SKU-264+ data:+ - id: prod_UkLWZg9DAJ+ name: Product 2053250+ slug: product-2053250+ meta_title:+ meta_description:+ meta_keywords:+ variant_count: 1+ available_on:+ preorder_ships_at:+ purchasable: true+ preorder: false+ in_stock: false+ backorderable: true+ available: true+ description: Maiores ut qui dolores ab autem. Architecto quos sequi+ minus debitis tempora molestiae. Quasi officiis minus voluptatum+ eveniet incidunt. Nisi laboriosam a aliquam eveniet occaecati+ ducimus. Provident quo amet nostrum sed assumenda cum odio. Distinctio+ perferendis quasi nisi exercitationem veritatis minima esse. In+ velit at corporis nobis. Voluptate mollitia nam pariatur enim.+ Recusandae necessitatibus earum deserunt sapiente eveniet quidem+ unde. Consectetur ab perspiciatis veniam dolor tempora. Omnis+ odit autem quae repellat. Delectus corrupti ea nisi reiciendis+ atque iure a molestias. Repellendus laboriosam sint molestias+ debitis in. Minima omnis accusantium modi accusamus doloribus+ fugit. Accusamus autem sequi perferendis saepe quos perspiciatis.+ description_html: |-+ Maiores ut qui dolores ab autem. Architecto quos sequi minus debitis tempora molestiae. Quasi officiis minus voluptatum eveniet incidunt. Nisi laboriosam a aliquam eveniet occaecati ducimus. Provident quo amet nostrum sed assumenda cum odio.+ Distinctio perferendis quasi nisi exercitationem veritatis minima esse. In velit at corporis nobis. Voluptate mollitia nam pariatur enim. Recusandae necessitatibus earum deserunt sapiente eveniet quidem unde.+ Consectetur ab perspiciatis veniam dolor tempora. Omnis odit autem quae repellat. Delectus corrupti ea nisi reiciendis atque iure a molestias.+ Repellendus laboriosam sint molestias debitis in. Minima omnis accusantium modi accusamus doloribus fugit. Accusamus autem sequi perferendis saepe quos perspiciatis.+ default_variant_id: variant_UkLWZg9DAJ+ buy_box_variant_id: variant_UkLWZg9DAJthumbnail_url:- fulfillments:- - id: ful_UkLWZg9DAJ- number: R1001-F1- status: unfulfilled- tracking: U10000- tracking_url:- fulfilled_at:- delivered_at:+ tags: []+ price:+ id: price_UkLWZg9DAJ+ amount: '19.99'+ amount_in_cents: 1999+ compare_at_amount:+ compare_at_amount_in_cents:+ currency: USD+ display_amount: "$19.99"+ display_compare_at_amount:+ price_list_id:+ original_price:+ seller_id: sel_UkLWZg9DAJ+ status: active+ metadata: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'- fulfillment_type: shipping- delivery_method_name: UPS Ground 93- stock_location_name: Kecia Pollich- stock_location_id: sloc_UkLWZg9DAJ- fulfillment_items:- - id: fi_UkLWZg9DAJ- quantity: 1- line_item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- name: Product 1983962- sku: SKU-264- options_text: ''- selected_delivery_rate_id: dr_gbHJdmfrXB- delivery_rates:- - id: dr_gbHJdmfrXB- name: UPS Ground 93- selected: true- cost: '10.0'- total: '10.0'- carrier:- service_level:- estimated_delivery_date:- display_cost: "$10.00"- display_total: "$10.00"- deliveries:- - id: dlv_UkLWZg9DAJ- tracking_number: U10000- carrier:- carrier_name:- service:- status: pending- tracking_url:- estimated_delivery_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- shipping_label_id:- labels: []- shipping_address:- id: addr_gbHJdmfrXB- label:- first_name: John- last_name: Doe- full_name: John Doe- address1: 181 Lovely Street- address2: Northwest- postal_code: '10118'- city: New York- phone: 555-555-0199- company: Company- country_name: United States- country_code: US- state_text: NY- state_code: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_abbr: NY- country_iso: US- state_name: New York- billing_address:- id: addr_UkLWZg9DAJ- label:- first_name: John- last_name: Doe- full_name: John Doe- address1: 180 Lovely Street- address2: Northwest- postal_code: '10118'- city: New York- phone: 555-555-0199- company: Company- country_name: United States- country_code: US- state_text: NY- state_code: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_abbr: NY- country_iso: US- state_name: New York+ product_type_id:+ delivery_profile_id: fp_UkLWZg9DAJ+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:schema:- "$ref": "#/components/schemas/Order"- patch:- summary: Update order notes+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Product"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ post:+ summary: Create a producttags:- - Orders+ - Productssecurity:- bearer_auth: []description: |- Send only the note that changes: an absent key leaves the other alone,- while an empty string clears it.+ Creates a product owned by the acting seller.- `internal_note` accepts HTML and is sanitized on save;- `internal_note_html` reads it back.+ The seller and the store are taken from the request context whatever the+ payload says, so a product cannot be created against another seller.++ The operator's own settings — tax category, delivery profile and whether+ the product is promotionable — are not writable here; they belong to the+ marketplace, not the seller.parameters:- name: X-Spree-Seller-Idin: header@@ -17180,198 +16603,141 @@ paths:schema:type: stringresponses:- '200':- description: notes updated+ '201':+ description: product createdcontent:application/json:example:- id: or_UkLWZg9DAJ- number: R1001- customer_note:- currency: USD- total_quantity: 1- status: placed- fulfillment_status:- payment_status:- completed_at: '2026-01-15T12:00:00.000Z'+ id: prod_gbHJdmfrXB+ name: Hand-thrown mug+ slug: hand-thrown-mug+ meta_title:+ meta_description:+ meta_keywords:+ variant_count: 0+ available_on:+ preorder_ships_at:+ purchasable: false+ preorder: false+ in_stock: false+ backorderable: false+ available: false+ description:+ description_html:+ default_variant_id: variant_gbHJdmfrXB+ buy_box_variant_id: variant_gbHJdmfrXB+ thumbnail_url:+ tags: []+ price:+ id: price_gbHJdmfrXB+ amount: '24.0'+ amount_in_cents: 2400+ compare_at_amount:+ compare_at_amount_in_cents:+ currency: USD+ display_amount: "$24.00"+ display_compare_at_amount:+ price_list_id:+ original_price:+ seller_id: sel_UkLWZg9DAJ+ status: draft+ metadata: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'- internal_note: Packed with the fragile insert.- internal_note_html: "<p>Packed with the fragile insert.</p>"- item_total: '10.0'- display_item_total: "$10.00"- delivery_total: '100.0'- display_delivery_total: "$100.00"- discount_total: '0.0'- display_discount_total: "$0.00"- adjustment_total: '0.0'- display_adjustment_total: "$0.00"- included_tax_total: '0.0'- display_included_tax_total: "$0.00"- additional_tax_total: '0.0'- display_additional_tax_total: "$0.00"- tax_total: '0.0'- display_tax_total: "$0.00"- total: '110.0'- display_total: "$110.00"- payment_total: '0.0'- display_payment_total: "$0.00"- amount_due: '110.0'- display_amount_due: "$110.00"- commission_amount_total: '0.0'- display_commission_amount_total: "$0.00"- commission_tax_total: '0.0'- display_commission_tax_total: "$0.00"- commission_total: '0.0'- display_commission_total: "$0.00"- canceled_at:- cancel_reason_name:- cancel_note:- items:- - id: li_UkLWZg9DAJ- name: Product 1995749- options_text: ''- quantity: 1- currency: USD- price: '10.0'- display_price: "$10.00"- total: '10.0'- display_total: "$10.00"- variant_id: variant_UkLWZg9DAJ- sku: SKU-265- thumbnail_url:- fulfillments:- - id: ful_UkLWZg9DAJ- number: R1001-F1- status: unfulfilled- tracking: U10000- tracking_url:- fulfilled_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- fulfillment_type: shipping- delivery_method_name: UPS Ground 94- stock_location_name: Ophelia Hartmann- stock_location_id: sloc_UkLWZg9DAJ- fulfillment_items:- - id: fi_UkLWZg9DAJ- quantity: 1- line_item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- name: Product 1995749- sku: SKU-265- options_text: ''- selected_delivery_rate_id: dr_gbHJdmfrXB- delivery_rates:- - id: dr_gbHJdmfrXB- name: UPS Ground 94- selected: true- cost: '10.0'- total: '10.0'- carrier:- service_level:- estimated_delivery_date:- display_cost: "$10.00"- display_total: "$10.00"- deliveries:- - id: dlv_UkLWZg9DAJ- tracking_number: U10000- carrier:- carrier_name:- service:- status: pending- tracking_url:- estimated_delivery_at:- delivered_at:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- shipping_label_id:- labels: []- shipping_address:- id: addr_gbHJdmfrXB- label:- first_name: John- last_name: Doe- full_name: John Doe- address1: 183 Lovely Street- address2: Northwest- postal_code: '10118'- city: New York- phone: 555-555-0199- company: Company- country_name: United States- country_code: US- state_text: NY- state_code: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_abbr: NY- country_iso: US- state_name: New York- billing_address:- id: addr_UkLWZg9DAJ- label:- first_name: John- last_name: Doe- full_name: John Doe- address1: 182 Lovely Street- address2: Northwest- postal_code: '10118'- city: New York- phone: 555-555-0199- company: Company- country_name: United States- country_code: US- state_text: NY- state_code: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_abbr: NY- country_iso: US- state_name: New York+ product_type_id:+ delivery_profile_id: fp_UkLWZg9DAJschema:- "$ref": "#/components/schemas/Order"+ "$ref": "#/components/schemas/Product"'422':- description: neither note named+ description: validation failedcontent:application/json:example:error:code: validation_error- message: customer_note or internal_note is required+ message: Name can't be blankdetails:- base:- - customer_note or internal_note is required+ name:+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"requestBody:content:application/json:schema:type: objectproperties:- customer_note:+ name:type: string- nullable: true- description: What the buyer asked for- internal_note:+ example: Hand-thrown mug+ description:type: string- nullable: true- description: The seller's own working note, as HTML- required: true- "/api/v3/seller/order_cancellation_reasons":+ slug:+ type: string+ example: hand-thrown-mug+ status:+ type: string+ example: draft+ meta_title:+ type: string+ meta_description:+ type: string+ meta_keywords:+ type: string+ product_type_id:+ type: string+ example: ptype_abc123+ tags:+ type: array+ items:+ type: string+ example:+ - ceramics+ - handmade+ category_ids:+ type: array+ items:+ type: string+ example:+ - cat_abc123+ metadata:+ type: object+ additionalProperties: true+ prices:+ type: array+ items:+ type: object+ properties:+ amount:+ type: string+ example: '24.00'+ compare_at_amount:+ type: string+ example: '30.00'+ currency:+ type: string+ example: USD+ required:+ - name+ "/api/v3/seller/products/{id}":+ parameters:+ - name: id+ in: path+ description: Product ID+ required: true+ schema:+ type: stringget:- summary: List order cancellation reasons+ summary: Get a producttags:- - Orders+ - Productssecurity:- bearer_auth: []description: |- Why an order was called off, as the marketplace defines it.+ A product the acting seller owns.- Read-only: a seller picks one when cancelling, and the operator decides- what the list holds. Retired reasons are left out.+ An id belonging to another seller answers `404`, not `403` — the seller+ is not told the record exists.parameters:- name: X-Spree-Seller-Idin: header@@ -17380,151 +16746,77 @@ paths:type: stringresponses:'200':- description: reasons listed+ description: product returnedcontent:application/json:example:- data:- - id: ocr_UkLWZg9DAJ- name: Out of stock- active: true- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:+ id: prod_UkLWZg9DAJ+ name: Product 2086710+ slug: product-2086710+ meta_title:+ meta_description:+ meta_keywords:+ variant_count: 1+ available_on:+ preorder_ships_at:+ purchasable: true+ preorder: false+ in_stock: false+ backorderable: true+ available: true+ description: Aliquid voluptate laudantium necessitatibus quidem eaque.+ Sapiente at autem eveniet exercitationem odio in dolores. Laborum+ accusantium nulla autem tempora qui inventore assumenda molestiae.+ Quisquam voluptas delectus ipsum totam ab incidunt. Sunt excepturi+ eius provident unde neque in. Earum pariatur enim odit delectus+ accusamus recusandae. Dolorem eligendi debitis iste voluptate laboriosam+ ab. Ab aut suscipit illo occaecati. Dolores libero cupiditate provident+ at itaque temporibus. Adipisci iste beatae quibusdam perferendis+ ea blanditiis saepe facilis.+ description_html: |-+ Aliquid voluptate laudantium necessitatibus quidem eaque. Sapiente at autem eveniet exercitationem odio in dolores. Laborum accusantium nulla autem tempora qui inventore assumenda molestiae. Quisquam voluptas delectus ipsum totam ab incidunt. Sunt excepturi eius provident unde neque in.+ Earum pariatur enim odit delectus accusamus recusandae. Dolorem eligendi debitis iste voluptate laboriosam ab. Ab aut suscipit illo occaecati. Dolores libero cupiditate provident at itaque temporibus. Adipisci iste beatae quibusdam perferendis ea blanditiis saepe facilis.+ default_variant_id: variant_UkLWZg9DAJ+ buy_box_variant_id: variant_UkLWZg9DAJ+ thumbnail_url:+ tags: []+ price:+ id: price_UkLWZg9DAJ+ amount: '19.99'+ amount_in_cents: 1999+ compare_at_amount:+ compare_at_amount_in_cents:+ currency: USD+ display_amount: "$19.99"+ display_compare_at_amount:+ price_list_id:+ original_price:+ seller_id: sel_UkLWZg9DAJ+ status: active+ metadata: {}+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ product_type_id:+ delivery_profile_id: fp_UkLWZg9DAJschema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Reason"- required:- - data- "/api/v3/seller/package_types":- get:- summary: List package types- tags:- - Package Types- security:- - bearer_auth: []- description: |- What this seller packs their goods into: the boxes their parcels ship- in, the cartons their products are packed into, the pallets a- wholesale order leaves on.-- The list carries the marketplace's own packaging alongside the- seller's, so a seller can pack into the operator's standard cartons- rather than measuring them again. Those rows report `editable: false`- and are refused by every write.-- The row marked `default` is the box this seller's parcels are quoted- with — its size and weight are added to every rate.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- - name: owner- in: query- required: false- schema:- type: string- enum:- - mine- description: Narrows the list to the seller's own packaging, leaving out the- marketplace's shared rows- - name: page- in: query- required: false- description: Page number- schema:- type: integer- - name: limit- in: query- required: false- description: Records per page (max 100)- schema:- type: integer- responses:- '200':- description: package types listed+ "$ref": "#/components/schemas/Product"+ '404':+ description: another seller's productcontent:application/json:example:- data:- - id: pkgtype_UkLWZg9DAJ- name: Standard mailer- kind: box- length: '30.0'- width: '20.0'- height: '15.0'- weight: '0.4'- max_weight:- default: true- metadata: {}- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- dimensions_unit: cm- weight_unit: kg- volume: '0.009'- editable: true- - id: pkgtype_gbHJdmfrXB- name: Marketplace carton- kind: carton- length: '40.0'- width: '30.0'- height: '25.0'- weight:- max_weight: '20.0'- default: false- metadata: {}- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- dimensions_unit: cm- weight_unit: kg- volume: '0.03'- editable: false- meta:- page: 1- limit: 25- count: 2- pages: 1- from: 1- to: 2- in: 2- previous:- next:+ error:+ code: record_not_found+ message: Product not foundschema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/PackageType"- meta:- "$ref": "#/components/schemas/PaginationMeta"- required:- - data- - meta- post:- summary: Create a package type+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update a producttags:- - Package Types+ - Productssecurity:- bearer_auth: []- description: |- Records a piece of the seller's own packaging. Marking it `default`- makes it the box their parcels are quoted with, and demotes whichever- of their rows held the flag before — the marketplace's default is a- different owner's row and is left alone.+ description: Edits a product the acting seller owns.parameters:- name: X-Spree-Seller-Idin: header@@ -17532,42 +16824,57 @@ paths:schema:type: stringresponses:- '201':- description: package type created+ '200':+ description: product updatedcontent:application/json:example:- id: pkgtype_EfhxLZ9ck8- name: Large mailer- kind: box- length: '40.0'- width: '30.0'- height: '20.0'- weight: '0.6'- max_weight:- default: false+ id: prod_UkLWZg9DAJ+ name: Hand-thrown mug, large+ slug: product-2118212+ meta_title:+ meta_description:+ meta_keywords:+ variant_count: 1+ available_on:+ preorder_ships_at:+ purchasable: true+ preorder: false+ in_stock: false+ backorderable: true+ available: true+ description: Vel minima recusandae iure deserunt non. Corrupti soluta+ pariatur recusandae saepe eveniet. Sequi deserunt fugiat architecto+ animi. Eum facilis veniam a consequatur minus. Dolor iure facilis+ repellendus tenetur. Nobis harum perferendis ab maiores labore eius+ eum quo.+ description_html: |-+ Vel minima recusandae iure deserunt non. Corrupti soluta pariatur recusandae saepe eveniet. Sequi deserunt fugiat architecto animi.+ Eum facilis veniam a consequatur minus. Dolor iure facilis repellendus tenetur. Nobis harum perferendis ab maiores labore eius eum quo.+ default_variant_id: variant_UkLWZg9DAJ+ buy_box_variant_id: variant_UkLWZg9DAJ+ thumbnail_url:+ tags: []+ price:+ id: price_UkLWZg9DAJ+ amount: '19.99'+ amount_in_cents: 1999+ compare_at_amount:+ compare_at_amount_in_cents:+ currency: USD+ display_amount: "$19.99"+ display_compare_at_amount:+ price_list_id:+ original_price:+ seller_id: sel_UkLWZg9DAJ+ status: activemetadata: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'- dimensions_unit: cm- weight_unit: kg- volume: '0.024'- editable: true- schema:- "$ref": "#/components/schemas/PackageType"- '422':- description: validation error- content:- application/json:- example:- error:- code: validation_error- message: Kind is not included in the list- details:- kind:- - is not included in the list+ product_type_id:+ delivery_profile_id: fp_UkLWZg9DAJschema:- "$ref": "#/components/schemas/ErrorResponse"+ "$ref": "#/components/schemas/Product"requestBody:content:application/json:@@ -17576,62 +16883,54 @@ paths:properties:name:type: string- kind:+ example: Hand-thrown mug, large+ description:type: string- enum:- - box- - envelope- - carton- - pallet- - container- length:- type: number- nullable: true- width:- type: number- nullable: true- height:- type: number- nullable: true- dimensions_unit:+ slug:type: string- nullable: true- weight:- type: number- nullable: true- description: The empty package's own weight, added to every quote- max_weight:- type: number- nullable: true- weight_unit:+ status:type: string- nullable: true- default:- type: boolean+ example: active+ tags:+ type: array+ items:+ type: string+ category_ids:+ type: array+ items:+ type: stringmetadata:type: object- nullable: true- required:- - name- - kind+ additionalProperties: true+ delete:+ summary: Delete a product+ tags:+ - Products+ security:+ - bearer_auth: []+ description: Deletes a product the acting seller owns.+ parameters:+ - name: X-Spree-Seller-Id+ in: headerrequired: true- "/api/v3/seller/package_types/{id}":- parameters:- - name: id- in: path- required: true- description: Package type ID- schema:- type: string+ schema:+ type: string+ responses:+ '204':+ description: product deleted+ "/api/v3/seller/profile":get:- summary: Get a package type+ summary: Get profiletags:- - Package Types+ - Profilesecurity:- bearer_auth: []description: |- Returns one package type by prefixed ID — the seller's own, or a- marketplace row they may pack into.+ The seller's own record.++ Singular by nature: the seller in play is always the one named by+ `X-Spree-Seller-Id`, never an id in the path — so a seller cannot address+ another seller here even by guessing one.parameters:- name: X-Spree-Seller-Idin: header@@ -17640,47 +16939,71 @@ paths:type: stringresponses:'200':- description: package type found+ description: profile returnedcontent:application/json:example:- id: pkgtype_UkLWZg9DAJ- name: Standard mailer- kind: box- length: '30.0'- width: '20.0'- height: '15.0'- weight: '0.4'- max_weight:- default: true- metadata: {}+ id: sel_UkLWZg9DAJ+ name: Seller 100+ slug: seller-100+ about: ''+ about_html: ''+ logo_url:+ square_logo_url:+ cover_photo_url:+ preferred_timezone: UTC+ status: approved+ legal_name:+ registration_number:+ contact_email:+ billing_email:+ tax_remittance: seller+ payouts_schedule_interval:+ holiday_mode_until:+ terms_accepted_at: '2026-01-15T12:00:00.000Z'created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- dimensions_unit: cm- weight_unit: kg- volume: '0.009'- editable: true+ minimum_payout_amount:+ on_holiday: false+ sellable: true+ default_currency: USD+ supported_currencies:+ - USD+ - EUR+ - GBP+ products_count: 0schema:- "$ref": "#/components/schemas/PackageType"- '404':- description: package type not found+ "$ref": "#/components/schemas/Profile"+ '403':+ description: no seller named, or not a member of itcontent:application/json:example:error:- code: record_not_found- message: Package type not found+ code: access_denied+ message: You do not have access to this seller.schema:"$ref": "#/components/schemas/ErrorResponse"patch:- summary: Update a package type+ summary: Update profiletags:- - Package Types+ - Profilesecurity:- bearer_auth: []description: |- Changes the seller's own packaging. A marketplace row is not theirs to- edit and answers 404.+ Edits presentation, contact details and addresses.++ Readable but **not** writable, by design: `status` — the lifecycle belongs+ to the marketplace operator's workflows — the settlement terms, and+ `slug`, since a seller renaming their own storefront address would break+ every link pointing at it.++ `accept_terms: true` stamps the moment the seller accepted the+ marketplace's terms, which is what the matching onboarding requirement+ reads. One-way — sending `false` does not unmake the stamp.++ `custom_fields` is narrowed server-side to the definitions this+ marketplace's onboarding actually asks this seller for; a field nothing+ asked for is ignored rather than written.parameters:- name: X-Spree-Seller-Idin: header@@ -17689,28 +17012,53 @@ paths:type: stringresponses:'200':- description: package type updated+ description: profile updatedcontent:application/json:example:- id: pkgtype_UkLWZg9DAJ- name: Standard mailer- kind: box- length: '30.0'- width: '20.0'- height: '15.0'- weight: '0.4'- max_weight: '25.0'- default: true- metadata: {}+ id: sel_UkLWZg9DAJ+ name: Acme Supplies+ slug: seller-102+ about: ''+ about_html: ''+ logo_url:+ square_logo_url:+ cover_photo_url:+ preferred_timezone: UTC+ status: approved+ legal_name:+ registration_number:+ contact_email: [email protected]+ billing_email:+ tax_remittance: seller+ payouts_schedule_interval:+ holiday_mode_until:+ terms_accepted_at: '2026-01-15T12:00:00.000Z'created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- dimensions_unit: cm- weight_unit: kg- volume: '0.009'- editable: true+ minimum_payout_amount:+ on_holiday: false+ sellable: true+ default_currency: USD+ supported_currencies:+ - USD+ - EUR+ - GBP+ products_count: 0+ schema:+ "$ref": "#/components/schemas/Profile"+ '422':+ description: validation failed+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Name can't be blank+ details:+ name:+ - can't be blankschema:- "$ref": "#/components/schemas/PackageType"+ "$ref": "#/components/schemas/ErrorResponse"requestBody:content:application/json:@@ -17719,196 +17067,169 @@ paths:properties:name:type: string- kind:+ example: Acme Supplies+ contact_email:type: string- enum:- - box- - envelope- - carton- - pallet- - container- length:- type: number+ format: emailnullable: true- width:- type: number+ example: [email protected]+ billing_email:+ type: string+ format: emailnullable: true- height:- type: number+ example: [email protected]+ about:+ type: stringnullable: true- dimensions_unit:+ description: Sanitized HTML — the seller's public description+ legal_name:type: stringnullable: true- weight:- type: number+ description: The business a commission invoice is made out to+ registration_number:+ type: stringnullable: true- max_weight:- type: number+ logo:+ type: stringnullable: true- weight_unit:+ description: ActiveStorage signed id; `null` removes the attachment+ square_logo:type: stringnullable: true- default:+ cover_photo:+ type: string+ nullable: true+ accept_terms:type: boolean- metadata:+ description: Stamps acceptance of the marketplace terms+ billing_address:type: object- nullable: true- required: true- delete:- summary: Delete a package type- tags:- - Package Types- security:- - bearer_auth: []- description: |- Retires one of the seller's own package types. The default box is- refused — name another default first, or every parcel silently falls- back to the marketplace's box.- parameters:- - name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '204':- description: package type deleted- "/api/v3/seller/payouts":- get:- summary: List payouts+ additionalProperties: true+ custom_fields:+ type: array+ items:+ type: object+ properties:+ custom_field_definition_id:+ type: string+ example: cfd_abc123+ value:+ description: Any JSON value the definition accepts+ "/api/v3/seller/requirements/{requirement_id}/submissions":+ parameters:+ - name: requirement_id+ in: path+ description: Requirement ID, as returned by `GET /api/v3/seller/onboarding`+ required: true+ schema:+ type: string+ post:+ summary: Submit against a requirementtags:- - Earnings+ - Onboardingsecurity:- bearer_auth: []description: |- Settlements to this seller: each one batches the transfers that had- accumulated since the last, on the seller's payout schedule. `pending`- and `processing` rows are owed; `completed` ones reached the seller's- bank. `transfers_count` says how many earnings a settlement covers —- list them with `GET /api/v3/seller/transfers?q[payout_id_eq]=…`.+ What the seller says about one requirement: an attestation they tick, a+ document they upload, a reference they paste.- Read-only: a payout is created by the marketplace's sweep and- confirmed by the payout provider or the operator.+ Create only. A submission records what was said and when, so a seller who+ needs to correct something submits again rather than editing, and the+ latest one counts.++ `file` is **not** a multipart upload — it is the `signed_id` returned by+ `POST /api/v3/seller/direct_uploads`, so the bytes are already in storage+ by the time this runs.++ An attestation is accepted on the spot; a requirement the operator+ reviews comes back `pending`.parameters:- name: X-Spree-Seller-Idin: headerrequired: trueschema:type: string- - name: page- in: query- required: false- description: Page number- schema:- type: integer- - name: limit- in: query- required: false- description: Records per page (max 100)- schema:- type: integer- - name: q[status_eq]- in: query- required: false- schema:- type: string- enum:- - pending- - processing- - completed- - failed- - unresolvedresponses:- '200':- description: payouts listed+ '201':+ description: submission recordedcontent:application/json:example:- data:- - id: vpo_UkLWZg9DAJ- status: pending- currency: USD- provider: Spree::PayoutProvider::System- reference:- period_start:- period_end:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- amount: '120.0'- display_amount: "$120.00"- transfers_count: 1- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:+ id: selsub_UkLWZg9DAJ+ status: accepted+ note: Confirmed.+ review_note:+ reference:+ reviewed_at: '2026-01-15T12:00:00.000Z'+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ file_url:+ file_name:schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Payout"- meta:- "$ref": "#/components/schemas/PaginationMeta"- required:- - data- - meta- "/api/v3/seller/payouts/{id}":+ "$ref": "#/components/schemas/RequirementSubmission"+ '404':+ description: a requirement belonging to another marketplace+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Seller requirement not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ note:+ type: string+ description: Anything the seller wants to say alongside the submission+ reference:+ type: string+ description: A reference number or external identifier, for requirements+ that ask for one+ file:+ type: string+ description: A direct-upload `signed_id`, for requirements that+ ask for a document+ "/api/v3/seller/requirement_submissions/{id}/download":parameters:- name: idin: path+ description: Submission IDrequired: true- description: Payout prefixed IDschema:type: stringget:- summary: Get a payout+ summary: Download a submitted documenttags:- - Earnings+ - Onboardingsecurity:- bearer_auth: []- description: One of this seller's settlements. Another seller's is not found,- whatever id is sent.+ description: |+ Streams the file attached to one of this seller's submissions.++ Served through the API rather than from a storage URL on purpose: these+ are identity and registration documents, so every read is authorized+ against the acting seller. Another seller's submission answers `404`.parameters:- name: X-Spree-Seller-Idin: headerrequired: true- schema:- type: string- responses:- '200':- description: payout found- content:- application/json:- example:- id: vpo_UkLWZg9DAJ- status: pending- currency: USD- provider: Spree::PayoutProvider::System- reference:- period_start:- period_end:- created_at: '2026-01-15T12:00:00.000Z'- updated_at: '2026-01-15T12:00:00.000Z'- amount: '120.0'- display_amount: "$120.00"- transfers_count: 1- schema:- "$ref": "#/components/schemas/Payout"+ schema:+ type: string+ responses:'404':- description: payout not found+ description: another seller's submissioncontent:application/json:example:error:code: record_not_found- message: Seller payout not found+ message: Seller requirement submission not found+ application/octet-stream:schema:"$ref": "#/components/schemas/ErrorResponse""/api/v3/seller/orders/{order_id}/returns":@@ -17942,34 +17263,6 @@ paths:description: returns listedcontent:application/json:- example:- data:- - id: ret_UkLWZg9DAJ- number: RET1001- status: requested- order_id: or_UkLWZg9DAJ- reason_id:- refund_total: '10.0'- display_refund_total: "$10.00"- approved_at:- received_at:- refunded_at:- canceled_at:- memo:- stock_location_id: sloc_UkLWZg9DAJ- refunded_total: '0.0'- refundable_total: '10.0'- display_refunded_total: "$0.00"- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:schema:type: objectproperties:@@ -18003,23 +17296,6 @@ paths:description: return openedcontent:application/json:- example:- id: ret_UkLWZg9DAJ- number: RET1001- status: requested- order_id: or_UkLWZg9DAJ- reason_id:- refund_total: '10.0'- display_refund_total: "$10.00"- approved_at:- received_at:- refunded_at:- canceled_at:- memo:- stock_location_id: sloc_UkLWZg9DAJ- refunded_total: '0.0'- refundable_total: '10.0'- display_refunded_total: "$0.00"schema:"$ref": "#/components/schemas/Return"'422':@@ -18089,23 +17365,6 @@ paths:description: return approvedcontent:application/json:- example:- id: ret_UkLWZg9DAJ- number: RET1001- status: approved- order_id: or_UkLWZg9DAJ- reason_id:- refund_total: '10.0'- display_refund_total: "$10.00"- approved_at: '2026-01-15T12:00:00Z'- received_at:- refunded_at:- canceled_at:- memo:- stock_location_id: sloc_UkLWZg9DAJ- refunded_total: '0.0'- refundable_total: '10.0'- display_refunded_total: "$0.00"schema:"$ref": "#/components/schemas/Return""/api/v3/seller/orders/{order_id}/returns/{id}/receive":@@ -18139,72 +17398,260 @@ paths:responses:'200':description: return received+ content:+ application/json:+ schema:+ "$ref": "#/components/schemas/Return"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ items:+ type: array+ items:+ type: object+ properties:+ return_line_item_id:+ type: string+ quantity:+ type: integer+ resellable:+ type: boolean+ required:+ - return_line_item_id+ - quantity+ "/api/v3/seller/orders/{order_id}/returns/{id}/refund":+ parameters:+ - name: order_id+ in: path+ required: true+ schema:+ type: string+ - name: id+ in: path+ required: true+ schema:+ type: string+ patch:+ summary: Refund a return+ tags:+ - Returns+ security:+ - bearer_auth: []+ description: |+ Gives the customer their money back.++ The seller is merchant of record for their own child order, so this is+ theirs to do. The amount is bounded by what the return is owed and, on+ a basket split between sellers, by this order's share of the payment —+ never a sibling's.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: return refunded+ content:+ application/json:+ schema:+ "$ref": "#/components/schemas/Return"+ '422':+ description: more than the return is owed+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ amount:+ type: string+ nullable: true+ refund_method:+ type: string+ enum:+ - original_payment+ - store_credit+ "/api/v3/seller/orders/{order_id}/returns/{id}/cancel":+ parameters:+ - name: order_id+ in: path+ required: true+ schema:+ type: string+ - name: id+ in: path+ required: true+ schema:+ type: string+ patch:+ summary: Cancel a return+ tags:+ - Returns+ security:+ - bearer_auth: []+ description: Calls the return off.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: return canceled+ content:+ application/json:+ schema:+ "$ref": "#/components/schemas/Return"+ "/api/v3/seller/return_reasons":+ get:+ summary: List return reasons+ tags:+ - Returns+ security:+ - bearer_auth: []+ description: |+ Why goods come back, as the marketplace defines it.++ Read-only: the vocabulary is the operator's, and a seller picks from+ it. Retired reasons are left out.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: reasons listedcontent:application/json:example:- id: ret_UkLWZg9DAJ- number: RET1001- status: received- order_id: or_UkLWZg9DAJ- reason_id:- refund_total: '10.0'- display_refund_total: "$10.00"- approved_at: '2026-01-15T12:00:00Z'- received_at: '2026-01-15T12:00:00Z'- refunded_at:- canceled_at:- memo:- stock_location_id: sloc_UkLWZg9DAJ- refunded_total: '0.0'- refundable_total: '10.0'- display_refunded_total: "$0.00"+ data:+ - id: rar_UkLWZg9DAJ+ name: Damaged in transit+ active: true+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Reason"+ required:+ - data+ "/api/v3/seller/stock_locations":+ get:+ summary: List stock locations+ tags:+ - Stock Locations+ security:+ - bearer_auth: []+ description: |+ Where this seller keeps stock, and so where their returns are sent.++ Rooted in the acting seller, so the marketplace operator's own warehouses+ never appear here.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ - name: page+ in: query+ required: false+ description: Page number+ schema:+ type: integer+ - name: limit+ in: query+ required: false+ description: Records per page (max 100)+ schema:+ type: integer+ - name: sort+ in: query+ required: false+ description: Sort field; prefix with `-` for descending+ schema:+ type: string+ responses:+ '200':+ description: stock locations listed+ content:+ application/json:+ example:+ data:+ - id: sloc_UkLWZg9DAJ+ name: Lesha Stroman+ address1: 1600 Pennsylvania Ave NW+ city: Washington+ zipcode: '20500'+ country_code: US+ country_name: United States+ state_code: AL+ state_text: AL+ pickup_ready_in_minutes:+ pickup_instructions:+ address2:+ state_name:+ phone: "(202) 456-1111"+ company:+ active: true+ default: false+ kind: warehouse+ returns_enabled: true+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:schema:- "$ref": "#/components/schemas/Return"- requestBody:- content:- application/json:- schema:- type: object- properties:- items:- type: array- items:- type: object- properties:- return_line_item_id:- type: string- quantity:- type: integer- resellable:- type: boolean- required:- - return_line_item_id- - quantity- "/api/v3/seller/orders/{order_id}/returns/{id}/refund":- parameters:- - name: order_id- in: path- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: string- patch:- summary: Refund a return+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/StockLocation"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ post:+ summary: Create a stock locationtags:- - Returns+ - Stock Locationssecurity:- bearer_auth: []description: |- Gives the customer their money back.+ Adds a place this seller ships from.- The seller is merchant of record for their own child order, so this is- theirs to do. The amount is bounded by what the return is owed and, on- a basket split between sellers, by this order's share of the payment —- never a sibling's.+ The seller and the store come from the request context whatever the+ payload says.parameters:- name: X-Spree-Seller-Idin: header@@ -18212,70 +17659,115 @@ paths:schema:type: stringresponses:- '200':- description: return refunded+ '201':+ description: stock location createdcontent:application/json:example:- id: ret_UkLWZg9DAJ- number: RET1001- status: refunded- order_id: or_UkLWZg9DAJ- reason_id:- refund_total: '10.0'- display_refund_total: "$10.00"- approved_at: '2026-01-15T12:00:00Z'- received_at: '2026-01-15T12:00:00Z'- refunded_at: '2026-01-15T12:00:00Z'- canceled_at:- memo:- stock_location_id: sloc_UkLWZg9DAJ- refunded_total: '10.0'- refundable_total: '0.0'- display_refunded_total: "$10.00"+ id: sloc_gbHJdmfrXB+ name: Main warehouse+ address1:+ city: Portland+ zipcode:+ country_code: US+ country_name: United States+ state_code:+ state_text:+ pickup_ready_in_minutes:+ pickup_instructions:+ address2:+ state_name:+ phone:+ company:+ active: true+ default: false+ kind: warehouse+ returns_enabled: true+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'schema:- "$ref": "#/components/schemas/Return"+ "$ref": "#/components/schemas/StockLocation"'422':- description: more than the return is owed+ description: validation failedcontent:application/json:example:error:- code: processing_error- message: That is more than the amount still refundable.+ code: validation_error+ message: Name can't be blank+ details:+ name:+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"requestBody:content:application/json:schema:type: objectproperties:- amount:+ name:+ type: string+ example: Main warehouse+ company:type: stringnullable: true- refund_method:+ address1:type: string- enum:- - original_payment- - store_credit- "/api/v3/seller/orders/{order_id}/returns/{id}/cancel":+ nullable: true+ example: 1 Kiln Lane+ address2:+ type: string+ nullable: true+ city:+ type: string+ nullable: true+ example: Portland+ zipcode:+ type: string+ nullable: true+ example: '97205'+ country_code:+ type: string+ nullable: true+ example: US+ state_code:+ type: string+ nullable: true+ example: OR+ state_name:+ type: string+ nullable: true+ phone:+ type: string+ nullable: true+ active:+ type: boolean+ description: Set `false` to retire a location — there is no delete+ default:+ type: boolean+ kind:+ type: string+ example: warehouse+ required:+ - name+ "/api/v3/seller/stock_locations/{id}":parameters:- - name: order_id- in: path- required: true- schema:- type: string- name: idin: path+ description: Stock location IDrequired: trueschema:type: string- patch:- summary: Cancel a return+ get:+ summary: Get a stock locationtags:- - Returns+ - Stock Locationssecurity:- bearer_auth: []- description: Calls the return off.+ description: |+ A stock location the acting seller owns. An id belonging to another+ seller — or to the marketplace operator — answers `404`.parameters:- name: X-Spree-Seller-Idin: header@@ -18284,75 +17776,121 @@ paths:type: stringresponses:'200':- description: return canceled+ description: stock location returnedcontent:application/json:example:- id: ret_UkLWZg9DAJ- number: RET1001- status: canceled- order_id: or_UkLWZg9DAJ- reason_id:- refund_total: '10.0'- display_refund_total: "$10.00"- approved_at:- received_at:- refunded_at:- canceled_at: '2026-01-15T12:00:00Z'- memo:- stock_location_id: sloc_UkLWZg9DAJ- refunded_total: '0.0'- refundable_total: '10.0'- display_refunded_total: "$0.00"+ id: sloc_UkLWZg9DAJ+ name: Marsha Turner+ address1: 1600 Pennsylvania Ave NW+ city: Washington+ zipcode: '20500'+ country_code: US+ country_name: United States+ state_code: AL+ state_text: AL+ pickup_ready_in_minutes:+ pickup_instructions:+ address2:+ state_name:+ phone: "(202) 456-1111"+ company:+ active: true+ default: false+ kind: warehouse+ returns_enabled: true+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'schema:- "$ref": "#/components/schemas/Return"- "/api/v3/seller/return_reasons":- get:- summary: List return reasons+ "$ref": "#/components/schemas/StockLocation"+ '404':+ description: another seller's stock location+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Stock location not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update a stock locationtags:- - Returns+ - Stock Locationssecurity:- bearer_auth: []description: |- Why goods come back, as the marketplace defines it.+ Edits a stock location the acting seller owns.- Read-only: the vocabulary is the operator's, and a seller picks from- it. Retired reasons are left out.+ There is no delete: a location holds stock levels and is named on+ historical fulfillments, so a seller retires one by setting `active` to+ `false`.parameters:- name: X-Spree-Seller-Id- in: header- required: true- schema:- type: string- responses:- '200':- description: reasons listed- content:- application/json:- example:- data:- - id: rar_UkLWZg9DAJ- name: Damaged in transit- active: true- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: stock location updated+ content:+ application/json:+ example:+ id: sloc_UkLWZg9DAJ+ name: Kiln Lane warehouse+ address1: 1600 Pennsylvania Ave NW+ city: Washington+ zipcode: '20500'+ country_code: US+ country_name: United States+ state_code: AL+ state_text: AL+ pickup_ready_in_minutes:+ pickup_instructions:+ address2:+ state_name:+ phone: "(202) 456-1111"+ company:+ active: true+ default: false+ kind: warehouse+ returns_enabled: true+ created_at: '2026-01-15T12:00:00.000Z'+ updated_at: '2026-01-15T12:00:00.000Z'schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Reason"- required:- - data+ "$ref": "#/components/schemas/StockLocation"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ example: Main warehouse+ address1:+ type: string+ nullable: true+ city:+ type: string+ nullable: true+ zipcode:+ type: string+ nullable: true+ country_code:+ type: string+ nullable: true+ state_code:+ type: string+ nullable: true+ phone:+ type: string+ nullable: true+ active:+ type: boolean+ default:+ type: boolean"/api/v3/seller/tax_identifiers":get:summary: List tax registrations@@ -18548,6 +18086,160 @@ paths:code: tax_id_not_validatablemessage: No registry validator is installed for tax identifier kind'eu_vat'+ "/api/v3/seller/team":+ get:+ summary: List team members+ tags:+ - Team+ security:+ - bearer_auth: []+ description: |+ The people who run this seller.++ Rooted at the acting seller throughout, so a seller only ever sees their+ own team. Unpaginated — a seller's team is small by nature.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: team members listed+ content:+ application/json:+ example:+ data:+ - id: adm_UkLWZg9DAJ+ email: [email protected]+ first_name: Bill+ last_name: Towne+ full_name: Bill Towne+ created_at: '2026-01-15T12:00:00.000Z'+ avatar_url:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/TeamMember"+ required:+ - data+ post:+ summary: Invite a team member+ tags:+ - Team+ security:+ - bearer_auth: []+ description: |+ Invites a colleague onto this seller's team. They join when they accept,+ on the same invitation rail — and the same email — the marketplace+ operator's own invitations use.++ Hiring is not a lifecycle transition: a trading seller's status is+ untouched by taking someone on.++ The role is not a parameter. Every member holds the seller's own seeded+ role, which already carries the whole seller vocabulary.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '201':+ description: invitation sent+ content:+ application/json:+ example:+ id: inv_UkLWZg9DAJ+ email: [email protected]+ created_at: '2026-01-15T12:00:00.000Z'+ expires_at: '2026-01-29T12:00:00.000Z'+ accepted_at:+ status: pending+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=3K6BfBtHGFeQgToPE45qUDWE"+ schema:+ "$ref": "#/components/schemas/Invitation"+ '422':+ description: validation failed+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Email is invalid and Email can't be blank+ details:+ email:+ - is invalid+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ email:+ type: string+ format: email+ example: [email protected]+ required:+ "/api/v3/seller/team/{id}":+ parameters:+ - name: id+ in: path+ description: Team member (user) ID+ required: true+ schema:+ type: string+ delete:+ summary: Remove a team member+ tags:+ - Team+ security:+ - bearer_auth: []+ description: |+ Revokes a member's access, removing every role they hold on this seller.++ The team can never reach zero: emptying it would leave a seller nobody+ can sign in to, and only the marketplace operator could put someone back.+ The last remaining member is refused with `422`.+ parameters:+ - name: X-Spree-Seller-Id+ in: header+ required: true+ schema:+ type: string+ responses:+ '204':+ description: member removed+ '422':+ description: cannot remove the last remaining member+ content:+ application/json:+ example:+ error:+ code: processing_error+ message: A seller needs at least one team member. Invite someone+ else before removing this one.+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ '404':+ description: not a member of this seller+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Admin user not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse""/api/v3/seller/transfers":get:summary: List transfers@@ -18853,7 +18545,7 @@ components:type: stringdescription: JWT access token, `seller_api` audienceuser:- "$ref": "#/components/schemas/TeamMember"+ "$ref": "#/components/schemas/Account"sellers:type: arraydescription: The sellers this user may act for. Pick one and send its `id`@@ -19124,7 +18816,7 @@ components:may do on the selected oneproperties:user:- "$ref": "#/components/schemas/TeamMember"+ "$ref": "#/components/schemas/Account"sellers:type: arrayitems:@@ -19567,6 +19259,40 @@ components:- display_compare_at_amount- price_list_idx-typelizer: true+ Account:+ type: object+ properties:+ id:+ type: string+ email:+ type: string+ first_name:+ type: string+ nullable: true+ last_name:+ type: string+ nullable: true+ full_name:+ type: string+ nullable: true+ created_at:+ type: string+ avatar_url:+ type: string+ nullable: true+ selected_locale:+ type: string+ nullable: true+ required:+ - id+ - first_name+ - last_name+ - full_name+ - created_at+ - avatar_url+ - selected_locale+ x-typelizer: trueBalance:type: objectproperties:diff --git a/packages/seller-dashboard/src/api-client.ts b/packages/seller-dashboard/src/api-client.tsindex 83827b62b1..b5b19825da 100644--- a/packages/seller-dashboard/src/api-client.ts+++ b/packages/seller-dashboard/src/api-client.ts@@ -56,7 +56,7 @@ export function createSellerApiClient({// and 403 them against a seller they may hold no role on.clearTenant: forgetSeller,fetchPermissions: async () => {- const response = await sellerClient().me()+ const response = await sellerClient().me.get()// Both shapes, exactly as the operator's dashboard receives them. The// framework's `<Can>` reads CanCanCan rules; the key list is what thediff --git a/packages/seller-dashboard/src/components/seller-switcher.tsx b/packages/seller-dashboard/src/components/seller-switcher.tsxindex 08a2fde426..76ae67e4d8 100644--- a/packages/seller-dashboard/src/components/seller-switcher.tsx+++ b/packages/seller-dashboard/src/components/seller-switcher.tsx@@ -42,7 +42,7 @@ export function SellerSwitcher() {// loaded by the page behind this.const { data: me, isLoading } = useQuery({queryKey: ['seller', 'me'],- queryFn: () => sellerClient().me(),+ queryFn: () => sellerClient().me.get(),})const { data: profile } = useQuery({diff --git a/packages/seller-dashboard/src/pages/seller-picker.tsx b/packages/seller-dashboard/src/pages/seller-picker.tsxindex 17fccd8420..3826ee6353 100644--- a/packages/seller-dashboard/src/pages/seller-picker.tsx+++ b/packages/seller-dashboard/src/pages/seller-picker.tsx@@ -15,7 +15,7 @@ export function SellerPicker() {const { t } = useTranslation()const { data, isLoading, error } = useQuery({queryKey: ['seller', 'me'],- queryFn: () => sellerClient().me(),+ queryFn: () => sellerClient().me.get(),})if (isLoading) return <CenteredMessage>{t('common.loading')}</CenteredMessage>diff --git a/packages/seller-dashboard/src/routes/_authenticated/index.tsx b/packages/seller-dashboard/src/routes/_authenticated/index.tsxindex 97090510f2..d545991bf0 100644--- a/packages/seller-dashboard/src/routes/_authenticated/index.tsx+++ b/packages/seller-dashboard/src/routes/_authenticated/index.tsx@@ -24,7 +24,7 @@ function SellerEntry() {const { data, isLoading, error } = useQuery({queryKey: ['seller', 'me'],- queryFn: () => sellerClient().me(),+ queryFn: () => sellerClient().me.get(),})const sellers = data?.sellers ?? []diff --git a/packages/seller-sdk/src/index.ts b/packages/seller-sdk/src/index.tsindex 7c8cf4f916..1c1b58db20 100644--- a/packages/seller-sdk/src/index.ts+++ b/packages/seller-sdk/src/index.ts@@ -7,6 +7,7 @@ export { SpreeError } from '@spree/sdk-core'export type { Client, Client as SellerApiClient, SellerClientConfig } from './client'export { createSellerClient } from './client'export type {+ AccountUpdateParams,BulkProductResult,DeliveryCalculatorType,DeliveryMethodParams,diff --git a/packages/seller-sdk/src/seller-client.ts b/packages/seller-sdk/src/seller-client.tsindex 02360dd8c2..7b666e6a7b 100644--- a/packages/seller-sdk/src/seller-client.ts+++ b/packages/seller-sdk/src/seller-client.ts@@ -1,6 +1,7 @@import type { ListParams, PaginatedResponse, RequestFn, RequestOptions } from '@spree/sdk-core'import { transformListParams } from '@spree/sdk-core'import type {+ Account,AuthTokens,Balance,Claim,@@ -133,14 +134,27 @@ export class SellerClient {}/**- * The signed-in seller: who they are, which sellers they may act for, and+ * The signed-in person: who they are, which sellers they may act for, and* what they may do on the selected one.** `permission_keys` is empty until a seller is named — capability is per* seller, so there is no answer spanning all of them.*/- me = (options?: RequestOptions): Promise<MeResponse> =>- this.request<MeResponse>('GET', '/me', options)+ readonly me = {+ get: (options?: RequestOptions): Promise<MeResponse> =>+ this.request<MeResponse>('GET', '/me', options),++ /**+ * Edits the signed-in person's own account — the name and photo their+ * team sees, and the panel's language. Not the seller business they act+ * for: that is `profile.update`.+ *+ * `avatar` takes a direct-upload signed id to set the photo, or `null` to+ * remove it; omitting it leaves the current one alone.+ */+ update: (params: AccountUpdateParams, options?: RequestOptions): Promise<MeResponse> =>+ this.request<MeResponse>('PATCH', '/me', { ...options, body: params }),+ }/** The seller's own record, as they maintain it. */readonly profile = {@@ -1670,13 +1684,31 @@ export interface PermissionRule {}export interface MeResponse {- user: TeamMember+ /**+ * `Account` rather than `TeamMember`: reading your own record also shows+ * the panel language you chose, which the team list does not publish about+ * a colleague.+ */+ user: Accountsellers: SellerSummary[]/** Empty until a seller is named — capability is per seller. */permissions: PermissionRule[]permission_keys: string[]}+/** What a seller may change on their own account. */+export interface AccountUpdateParams {+ first_name?: string+ last_name?: string+ /** The panel's UI language, as a bundle code the panel ships (e.g. `de`). */+ selected_locale?: string+ /**+ * ActiveStorage signed id to set the photo, or `null` to remove it. Omit to+ * leave the current one alone.+ */+ avatar?: string | null+}+/** The fields a seller may change on their own record. */export interface ProfileUpdateParams {name?: stringdiff --git a/packages/seller-sdk/src/types/generated/Account.ts b/packages/seller-sdk/src/types/generated/Account.tsnew file mode 100644index 0000000000..15060a8976--- /dev/null+++ b/packages/seller-sdk/src/types/generated/Account.ts@@ -0,0 +1,16 @@+// Typelizer digest ae84f777b1ccf70ce8e48a7e5ac06111+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++type Account = {+ id: string;+ email: string;+ first_name: string | null;+ last_name: string | null;+ full_name: string | null;+ created_at: string;+ avatar_url: string | null;+ selected_locale: string | null;+}++export default Account;diff --git a/packages/seller-sdk/src/types/generated/index.ts b/packages/seller-sdk/src/types/generated/index.tsindex 93b9b27e76..d0703f6105 100644--- a/packages/seller-sdk/src/types/generated/index.ts+++ b/packages/seller-sdk/src/types/generated/index.ts@@ -1,4 +1,4 @@-// Typelizer digest d0331637341450312e6cc6cbb1c33b08+// Typelizer digest 6319e187657fb620d87ebc1541716387//// DO NOT MODIFY: This file was automatically generated by Typelizer.export type { ClaimStatus, ExchangeStatus, FulfillmentStatus, ImportRowStatus, ImportStatus, InvitationStatus, ProductStatus, ProductSubmissionStatus, ReturnStatus, SellerRequirementSubmissionStatus, SellerStatus, ShippingLabelStatus, StockLocationKind } from './Enums'@@ -9,6 +9,7 @@ export type { default as OptionType } from './OptionType'export type { default as OptionValue } from './OptionValue'export type { default as PriceHistory } from './PriceHistory'export type { default as Price } from './Price'+export type { default as Account } from './Account'export type { default as Balance } from './Balance'export type { default as ClaimLineItem } from './ClaimLineItem'export type { default as Claim } from './Claim'diff --git a/packages/seller-sdk/src/types/index.ts b/packages/seller-sdk/src/types/index.tsindex e7525a883f..c05a9d44ee 100644--- a/packages/seller-sdk/src/types/index.ts+++ b/packages/seller-sdk/src/types/index.ts@@ -13,7 +13,7 @@ export type {// drift apart silently.export * from './generated'-import type { default as TeamMember } from './generated/TeamMember'+import type { default as Account } from './generated/Account'/*** A seller as the login and `/me` responses summarise it — enough for the@@ -29,7 +29,13 @@ export interface SellerSummary {/** What the login and refresh endpoints answer. */export interface AuthTokens {token: string- user: TeamMember+ /**+ * `Account`, not `TeamMember`: the panel adopts the signed-in person's saved+ * language from this payload at sign-in, which is what carries the choice to+ * a second browser. Serialized only for the person signing in, so it does+ * not publish a colleague's preference the way widening the team shape would.+ */+ user: Accountsellers: SellerSummary[]}diff --git a/spree/api/app/controllers/spree/api/v3/seller/auth_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/auth_controller.rbindex ef9642cc68..92578a66c6 100644--- a/spree/api/app/controllers/spree/api/v3/seller/auth_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/seller/auth_controller.rb@@ -136,7 +136,7 @@ module Spreedef auth_response(user){token: generate_jwt(user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER),- user: Spree.api.seller_team_member_serializer.new(user, params: { store: user.sellers.first&.store }).to_h,+ user: Spree.api.seller_account_serializer.new(user, params: { store: user.sellers.first&.store }).to_h,sellers: serialized_sellers(user)}enddiff --git a/spree/api/app/controllers/spree/api/v3/seller/invitation_acceptances_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/invitation_acceptances_controller.rbindex fa7712c010..f4d175fa5f 100644--- a/spree/api/app/controllers/spree/api/v3/seller/invitation_acceptances_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/seller/invitation_acceptances_controller.rb@@ -127,7 +127,7 @@ module Spreedef auth_response(user){token: generate_jwt(user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER),- user: Spree.api.seller_team_member_serializer.new(+ user: Spree.api.seller_account_serializer.new(user, params: { store: @invitation.store }).to_h,sellers: serialized_sellers(user)diff --git a/spree/api/app/controllers/spree/api/v3/seller/me_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/me_controller.rbindex a30a5e0674..e27765e374 100644--- a/spree/api/app/controllers/spree/api/v3/seller/me_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/seller/me_controller.rb@@ -20,11 +20,32 @@ module Spreerender json: me_responseend+ # Self-service update of the signed-in person's own account — the+ # name and photo their team sees, and the panel's language. It+ # operates on `current_user` directly, so it needs no per-record+ # authorization, and no seller role either: this is theirs whichever+ # seller they are acting for.+ #+ # Distinct from PATCH /profile, which writes the seller business.+ # `avatar` accepts an ActiveStorage direct-upload signed id to set+ # the photo, or `null` to remove it.+ def update+ if current_user.update(permitted_params)+ render json: me_response+ else+ render_validation_error(current_user.errors)+ end+ end+private+ def permitted_params+ params.permit(:selected_locale, :first_name, :last_name, :avatar)+ end+def me_response{- user: Spree.api.seller_team_member_serializer.new(current_user, params: serializer_params).to_h,+ user: Spree.api.seller_account_serializer.new(current_user, params: serializer_params).to_h,sellers: serialized_sellers,# Both shapes, exactly as the admin `/me`: the panel's `<Can>`# reads CanCanCan rules, the key gate reads keys. Sending onlydiff --git a/spree/api/app/controllers/spree/api/v3/seller/password_resets_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/password_resets_controller.rbindex c58146a6bf..b6ce7577c9 100644--- a/spree/api/app/controllers/spree/api/v3/seller/password_resets_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/seller/password_resets_controller.rb@@ -128,7 +128,7 @@ module Spreedef auth_response(user){token: generate_jwt(user, audience: Spree::Api::V3::JwtAuthentication::JWT_AUDIENCE_SELLER),- user: Spree.api.seller_team_member_serializer.new(+ user: Spree.api.seller_account_serializer.new(user, params: { store: seller_store(user) }).to_h,sellers: serialized_sellers(user)diff --git a/spree/api/app/serializers/spree/api/v3/seller/account_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/account_serializer.rbnew file mode 100644index 0000000000..f202afc94d--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/seller/account_serializer.rb@@ -0,0 +1,19 @@+module Spree+ module Api+ module V3+ module Seller+ # The signed-in person's own account, as `/me` answers it.+ #+ # Extends the team member shape rather than widening it: `selected_locale`+ # is a preference its owner sets, and the team list serializes colleagues+ # with the parent — where publishing each member's chosen language would+ # tell the whole team something none of them asked to share.+ class AccountSerializer < Seller::TeamMemberSerializer+ typelize selected_locale: [:string, nullable: true]++ attributes :selected_locale+ end+ end+ end+ end+enddiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex f48968beea..00cbcfbd45 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -875,6 +875,10 @@ Spree::Core::Engine.add_routes dopatch 'auth/password_resets/:id', to: 'password_resets#update'get 'me', to: 'me#show'+ # Self-service edits to the signed-in person's own account — their+ # name, photo and panel language. Distinct from `profile`, which is+ # the seller business they act for.+ patch 'me', to: 'me#update'# Singular: the seller in play is always `current_seller`.resource :profile, only: [:show, :update], controller: 'profile'diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rbindex 1b7da6c051..c462d547db 100644--- a/spree/api/lib/spree/api/dependencies.rb+++ b/spree/api/lib/spree/api/dependencies.rb@@ -187,6 +187,7 @@ module Spreeseller_profile_serializer: 'Spree::Api::V3::Seller::ProfileSerializer',seller_policy_serializer: 'Spree::Api::V3::Seller::PolicySerializer',seller_team_member_serializer: 'Spree::Api::V3::Seller::TeamMemberSerializer',+ seller_account_serializer: 'Spree::Api::V3::Seller::AccountSerializer',seller_invitation_serializer: 'Spree::Api::V3::Seller::InvitationSerializer',seller_product_serializer: 'Spree::Api::V3::Seller::ProductSerializer',seller_product_type_serializer: 'Spree::Api::V3::Seller::ProductTypeSerializer',diff --git a/spree/api/lib/spree/api/openapi/schema_helper.rb b/spree/api/lib/spree/api/openapi/schema_helper.rbindex 050b63284e..fb806e2f2b 100644--- a/spree/api/lib/spree/api/openapi/schema_helper.rb+++ b/spree/api/lib/spree/api/openapi/schema_helper.rb@@ -250,8 +250,8 @@ module Spree## The seller branch has no API-key credential, so its AuthResponse is# neither the store's nor the admin's: signing in returns the JWT, the- # team member who signed in, and the sellers they may act for — the- # panel cannot make another request until it has picked one.+ # person who signed in, and the sellers they may act for — the panel+ # cannot make another request until it has picked one.def seller_schemasschemas = common_schemas@@ -259,7 +259,10 @@ module Spreetype: :object,properties: {token: { type: :string, description: 'JWT access token, `seller_api` audience' },- user: { '$ref' => '#/components/schemas/TeamMember' },+ # `Account`, not `TeamMember`: the panel adopts the signed-in+ # person's saved language from this payload, which is what+ # carries the choice to a second browser.+ user: { '$ref' => '#/components/schemas/Account' },sellers: {type: :array,description: 'The sellers this user may act for. Pick one and send its `id` as `X-Spree-Seller-Id` on every subsequent request.',@@ -309,7 +312,10 @@ module Spreetype: :object,description: 'The signed-in user, the sellers they may act for, and what they may do on the selected one',properties: {- user: { '$ref' => '#/components/schemas/TeamMember' },+ # `Account`, not `TeamMember`: the person reading their own+ # record also sees the panel language they chose, which the+ # team list does not publish about a colleague.+ user: { '$ref' => '#/components/schemas/Account' },sellers: { type: :array, items: { '$ref' => '#/components/schemas/SellerMeSummary' } },permissions: { type: :array, items: { '$ref' => '#/components/schemas/PermissionRule' } },permission_keys: {diff --git a/spree/api/spec/controllers/spree/api/v3/seller/auth_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/auth_controller_spec.rbindex 087e482ddb..b3c036218c 100644--- a/spree/api/spec/controllers/spree/api/v3/seller/auth_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/seller/auth_controller_spec.rb@@ -29,6 +29,18 @@ RSpec.describe Spree::Api::V3::Seller::AuthController, type: :controller doexpect(json_response['sellers'].pluck('id')).to eq([seller.prefixed_id])end+ # The panel adopts the account's saved language from this payload at+ # sign-in — that is what carries the choice to a second browser, where+ # localStorage has nothing. Serialized with the account serializer for+ # exactly this; the team shape has no locale.+ it 'returns the language the account chose' do+ seller_user.update!(selected_locale: 'de')++ post :create, params: { email: seller_user.email, password: 'secret123' }, as: :json++ expect(json_response['user']['selected_locale']).to eq('de')+ end+it 'refuses a store staff member who runs no seller' dostaff = create(:admin_user, password: 'secret123', password_confirmation: 'secret123')diff --git a/spree/api/spec/controllers/spree/api/v3/seller/me_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/me_controller_spec.rbindex 9676da11d1..2ce6308aff 100644--- a/spree/api/spec/controllers/spree/api/v3/seller/me_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/seller/me_controller_spec.rb@@ -61,4 +61,137 @@ RSpec.describe Spree::Api::V3::Seller::MeController, type: :controller doexpect(json_response['permissions']).to eq([])end++ describe 'PATCH #update' do+ subject { patch :update, params: params, as: :json }++ context 'with a name' do+ let(:params) { { first_name: 'Ada', last_name: 'Lovelace' } }++ it 'persists the name and returns it' do+ subject++ expect(response).to have_http_status(:ok)+ expect(json_response['user']['full_name']).to eq('Ada Lovelace')+ expect(seller_user.reload.first_name).to eq('Ada')+ end+ end++ # An emptied field is how a person removes a name they once gave: the+ # model normalizes blank to nil, so the panel sends the empty string+ # rather than omitting the field.+ context 'with a blank name' do+ before { seller_user.update!(first_name: 'Ada', last_name: 'Lovelace') }++ let(:params) { { first_name: '', last_name: '' } }++ it 'clears it' do+ subject++ expect(response).to have_http_status(:ok)+ expect(seller_user.reload.first_name).to be_nil+ expect(json_response['user']['full_name']).to be_nil+ end+ end++ # The panel language is a client concern — the seller panel ships its own+ # locale bundles — so the API stores whatever code it is sent.+ context 'with a locale code' do+ let(:params) { { selected_locale: 'pl' } }++ it 'persists the locale' do+ subject++ expect(response).to have_http_status(:ok)+ expect(json_response['user']['selected_locale']).to eq('pl')+ expect(seller_user.reload.selected_locale).to eq('pl')+ end+ end++ # The account is the person's own, so it answers before a seller is named+ # — the same exemption `show` relies on.+ it 'updates before a seller is chosen' do+ patch :update, params: { first_name: 'Grace' }, as: :json++ expect(response).to have_http_status(:ok)+ expect(seller_user.reload.first_name).to eq('Grace')+ end++ # One photo, used both as a fresh upload and as the already-attached+ # avatar the clear case removes.+ let(:image_attributes) do+ {+ io: File.open(Spree::Core::Engine.root.join('spec', 'fixtures', 'thinking-cat.jpg')),+ filename: 'avatar.jpg',+ content_type: 'image/jpeg'+ }+ end++ context 'with an avatar signed id' do+ let(:blob) { ActiveStorage::Blob.create_and_upload!(**image_attributes) }+ let(:params) { { avatar: blob.signed_id } }++ it 'attaches the avatar and returns its url' do+ subject++ expect(response).to have_http_status(:ok)+ expect(seller_user.reload.avatar).to be_attached+ expect(json_response['user']['avatar_url']).to be_present+ end+ end++ context 'with a non-image avatar' do+ let(:blob) do+ ActiveStorage::Blob.create_and_upload!(+ io: StringIO.new('<svg xmlns="http://www.w3.org/2000/svg"></svg>'),+ filename: 'avatar.svg',+ content_type: 'image/svg+xml'+ )+ end+ let(:params) { { avatar: blob.signed_id } }++ it 'rejects the upload with a validation error' do+ subject++ expect(response).to have_http_status(:unprocessable_content)+ expect(seller_user.reload.avatar).not_to be_attached+ end+ end++ context 'clearing the avatar' do+ before { seller_user.avatar.attach(**image_attributes) }+ let(:params) { { avatar: nil } }++ it 'purges the avatar' do+ subject++ expect(response).to have_http_status(:ok)+ expect(seller_user.reload.avatar).not_to be_attached+ expect(json_response['user']['avatar_url']).to be_nil+ end+ end++ # A seller writes their own account and nothing else through it — the+ # marketplace decides which sellers they may act for.+ context 'with an attribute the endpoint does not accept' do+ let(:params) { { first_name: 'Ada', email: '[email protected]' } }++ it 'ignores it' do+ subject++ expect(response).to have_http_status(:ok)+ expect(seller_user.reload.email).not_to eq('[email protected]')+ end+ end++ context 'without authentication' do+ before { request.headers['Authorization'] = nil }++ it 'returns unauthorized' do+ patch :update, params: { first_name: 'Ada' }, as: :json++ expect(response).to have_http_status(:unauthorized)+ end+ end+ endenddiff --git a/spree/api/spec/integration/spree/api/v3/seller/me_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/me_spec.rbindex 996c9a7086..f5fa4bcdd4 100644--- a/spree/api/spec/integration/spree/api/v3/seller/me_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/seller/me_spec.rb@@ -47,5 +47,74 @@ RSpec.describe 'Seller Account API', type: :request, swagger_doc: 'api-referencerun_test!endend++ patch 'Update your account' do+ tags 'Account'+ consumes 'application/json'+ produces 'application/json'+ security [bearer_auth: []]+ description <<~DESC+ Edits the signed-in person's own account — the name and photo their team+ sees, and the language their panel displays.++ This is the person, not the business: the seller they act for is+ `PATCH /profile`. Like `GET /me` it answers without+ `X-Spree-Seller-Id`, because the account is the same whichever seller+ they are acting for.++ `avatar` takes an ActiveStorage direct-upload signed id to set the+ photo, or `null` to remove it; omit it to leave the current one alone.+ `email` is identity-bound and cannot be changed here.+ DESC++ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ first_name: { type: :string, example: 'Ada' },+ last_name: { type: :string, example: 'Lovelace' },+ selected_locale: { type: :string, example: 'de', description: 'Panel display language, as a code the panel ships.' },+ avatar: { type: :string, nullable: true, description: 'Direct-upload signed id, or `null` to remove the photo.' }+ }+ }++ response '200', 'account updated' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:body) { { first_name: 'Ada', last_name: 'Lovelace' } }++ schema '$ref' => '#/components/schemas/SellerMeResponse'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['user']['full_name']).to eq('Ada Lovelace')+ end+ end++ # The only way this endpoint refuses a well-formed request: the photo+ # must be a web image, since a seller's avatar is rendered in a browser.+ response '422', 'the photo is not a web image' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:blob) do+ ActiveStorage::Blob.create_and_upload!(+ io: StringIO.new('<svg xmlns="http://www.w3.org/2000/svg"></svg>'),+ filename: 'avatar.svg',+ content_type: 'image/svg+xml'+ )+ end+ let(:body) { { avatar: blob.signed_id } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end++ response '401', 'missing or invalid token' do+ let(:Authorization) { nil }+ let(:body) { { first_name: 'Ada' } }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test!+ end+ endendend