Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.yaml
index 236f53b971..fd41966380 100644
--- a/docs/api-reference/seller.yaml
+++ b/docs/api-reference/seller.yaml
@@ -91,6 +91,7 @@ paths:
full_name: Jan Cummerata
created_at: '2026-01-15T12:00:00.000Z'
avatar_url:
+ selected_locale:
sellers:
- id: sel_UkLWZg9DAJ
name: Seller 1
@@ -157,6 +158,7 @@ paths:
full_name: Magdalen Hayes
created_at: '2026-01-15T12:00:00.000Z'
avatar_url:
+ selected_locale:
sellers:
- id: sel_UkLWZg9DAJ
name: Seller 3
@@ -202,512 +204,326 @@ paths:
kind: password
schema:
"$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 balances
tags:
- - 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: header
required: true
- description: The token from the emailed link
schema:
type: string
responses:
'200':
- description: invitation found
- content:
- application/json:
- example:
- id: inv_UkLWZg9DAJ
- 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 listed
content:
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_id
in: path
- description: Invitation ID from the emailed link
+ description: Prefixed order ID
required: true
schema:
type: string
- post:
- summary: Accept an invitation
+ get:
+ summary: List claims
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.
+ - 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: header
required: true
- description: The token from the emailed link
schema:
type: string
responses:
'200':
- description: invitation accepted, session issued
- content:
- application/json:
- example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjRmYzVlNzBmLWU1ODAtNDExNi1hOWU5LTBjNDliMGExYjMxNCIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.H0mJ1zDqTi6mNs_BZBRTJ77OMsWAqeUXvQM09YPLefs
- user:
- id: adm_gbHJdmfrXB
- 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 listed
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/auth/password_resets":
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Claim"
+ required:
+ - data
post:
- summary: Request password reset
+ summary: Open a claim
tags:
- - 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: string
responses:
- '202':
- description: reset requested
+ '201':
+ description: claim opened
content:
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: object
properties:
- 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
- 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: true
required:
- - email
- "/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: string
patch:
- summary: Reset password
+ summary: Approve a claim
tags:
- - 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: header
required: true
schema:
type: string
responses:
'200':
- description: password reset
+ description: claim approved
content:
application/json:
- example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImJjMDM3NTNhLTEzN2MtNGM1Zi1hMzM2LWUzMjBlZTNiMjQ5YyIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.EASrzbGpJVyAl10SJyzs8na68Wmvedkm7G66wTBq_0k
- user:
- id: adm_UkLWZg9DAJ
- 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: approved
schema:
- "$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 resolved
content:
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: object
properties:
- 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: string
required:
- - 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 reasons
tags:
- - Account
+ - Claims
security:
- 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-Id
in: header
- required: false
- description: The seller to report capability for. Omit to list sellers without
- narrowing permissions.
+ required: true
schema:
type: string
responses:
'200':
- description: current user returned
+ description: reasons listed
content:
application/json:
example:
- user:
- id: adm_UkLWZg9DAJ
- 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 upload
tags:
- - Onboarding
+ - Uploads
security:
- 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-Id
in: header
@@ -13017,43 +12833,62 @@ paths:
schema:
type: string
responses:
- '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 created
content:
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==--8689a8a2636cd26ac1081498c4c5d7b905fcd0ee
schema:
- "$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 exchanges
tags:
- - Onboarding
+ - Exchanges
security:
- 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-Id
in: header
@@ -13062,55 +12897,137 @@ paths:
type: string
responses:
'200':
- description: submitted for review
+ description: exchanges listed
content:
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 opened
content:
application/json:
- example:
- error:
- code: processing_error
- message: Requirements Accept terms is not complete
schema:
- "$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: id
in: path
- description: Requirement ID, as returned by `GET /api/v3/seller/onboarding`
required: true
schema:
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 export
tags:
- - Onboarding
+ - Exports
security:
- 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-Id
in: header
@@ -13119,30 +13036,31 @@ paths:
type: string
responses:
'201':
- description: submission recorded
+ description: export queued
content:
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: csv
created_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 seller
content:
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: object
properties:
- 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: id
in: path
- description: Submission ID
+ description: Export ID
required: true
schema:
type: string
get:
- summary: Download a submitted document
+ summary: Get an export
tags:
- - Onboarding
+ - Exports
security:
- 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-Id
in: header
@@ -13189,63 +13117,162 @@ paths:
schema:
type: string
responses:
+ '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 export
content:
application/json:
example:
error:
code: record_not_found
- message: Seller requirement submission not found
- application/octet-stream:
+ message: Export not found
schema:
"$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: string
get:
- summary: List policies
+ summary: Download an export
tags:
- - Policies
+ - Exports
security:
- 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-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)
+ 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: true
schema:
- type: integer
+ type: string
responses:
'200':
- description: policies listed
+ description: fulfillments listed
content:
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: 1
limit: 25
@@ -13262,24 +13289,38 @@ paths:
data:
type: array
items:
- "$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 parcel
tags:
- - Policies
+ - Fulfillments
security:
- 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-Id
in: header
@@ -13287,52 +13328,113 @@ paths:
schema:
type: string
responses:
- '201':
- description: policy created
+ '200':
+ description: parcel shipped
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'
+ 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: object
properties:
- 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: id
in: path
required: true
- description: Policy prefixed ID or slug
schema:
type: string
- get:
- summary: Get a policy
+ patch:
+ summary: Update tracking
tags:
- - Policies
+ - Fulfillments
security:
- 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-Id
in: header
@@ -13341,76 +13443,92 @@ paths:
type: string
responses:
'200':
- description: policy found
+ description: tracking recorded
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'
+ 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: object
properties:
- 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 parcel
tags:
- - Policies
+ - Fulfillments
security:
- 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-Id
in: header
@@ -13418,236 +13536,329 @@ paths:
schema:
type: string
responses:
- '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 carriers
tags:
- - Product Types
+ - Fulfillments
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.
+ 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-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
+ description: carriers 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:
+ - 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
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}":
+ 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: string
get:
- summary: Get a product type
+ summary: Look up an invitation
tags:
- - 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: query
required: true
+ description: The token from the emailed link
schema:
type: string
- - name: id
- in: path
+ responses:
+ '200':
+ description: invitation found
+ content:
+ application/json:
+ example:
+ id: inv_UkLWZg9DAJ
+ 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: query
required: true
- description: Product type ID
+ description: The token from the emailed link
schema:
type: string
responses:
'200':
- description: product type found
+ description: invitation accepted, session issued
content:
application/json:
example:
- id: pt_UkLWZg9DAJ
- name: Apparel
- option_type_labels: []
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjRmYzVlNzBmLWU1ODAtNDExNi1hOWU5LTBjNDliMGExYjMxNCIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.H0mJ1zDqTi6mNs_BZBRTJ77OMsWAqeUXvQM09YPLefs
+ user:
+ id: adm_gbHJdmfrXB
+ 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: approved
schema:
- "$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 invitations
tags:
- - Products
+ - Team
security:
- 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-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: products listed
+ description: invitations listed
content:
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
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: object
properties:
data:
type: array
items:
- "$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 invitation
tags:
- - Products
+ - Team
security:
- 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-Id
in: header
@@ -13655,141 +13866,45 @@ paths:
schema:
type: string
responses:
- '201':
- description: product created
+ '200':
+ description: invitation resent
content:
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
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 invitation
content:
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 found
schema:
"$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: id
in: path
- description: Product ID
+ description: Invitation ID
required: true
schema:
type: string
- get:
- summary: Get a product
+ delete:
+ summary: Revoke an invitation
tags:
- - Products
+ - Team
security:
- 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-Id
in: header
@@ -13797,1078 +13912,387 @@ paths:
schema:
type: string
responses:
- '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 invitation
content:
application/json:
example:
error:
code: record_not_found
- message: Product not found
+ message: Invitation not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a product
+ "/api/v3/seller/me":
+ get:
+ summary: Current user
tags:
- - Products
+ - Account
security:
- 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-Id
in: header
- required: true
+ required: false
+ description: The seller to report capability for. Omit to list sellers without
+ narrowing permissions.
schema:
type: string
responses:
'200':
- description: product updated
+ description: current user returned
content:
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
- billing_email:
- type: string
- format: email
- nullable: true
- 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
- 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
- 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
- first_name: Bill
- last_name: Towne
- full_name: Bill Towne
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Nadia
+ last_name: Effertz
+ full_name: Nadia Effertz
created_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_products
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
- 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 token
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
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- required:
- - email
- "/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 account
tags:
- - Team
+ - Account
security:
- 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 updated
content:
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
+ 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 image
content:
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 token
content:
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 required
schema:
- "$ref": "#/components/schemas/DirectUploadResponse"
+ "$ref": "#/components/schemas/ErrorResponse"
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/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 checklist
tags:
- - Earnings
+ - Onboarding
security:
- 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-Id
in: header
@@ -14877,105 +14301,42 @@ paths:
type: string
responses:
'200':
- description: balances listed
+ description: checklist returned
content:
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 it
content:
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 review
tags:
- - Claims
+ - Onboarding
security:
- 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-Id
in: header
@@ -14983,204 +14344,265 @@ paths:
schema:
type: string
responses:
- '201':
- description: claim opened
+ '200':
+ description: submitted for review
content:
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 orders
tags:
- - Claims
+ - Orders
security:
- 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-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: claim approved
+ description: orders listed
content:
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: id
in: path
+ description: Prefixed order ID
required: true
schema:
type: string
- patch:
- summary: Resolve a claim
+ get:
+ summary: Get an order
tags:
- - Claims
+ - Orders
security:
- 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-Id
in: header
@@ -15189,143 +14611,195 @@ paths:
type: string
responses:
'200':
- description: claim denied
+ description: order found
content:
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 York
schema:
- "$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 order
content:
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 found
schema:
- 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: id
in: path
description: Prefixed order ID
required: true
schema:
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 order
tags:
- - Exchanges
+ - Orders
security:
- 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-Id
in: header
@@ -15333,134 +14807,55 @@ paths:
schema:
type: string
responses:
- '201':
- description: exchange opened
+ '200':
+ description: order canceled
content:
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_UkLWZg9DAJ
schema:
- "$ref": "#/components/schemas/Exchange"
+ "$ref": "#/components/schemas/Order"
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:
+ cancel_reason_id:
type: string
nullable: true
- memo:
+ description: A reason from GET /order_cancellation_reasons
+ cancel_note:
type: string
nullable: 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: id
in: path
+ description: Prefixed order ID
required: true
schema:
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:
- 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 address
tags:
- - Exports
+ - Orders
security:
- 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-Id
in: header
@@ -15468,81 +14863,266 @@ paths:
schema:
type: string
responses:
- '201':
- description: export queued
+ '200':
+ description: address corrected
content:
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 York
schema:
- "$ref": "#/components/schemas/Export"
+ "$ref": "#/components/schemas/Order"
'422':
- description: type cannot be scoped to one seller
+ description: neither address named
content:
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 required
requestBody:
content:
application/json:
schema:
type: object
properties:
- 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_id
in: path
- description: Export ID
+ description: Prefixed order ID
required: true
schema:
type: string
get:
- summary: Get an export
+ summary: Get order notes
tags:
- - Exports
+ - Orders
security:
- 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-Id
in: header
@@ -15551,101 +15131,171 @@ paths:
type: string
responses:
'200':
- description: export found
+ description: notes
content:
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 notes
tags:
- - Fulfillments
+ - Orders
security:
- 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-Id
in: header
@@ -15654,11 +15304,66 @@ paths:
type: string
responses:
'200':
- description: fulfillments listed
+ description: notes updated
content:
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_UkLWZg9DAJ
number: R1001-F1
status: 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 Hartmann
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
+ name: Product 1995749
+ sku: SKU-265
options_text: ''
selected_delivery_rate_id: dr_gbHJdmfrXB
delivery_rates:
- id: dr_gbHJdmfrXB
- name: UPS Ground 81
+ name: UPS Ground 94
selected: true
cost: '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: false
meta:
page: 1
limit: 25
- count: 1
+ count: 2
pages: 1
from: 1
- to: 1
- in: 1
+ to: 2
+ in: 2
previous:
next:
schema:
@@ -15722,38 +15631,23 @@ paths:
data:
type: array
items:
- "$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 type
tags:
- - Fulfillments
+ - Package Types
security:
- 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-Id
in: header
@@ -15761,207 +15655,106 @@ paths:
schema:
type: string
responses:
- '200':
- description: parcel shipped
+ '201':
+ description: package type created
content:
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: true
schema:
- "$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 error
content:
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 list
schema:
- "$ref": "#/components/schemas/Fulfillment"
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
properties:
- tracking:
+ name:
+ type: string
+ kind:
type: string
+ enum:
+ - box
+ - envelope
+ - carton
+ - pallet
+ - container
+ length:
+ type: number
nullable: true
- tracking_carrier:
+ width:
+ type: number
+ nullable: true
+ height:
+ type: number
+ nullable: true
+ dimensions_unit:
type: string
nullable: 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: id
in: path
required: true
+ description: Package type ID
schema:
type: string
- patch:
- summary: Cancel a parcel
+ get:
+ summary: Get a package type
tags:
- - Fulfillments
+ - Package Types
security:
- 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-Id
in: header
@@ -15970,69 +15763,47 @@ paths:
type: string
responses:
'200':
- description: parcel canceled
+ description: package type found
content:
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: true
schema:
- "$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 type
tags:
- - Fulfillments
+ - Package Types
security:
- 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-Id
in: header
@@ -16041,494 +15812,306 @@ paths:
type: string
responses:
'200':
- description: carriers listed
+ description: package type updated
content:
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: true
schema:
- 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 type
tags:
- - Orders
+ - Package Types
security:
- 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-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: 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 requested
content:
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
+ redirect_url:
+ type: string
+ example: https://sellers.your-store.com/reset-password
+ description: Must match an allowed origin of the store; ignored
+ otherwise.
+ required:
+ - email
+ "/api/v3/seller/auth/password_resets/{id}":
+ patch:
+ summary: Reset password
tags:
- - Orders
- security:
- - bearer_auth: []
+ - Authentication
description: |
- 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 link
required: true
schema:
type: string
responses:
'200':
- description: order found
+ description: password reset
content:
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
+ first_name: Ariana
+ last_name: Wiza
+ full_name: Ariana Wiza
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 York
+ avatar_url:
+ selected_locale:
+ sellers:
+ - id: sel_UkLWZg9DAJ
+ name: Seller 80
+ status: approved
schema:
- "$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 listed
content:
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: id
in: path
- description: Prefixed order ID
required: true
+ description: Payout prefixed ID
schema:
type: string
- patch:
- summary: Cancel an order
+ get:
+ summary: Get a payout
tags:
- - Orders
+ - Earnings
security:
- 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-Id
in: header
@@ -16537,642 +16120,482 @@ paths:
type: string
responses:
'200':
- description: order canceled
+ description: payout found
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R1001
- customer_note:
+ id: vpo_UkLWZg9DAJ
+ status: pending
currency: 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: 1
schema:
- "$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 policies
tags:
- - Orders
+ - Policies
security:
- 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-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: address corrected
+ description: policies listed
content:
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 found
content:
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: object
properties:
- 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: header
required: 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 products
tags:
- - Orders
+ - Products
security:
- 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-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: notes
+ description: products listed
content:
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_UkLWZg9DAJ
thumbnail_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 product
tags:
- - Orders
+ - Products
security:
- 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-Id
in: header
@@ -17180,198 +16603,141 @@ paths:
schema:
type: string
responses:
- '200':
- description: notes updated
+ '201':
+ description: product created
content:
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_UkLWZg9DAJ
schema:
- "$ref": "#/components/schemas/Order"
+ "$ref": "#/components/schemas/Product"
'422':
- description: neither note named
+ description: validation failed
content:
application/json:
example:
error:
code: validation_error
- message: customer_note or internal_note is required
+ message: Name can't be blank
details:
- base:
- - customer_note or internal_note is required
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
properties:
- 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: string
get:
- summary: List order cancellation reasons
+ summary: Get a product
tags:
- - Orders
+ - Products
security:
- 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-Id
in: header
@@ -17380,151 +16746,77 @@ paths:
type: string
responses:
'200':
- description: reasons listed
+ description: product returned
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:
+ 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:
- 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 product
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: 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 found
schema:
- 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 product
tags:
- - Package Types
+ - Products
security:
- 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-Id
in: header
@@ -17532,42 +16824,57 @@ paths:
schema:
type: string
responses:
- '201':
- description: package type created
+ '200':
+ description: product updated
content:
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: active
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.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_UkLWZg9DAJ
schema:
- "$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: string
metadata:
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: header
required: 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 profile
tags:
- - Package Types
+ - Profile
security:
- 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-Id
in: header
@@ -17640,47 +16939,71 @@ paths:
type: string
responses:
'200':
- description: package type found
+ description: profile returned
content:
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: 0
schema:
- "$ref": "#/components/schemas/PackageType"
- '404':
- description: package type not found
+ "$ref": "#/components/schemas/Profile"
+ '403':
+ description: no seller named, or not a member of it
content:
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 profile
tags:
- - Package Types
+ - Profile
security:
- 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-Id
in: header
@@ -17689,28 +17012,53 @@ paths:
type: string
responses:
'200':
- description: package type updated
+ description: profile updated
content:
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 blank
schema:
- "$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: email
nullable: true
- width:
- type: number
+ billing_email:
+ type: string
+ format: email
nullable: true
- height:
- type: number
+ about:
+ type: string
nullable: true
- dimensions_unit:
+ description: Sanitized HTML — the seller's public description
+ legal_name:
type: string
nullable: true
- weight:
- type: number
+ description: The business a commission invoice is made out to
+ registration_number:
+ type: string
nullable: true
- max_weight:
- type: number
+ logo:
+ type: string
nullable: true
- weight_unit:
+ description: ActiveStorage signed id; `null` removes the attachment
+ square_logo:
type: string
nullable: 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 requirement
tags:
- - Earnings
+ - Onboarding
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]=…`.
+ 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-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 listed
+ '201':
+ description: submission recorded
content:
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: id
in: path
+ description: Submission ID
required: true
- description: Payout prefixed ID
schema:
type: string
get:
- summary: Get a payout
+ summary: Download a submitted document
tags:
- - Earnings
+ - Onboarding
security:
- 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-Id
in: header
required: 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 submission
content:
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 listed
content:
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: object
properties:
@@ -18003,23 +17296,6 @@ paths:
description: return opened
content:
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 approved
content:
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 listed
content:
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 location
tags:
- - Returns
+ - Stock Locations
security:
- 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-Id
in: header
@@ -18212,70 +17659,115 @@ paths:
schema:
type: string
responses:
- '200':
- description: return refunded
+ '201':
+ description: stock location created
content:
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 failed
content:
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: object
properties:
- amount:
+ name:
+ type: string
+ example: Main warehouse
+ company:
type: string
nullable: 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: id
in: path
+ description: Stock location ID
required: true
schema:
type: string
- patch:
- summary: Cancel a return
+ get:
+ summary: Get a stock location
tags:
- - Returns
+ - Stock Locations
security:
- 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-Id
in: header
@@ -18284,75 +17776,121 @@ paths:
type: string
responses:
'200':
- description: return canceled
+ description: stock location returned
content:
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 location
tags:
- - Returns
+ - Stock Locations
security:
- 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_validatable
message: 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
+ 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
+ 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
+ required:
+ - email
+ "/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: string
description: JWT access token, `seller_api` audience
user:
- "$ref": "#/components/schemas/TeamMember"
+ "$ref": "#/components/schemas/Account"
sellers:
type: array
description: The sellers this user may act for. Pick one and send its `id`
@@ -19124,7 +18816,7 @@ components:
may do on the selected one
properties:
user:
- "$ref": "#/components/schemas/TeamMember"
+ "$ref": "#/components/schemas/Account"
sellers:
type: array
items:
@@ -19567,6 +19259,40 @@ components:
- display_compare_at_amount
- price_list_id
x-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
+ - email
+ - first_name
+ - last_name
+ - full_name
+ - created_at
+ - avatar_url
+ - selected_locale
+ x-typelizer: true
Balance:
type: object
properties:
diff --git a/packages/seller-dashboard/src/api-client.ts b/packages/seller-dashboard/src/api-client.ts
index 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 the
diff --git a/packages/seller-dashboard/src/components/seller-switcher.tsx b/packages/seller-dashboard/src/components/seller-switcher.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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: Account
sellers: 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?: string
diff --git a/packages/seller-sdk/src/types/generated/Account.ts b/packages/seller-sdk/src/types/generated/Account.ts
new file mode 100644
index 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.ts
index 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.ts
index 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: Account
sellers: 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.rb
index 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 Spree
def 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)
}
end
diff --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.rb
index 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 Spree
def 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.rb
index 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 Spree
render json: me_response
end
+ # 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 only
diff --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.rb
index 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 Spree
def 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.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index f48968beea..00cbcfbd45 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -875,6 +875,10 @@ Spree::Core::Engine.add_routes do
patch '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.rb
index 1b7da6c051..c462d547db 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -187,6 +187,7 @@ module Spree
seller_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.rb
index 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_schemas
schemas = common_schemas
@@ -259,7 +259,10 @@ module Spree
type: :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 Spree
type: :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.rb
index 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 do
expect(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' do
staff = 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.rb
index 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 do
expect(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
+ end
end
diff --git a/spree/api/spec/integration/spree/api/v3/seller/me_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/me_spec.rb
index 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-reference
run_test!
end
end
+
+ 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
+ end
end
end