add_inventory_item

xyz.rubenayla.partle/marketplace · Verify this server

Add an item to the caller's personal inventory. Authenticated. Required OAuth scope: `inventory:write`. One creation tool covers all lifecycle states — set ``status`` based on the user's intent: "I bought" → ``owned``, "I want" → ``wanted``, "I'm selling" → ``for_sale``. Either ``product_id`` (linked to an existing Partle product) or ``name`` (freeform) must be set. **Not idempotent** — each call creates a new row. Args: name: Freeform name for items not yet linked to a Partle product. Either ``name`` or ``product_id`` must be set. product_id: Link to a canonical Partle product. status: Lifecycle. One of: ``owned``, ``wanted``, ``for_sale``, ``sold``, ``discarded``. Default ``owned``. quantity: How many. Fractional allowed. Default 1. notes: Freeform multi-line text — the dumping ground for anything not modeled as a column: extra URLs, comments, where stored, condition narrative, purpose, source, history, log entries. Markdown is fine. **Put extra URLs here, not in another field.** acquisition_price: What the user paid. acquisition_currency: Currency of acquisition_price. purchased_at: ISO date (YYYY-MM-DD) when it was acquired. asking_price: When status=for_sale, asking price. asking_currency: Currency of asking_price. condition: Free string — typical: ``new``, ``like_new``, ``good``, ``fair``, ``poor``. external_link: **Primary** click-through URL only (source listing, vendor page, manufacturer page). Exactly one. Additional URLs go in ``notes`` as markdown links. external_id: Stable identifier from the source system, used as a **dedup key**. Per-user unique when set — same external_id can't appear twice for one user. Format is up to you (e.g. ``aliexpress:1005004714348221``, ``amazon:order/3024.../line/1``, content hash). Leave null for handwritten items. project: Tag for grouping (e.g. "kitchen-renovation"). api_key: Optional API key (`pk_*`, generate at /account). Used when there is no OAuth token, and also when the OAuth token lacks the required scope — an explicitly passed key overrides an ambient token that is scoped too narrowly. An invalid or revoked token still fails regardless. Returns: The newly-created inventory row (with embedded `product` if linked), or ``{"error": ...}`` on auth/validation failure.