Sharetribe

Sharetribe

Operator-level surface for a Sharetribe marketplace. Every tool runs as the marketplace operator across the entire tenancy — there is no per-user scoping at this level. Users sign up via the marketplace front-end (Marketplace API), not through this surface; create-user is intentionally absent because Sharetribe does not expose it on the Integration API.

Resource hierarchy

• Marketplace — the tenancy. One per credential pair. Carries name, description, currency.
• Users — accounts on the marketplace. State is active, pendingApproval, banned, or deleted. Each user has a permission set controlling whether they can post listings, initiate transactions, and read marketplace content.
• Listings — offers (products / services / bookable assets). State is draft, pendingApproval, published, or closed. Listings carry a price Money object (amount in minor units + ISO 4217 currency), an availabilityPlan for time-based bookings, and free-form publicData / privateData / metadata extended-data objects.
• Transactions — purchases or bookings against a listing. Each transaction runs a transaction process (e.g. default-booking/release-1) which defines the allowed states and transitions. A transaction's lastTransition tells you where it is in the process.
• Availability exceptions — per-listing overrides on top of the listing's availabilityPlan. Block out holidays with seats=0; add extra capacity with seats>=1.
• Stock — per-listing inventory for purchase processes. Two write surfaces: set_stock is compare-and-set (race-safe); create_stock_adjustment is unconditional signed delta.
• Stock reservations — read-only allocations created automatically by purchase-process transactions during checkout.
• Events — append-only audit log of every mutation across the tenancy.

Pattern: combined get_* tools

Read tools that target a list-able resource accept an optional id:

• No id → query the collection with page + per_page (default 25, max 100), plus resource-specific filters.
• With id → fetch the single entity. The same include (JSON:API side-load) applies on both branches.

include accepts a comma-separated string or a list — both "author,images" and ["author","images"] work.

Pattern: combined upsert_listing

The upsert listing tool selects create (no id) vs update (with id) automatically. On create, title and authorId are required and state must be published or pendingApproval. On update, every field is a partial overwrite; extended-data objects merge at the top level and top-level null keys are removed.

Listing photos: upload_image → upsert_listing

The Integration API exposes a multipart image upload surface. Workflow:

1. Upload the image with file_url or file_content_base64 + filename.
2. Capture the returned id (image UUID).
3. Pass images: ["<uuid>"] on listing create or update.

Each image UUID attaches to one listing only. HTTP 409 image-invalid means the UUID is missing or already used elsewhere — upload a fresh image and retry. Omit images to publish without photos.

Money objects

Sharetribe represents money as {amount: <integer>, currency: <ISO 4217>}. Amount is in minor units — {amount: 1590, currency: "USD"} is $15.90, not $1,590. Always pass minor units when creating or updating prices, and always interpret returned amounts as minor units.

Pagination semantics

Sharetribe pagination is integer page (1-indexed) plus perPage, NOT an opaque cursor token. The wrapper normalizes list responses to {items, page, per_page, total, total_pages, has_more, next_page, included} so callers can iterate without parsing meta themselves.

The events stream is the exception: it advertises paginationUnsupported: true and returns total: null / total_pages: null / has_more: null. Walk it with createdAtStart + createdAtEnd windows or with the startAfterSequenceId forward cursor.

Transaction transitions

Transactions are state machines. To move a transaction along its process, call the transition transaction tool with the transaction id and the transition name (e.g. transition/accept, transition/cancel, transition/mark-delivered). The transition's params shape depends on the process definition — consult the marketplace's transaction process. Set speculative=true to validate a transition and produce the resulting transaction shape WITHOUT committing; useful for previewing line-item math before charging.

State-transition operations on listings and users

• Close listing / open listing — hide / un-hide a listing without deleting. Reversible.
• Approve listing — only relevant when the marketplace requires operator approval; otherwise listings reach published on create.
• Approve user — moves a user from pendingApproval to active.
• Update user permissions — operator-level allow/deny on postListings, initiateTransactions, read. Effect is immediate.

Operational order

1. Confirm the marketplace tenancy answers (get_marketplace) before anything credential-sensitive.
2. Discover the relevant author when working with listings — get_users first, capture the user id, then create / query listings filtered by authorId.
3. For booking flows, confirm the listing's availabilityPlan and any availability_exceptions in the booking window before transitioning a transaction.
4. For purchase flows, check current stock with get_listings (include=currentStock) before transitioning; use set_stock (CAS) for absolute updates and create_stock_adjustment for incremental deltas.
5. Use get_events as the canonical audit source after any operator mutation — events surface what actually happened upstream, not what the API call appeared to do.

Gotchas

• No user create. Sharetribe Integration API does not expose users/create; users sign up via the Marketplace API / front-end. Tools assume the user already exists.
• Listing images — upload via the Integration API image upload tool (returns an image UUID), then pass images: ["<uuid>", ...] on upsert listing. Do not pass URLs, local paths, or placeholder IDs. HTTP 409 image-invalid means the UUID is missing or already used on another listing. Omit images to publish without photos.
• No user delete on this surface either. No users/delete endpoint exists on the Integration API. User deletion is a marketplace-admin-console operation. To soft-disable a user from the Integration API, use update_user_permissions to deny postListings / initiateTransactions / read.
• Transitions can be permission-gated. Some processes restrict certain transitions to specific actors (customer-only, provider-only). Operator transitions go through unconditionally; if you see an upstream permission/denied error, the process definition is gating the transition rather than auth failing.
• expand=true is on by default for every write tool — the response is the full updated entity, not just the id. Set expand=false to opt into a smaller response.
• Closed-listing edits. A closed listing can still be updated (upsert_listing with id) but will not become visible until open_listing is called.
• Events are returned OLDEST-FIRST. get_events page 1 is the oldest events on the marketplace, not the newest. There is no descending sort. To answer "most recent N events", pass createdAtStart=<recent ISO timestamp> to narrow the window, or walk the stream with startAfterSequenceId until exhausted and read the tail. Do NOT call page-1 results "the most recent".
• set_stock is CAS-only — oldTotal and newTotal are REQUIRED. Sharetribe's compare_and_set body uses listingId, oldTotal, and newTotal (not total). Read current stock first via get_listings(id=<listing>, include='currentStock') and pass that value as oldTotal. If you don't have the current value or don't want a race-safe write, use create_stock_adjustment with a signed quantity instead — that endpoint is unconditional and incremental.
• All time-window arguments require explicit timezone. ISO-8601 timestamps passed to availability tools, stock-adjustment queries, transaction filters, and event windows MUST include a Z suffix or full UTC offset (e.g. +01:00). Naive timestamps are rejected with HTTP 400. When converting local times, account for DST yourself — UK in May is BST (UTC+1), so 9am UK = 08:00:00Z.