# Tradeics Developers — full documentation dump

> Generated for AI agents. Index: https://developers.tradeics.com/llms.txt — Live site: https://developers.tradeics.com/

Base URLs: REST `https://api.tradeics.example/v2/` · LLM `https://llm.tradeics.example/v1` · MCP `https://api.tradeics.example/mcp/`

---

# Authoring

Source: https://developers.tradeics.com/guides/agent-skills/authoring/

Publish internal or product skills that stay aligned with Tradeics docs structure. Use this page when your team needs a custom skill on top of the official pack.

# Principles

1. **Structure first** — mirror official section headings so maintenance is mechanical.
2. **Link out** — skills should point at guides/references, not duplicate full HTTP contracts.
3. **Version deliberately** — bump skill version when REST groups or MCP tool names change.
4. **Secrets never live in skills** — only env var *names*.

# Recommended file layout

```text
tradeics-<name>/
  SKILL.md          # required frontmatter + instructions
  references.md     # optional deep links
  examples/         # optional prompts / evals
```

# Frontmatter pattern (placeholder)

```yaml
---
name: tradeics-custom-erp
description: ERP sync patterns for Acme on Tradeics REST V2
---
```

# Drafting checklist

| Section | Include |
| --- | --- |
| When to use | Trigger phrases and out-of-scope cases |
| Sources | Absolute `developers.tradeics.com` URLs |
| Auth | Pointer to Getting Started → Authentication |
| Domains | Tables like Platform / API skills |
| Safety | Write confirmation rules |
| Eval prompts | 3–5 prompts that prove the skill works |

# Review gates

- Does it invent endpoints? Reject.
- Does it conflict with [MCP tool conventions](/guides/mcp-server/tool-conventions/)? Align names.
- Does it duplicate [Best practices](../best-practices/)? Link instead.

# Next

+ Navigation
  | Best practices: Operate skills in production. -> ../best-practices/
  | Install: Distribution paths. -> ../install/
  | Tool conventions: Keep MCP + skills aligned. -> /guides/mcp-server/tool-conventions/

---

# Best practices

Source: https://developers.tradeics.com/guides/agent-skills/best-practices/

Operate Tradeics Agent Skills like production dependencies — versioned, reviewed, and paired with the right MCP servers.

# Do

- Enable **Docs** skill globally; add domain skills per repository.
- Keep [`/llms.txt`](/llms.txt) as the discovery index in every agent prompt template.
- Attach **one** MCP server at a time when debugging tools; expand after stability.
- Review write-capable agent sessions (Platform MCP, Finance paths) weekly early on.
- Rotate tokens on schedule; skills only name env keys.

# Don’t

- Don’t paste live bearer tokens into skill files or chat transcripts.
- Don’t run write tools with production keys from an unsupervised agent loop.
- Don’t teach skills undocumented private APIs.
- Don’t fork official skills without tracking upstream structure changes.

# Skills + MCP pairing matrix

| Task | Skill | MCP |
| --- | --- | --- |
| Answer “how does X work?” | Docs | Docs MCP |
| Implement REST client | API | — (or Platform MCP for fixtures) |
| Operate live RFX / catalog | Platform | Platform MCP |
| Classify / summarize with models | AI | AI MCP (+ LLM HTTPS for batch) |

# Maintenance cadence

| Cadence | Action |
| --- | --- |
| Per API release | Diff skill checklists against REST / MCP changelogs |
| Monthly | Re-run install verification prompts |
| On incident | Disable write MCP tools; keep Docs skill for recovery |

# Next

+ Navigation
  | Overview: Stacking model. -> ../overview/
  | MCP security: Token and scope rules. -> /guides/mcp-server/security/
  | Platform changes: Track breaking updates. -> /changes/

---

# Agent Skills

Source: https://developers.tradeics.com/guides/agent-skills/

**Agent Skills** teach coding agents how to work the Tradeics way — authentication, REST V2, docs lookup, platform workflows, and AI helpers — without dumping the whole corpus into every prompt.

Skills are portable instruction packs (Cursor-style and compatible hosts). Pair them with [`/llms.txt`](/llms.txt) for discovery and with [MCP Servers](/guides/mcp-server/) when the agent needs live workspace tools.

| Skill | What it teaches the agent | Pair with |
| --- | --- | --- |
| **Tradeics Docs** | Find and cite official developer docs | Docs MCP, `llms.txt` |
| **Tradeics Platform** | B2B marketplace, S2P, sales, network flows | Platform MCP, REST V2 |
| **Tradeics API** | Auth, envelopes, pagination, clients | REST / OpenAPI |
| **Tradeics AI** | LLM proxy + assistive patterns | AI MCP, LLM API |

Start with [Overview](./overview/), then [Install](./install/). Server URLs and skill package names below use placeholders until GA — the **page structure is final**.

+ Navigation
  | Overview: What skills are and when to use them. -> ./overview/
  | Install: Add Tradeics skills to Cursor and other hosts. -> ./install/
  | Tradeics Docs skill: Navigation and citation rules. -> ./tradeics-docs/
  | Tradeics Platform skill: Product workflow playbooks. -> ./tradeics-platform/
  | Tradeics API skill: REST V2 integration patterns. -> ./tradeics-api/
  | Tradeics AI skill: LLM and assistive automation. -> ./tradeics-ai/
  | Authoring: Ship custom skills for your team. -> ./authoring/
  | Best practices: Safety, grounding, and maintenance. -> ./best-practices/
  | MCP Servers: Live tools beside skills. -> /guides/mcp-server/

! Skills = how the agent should think. MCP = what the agent can call at runtime. Use both for world-class agent UX.

---

# Install

Source: https://developers.tradeics.com/guides/agent-skills/install/

Install Tradeics Agent Skills once per machine or per project, then let your host auto-select them when the conversation matches Tradeics work.

# Prerequisites

- A coding agent that supports skills (Cursor Skills, Claude projects/skills-compatible hosts, or your own skill runner).
- Access to the official Tradeics skill pack (early access) **or** a local clone of the skill definitions your team maintains.
- Optional but recommended: [MCP Servers](/guides/mcp-server/) for live tools.

!! Skill package names and install channels below are reserved placeholders (`@tradeics/…`). Swap in GA package ids when published — keep this page’s section order.

# Cursor

1. Open **Cursor Settings → Rules / Skills** (or your team’s skills directory).
2. Add the Tradeics skill pack (marketplace entry or local path).
3. Enable at least **Tradeics Docs** globally; enable Platform / API / AI per repo as needed.
4. Start a chat that mentions Tradeics — confirm the skill appears in the agent’s loaded context.

Local path pattern (placeholder):

```text
~/.cursor/skills/tradeics-docs/
~/.cursor/skills/tradeics-platform/
~/.cursor/skills/tradeics-api/
~/.cursor/skills/tradeics-ai/
```

# Claude / ChatGPT / custom hosts

1. Import the skill markdown (or pack zip) into the host’s skill / project-knowledge slot.
2. Pin **Tradeics Docs** for documentation tasks.
3. Point the agent at [`https://developers.tradeics.com/llms.txt`](https://developers.tradeics.com/llms.txt) as a primary index.
4. Attach MCP only when live calls are required ([Connect in agents](/guides/mcp-server/usage-in-agents/)).

# Verify

Ask the agent:

> Using the Tradeics Docs skill, summarize Authentication and link the REST API V2 base URL. Do not invent endpoints.

Expect: links into `/guides/getting-started/authentication/` and `https://api.tradeics.example/v2/` (or production hosts when live).

# Next

+ Navigation
  | Tradeics Docs skill: What the skill encodes. -> ../tradeics-docs/
  | Best practices: Keep skills and MCPs in sync. -> ../best-practices/
  | Authoring: Publish internal skills. -> ../authoring/

---

# Overview

Source: https://developers.tradeics.com/guides/agent-skills/overview/

Agent Skills are reusable instruction packs that encode Tradeics developer conventions. When an agent loads a skill, it inherits the right auth headers, API bases, safety rules, and product vocabulary before it writes code or proposes a change.

# Skills vs MCP vs llms.txt

| Surface | Role | Load when |
| --- | --- | --- |
| **Agent Skills** | Procedural guidance (“how to integrate Tradeics”) | Agent starts a Tradeics task |
| **[`/llms.txt`](/llms.txt)** | Curated index of docs | Agent needs a map of the hub |
| **[`/llms-full.txt`](/llms-full.txt)** | Full docs corpus | Offline / deep research |
| **[MCP Servers](/guides/mcp-server/)** | Live tools against docs or workspace | Agent must call APIs or search docs live |

Skills never replace authentication: they teach the agent *where* credentials come from. See [Authentication](/guides/getting-started/authentication/).

# Skill catalog (structure)

| Skill id (placeholder) | Audience | Primary outcomes |
| --- | --- | --- |
| `tradeics-docs` | Any agent answering from official docs | Correct links, no invented routes |
| `tradeics-platform` | Marketplace / S2P / sales integrators | Correct domain model and workflows |
| `tradeics-api` | Backend / middleware engineers | REST V2 envelopes, pagination, clients |
| `tradeics-ai` | Teams using the LLM proxy or AI helpers | Safe inference + assistive boundaries |

Package distribution (npm, GitHub, Cursor marketplace) lands when skills GA. Until then, treat these pages as the **canonical outline** teams and agents should follow.

# Recommended stacking

1. Install **Tradeics Docs** for every Tradeics conversation.
2. Add **Tradeics API** when generating client code or Postman flows.
3. Add **Tradeics Platform** or **Tradeics AI** for domain-specific work.
4. Attach the matching [MCP server](/guides/mcp-server/overview/) for live lookups and actions.

# Next

+ Navigation
  | Install: Wire skills into Cursor and other hosts. -> ../install/
  | Tradeics Docs skill: First skill to enable. -> ../tradeics-docs/
  | MCP overview: Which server pairs with which skill. -> /guides/mcp-server/overview/

---

# Tradeics AI skill

Source: https://developers.tradeics.com/guides/agent-skills/tradeics-ai/

The **Tradeics AI** skill teaches agents how to use Tradeics assistive AI and the OpenAI-compatible LLM proxy safely — embeddings, chat completions, and product helpers — without treating model output as a payment or award authority.

# Goals

- Point agents at [Tradeics AI guides](/guides/ai/) and the [LLM API](/references/llm-api/v1/).
- Use [AI MCP](/guides/mcp-server/ai-mcp/) for tool-shaped assistants; use HTTPS for high-volume inference.
- Keep a hard boundary: **assistive, not authoritative**.

# Surfaces

| Surface | Use for | Docs |
| --- | --- | --- |
| Product AI helpers | Summaries, classification, drafting | [Capabilities](/guides/ai/capabilities/) |
| LLM proxy | Your app’s Chat Completions / embeddings | [Call the LLM](/guides/ai/llm-api/) |
| AI MCP | Agent-discovered assist tools | [AI MCP](/guides/mcp-server/ai-mcp/) |

Base (placeholder):

```text
https://llm.tradeics.example/v1
```

# Behavior contract

- Do not auto-award POs, release wallets, or settle invoices from model output alone.
- Prefer structured JSON when chaining into REST writes.
- Rate-limit autonomous loops; cache embeddings when possible.
- Label AI-generated text in operator UIs when policy requires it.

# Contents checklist

1. Auth notes (`Authorization` and `x-tradeics-llm-api-key`).
2. Model selection / placeholders until GA catalog ships.
3. Prompt patterns for RFX summary and catalog classification.
4. Escalation to REST for durable storage of AI results.
5. Pairing with Platform skill when AI touches live RFXs.

# Next

+ Navigation
  | AI MCP: Tool access for agents. -> /guides/mcp-server/ai-mcp/
  | Call the LLM: HTTPS samples. -> /guides/ai/llm-api/
  | Best practices: Safe agent loops. -> ../best-practices/

---

# Tradeics API skill

Source: https://developers.tradeics.com/guides/agent-skills/tradeics-api/

The **Tradeics API** skill focuses agents on correct HTTP integration — auth, envelopes, pagination, errors, clients, and versioning — independent of any single product domain.

# Goals

- Generate code that matches [REST API V2](/references/rest-api/v2/).
- Prefer official [API clients](/guides/getting-started/api-clients/) (Postman, OpenAPI, Insomnia, Bruno, Hoppscotch).
- Honor [rate limits](/guides/getting-started/rate-limits/), [errors](/guides/getting-started/errors/), and [pagination](/guides/getting-started/pagination/).

# Core conventions the skill must encode

| Topic | Canonical guide |
| --- | --- |
| Bearer auth | [Authentication](/guides/getting-started/authentication/) |
| First call | [First request](/guides/getting-started/first-request/) |
| Envelope & status | Reference intro + Errors guide |
| Environments | [Versioning](/guides/getting-started/versioning/) |
| Collections | OpenAPI / Postman under References |

Base URL (placeholder):

```text
https://api.tradeics.example/v2/
```

# Behavior contract

- Prefer `/v2/` — never invent legacy V1 paths.
- Put secrets in env vars / secret stores, not source.
- On `429`, exponential backoff with jitter.
- Ignore unknown response fields.

# Contents checklist

1. Auth header templates (REST + LLM variants).
2. Multi-language snippets pointer (First request).
3. Client import links (OpenAPI 3.1, Postman).
4. Common mistake catalog (wrong host, missing page param, ignoring scopes).
5. When to escalate to Platform / Finance skills.

# Next

+ Navigation
  | Tradeics Docs skill: Citation and discovery. -> ../tradeics-docs/
  | REST API V2: Contracts. -> /references/rest-api/v2/
  | First request: Code samples. -> /guides/getting-started/first-request/

---

# Tradeics Docs skill

Source: https://developers.tradeics.com/guides/agent-skills/tradeics-docs/

The **Tradeics Docs** skill teaches agents to navigate the official developer hub, prefer canonical URLs, and refuse invented API routes.

# Goals

- Always ground answers in Tradeics docs (`developers.tradeics.com`).
- Prefer [`/llms.txt`](/llms.txt) → relevant guide/reference → cite the path.
- Distinguish Guides (concepts) from References (HTTP contracts).
- Pair with [Docs MCP](/guides/mcp-server/docs-mcp/) for live search when available.

# Behavior contract (fill package with this)

| Rule | Agent must |
| --- | --- |
| Source of truth | Use official docs; never invent `/v1/` REST routes |
| Discovery | Start from `llms.txt`, deepen with `llms-full.txt` only when needed |
| Citations | Link concrete guide/reference paths |
| Secrets | Never ask users to paste live tokens into shared skills |
| Placeholders | Keep `.example` hosts until production domains are confirmed |

# Contents checklist (for skill authors)

Use this checklist when packaging the skill — structure is fixed; body copy can expand:

1. **Identity** — name, description, when to trigger.
2. **Primary URLs** — hub base, `llms.txt`, REST V2, LLM, MCP catalog.
3. **Map of the hub** — Getting Started, products, Agent Skills, MCP Servers, CLI, References.
4. **Citation template** — how to quote paths and titles.
5. **Refusal rules** — no undocumented private endpoints; no secret dumping.

# Example prompts

- “Find how Tradeics handles pagination and link the guide.”
- “Compare REST V2 vs MCP for catalog sync — cite both.”
- “Give me the Getting Started path for webhooks.”

# Next

+ Navigation
  | Tradeics API skill: HTTP integration conventions. -> ../tradeics-api/
  | Docs MCP: Live docs tools for agents. -> /guides/mcp-server/docs-mcp/
  | llms.txt: Agent index files. -> /guides/getting-started/api-clients/

---

# Tradeics Platform skill

Source: https://developers.tradeics.com/guides/agent-skills/tradeics-platform/

The **Tradeics Platform** skill encodes B2B product knowledge — marketplace, source-to-pay, sales, and network — so agents propose workflows that match Tradeics domain models.

# Goals

- Speak Tradeics product language (RFX, catalogs, POs, opportunities, partners).
- Route implementers to the right [B2B Platform guides](/guides/b2b-platform/) and [REST V2](/references/rest-api/v2/) groups.
- Prefer [Platform MCP](/guides/mcp-server/platform-mcp/) for live reads/writes under policy.

# Domains covered

| Domain | Typical agent tasks | Guide | REST group |
| --- | --- | --- | --- |
| Marketplace | Sync catalogs / products | [Marketplace](/guides/b2b-platform/marketplace/) | Marketplace |
| Source to Pay | RFX and purchase orders | [Source-to-pay](/guides/b2b-platform/source-to-pay/) | Source to Pay |
| Sales | Opportunities and quotes | [B2B sales](/guides/b2b-platform/b2b-sales/) | Sales |
| Network | Partners and relationships | B2B guides + Network refs | Network |
| Integrations | ERP / OMS / CRM patterns | [Integrations](/guides/b2b-platform/integrations/) | — |

# Behavior contract

- Never auto-award an RFX or release a PO without an explicit operator confirmation rule.
- Treat write tools as privileged; default to read → plan → confirm → write.
- Align field names with REST V2 envelopes; ignore unknown JSON fields.

# Contents checklist

1. Domain glossary (buyer, supplier, RFX, catalog, opportunity).
2. Happy-path workflows (list → get → create draft).
3. Idempotency and retry notes for mutating calls.
4. Cross-links to Finance when payments follow a PO.
5. Pairing instructions for Platform MCP scopes.

# Next

+ Navigation
  | Tradeics API skill: Shared REST conventions. -> ../tradeics-api/
  | Platform MCP: Live workspace tools. -> /guides/mcp-server/platform-mcp/
  | B2B Platform guides: Human-readable product docs. -> /guides/b2b-platform/

---

# Capabilities

Source: https://developers.tradeics.com/guides/ai/capabilities/

Tradeics AI support concentrates where B2B trade generates high decision load. Plan integrations around these capability areas.

# Sourcing & procurement

- Ranking or shortlisting suppliers based on category fit, history, and network signals
- Helping teams draft or refine RFX content and evaluation criteria
- Highlighting spend anomalies once invoice and PO history are connected

**Integration prep:** sync rich supplier attributes and historical PO outcomes; keep category mappings current.

# Sales & marketplace

- Prioritizing inbound RFQs / public projects for seller response teams
- Assisting catalog enrichment (attributes, categorization) for better discovery
- Surfacing buyers or opportunities aligned to a supplier’s strengths

**Integration prep:** keep catalog completeness high; push response SLAs and win/loss outcomes back when available.

# Operations & risk

- Flagging unusual payment or wallet patterns for review (with Finance)
- Assisting contract clause review workflows before signature
- Summarizing status across multi-party transactions for operators

**Integration prep:** expose clear state machines and audit trails in your middleware so AI and humans share one timeline.

# Guardrails for your build

1. Log who accepted or overrode an AI suggestion.
2. Do not auto-post ERP journals from unverified AI output.
3. Expect localized and industry-specific behavior — do not assume one global ranking model for every market.

# Calling models from your stack

When you need your own prompts (not only in-product assists), use the Tradeics LLM proxy:

```bash
curl https://llm.tradeics.example/v1/chat/completions \
  -H "Authorization: Bearer $TRADEICS_LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model_id>",
    "messages": [
      {"role": "system", "content": "You assist Tradeics procurement users."},
      {"role": "user", "content": "Propose evaluation criteria for this RFX."}
    ]
  }'
```

Full examples and OpenAI SDK setup: [Call the LLM](../llm-api/).

# Related reading

+ Navigation
  | Call the LLM: Base URL and code samples. -> ../llm-api/
  | AI overview: Architecture position. -> ../overview/
  | Source-to-pay: Procurement objects. -> /guides/b2b-platform/source-to-pay/
  | Tradeics Finance: Settlement context. -> /guides/finance/

---

# Tradeics AI

Source: https://developers.tradeics.com/guides/ai/

Tradeics AI assists procurement, sales, and operations — and exposes an OpenAI-compatible LLM proxy for your own applications. Connect agents with [AI MCP](/guides/mcp-server/ai-mcp/) and teach them conventions via the [Tradeics AI skill](/guides/agent-skills/tradeics-ai/).

+ Navigation
  | Overview: AI in the Tradeics stack. -> ./overview/
  | Capabilities: Practical areas AI supports. -> ./capabilities/
  | Call the LLM: Code examples against `https://llm.tradeics.example`. -> ./llm-api/
  | AI MCP: Assistive tools for agents. -> /guides/mcp-server/ai-mcp/
  | Agent Skills: Tradeics AI skill pack. -> /guides/agent-skills/

---

# Call the LLM

Source: https://developers.tradeics.com/guides/ai/llm-api/

Call Tradeics models through the OpenAI-compatible proxy at **`https://llm.tradeics.example`**.

The [LLM API Reference](/references/llm-api/v1/) right panel shows live HTTP request/response samples per endpoint. This guide adds copy-paste clients in multiple languages.

# Base URL

| Use | URL |
| --- | --- |
| Proxy root | `https://llm.tradeics.example` |
| OpenAI SDK `base_url` | `https://llm.tradeics.example/v1` |
| Chat | `POST /v1/chat/completions` |
| Models | `GET /v1/models` |
| Embeddings | `POST /v1/embeddings` |

# Authenticate

```bash
export TRADEICS_LLM_API_KEY="sk-..."
```

```http
Authorization: Bearer $TRADEICS_LLM_API_KEY
```

# List models

```bash
curl https://llm.tradeics.example/v1/models \
  -H "Authorization: Bearer $TRADEICS_LLM_API_KEY"
```

# Chat completion — multi-language

Replace `<model_id>` with an id from `/v1/models`.

## cURL

```bash
curl https://llm.tradeics.example/v1/chat/completions \
  -H "Authorization: Bearer $TRADEICS_LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model_id>",
    "messages": [
      {"role": "system", "content": "You help procurement teams evaluate B2B suppliers."},
      {"role": "user", "content": "Summarize this RFQ in three bullets."}
    ],
    "temperature": 0.2
  }'
```

## Python

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TRADEICS_LLM_API_KEY"],
    base_url="https://llm.tradeics.example/v1",
)

response = client.chat.completions.create(
    model="<model_id>",
    messages=[
        {"role": "system", "content": "You help procurement teams evaluate B2B suppliers."},
        {"role": "user", "content": "Draft three clarifying questions for this RFQ."},
    ],
)

print(response.choices[0].message.content)
```

## Node.js

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TRADEICS_LLM_API_KEY,
  baseURL: "https://llm.tradeics.example/v1",
});

const response = await client.chat.completions.create({
  model: "<model_id>",
  messages: [
    { role: "system", content: "You help procurement teams evaluate B2B suppliers." },
    { role: "user", content: "Turn this supplier email into a structured quote summary." },
  ],
});

console.log(response.choices[0].message.content);
```

## Go

```go
package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "os"
)

func main() {
  body := map[string]any{
    "model": "<model_id>",
    "messages": []map[string]string{
      {"role": "system", "content": "You help procurement teams evaluate B2B suppliers."},
      {"role": "user", "content": "Score these three suppliers briefly."},
    },
  }
  b, _ := json.Marshal(body)
  req, _ := http.NewRequest("POST", "https://llm.tradeics.example/v1/chat/completions", bytes.NewReader(b))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("TRADEICS_LLM_API_KEY"))
  req.Header.Set("Content-Type", "application/json")
  res, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer res.Body.Close()
  fmt.Println(res.Status)
}
```

## PHP

```php
<?php
$payload = [
  "model" => "<model_id>",
  "messages" => [
    ["role" => "system", "content" => "You help procurement teams evaluate B2B suppliers."],
    ["role" => "user", "content" => "Summarize this RFQ in three bullets."],
  ],
];

$ch = curl_init("https://llm.tradeics.example/v1/chat/completions");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("TRADEICS_LLM_API_KEY"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
```

## Java

```java
var client = HttpClient.newHttpClient();
var json = """
  {
    "model": "<model_id>",
    "messages": [
      {"role": "system", "content": "You help procurement teams evaluate B2B suppliers."},
      {"role": "user", "content": "Summarize this RFQ in three bullets."}
    ]
  }
  """;
var request = HttpRequest.newBuilder()
  .uri(URI.create("https://llm.tradeics.example/v1/chat/completions"))
  .header("Authorization", "Bearer " + System.getenv("TRADEICS_LLM_API_KEY"))
  .header("Content-Type", "application/json")
  .POST(HttpRequest.BodyPublishers.ofString(json))
  .build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

## Ruby

```ruby
require "net/http"
require "json"
require "uri"

uri = URI("https://llm.tradeics.example/v1/chat/completions")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV["TRADEICS_LLM_API_KEY"]}"
req["Content-Type"] = "application/json"
req.body = {
  model: "<model_id>",
  messages: [
    { role: "system", content: "You help procurement teams evaluate B2B suppliers." },
    { role: "user", content: "Summarize this RFQ in three bullets." }
  ]
}.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body
```

# Embeddings

```bash
curl https://llm.tradeics.example/v1/embeddings \
  -H "Authorization: Bearer $TRADEICS_LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<embedding_model_id>",
    "input": ["M8 hex bolt stainless", "hydraulic pump 5HP"]
  }'
```

# Production checklist

- Keep keys on the server only.
- Log model + latency — not secrets inside prompts.
- Treat model output as assistive before awarding POs or releasing payments.
- Use [REST API V2](/references/rest-api/v2/) for masters and transactions; this LLM API for inference.
- Prefer [MCP](/guides/mcp-server/) when an agent should operate on workspace data (not for high-volume batch inference).

+ Navigation
  | LLM API Reference: Right-panel HTTP examples. -> /references/llm-api/v1/
  | MCP Servers: Workspace tools for agents. -> /guides/mcp-server/
  | AI capabilities: Where to apply models. -> ../capabilities/
  | REST API V2: Platform data APIs. -> /references/rest-api/v2/

---

# Overview

Source: https://developers.tradeics.com/guides/ai/overview/

Tradeics uses AI (alongside blockchain and cloud infrastructure) to make B2B trade faster and more transparent — assisting teams across procure-to-pay, sales, and operational decisions.

# Where AI sits in the architecture

AI features operate **on top of** platform data. Clean masters and transactional history make recommendations useful; dirty ERP mirrors limit value.

```text
ERP / CRM  ──sync──►  Tradeics B2B Platform  ──►  Tradeics AI assists
                              │
                              └──► Tradeics Finance settles

Your app  ──HTTPS──►  https://llm.tradeics.example/v1  ──►  models
```

# Two ways to use Tradeics AI

| Path | When to use | Entry point |
| --- | --- | --- |
| **Product AI** | Recommendations and assists inside Tradeics workflows | [Capabilities](../capabilities/) |
| **LLM API** | Call models from your backend with OpenAI-compatible SDKs | [Call the LLM](../llm-api/) · [LLM API Reference](/references/llm-api/v1/) |

# Quick LLM example

```bash
curl https://llm.tradeics.example/v1/chat/completions \
  -H "Authorization: Bearer $TRADEICS_LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model_id>",
    "messages": [
      {"role": "user", "content": "Summarize this RFQ for a buyer."}
    ]
  }'
```

# Developer implications

- Prefer structured fields (categories, units, Incoterms, currencies) over free-text only payloads.
- Keep stable identifiers — AI outputs should reference Tradeics object IDs your systems already store.
- Treat AI suggestions as **assistive**: require human or policy confirmation before irreversible commits (PO award, payout release) unless a product API explicitly defines auto-apply modes.

# What this launch documents

- LLM inference routes on `https://llm.tradeics.example` (chat, models, embeddings, and more)
- Product AI capability areas to design around while workflow APIs expand
- Platform REST **V2** for masters and upcoming product routes

+ Navigation
  | Call the LLM: Copy-paste integrations. -> ../llm-api/
  | Capabilities: Concrete AI opportunity areas. -> ../capabilities/
  | REST API V2: Platform HTTP APIs. -> /references/rest-api/v2/

---

# AI Builder

Source: https://developers.tradeics.com/guides/apps-plugins/ai-builder/

**AI Builder** helps Tradeics users spin up apps and plugins in minutes — prompt → draft manifest, handlers, and Store listing copy — then humans review, test, and publish.

# What AI Builder produces

| Artifact | Purpose |
| --- | --- |
| Draft **manifest** | Capabilities, scopes, UI slots |
| Starter **handlers** | HTTPS stubs or hosted function scaffolds |
| **Listing** draft | Name, summary, screenshots placeholders |
| **Test plan** | Suggested sandbox checks |
| **Risk notes** | Scope warnings and write-tool caution |

# Flow

```text
Brief ("sync RFXs to our ERP and notify Slack")
    → AI Builder draft
    → Developer edits scopes & branding
    → Sandbox install
    → Publish (private or Store)
```

Pair with [Tradeics AI](/guides/ai/) and [LLM API](/references/llm-api/v1/) for custom inference inside your app — AI Builder scaffolds the **extension**, not unlimited production inference quota.

# Guardrails (non-negotiable)

- AI output is **assistive** — builders remain accountable for Store policy.  
- Write scopes and billing changes require explicit human confirmation.  
- Generated secrets are **rotated** after first display.  
- Paid listings cannot go live without pricing + support contacts.

# Prompt patterns

1. “Private plugin: badge open RFXs older than 7 days; scope `s2p:read` only.”  
2. “Public free app: catalog CSV export; UI slot on Marketplace.”  
3. “Paid subscription: settlement digest email; meter per send.”

# Next

+ Navigation
  | Manifest: Review generated fields. -> ../manifest/
  | Publishing: Human review gates. -> ../publishing/
  | Security: What review looks for. -> ../security/

---

# App Store

Source: https://developers.tradeics.com/guides/apps-plugins/app-store/

The **Tradeics App Store** is the marketplace for apps and plugins — discovery, trust signals, install, and commercial terms — inside Tradeics and Tradeics Platform.

# Store jobs

| Job | Detail |
| --- | --- |
| **Discover** | Search, categories, collections, editor picks |
| **Evaluate** | Screenshots, scopes, pricing, publisher reputation |
| **Install** | Consent + billing → installation |
| **Manage** | Updates, seats, uninstall |
| **Transact** | Free / paid entitlements for the org |

# Listing anatomy (fixed)

1. Title, slug, publisher  
2. Short / long description  
3. Categories & tags  
4. Visibility (public / private / unlisted)  
5. Pricing plans  
6. Required scopes (honest disclosure)  
7. Support URL & privacy policy  
8. Version changelog  

# Builder path into the Store

```text
Private install success → Listing draft → Pricing
    → Security questionnaire → Review → Public / paid live
```

# Next

+ Navigation
  | Visibility: Who sees the listing. -> ../visibility/
  | Monetization: Plans and payouts. -> ../monetization/
  | Publishing: Review SLA & gates. -> ../publishing/

---

# Architecture

Source: https://developers.tradeics.com/guides/apps-plugins/architecture/

World-class extension architecture for Tradeics: isolated runtimes, explicit capabilities, Store as distribution, Platform as control plane.

# Control plane vs data plane

```text
┌─────────────────────────────────────────────────────────┐
│ Tradeics Platform (control)                             │
│  Developer apps · listings · billing · review · keys    │
└───────────────┬─────────────────────────────▲───────────┘
                │ Apps API / webhooks           │ telemetry
┌───────────────▼─────────────────────────────┴───────────┐
│ Tradeics products (B2B · Finance · AI · …)              │
│  UI extension slots · actions · events                  │
└───────────────┬─────────────────────────────────────────┘
                │ install token + scoped calls
┌───────────────▼─────────────────────────────────────────┐
│ App / plugin runtime (sandboxed or your HTTPS endpoint) │
└─────────────────────────────────────────────────────────┘
```

# Core components (stable)

| Component | Responsibility |
| --- | --- |
| **Manifest** | Declares identity, capabilities, scopes, UI slots |
| **Runtime** | Executes handlers (Tradeics-hosted or URL callbacks) |
| **Install token** | Short-lived / rotatable credential for one org install |
| **Event bus** | Delivers signed webhooks / event streams to the app |
| **Store catalog** | Search, filters, pricing display, install CTA |
| **Billing engine** | Entitlements, invoices, payouts to publishers |
| **AI Builder** | Generates draft manifest + starter handlers |

# Isolation rules

1. No ambient access to other tenants.  
2. Scopes are **least privilege** and re-prompted on expand.  
3. Network egress can be allowlisted for hosted runtimes.  
4. Secrets live in Platform — never in the public listing.

# Environments

| Env | Use |
| --- | --- |
| **Dev** | Local / tunnel callbacks |
| **Sandbox org** | Install private drafts end-to-end |
| **Production** | Public or paid installs |

# Next

+ Navigation
  | Manifest: Declarative contract. -> ../manifest/
  | Capabilities: What you can hook. -> ../capabilities/
  | Platform API: Automate the control plane. -> ../platform-api/

---

# Authentication

Source: https://developers.tradeics.com/guides/apps-plugins/authentication/

Apps authenticate **as the installation**, not as an end-user password. Admins grant scopes at install time; runtimes use install tokens.

# Token types

| Token | Owner | Use |
| --- | --- | --- |
| **Developer credentials** | Publisher | Manage apps via Platform / Apps API |
| **Install token** | One org install | Call Tradeics APIs under granted scopes |
| **Webhook signing secret** | One app or install | Verify event authenticity |

# Install handshake (structure)

1. Admin starts install from Store or private link.  
2. Consent screen shows scopes + pricing.  
3. Platform redirects / POSTs to your `setup` URL with an authorization payload.  
4. Your runtime stores the install id; retrieves install token via Apps API.  
5. Token rotation: Platform can revoke; your app must refresh per docs at GA.

# Authorization header

```http
Authorization: Bearer <INSTALL_TOKEN>
```

Same family as [Getting Started → Authentication](/guides/getting-started/authentication/), different audience (installation).

# Next

+ Navigation
  | Security: Threat model. -> ../security/
  | Platform API: Token endpoints. -> ../platform-api/
  | Quickstart: First install. -> ../quickstart/

---

# Best practices

Source: https://developers.tradeics.com/guides/apps-plugins/best-practices/

Operate Apps & Plugins like a product line on Tradeics — trustworthy listings, tight scopes, and support that matches price.

# Do

- Start **private + free**; widen visibility after polish.  
- Use **AI Builder** for speed, humans for policy and UX.  
- Disclose scopes in plain language on the listing.  
- Version manifests; never hot-patch production without a version.  
- Meter only what you document.

# Don’t

- Don’t request write scopes “just in case.”  
- Don’t hide paid features behind undeclared charges.  
- Don’t embed customer data in publisher analytics without disclosure.  
- Don’t break installs on major bumps without migration notes.

# Quality bar for public apps

| Bar | Bar |
| --- | --- |
| Reliability | No crash loops in sandbox week |
| Support | Monitored channel + response target |
| Docs | In-app help or external guide link |
| Accessibility | Keyboard paths for UI slots |

# Next

+ Navigation
  | Overview: Re-read the journey. -> ../overview/
  | Monetization: Align price to value. -> ../monetization/
  | App Store: Listing craft. -> ../app-store/

---

# Capabilities

Source: https://developers.tradeics.com/guides/apps-plugins/capabilities/

Capabilities declare **where and how** an app hooks Tradeics. Only listed capabilities are loaded at runtime.

# Capability families

| Family | Examples |
| --- | --- |
| **UI slots** | Toolbar buttons, side panels, settings pages |
| **Actions** | Operator-triggered jobs with confirmations |
| **Events / webhooks** | `rfx.updated`, `payment.captured`, … |
| **Data scopes** | REST scopes bridging to [REST V2](/references/rest-api/v2/) |
| **AI helpers** | Optional assist tools via [AI MCP](/guides/mcp-server/ai-mcp/) patterns |
| **Background jobs** | Scheduled or queued work (metered when paid) |

# Product surface map (extend over time)

| Product | Example slots (placeholders) |
| --- | --- |
| B2B S2P | `s2p.rfx.list.toolbar`, `s2p.po.detail.panel` |
| Marketplace / E-store | `marketplace.product.detail.actions` |
| Finance | `finance.invoice.list.toolbar` |
| Global | `settings.integrations.page` |

# Design rules

- Prefer read scopes first.  
- Destructive actions require Platform confirmation UI.  
- UI must degrade if the slot is unavailable in an older product build.

# Next

+ Navigation
  | Manifest: Wire capabilities in JSON. -> ../manifest/
  | App Store: How capabilities appear in listing. -> ../app-store/
  | Testing: Slot coverage matrix. -> ../testing/

---

# Concepts

Source: https://developers.tradeics.com/guides/apps-plugins/concepts/

Shared vocabulary for builders, Store ops, and Platform APIs. Keep these terms stable as products GA.

# App vs plugin

| Term | Definition | Typical shape |
| --- | --- | --- |
| **App** | Installable product experience on Tradeics | Store listing + runtime + optional UI |
| **Plugin** | Focused extension that hooks a product surface | Manifest capabilities + handlers |
| **Listing** | Store-facing metadata (name, pricing, screenshots) | Bound to one or more app versions |
| **Installation** | Org-level grant to run an app | Scopes + billing state |

Plugins are often shipped **as** apps (one listing, narrower capabilities). Use **plugin** in docs when emphasizing a product hook; use **app** for Store and billing.

# Visibility

| Mode | Who can find / install |
| --- | --- |
| **Public** | Discoverable in the App Store (subject to review) |
| **Private** | Only invited orgs / same publisher org (and partners) |
| **Unlisted** | Install via direct link; not search-indexed (when enabled) |

# Commercial models

| Model | Notes |
| --- | --- |
| **Free** | No charge; still subject to review and rate limits |
| **One-time** | Single purchase per org (or seat pack) |
| **Subscription** | Recurring org or seat billing |
| **Usage-metered** | Bill against metered events (API calls, jobs) |
| **Freemium** | Free tier + paid plan upgrade |

# Trust & tenancy

- Installations are **per workspace** (never silently global).
- Data access follows declared **scopes** and org admin approval.
- Publishers never receive customer API keys — they receive **app install tokens** with limited scopes.

# Next

+ Navigation
  | Architecture: Runtime and tenancy diagram. -> ../architecture/
  | Visibility: Deep dive on public/private. -> ../visibility/
  | Monetization: Pricing and payouts. -> ../monetization/

---

# Apps & Plugins

Source: https://developers.tradeics.com/guides/apps-plugins/

**Build with, for, and on Tradeics** — integrate Tradeics into your stack (**with**), deepen product workflows (**for**), and extend the platform itself with **apps and plugins** (**on**).

The Tradeics **App Store** is where workspaces discover, install, and (optionally) purchase extensions. Builders publish **public** or **private** apps — **free** or **paid** — from Tradeics Platform. Creation can be **AI-assisted**: describe the job, spin up a draft app/plugin, then refine and publish.

| Pillar | Who | Docs |
| --- | --- | --- |
| **With** Tradeics | Integrators & ERP partners | [Getting Started](/guides/getting-started/), [REST V2](/references/rest-api/v2/) |
| **For** Tradeics | Product teams on B2B / Finance / AI | Product [Guides](/guides/) |
| **On** Tradeics | App & plugin builders | **This section** |

!! Structure is final. Tradeics Platform App Store, AI Builder, and Apps APIs ship in phases — replace placeholders (hosts, IDs, fee schedules) without reshaping these pages.

+ Navigation
  | Overview: Personas, surfaces, and end-to-end journey. -> ./overview/
  | Concepts: App vs plugin, visibility, pricing models. -> ./concepts/
  | Architecture: Runtime, sandboxes, events, APIs. -> ./architecture/
  | Quickstart: Scaffold your first extension. -> ./quickstart/
  | AI Builder: Spin up apps and plugins with AI. -> ./ai-builder/
  | Manifest: Declarative app definition. -> ./manifest/
  | Authentication: Install tokens and OAuth. -> ./authentication/
  | Capabilities: UI, actions, webhooks, data scopes. -> ./capabilities/
  | App Store: Discovery, listing, install UX. -> ./app-store/
  | Visibility: Public vs private distribution. -> ./visibility/
  | Monetization: Free, paid, billing, payouts. -> ./monetization/
  | Publishing: Review, versions, go-live. -> ./publishing/
  | Platform API: Manage apps from Tradeics Platform. -> ./platform-api/
  | Security: Sandbox, review, abuse controls. -> ./security/
  | Testing: Local, sandbox orgs, certification. -> ./testing/
  | Best practices: Quality bar for Store apps. -> ./best-practices/
  | REST Apps API: HTTP contracts (scaffold). -> /references/rest-api/v2/#apps-plugins-developer-apps/

! Prefer private org installs while learning. Prefer public + free listings for community reach; add paid plans when value and support are proven.

---

# Manifest

Source: https://developers.tradeics.com/guides/apps-plugins/manifest/

The **manifest** is the declarative contract for an app/plugin — identity, capabilities, scopes, and Store hints. Platform rejects installs that diverge from the signed manifest version.

# Required top-level fields (structure)

| Field | Purpose |
| --- | --- |
| `id` / `slug` | Stable app identifier |
| `name` | Display name |
| `version` | Semver of this manifest |
| `publisher` | Publisher org id |
| `runtime` | `hosted` \| `https` endpoint config |
| `scopes` | Requested OAuth / install scopes |
| `capabilities` | UI slots, actions, events |
| `webhooks` | Event subscriptions |
| `store` | Listing defaults (category, privacy) |

# Example (placeholder)

```json
{
  "slug": "rfx-aging-alerts",
  "name": "RFX aging alerts",
  "version": "0.1.0",
  "runtime": {
    "type": "https",
    "base_url": "https://apps.example.com/tradeics/rfx-aging"
  },
  "scopes": ["s2p:read"],
  "capabilities": {
    "ui": [{ "slot": "s2p.rfx.list.toolbar", "entry": "/ui/toolbar" }],
    "actions": [{ "id": "scan_aging", "title": "Scan aging RFXs" }]
  },
  "webhooks": ["rfx.updated"],
  "store": {
    "visibility": "private",
    "pricing": "free"
  }
}
```

# Versioning rules

- Additive capabilities: minor bump.  
- Scope expansion: requires re-consent on install.  
- Breaking handler URLs: major bump + migration notes.

# Next

+ Navigation
  | Capabilities: Allowed hooks. -> ../capabilities/
  | Authentication: Tokens bound to installs. -> ../authentication/
  | Publishing: Ship a version. -> ../publishing/

---

# Monetization

Source: https://developers.tradeics.com/guides/apps-plugins/monetization/

Builders can **monetize** through the Tradeics App Store — Tradeics meters entitlements and pays publishers; apps never handle raw card data for Store purchases.

# Plan types (structure)

| Plan | Entitlement unit | Good for |
| --- | --- | --- |
| Free | Org install | Adoption |
| One-time | Org or seat pack | Simple utilities |
| Subscription | Org / month or seat / month | Ongoing value |
| Metered | Billable events | High-variance workloads |
| Add-ons | Optional modules | Upsell |

# Commercial flow

```text
Buyer selects plan → Tradeics checkout / invoice
    → Entitlement active on installation
    → Usage reported (if metered)
    → Publisher payout (minus platform fee)
```

# Publisher obligations

- Clear pricing on the listing (no hidden fees in-app for Store SKUs).  
- Support SLA matching paid tier.  
- Tax / payout profile completed in Platform before paid go-live.  

!! In-app purchases that bypass Store billing are disallowed for public listings unless Platform explicitly programs an exception.

# Next

+ Navigation
  | Publishing: Paid listing checklist. -> ../publishing/
  | Platform API: Plans & earnings endpoints. -> ../platform-api/
  | Best practices: Pricing honesty. -> ../best-practices/

---

# Overview

Source: https://developers.tradeics.com/guides/apps-plugins/overview/

Tradeics Apps & Plugins let teams **extend the operating system** — new workflows, UI surfaces, automations, and industry packs — without forking the core platform.

# Build with · for · on

| Mode | Meaning | Typical artifact |
| --- | --- | --- |
| **With** | Call Tradeics from your systems | REST / LLM / MCP / CLI clients |
| **For** | Operate Tradeics products well | Guides, configurations, playbooks |
| **On** | Ship extensions others install | Apps, plugins, App Store listings |

This section is the **on** lane.

# Personas

| Persona | Goal |
| --- | --- |
| **Builder** | Create and publish apps/plugins (human or AI-assisted) |
| **Publisher** | Own listing, pricing, support, and payouts on the Store |
| **Admin** | Install, approve, and govern apps for a workspace |
| **End user** | Use installed extensions inside Tradeics products |
| **Platform** | Review, meter, bill, and safeguard the ecosystem |

# Journey (fixed pipeline)

```text
Idea → AI Builder / scaffold → Manifest + capabilities
    → Auth & scopes → Test in sandbox org
    → Listing (public/private · free/paid)
    → Review → Publish → Install → Meter & support
```

# Surfaces

| Surface | Role |
| --- | --- |
| **Tradeics Platform** | Developer console: apps, keys, listings, earnings |
| **App Store** | Discovery and install for orgs |
| **Runtime** | Hosted or customer-hosted extension process |
| **Apps API** | Programmatic manage / install / monetize ([guide](../platform-api/), [REST](/references/rest-api/v2/#apps-plugins-developer-apps/)) |
| **AI Builder** | Natural-language → draft app ([guide](../ai-builder/)) |

# Next

+ Navigation
  | Concepts: Vocabulary that stays stable. -> ../concepts/
  | Architecture: How pieces connect. -> ../architecture/
  | Quickstart: Ship a private draft. -> ../quickstart/

---

# Platform API

Source: https://developers.tradeics.com/guides/apps-plugins/platform-api/

Tradeics **Platform Apps API** (under REST V2 Apps & Plugins) lets automation create developer apps, manage listings, and read installations — the same control plane the UI uses.

Base (placeholder):

```text
https://api.tradeics.example/v2/apps/v2.0/
```

# Resource map (stable)

| Resource | Purpose |
| --- | --- |
| **Developer apps** | CRUD app registration |
| **Manifests / versions** | Upload and activate versions |
| **Listings** | Store metadata & visibility |
| **Installations** | Read org installs (publisher or admin) |
| **Plans** | Pricing definitions |
| **Earnings** | Payout statements (publisher) |
| **AI Builder jobs** | Start / poll scaffold generation |

See HTTP details in [REST → Apps & Plugins](/references/rest-api/v2/#apps-plugins-developer-apps/).

# Auth

Use **developer** credentials (not install tokens) for control-plane routes. Install tokens remain for runtime data access.

# Next

+ Navigation
  | Architecture: Control vs data plane. -> ../architecture/
  | Monetization: Plans object model. -> ../monetization/
  | REST Apps API: Endpoints. -> /references/rest-api/v2/#apps-plugins-developer-apps/

---

# Publishing

Source: https://developers.tradeics.com/guides/apps-plugins/publishing/

Publishing promotes a tested version from sandbox to **private allowlist** or **public Store**. Paid listings include commercial verification.

# Gates (ordered)

1. Manifest validates  
2. Sandbox install smoke tests pass  
3. Security questionnaire complete  
4. Listing copy + policies attached  
5. Pricing configured (if paid)  
6. Automated scanners + human review  
7. Status → `published`  

# Version rollout

| Strategy | Behavior |
| --- | --- |
| Immediate | All installs move on approve |
| Staged | Percentage or cohort rollout |
| Manual | Admins opt in per org |

# Reject / remediate

Reviewers cite concrete failures (scope honesty, crash loops, policy). Fix → resubmit; structure of this page stays unchanged.

# Next

+ Navigation
  | Testing: What to attach to the ticket. -> ../testing/
  | Security: Common reject reasons. -> ../security/
  | Visibility: Confirm distribution mode. -> ../visibility/

---

# Quickstart

Source: https://developers.tradeics.com/guides/apps-plugins/quickstart/

Create a **private free** draft app, install it on a sandbox org, and call one scoped API — before AI Builder or Store listing.

# Prerequisites

- Tradeics Platform developer access (early access / account manager until self-serve GA).  
- A sandbox workspace.  
- Optional: [CLI](/guides/tradeics-cli/) and [REST V2](/references/rest-api/v2/) familiarity.

# Steps

1. **Create developer app** in Platform → Apps (or `POST /apps/v2.0/developer-apps`).  
2. **Edit manifest** — name, callback URL, minimal scopes (e.g. `master:read`).  
3. **Register a health / handshake** endpoint your runtime exposes.  
4. **Install privately** on the sandbox org.  
5. **Exchange install** for an install token; call one read API.  
6. **Iterate** — add a UI slot or webhook; keep it private until review-ready.

```http
Authorization: Bearer <INSTALL_TOKEN>
```

!! Never use personal user tokens inside production app backends. Always use install tokens issued for the installation.

# Success criteria

- Sandbox admin sees the app under Installed.  
- Your runtime receives a signed install event.  
- One scoped REST call succeeds; an over-scoped call returns `403`.

# AI-accelerated path

Prefer [AI Builder](../ai-builder/) when you want a draft manifest + handlers from a natural-language brief — then return here to install and verify.

# Next

+ Navigation
  | AI Builder: Generate the scaffold. -> ../ai-builder/
  | Manifest: Fields you must fill. -> ../manifest/
  | Testing: Certification checklist. -> ../testing/

---

# Security

Source: https://developers.tradeics.com/guides/apps-plugins/security/

Ecosystem security protects tenants, publishers, and Tradeics. Review depth scales with visibility, scopes, and monetization.

# Principles

1. Least privilege scopes.  
2. Install-scoped credentials only.  
3. Signed webhooks; reject unsigned events.  
4. No silent exfiltration of PII.  
5. Public paid apps get the highest review bar.

# Threat checklist

| Risk | Mitigation |
| --- | --- |
| Scope creep | Re-consent + review on widen |
| Token leak | Rotation, short TTL, secret scanning |
| Abusive metering | Caps, anomaly alerts |
| Malicious listing | Publisher verification, takedown policy |

# Builder duties

- Complete security questionnaire for public/write apps.  
- Store secrets in Platform or your HSM — never in git.  
- Publish a privacy policy URL for public listings.

# Next

+ Navigation
  | Testing: Security test cases. -> ../testing/
  | Publishing: Review inputs. -> ../publishing/
  | Authentication: Token handling. -> ../authentication/

---

# Testing

Source: https://developers.tradeics.com/guides/apps-plugins/testing/

Prove installs, scopes, UI slots, and billing **before** Store review.

# Environments

| Env | Prove |
| --- | --- |
| Local | Handler unit tests, manifest schema |
| Sandbox org | Install, consent, happy-path actions |
| Billing sandbox | Plan purchase / cancel (paid apps) |

# Minimum matrix

| Case | Expected |
| --- | --- |
| Install free private | Active installation |
| Call allowed scope | `200` |
| Call missing scope | `403` |
| Uninstall | Token revoked; UI gone |
| Webhook signature bad | Rejected |
| Paid plan cancel | Entitlement ends per policy |

# Attachments for review

- Recording or checklist of matrix above  
- Manifest version hash  
- Support contact  

# Next

+ Navigation
  | Publishing: Submit. -> ../publishing/
  | Best practices: Quality bar. -> ../best-practices/
  | Quickstart: First sandbox install. -> ../quickstart/

---

# Visibility

Source: https://developers.tradeics.com/guides/apps-plugins/visibility/

Choose distribution carefully — visibility is independent from pricing (you can have **private paid** or **public free**).

# Matrix

| Visibility | Pricing | Typical use |
| --- | --- | --- |
| Private | Free | Internal tools, pilots |
| Private | Paid | Partner SKUs, invited customers |
| Public | Free | Community growth, lead gen |
| Public | Paid | Productized ISV business |
| Unlisted | Either | Soft launch, selective links |

# Private rules

- Install limited to publisher org + allowlisted org ids.  
- Not searchable in the public Store.  
- Still must pass **basic** security checks if it requests write scopes.

# Public rules

- Full Store review ([Publishing](../publishing/)).  
- Privacy policy and support channel required.  
- Scope changes that widen access trigger re-review.

# Next

+ Navigation
  | Monetization: Attach plans. -> ../monetization/
  | Security: Review depth by visibility. -> ../security/
  | App Store: Listing UX. -> ../app-store/

---

# B2B sales

Source: https://developers.tradeics.com/guides/b2b-platform/b2b-sales/

Tradeics B2B Sales helps suppliers automate sales operations and reach buyers through the marketplace, public projects, e-auctions, and the buyers network.

# What sellers automate

- Lead and opportunity intake from marketplace and public projects
- Response workflows for RFQs and auctions
- Client / account management inside the Tradeics network
- Quote-to-order progression into fulfillment and payment

# Integration targets

Connect CRM or sales ops tools when you need to:

1. Mirror inbound RFQs / project invitations into your CRM pipeline.
2. Push catalog availability and commercial terms from your PIM / ERP.
3. Bring auction awards and accepted quotes back as confirmed orders.
4. Keep partner contacts and negotiation ownership aligned across systems.

# Implementation tips

- Separate **catalog sync** (what you sell) from **opportunity sync** (who is asking and where they are in the funnel).
- Treat auction and RFQ timelines as first-class fields — late responses lose deals.
- When payment confirmation is required before fulfillment, join sales records to [Tradeics Pay / wallet](/guides/finance/tradeics-pay/) events instead of relying on UI status alone.

+ Navigation
  | Marketplace & network: Buyer/supplier surfaces. -> ../marketplace/
  | Source-to-pay: Procurement counterparts. -> ../source-to-pay/
  | Integrations: System connection approach. -> ../integrations/

---

# Tradeics B2B Platform

Source: https://developers.tradeics.com/guides/b2b-platform/

Tradeics B2B Platform is the core operating layer for global B2B trade — marketplace commerce, procure-to-pay, sales automation, and partner networks on one stack.

Use these guides to understand the domains you will sync when connecting ERPs, OMS, CRM, or custom middleware.

+ Navigation
  | Overview: Product map and integration patterns. -> ./overview/
  | Marketplace & network: Catalogues, buyers, suppliers, public projects. -> ./marketplace/
  | REST B2B E-store: Branded storefronts, carts, and store orders. -> /references/rest-api/v2/#b2b-platform-b2b-e-store
  | Source-to-pay: Sourcing, approvals, POs, contracts, spend. -> ./source-to-pay/
  | B2B sales: Opportunity, auction, and sales workflow automation. -> ./b2b-sales/
  | Integrations: ERP and system integration approach. -> ./integrations/

---

# Integrations

Source: https://developers.tradeics.com/guides/b2b-platform/integrations/

Tradeics is designed for ERP and business-system connectivity without long custom projects. Most integrators start with a narrow vertical slice, then expand.

# Suggested first slice

1. Authenticate and read master data (categories / reference lists).
2. Sync one master object you already own in ERP (for example suppliers or items).
3. Mirror one transactional object (RFX or PO) in a single direction.
4. Add payment status only after masters and orders are stable.

# Patterns that work well

**Middleware / iPaaS**

Use an integration layer to transform schemas, retry safely, and quarantine bad payloads without blocking business users. Keep Tradeics REST as the system of record for partner-facing contracts — see [REST API V2](/references/rest-api/v2/).

**Identifier map table**

Always persist `tradeics_id ↔ erp_id` (and timestamps). Every later Finance and AI feature depends on clean joins.

**Environment separation**

Keep staging credentials and data completely separate from production. Do not copy production tokens into local `.env` files checked into git.

# ERP touchpoints

| Domain | Typical ERP objects |
| --- | --- |
| Masters | Vendors, customers, items, categories, cost centers |
| Procurement | Requisitions, POs, goods receipts, AP invoices |
| Sales | Quotes, sales orders, delivery notes |
| Finance | Payment runs, bank statements, wallet-equivalent GL codes |

# Where to go next

+ Navigation
  | Platform overview: Product map. -> ../overview/
  | Authentication: Credentials. -> /guides/getting-started/authentication/
  | Tradeics Finance: Payment integrations. -> /guides/finance/
  | REST API V2: Partner HTTP contracts. -> /references/rest-api/v2/

---

# Marketplace & network

Source: https://developers.tradeics.com/guides/b2b-platform/marketplace/

The Tradeics B2B Marketplace lets buyers purchase instantly or source competitively, and lets suppliers sell into a verified network — including public projects and category experts.

# What the marketplace covers

- Product and service listings from verified suppliers
- Direct buy flows and RFQ-driven sourcing
- Supplier network across 50+ industries (local and global)
- Public projects where buyers post needs and receive proposals
- Category experts for on-demand professional services

# Integration focus areas

When you connect an external system, plan for these objects:

1. **Catalog / offerings** — SKUs or service packages, attributes, and commercial terms.
2. **Partner profiles** — buyer / supplier / expert identities and verification state.
3. **Orders & proposals** — marketplace orders and project proposals that must land in ERP or CRM.
4. **B2B E-store** — branded direct-buy storefronts (cart + checkout) — see [REST B2B E-store](/references/rest-api/v2/#b2b-platform-b2b-e-store).
5. **Categories** — taxonomy alignment (Tradeics already exposes vendor sub-category master data via API).

# Practical notes

- Tradeics is infrastructure for trade between parties; commercial contracts and product compliance remain between buyer and supplier.
- Keep your internal category codes mapped to Tradeics categories early — it simplifies search, reporting, and later AI enrichment.
- For first connectivity, start with read-only category / master sync before writing order events.

+ Navigation
  | Source-to-pay: Procurement stack. -> ../source-to-pay/
  | First request: Call category masters. -> /guides/getting-started/first-request/
  | REST API V2: Available HTTP routes. -> /references/rest-api/v2/

---

# Overview

Source: https://developers.tradeics.com/guides/b2b-platform/overview/

Tradeics B2B Platform covers the full path from sourcing and selling through contracting and fulfillment coordination.

# Product map

| Capability | Role in the platform | Why it matters for integrations |
| --- | --- | --- |
| **B2B Marketplace** | Instant purchase and global sell across verified partners | Catalog, pricing, and order sync |
| **Source-to-Pay** | Strategic sourcing → approvals → POs → contracts → invoices | Procurement system of record alignment |
| **B2B Sales** | Sales workflows, auctions, buyer network reach | Opportunity and quote pipelines |
| **Business Network** | Trusted partner graph across industries | Supplier / buyer master sync |

# Common integration shapes

**Inbound to Tradeics**

- Push approved suppliers, items, and price lists from ERP.
- Create or update RFXs / procurement requests from internal tools.
- Mirror organizational approval decisions into Tradeics workflows.

**Outbound from Tradeics**

- Pull POs, contract status, auction results, and order events into ERP / OMS.
- Mirror supplier onboarding status and category mappings.
- Stream spend and operational events into BI / data warehouse.

# Design principles

- Treat Tradeics as the collaboration layer between trading partners; your ERP remains the financial system of record unless you explicitly adopt Tradeics Finance settlement in the loop.
- Prefer idempotent upserts for masters (suppliers, SKUs, categories).
- Store Tradeics identifiers on your side so later payment and AI enrichment join cleanly.

# Next

+ Navigation
  | Marketplace & network: Commerce surfaces. -> ../marketplace/
  | Source-to-pay: Procurement deep dive. -> ../source-to-pay/
  | Integrations: ERP connection guidance. -> ../integrations/

---

# Source-to-pay

Source: https://developers.tradeics.com/guides/b2b-platform/source-to-pay/

Tradeics Source-to-Pay (procure-to-pay) compresses sourcing, approvals, purchasing, contracting, and invoice payment into one flow.

# Capabilities you will typically sync

| Capability | Description | Integration signal |
| --- | --- | --- |
| **Strategic sourcing / RFX** | Unlimited RFXs to collect competitive responses | Create / close RFXs; pull awards |
| **e-Auction** | Live reverse or forward auctions | Auction lifecycle + bid outcomes |
| **Approval workflows** | Automated routing for compliance and speed | Approval state machines |
| **PO management** | Order placement through delivery tracking | PO headers/lines and status |
| **Smart contracts** | Digital contracts with integrity controls | Contract versions and signatures |
| **e-Invoice / payments** | Invoice capture linked to payment rails | Invoice + payable status |
| **Spend analytics** | Procurement insight for finance and ops | Aggregated spend extracts |

# Recommended sync order

1. Organizational units and approval roles
2. Supplier masters and categories
3. RFX / auction events
4. Purchase orders and fulfillment status
5. Contracts and invoice / payment anchors (handoff to Tradeics Finance)

# Notes for implementers

- Model approvals as explicit states (`draft`, `pending`, `approved`, `rejected`, `cancelled`) even if you later map richer workflow graphs.
- Do not invent payment settlement logic inside PO sync — settle through [Tradeics Finance](/guides/finance/) when wallet or Tradeics Pay is in scope.
- Prefer event-driven pulls (polling or future webhooks) keyed by Tradeics identifiers rather than fragile name matching.

+ Navigation
  | B2B sales: Seller-side workflows. -> ../b2b-sales/
  | Tradeics Finance: Payment layer. -> /guides/finance/
  | Integrations: ERP patterns. -> ../integrations/

---

# Tradeics Finance

Source: https://developers.tradeics.com/guides/finance/

Tradeics Finance is the payments and settlement layer for B2B trade on Tradeics — covering Tradeics Pay, in-platform wallets, invoices, and reconciliation.

+ Navigation
  | Overview: How money moves on Tradeics. -> ./overview/
  | Tradeics Pay: Cards, transfers, gateways, and permissioned connections. -> ./tradeics-pay/
  | Wallets & settlement: Closed-loop wallet behavior and finance system joins. -> ./wallets/

---

# Overview

Source: https://developers.tradeics.com/guides/finance/overview/

Tradeics Finance sits beside procurement and sales so buyers and suppliers can pay, get paid, and reconcile without leaving the trade context.

# What Finance covers

- **Tradeics Pay** — cards, bank transfers, local gateways, and wallet rails in one payment surface
- **Wallets** — closed-loop balances for platform transactions (not bank accounts)
- **Invoices & e-pay** — invoice capture tied to payable / receivable outcomes
- **Permissions & sync** — conditional access for connected platforms and up-to-date payment state

# How it relates to B2B Platform

| Flow | Platform creates | Finance settles |
| --- | --- | --- |
| Marketplace order | Commercial order between parties | Payment / wallet movement |
| PO + invoice | Procurement document chain | Payable confirmation |
| Expert service order | Completed work record | Commission and payout handling |

Tradeics provides infrastructure (including smart escrow-style controls where applicable). Tradeics is not the buyer or seller of goods and services, and wallets are not interest-bearing bank accounts.

# Integration posture for this launch

Documented HTTP payment routes will expand as Tradeics Platform API coverage grows. Design your domain models now around:

1. Payment intent / attempt
2. Wallet ledger entries
3. Invoice ↔ payment linkage
4. Final settlement status for ERP posting

+ Navigation
  | Tradeics Pay: Payment methods and partner access. -> ../tradeics-pay/
  | Wallets & settlement: Ledger and ERP posting. -> ../wallets/
  | Source-to-pay: Upstream procurement context. -> /guides/b2b-platform/source-to-pay/

---

# Tradeics Pay

Source: https://developers.tradeics.com/guides/finance/tradeics-pay/

Tradeics Pay simplifies B2B payments for buyers and suppliers with flexible rails and visibility across every transaction.

# Payment methods

Integrations should assume method diversity:

- Cards
- Bank transfers
- Local payment gateways
- In-platform wallets

Your middleware should treat **method** as metadata on a payment attempt, not as separate business processes, so finance posting stays consistent.

# Product capabilities that matter to developers

| Capability | Meaning for integrations |
| --- | --- |
| **Unified documentation surface** | One place for payment and connection contracts as APIs ship |
| **Smart synchronization** | Keep connected platforms aligned on balances, statuses, and invoices |
| **Advanced permissions** | Grant conditional access to connected platforms by business need |

# Design guidance

- Capture `payment_id`, `method`, `currency`, `amount`, `status`, and timestamps on your side.
- Never store full card PANs or sensitive gateway secrets in your application database — use the PSP / Tradeics tokenization model.
- Map payment status to ERP postings only on terminal states (`succeeded`, `failed`, `cancelled`, `refunded`) to avoid duplicate books.
- When permissions are scoped per connected platform, fail closed if a token lacks entitlement for a payout or refund action.

# Related

+ Navigation
  | Wallets & settlement: Wallet-specific rules. -> ../wallets/
  | Finance overview: Money movement model. -> ../overview/
  | Getting started: Auth model. -> /guides/getting-started/authentication/

---

# Wallets & settlement

Source: https://developers.tradeics.com/guides/finance/wallets/

Tradeics wallets are closed-loop instruments for platform transactions between buyers, suppliers, and experts. They fund and settle Tradeics activity — they are not bank accounts, do not earn interest, and are not deposit-insured accounts.

# Integration model

Think in **ledger terms**:

1. **Funding** — inbound value into a wallet (subject to PSP and compliance rules)
2. **Hold / escrow-style states** — funds reserved for an active trade
3. **Release / payout** — settlement to the counterparty according to platform rules
4. **Adjustments** — refunds, fees, commissions, or compliance holds

# ERP joining rules

| Tradeics concept | Typical ERP treatment |
| --- | --- |
| Wallet balance | Control account / clearing account — not AR/AP by itself |
| Successful settlement | Clear clearing → post AP/AR or cash as your policy requires |
| Fees / commissions | Expense or contra-revenue accounts |
| Frozen / suspended wallet | Block outbound automation; alert finance ops |

# Compliance awareness

PSPs and Tradeics may freeze, suspend, or deduct balances for fraud prevention, AML obligations, chargebacks, or outstanding liabilities. Build monitoring for unexpected wallet state changes rather than assuming balances only move from your own API calls.

!! Do not present wallet balances to end users as bank balances. Label them as Tradeics wallet funds.

# Next

+ Navigation
  | Tradeics Pay: Broader payment rails. -> ../tradeics-pay/
  | B2B Platform integrations: End-to-end sync. -> /guides/b2b-platform/integrations/
  | REST API V2: Current HTTP surface. -> /references/rest-api/v2/

---

# API clients

Source: https://developers.tradeics.com/guides/getting-started/api-clients/

Explore Tradeics APIs in the leading HTTP clients — Postman, Insomnia, Bruno, Hoppscotch, and HTTPie — or import OpenAPI into codegen tools.

# REST API V2

| Artifact | Best for |
| --- | --- |
| [Postman collection](/static/user/data/collections/rest-api-v2.postman) | Postman, HTTPie Desktop |
| [OpenAPI 3.1](/static/user/data/openapi/rest-api-v2.openapi.json) | Insomnia, Bruno, Hoppscotch, SDKs |

<div class="tradeics-client-tools">
  <a class="tradeics-client-pill tradeics-client-pill--postman" href="/static/user/data/collections/rest-api-v2.postman" target="_blank" rel="noopener" title="Import in Postman" data-label="Postman"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-postman.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Postman</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--insomnia" href="/static/user/data/openapi/rest-api-v2.openapi.json" target="_blank" rel="noopener" title="Import in Insomnia" data-label="Insomnia"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-insomnia.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Insomnia</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--bruno" href="/static/user/data/openapi/rest-api-v2.openapi.json" target="_blank" rel="noopener" title="Import in Bruno" data-label="Bruno"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-bruno.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Bruno</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--hoppscotch" href="/static/user/data/openapi/rest-api-v2.openapi.json" target="_blank" rel="noopener" title="Import in Hoppscotch" data-label="Hoppscotch"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-hoppscotch.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Hoppscotch</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--openapi" href="/static/user/data/openapi/rest-api-v2.openapi.json" target="_blank" rel="noopener" title="Download OpenAPI" data-label="OpenAPI"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-openapiinitiative.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">OpenAPI</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--httpie" href="/static/user/data/collections/rest-api-v2.postman" target="_blank" rel="noopener" title="Import in HTTPie" data-label="HTTPie"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/httpie.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">HTTPie</span></a>
</div>

After import, set `tradeics_api_key` (bearer). Base URL defaults to `https://api.tradeics.example/v2`.

# LLM API

| Artifact | Best for |
| --- | --- |
| [Postman collection](/static/user/data/collections/llm-api-v1.postman) | Chat, models, embeddings |
| [Live OpenAPI](https://llm.tradeics.example/openapi.json) | Full proxy catalog for any OpenAPI client |

<div class="tradeics-client-tools">
  <a class="tradeics-client-pill tradeics-client-pill--postman" href="/static/user/data/collections/llm-api-v1.postman" target="_blank" rel="noopener" title="Import in Postman" data-label="Postman"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-postman.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Postman</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--insomnia" href="https://llm.tradeics.example/openapi.json" target="_blank" rel="noopener" title="Import in Insomnia" data-label="Insomnia"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-insomnia.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Insomnia</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--bruno" href="https://llm.tradeics.example/openapi.json" target="_blank" rel="noopener" title="Import in Bruno" data-label="Bruno"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-bruno.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Bruno</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--hoppscotch" href="https://llm.tradeics.example/openapi.json" target="_blank" rel="noopener" title="Import in Hoppscotch" data-label="Hoppscotch"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-hoppscotch.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Hoppscotch</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--openapi" href="https://llm.tradeics.example/openapi.json" target="_blank" rel="noopener" title="Download OpenAPI" data-label="OpenAPI"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-openapiinitiative.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">OpenAPI</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--httpie" href="/static/user/data/collections/llm-api-v1.postman" target="_blank" rel="noopener" title="Import in HTTPie" data-label="HTTPie"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/httpie.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">HTTPie</span></a>
</div>

Set `tradeics_llm_api_key` and `model_id` (from List models) before chat completions.

# For coding agents

Paste a ready prompt into Cursor, Claude, ChatGPT, or any agent — or fetch the machine-readable docs corpus.

<div class="tradeics-agent-tools">
  <p class="tradeics-agent-tools__label font-sans-semibold">Coding agents</p>
  <div class="tradeics-agent-tools__row">
    <button type="button" class="tradeics-agent-pill tradeics-agent-pill--copy" data-agent-action="copy" data-label="Copy for agent">Copy for agent</button>
    <a class="tradeics-agent-pill tradeics-agent-pill--cursor" href="#" data-agent-action="cursor" data-label="Open in Cursor">Open in Cursor</a>
    <a class="tradeics-agent-pill tradeics-agent-pill--claude" href="#" data-agent-action="claude" data-label="Open in Claude">Open in Claude</a>
    <a class="tradeics-agent-pill tradeics-agent-pill--chatgpt" href="#" data-agent-action="chatgpt" data-label="Open in ChatGPT">Open in ChatGPT</a>
  </div>
</div>

| Artifact | Best for |
| --- | --- |
| [`/llms.txt`](/llms.txt) | Curated index for agents ([llms.txt](https://llmstxt.org/) spec) |
| [`/llms-full.txt`](/llms-full.txt) | Entire guides + references in one file |
| [`/llm.txt`](/llm.txt) | Alias of `llms.txt` |

# Which client?

| Client | Strength |
| --- | --- |
| **Postman** | Collaboration, collection runner, environments |
| **Insomnia** | Clean design / GraphQL-friendly debugging |
| **Bruno** | Git-native collections beside your repo |
| **Hoppscotch** | Fast browser-based testing |
| **HTTPie** | Readable CLI + desktop import |
| **Tradeics CLI** | Official `tradeics` binary for terminal + CI ([guide](/guides/tradeics-cli/)) |
| **OpenAPI** | Spec source of truth for codegen and any importer |

# Import tips

1. **Postman / HTTPie** — Import the `.postman` collection file.
2. **Insomnia / Bruno / Hoppscotch** — Import From File / URL using the OpenAPI JSON.
3. Map `Authorization: Bearer` from collection or environment variables.
4. Never commit API keys.

# Related

+ Navigation
  | First request: Multi-language HTTP samples. -> ../first-request/
  | Tradeics CLI: Terminal alternative to Postman. -> /guides/tradeics-cli/
  | REST API V2: Endpoint contracts. -> /references/rest-api/v2/
  | LLM API Reference: Inference routes. -> /references/llm-api/v1/
  | Call the LLM: SDK examples. -> /guides/ai/llm-api/

---

# Authentication

Source: https://developers.tradeics.com/guides/getting-started/authentication/

Tradeics APIs authenticate callers with a bearer token issued for your **workspace**. Keys and sessions resolve to one workspace (users can belong to many). The same family of credentials unlocks REST V2, [MCP Servers](/guides/mcp-server/), and (with LLM keys) inference.

# Current model

Send the token on every request:

```http
Authorization: Bearer <your_api_key>
Content-Type: application/json
```

Until Tradeics Platform ships self-serve key management:

1. Create a Tradeics account at [tradeics.example/get-started](https://tradeics.example/get-started).
2. Contact support (or your account manager) for early API access — ask for MCP enablement if agents will connect.
3. Store the key only in your secrets manager — never in client-side code, public repos, or pasted into shared chat logs.

# Practices to follow now

- Prefer server-to-server calls. Do not embed keys in mobile or browser apps.
- Rotate keys when people leave the project or when a leak is suspected.
- Scope integrations by environment when you receive separate staging credentials ([versioning](../versioning/)).
- Log request IDs / correlation IDs from responses when debugging with support.
- For MCP hosts that cannot send headers, use a short-lived token via `?token=` only as a fallback.

!! Platform REST and MCP use `Authorization: Bearer`. Tradeics LLM also accepts `x-tradeics-llm-api-key`. Confirm against [REST API V2](/references/rest-api/v2/), [LLM API](/references/llm-api/v1/), or [MCP Authentication](/guides/mcp-server/authentication/).

# Next

+ Navigation
  | First request: Authenticate and call an endpoint. -> ../first-request/
  | MCP Servers: Connect Docs / Platform / AI MCP. -> /guides/mcp-server/
  | Agent Skills: Teach agents Tradeics conventions. -> /guides/agent-skills/
  | REST API V2: Full route contracts. -> /references/rest-api/v2/
  | Call the LLM: Inference auth and SDKs. -> /guides/ai/llm-api/

---

# Errors & retries

Source: https://developers.tradeics.com/guides/getting-started/errors/

How Tradeics APIs report failures and how clients should retry safely.

# Envelope errors (REST V2)

```json
{
  "error": true,
  "reason": "unauthorized",
  "data": {}
}
```

Use `reason` for branching — do not parse human message strings.

# LLM proxy errors

OpenAI-style:

```json
{
  "error": {
    "message": "Authentication Error, No api key passed in.",
    "type": "auth_error",
    "code": "401"
  }
}
```

# Retry policy

| Status | Retry? | Guidance |
| --- | --- | --- |
| `429` | Yes | Exponential backoff + jitter |
| `500` / `502` / `503` | Yes | Idempotent methods only |
| `400` / `401` / `403` / `404` / `422` | No | Fix request or credentials |

# Idempotency

- Prefer natural keys (`external_id`) on upserts.
- Do not double-post payments after timeouts — read payment status first.
- For LLM calls, treat completions as non-idempotent; store request ids if you need audit.
- Webhook consumers and MCP write tools must be idempotent — see [Webhooks](../webhooks/).

+ Navigation
  | First request: Connectivity check. -> ../first-request/
  | Rate limits: 429 handling. -> ../rate-limits/
  | REST API V2: Status codes. -> /references/rest-api/v2/
  | LLM API: Auth failures. -> /references/llm-api/v1/

---

# First request

Source: https://developers.tradeics.com/guides/getting-started/first-request/

Call a V2 master-data endpoint to verify credentials before building a full integration.

# Prerequisites

- HTTPS access to `https://api.tradeics.example`
- A workspace API key
- Any HTTP client (`curl`, Postman, or an SDK)

# Endpoint

```text
GET https://api.tradeics.example/v2/master-management/v2.0/vendor-sub-category?page=1
```

# Multi-language examples

## cURL

```bash
curl "https://api.tradeics.example/v2/master-management/v2.0/vendor-sub-category?page=1" \
  --get \
  --header "Authorization: Bearer $TRADEICS_API_KEY" \
  --header "Accept: application/json"
```

## Python

```python
import os
import requests

res = requests.get(
    "https://api.tradeics.example/v2/master-management/v2.0/vendor-sub-category",
    params={"page": 1},
    headers={
        "Authorization": f"Bearer {os.environ['TRADEICS_API_KEY']}",
        "Accept": "application/json",
    },
    timeout=30,
)
print(res.status_code, res.json())
```

## Node.js

```javascript
const res = await fetch(
  "https://api.tradeics.example/v2/master-management/v2.0/vendor-sub-category?page=1",
  {
    headers: {
      Authorization: `Bearer ${process.env.TRADEICS_API_KEY}`,
      Accept: "application/json",
    },
  }
);
console.log(await res.json());
```

## Go

```go
req, _ := http.NewRequest(
  "GET",
  "https://api.tradeics.example/v2/master-management/v2.0/vendor-sub-category?page=1",
  nil,
)
req.Header.Set("Authorization", "Bearer "+os.Getenv("TRADEICS_API_KEY"))
req.Header.Set("Accept", "application/json")
res, err := http.DefaultClient.Do(req)
```

## PHP

```php
<?php
$ch = curl_init("https://api.tradeics.example/v2/master-management/v2.0/vendor-sub-category?page=1");
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("TRADEICS_API_KEY"),
    "Accept: application/json",
  ],
  CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
```

## Java

```java
var request = HttpRequest.newBuilder()
  .uri(URI.create("https://api.tradeics.example/v2/master-management/v2.0/vendor-sub-category?page=1"))
  .header("Authorization", "Bearer " + System.getenv("TRADEICS_API_KEY"))
  .header("Accept", "application/json")
  .GET()
  .build();
var response = HttpClient.newHttpClient()
  .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

# Expected outcomes

| Result | Meaning |
| --- | --- |
| `200` + `error: false` | Connected — map fields into your ERP model |
| `401` | Missing / invalid key |
| `403` | Key not entitled for this route |
| `404` | Resource unavailable for this account |

# Next

1. Browse [REST API V2](/references/rest-api/v2/) — scroll endpoints for right-panel HTTP samples.
2. Read [B2B Platform](/guides/b2b-platform/) for suppliers, RFXs, and POs.
3. For model inference, use [Call the LLM](/guides/ai/llm-api/) against `https://llm.tradeics.example`.

+ Navigation
  | REST API V2: Endpoint contracts + right panel. -> /references/rest-api/v2/
  | Call the LLM: Multi-language LLM clients. -> /guides/ai/llm-api/
  | Authentication: Credential model. -> ../authentication/

---

# Getting Started

Source: https://developers.tradeics.com/guides/getting-started/

Start here if you are integrating Tradeics for the first time — platform map, auth, first call, resilience patterns, and API tooling.

+ Navigation
  | Platform overview: Products and API surfaces. -> ./overview/
  | Authentication: Credentials and headers. -> ./authentication/
  | First request: Multi-language connectivity check. -> ./first-request/
  | Errors & retries: Status codes and backoff. -> ./errors/
  | API clients: Postman, Insomnia, OpenAPI. -> ./api-clients/
  | Rate limits: Quotas, 429s, and backoff. -> ./rate-limits/
  | Versioning & environments: V2 path, staging vs prod. -> ./versioning/
  | Pagination: Page large collections safely. -> ./pagination/
  | Webhooks: Event-driven receivers (rolling out). -> ./webhooks/
  | Agent Skills: Teach coding agents Tradeics conventions. -> /guides/agent-skills/
  | MCP Servers: Docs, Platform, and AI MCP. -> /guides/mcp-server/
  | Apps & Plugins: Build on Tradeics — App Store & AI Builder. -> /guides/apps-plugins/
  | Tradeics CLI: Install and first commands. -> /guides/tradeics-cli/

---

# Platform overview

Source: https://developers.tradeics.com/guides/getting-started/overview/

Tradeics is a B2B trade operating system. It connects buyers, suppliers, and experts across procurement, sales, and payments — with AI-backed controls where integrity and automation matter.

Docs and resources help you build **with**, **for**, and **on** Tradeics.

# What you can build

| Mode | What it means | Typical goals |
| --- | --- | --- |
| **With** Tradeics | Call Tradeics from your ERP, OMS, CRM, agents | REST, LLM, MCP, CLI integrations |
| **For** Tradeics | Operate B2B, Finance, and AI products well | Catalogs, S2P, e-store, payments, AI helpers |
| **On** Tradeics | Extend the platform with apps & plugins | App Store listings, AI Builder, monetization |

| Product | What it covers | Typical integration goals |
| --- | --- | --- |
| **Tradeics B2B Platform** | Marketplace, e-store, source-to-pay, B2B sales, network | Sync catalogues, POs, RFXs, store orders with ERP / OMS |
| **Tradeics Finance** | Tradeics Pay, wallets, invoices, settlement | Trigger payments, reconcile wallets |
| **Tradeics AI** | Assistive automation + LLM proxy | Recommendations and your own inference |
| **Apps & Plugins** | Extensions on the Tradeics App Store | Private/public, free/paid apps powered by Platform + AI Builder |

# How the developer hub is organized

1. **Guides** — product concepts and integration patterns (**with / for / on**).  
2. **Agent Skills** — teach coding agents Tradeics conventions.  
3. **MCP Servers** — Docs, Platform, and AI tools for agents.  
4. **Apps & Plugins** — build on Tradeics; App Store & monetization.  
5. **Tradeics CLI** — terminal workflows for REST, LLM, and webhooks.  
6. **References** — HTTP contracts for available APIs.  
7. **Platform changes** — ledger of notable updates.

# Access today

API credentials and usage will be managed from **Tradeics Platform** (coming soon). Until self-serve keys are available, request early API access through support or your Tradeics account manager.

Base URL for REST (placeholder):

```text
https://api.tradeics.example/v2/
```

MCP servers (Streamable HTTP, placeholders):

```text
https://mcp.tradeics.example/docs
https://mcp.tradeics.example/platform
https://mcp.tradeics.example/ai
```

All production traffic must use HTTPS.

# Next

+ Navigation
  | Authentication: How requests are authorized. -> ../authentication/
  | First request: Make your first call. -> ../first-request/
  | Apps & Plugins: Extend Tradeics on the App Store. -> /guides/apps-plugins/
  | Agent Skills: Procedural packs for coding agents. -> /guides/agent-skills/
  | MCP Servers: Docs, Platform, and AI MCP. -> /guides/mcp-server/
  | Tradeics CLI: Install and call from the terminal. -> /guides/tradeics-cli/
  | Tradeics B2B Platform: Product deep dive. -> /guides/b2b-platform/

---

# Pagination

Source: https://developers.tradeics.com/guides/getting-started/pagination/

Large Tradeics collections (catalogs, RFQs, suppliers, wallet movements) should be fetched page by page. Design clients for pagination **before** volumes grow.

# Conventions to expect

As REST V2 routes expand, list endpoints typically accept:

| Parameter | Role |
| --- | --- |
| `limit` / `page_size` | Page size (cap enforced server-side) |
| `offset` / `page` | Offset- or page-based traversal |
| `cursor` / `starting_after` | Cursor traversal when offered |

Responses usually include either:

- a `data` array plus pagination metadata (`has_more`, `next_cursor`, totals), or
- link headers / next-page tokens documented per route.

Always read the route notes in [REST API V2](/references/rest-api/v2/) — do not assume Stripe-identical cursor names until the field is documented.

# Client rules

1. Cap page size to what the API allows; bigger pages can hit timeouts and [rate limits](../rate-limits/).
2. Stop when `has_more` is false / next cursor is empty — never invent offsets.
3. Stabilize sorts (`created_at`, `id`) when stitching pages for sync jobs.
4. Persist cursors for incremental syncs; do not restart from page 1 every minute.
5. MCP tools that wrap lists should request modest pages so agents stay within token and rate budgets.

# Sync pattern

```text
cursor = null
loop:
  page = GET /resource?limit=100&cursor=cursor
  upsert(page.data)
  if not page.has_more: break
  cursor = page.next_cursor
```

# Next

+ Navigation
  | Rate limits: Stay under quotas while paging. -> ../rate-limits/
  | First request: Connectivity check. -> ../first-request/
  | B2B integrations: Vertical sync slices. -> /guides/b2b-platform/integrations/

---

# Rate limits

Source: https://developers.tradeics.com/guides/getting-started/rate-limits/

Tradeics applies fair-use rate limits so one integration cannot starve others. Limits are shared across REST V2, MCP tools that call the same resources, and (separately) the LLM proxy.

# How limits are measured

- Counters are typically per **API key** (and sometimes per workspace).
- Burst capacity absorbs short spikes; sustained traffic should stay under the published steady rate for your tier.
- MCP tool calls count against the same resource quotas as equivalent REST requests.

Exact numbers depend on your early-access agreement. When self-serve Platform rolls out, limits will appear on the developer dashboard.

# Response signals

When you exceed a limit, expect HTTP `429` (or an LLM-style rate error from `https://llm.tradeics.example`).

Honor these response headers when present:

| Header | Meaning |
| --- | --- |
| `Retry-After` | Seconds (or HTTP date) to wait before retrying |
| `X-RateLimit-Limit` | Ceiling for the current window |
| `X-RateLimit-Remaining` | Calls left in the window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |

!! Treat missing headers as “retry with backoff” — do not tight-loop `429`s.

# Client best practices

1. Cache read-mostly master data (categories, dictionaries) instead of polling every second.
2. Use exponential backoff with jitter on `429` and `5xx` (see [Errors & retries](../errors/)).
3. Batch work: prefer list endpoints with pagination over N× single-id GETs.
4. Separate LLM traffic (`llm.tradeics.example`) from platform REST — different capacity pools.
5. For agents via [MCP](/guides/mcp-server/), throttle autonomous loops; prefer human-confirmed writes.

# Next

+ Navigation
  | Errors & retries: Status matrix and idempotency. -> ../errors/
  | Pagination: Fetch large collections safely. -> ../pagination/
  | MCP Servers: Agent traffic shares these quotas. -> /guides/mcp-server/

---

# Versioning & environments

Source: https://developers.tradeics.com/guides/getting-started/versioning/

Pin integrations to an explicit API version and keep staging traffic away from production credentials — the same baseline Stripe- and Crisp-style hubs expect from serious partners.

# REST versioning

Platform HTTP lives under the **V2** prefix:

```text
https://api.tradeics.example/v2/
```

- Prefer path versioning (`/v2/...`) over guessing undecided hosts.
- Do not hard-code scrapes of undocumented V1 paths; [REST API V2](/references/rest-api/v2/) is the contract.
- Breaking changes are called out in [Platform Changes](/changes/) (breaking entries appear emphasized).

The LLM proxy is separately versioned as OpenAI-compatible **`/v1`** on `https://llm.tradeics.example` — that `v1` is the LLM surface, not Tradeics REST V1.

# Environments

| Environment | Purpose | Credentials |
| --- | --- | --- |
| **Staging / sandbox** | Integration testing, agent experiments | Dedicated early-access keys when issued |
| **Production** | Live buyer / supplier data | Production keys only |

Practices:

- Never reuse production tokens in CI or local agent configs.
- Point staging at staging base URLs when provided; otherwise isolate with separate keys even on the same host.
- Document which environment each webhook or MCP connection targets.

# Compatibility expectations

- Additive fields may appear without a major bump — clients must ignore unknown JSON properties.
- Removals and semantic changes land as breaking changes in the ledger.
- MCP tool schemas evolve with REST scopes; pin agent prompts to stable tool names when you automate.

# Next

+ Navigation
  | Authentication: Per-environment secrets. -> ../authentication/
  | Pagination: Stable list contracts. -> ../pagination/
  | Platform Changes: Watch for breaks. -> /changes/

---

# Webhooks

Source: https://developers.tradeics.com/guides/getting-started/webhooks/

Event-driven integrations (order status, RFQ updates, payment state) should use webhooks instead of tight polling — the same model used by [Crisp](https://docs.crisp.chat/) and [Stripe](https://docs.stripe.com/).

!! Tradeics Web Hooks delivery is rolling out with Platform. Use this guide to design receivers **now**, and poll only as a temporary bridge.

# Design your receiver first

1. Expose an HTTPS endpoint your edge can verify (TLS required).
2. Accept `POST` with a JSON body; respond `2xx` quickly (under a few seconds).
3. Process asynchronously — enqueue work, then acknowledge.
4. Treat deliveries as **at-least-once**: dedupe on event id / `external_id`.
5. Verify signatures when Tradeics publishes a signing secret (HMAC over the raw body).

# Event categories (planned)

| Domain | Example reasons to subscribe |
| --- | --- |
| **Marketplace / network** | Catalog publish, partner invites, order state |
| **Source-to-pay** | RFQ open / award, PO approved, invoice posted |
| **Finance** | Payment captured, wallet movement, settlement batch |
| **Platform** | Membership / permission changes |

Exact event names will ship in a Web Hooks reference when live. Prefer durable event ids over brittle type strings in your storage key.

# Security checklist

- Rotating secrets: support dual secrets during rotation windows.
- Reject unsigned or stale timestamps.
- Never expose receiver URLs without auth or signature checks.
- Log delivery ids for support — include them when [contacting us](#crisp-chat-open).

# Until webhooks ship

- Poll with [pagination](../pagination/) and respectful [rate limits](../rate-limits/).
- Prefer ETag / `updated_since` filters when a route exposes them.
- Agent automations via [MCP](/guides/mcp-server/) can watch for change *interactively*, but are not a substitute for reliable delivery to your ERP.

# Next

+ Navigation
  | Errors & retries: Idempotent consumers. -> ../errors/
  | B2B integrations: Where events fit your ERP. -> /guides/b2b-platform/integrations/
  | RTM API: Realtime channel (coming soon). -> /references/rtm-api/v1/

---

# Guides

Source: https://developers.tradeics.com/guides/

**Docs and resources to help you build with, for, and on Tradeics.**

| Mode | Meaning | Start here |
| --- | --- | --- |
| **With** | Integrate Tradeics into your systems | [Getting Started](./getting-started/), [REST V2](/references/rest-api/v2/) |
| **For** | Run B2B, Finance, and AI products | Product guides below |
| **On** | Extend Tradeics with apps & plugins on the App Store | [Apps & Plugins](./apps-plugins/) |

Also covered: **Agent Skills**, **MCP Servers**, and the **Tradeics CLI**. Use guides with the [REST API V2](/references/rest-api/v2/) and [LLM API](/references/llm-api/v1/) when you call endpoints.

Coding agents can ingest the hub via [`/llms.txt`](/llms.txt) or [`/llms-full.txt`](/llms-full.txt). Every guide has **Copy for agent** and **Open in Cursor / Claude / ChatGPT**.

+ Navigation
  | Getting Started: Auth, first call, rate limits, webhooks, pagination. -> ./getting-started/
  | Tradeics B2B Platform: Marketplace, e-store, source-to-pay, sales. -> ./b2b-platform/
  | Tradeics Finance: Payments, wallets, settlement, and Tradeics Pay. -> ./finance/
  | Tradeics AI: Product AI plus the OpenAI-compatible LLM proxy. -> ./ai/
  | Agent Skills: Teach agents Tradeics docs, API, platform, and AI patterns. -> ./agent-skills/
  | MCP Servers: Docs, Platform, and AI MCP for agents. -> ./mcp-server/
  | Apps & Plugins: Build on Tradeics — App Store, AI Builder, monetization. -> ./apps-plugins/
  | Tradeics CLI: Terminal workflows for REST, LLM, webhooks, and CI. -> ./tradeics-cli/

! Technical questions while integrating? [Chat with our support team](#crisp-chat-open).

---

# AI MCP

Source: https://developers.tradeics.com/guides/mcp-server/ai-mcp/

**AI MCP** exposes assistive AI tools for agents — summaries, classification, and other helpers — without replacing the high-volume [LLM HTTPS API](/guides/ai/llm-api/).

Pair with the [Tradeics AI skill](/guides/agent-skills/tradeics-ai/).

# Connection

| Field | Value (placeholder) |
| --- | --- |
| Transport | Streamable HTTP |
| URL | `https://mcp.tradeics.example/ai` |
| Auth | Bearer token with AI scopes (`ai:write` or equivalent) |

# Tool surface (structure)

| Capability | Example tool id (placeholder) | Notes |
| --- | --- | --- |
| Summarize RFX | `assist_summarize_rfx` | Assistive — not an award decision |
| Classify catalog line | `assist_classify_item` | Returns suggestions only |
| Health | `ai_liveliness` | Proxy / assist readiness |
| (Future) embeddings helper | `assist_embed_texts` | Prefer HTTPS LLM for bulk jobs |

For Chat Completions / embeddings at scale, call `https://llm.tradeics.example/v1` directly — see [Call the LLM](/guides/ai/llm-api/).

# When to use

- Agent sessions that need **occasional** assistive tools alongside Platform MCP  
- Interactive RFX review / taxonomy suggestions  

# When not to use

- Batch embeddings or high QPS chat → LLM API  
- Durable writes of commercial state → Platform MCP / REST after human confirmation  

# Example prompts

1. “Summarize this RFX id for a buyer — label the result as AI-assisted.”
2. “Suggest a category for this free-text item line.”

# Page sections to fill at GA

1. Exact schemas and model metadata returned  
2. Latency / rate-limit notes  
3. Content-safety / retention policy links  
4. Versioning of assist tools  

# Next

+ Navigation
  | Connect in agents: Attach AI MCP. -> ../usage-in-agents/
  | LLM API guide: HTTPS inference. -> /guides/ai/llm-api/
  | Tradeics AI skill: Procedural pack. -> /guides/agent-skills/tradeics-ai/

---

# Authentication

Source: https://developers.tradeics.com/guides/mcp-server/authentication/

MCP servers use the same bearer-token family as [REST API V2](/references/rest-api/v2/). Scopes decide **which servers and tools** a token may call.

# Obtain a token

Until Tradeics Platform ships self-serve developer settings:

1. Create a Tradeics account at [tradeics.example/get-started](https://tradeics.example/get-started).
2. Request early API / MCP access from support or your account manager.
3. Store the token in a secrets manager — never in skill files or shared prompts.

When self-serve lands, expect **Tradeics Platform → Developer → MCP** with per-server enablement and scopes (same family as REST keys). Regenerating a workspace key may invalidate REST **and** MCP — coordinate with your team.

# Send credentials

Preferred:

```http
Authorization: Bearer <TRADEICS_MCP_TOKEN>
```

Fallback (hosts without custom headers):

```text
https://mcp.tradeics.example/<server>/?token=<URL_ENCODED_TOKEN>
```

# Scopes model (structure)

| Scope pattern (placeholder) | Intended server | Notes |
| --- | --- | --- |
| `docs:read` | Docs MCP | Default for documentation agents |
| `platform:read` / `platform:write` | Platform MCP | Split read vs write |
| `ai:write` | AI MCP | Assistive invocations |
| Product REST scopes | Platform tools | Align with REST groups (`master:read`, `s2p:write`, …) |

Exact scope strings finalize with GA — keep this table’s rows; replace names when shipping.

# Environments

| Environment | Use |
| --- | --- |
| Staging MCP | Experiment with write tools |
| Production MCP | Operator-supervised automation |

See [Versioning & environments](/guides/getting-started/versioning/).

# Next

+ Navigation
  | Security: Least privilege checklist. -> ../security/
  | Quickstart: Wire the header once. -> ../quickstart/
  | Getting Started auth: Shared REST story. -> /guides/getting-started/authentication/

---

# Docs MCP

Source: https://developers.tradeics.com/guides/mcp-server/docs-mcp/

**Docs MCP** gives agents read-only tools over the official Tradeics developer hub — search, fetch pages, and retrieve snippets — without touching customer workspace data.

Pair with the [Tradeics Docs skill](/guides/agent-skills/tradeics-docs/) and [`/llms.txt`](/llms.txt).

# Connection

| Field | Value (placeholder) |
| --- | --- |
| Transport | Streamable HTTP |
| URL | `https://mcp.tradeics.example/docs` |
| Auth | `Authorization: Bearer <token>` with `docs:read` (or equivalent) |

# Tool surface (structure)

Populate tool names at GA; keep these **capability buckets**:

| Capability | Example tool id (placeholder) | Description |
| --- | --- | --- |
| Search | `docs_search` | Full-text / semantic search across guides + references |
| Fetch page | `docs_get` | Fetch a path or URL from the developer hub |
| Index | `docs_llms_index` | Return `llms.txt` structure for navigation |
| Cite | `docs_resolve` | Resolve a topic → canonical path |

All tools are **read-only**. No mutations of workspace data.

# When to use

- Agent answers “how do I…?” from official docs  
- Codegen that must cite Authentication / Pagination / REST groups  
- Evaluating whether a host prompt invents endpoints  

# When not to use

- Live RFX / catalog operations → [Platform MCP](../platform-mcp/)  
- Batch inference → [LLM API](/guides/ai/llm-api/)  

# Example prompts

1. “Using Docs MCP, find versioning guidance and quote the path.”
2. “Resolve ‘webhook retries’ to the correct Getting Started page.”

# Page sections to fill at GA

1. Exact tool schemas (JSON)  
2. Rate limits specific to Docs MCP  
3. Supported locales / version pins  
4. Changelog for tool renames  

# Next

+ Navigation
  | Platform MCP: Workspace tools. -> ../platform-mcp/
  | Tool conventions: Shared naming rules. -> ../tool-conventions/
  | Tradeics Docs skill: Procedural pack. -> /guides/agent-skills/tradeics-docs/

---

# MCP Servers

Source: https://developers.tradeics.com/guides/mcp-server/

Tradeics exposes **multiple MCP servers** so AI agents get the right tools for the job — documentation lookup, live platform operations, and AI helpers — instead of a single overloaded tool bag.

[MCP](https://modelcontextprotocol.io/) (Model Context Protocol) lets hosts such as Cursor, Claude, ChatGPT, and custom agents discover tools with schemas. Each Tradeics server is independently auth’d, scoped, and versioned.

| Server | Purpose | URL (placeholder) | Status |
| --- | --- | --- | --- |
| **[Docs MCP](./docs-mcp/)** | Search and read official developer docs | `https://mcp.tradeics.example/docs` | Structure ready |
| **[Platform MCP](./platform-mcp/)** | Live workspace: catalogs, S2P, sales, network, finance posture | `https://mcp.tradeics.example/platform` | Early access |
| **[AI MCP](./ai-mcp/)** | Assistive AI tools + LLM-oriented helpers | `https://mcp.tradeics.example/ai` | Structure ready |

Transport for all servers: **Streamable HTTP**. Auth: bearer tokens from the same family as [REST V2](/references/rest-api/v2/) (server-specific scopes). Pair with [Agent Skills](/guides/agent-skills/) for procedural guidance.

!! Hostnames and path prefixes above are reserved placeholders. Keep this catalog and per-server page layout stable when production URLs go live — only replace values, not section structure.

+ Navigation
  | Overview: Architecture and which MCP to enable. -> ./overview/
  | Quickstart: Connect your first MCP in minutes. -> ./quickstart/
  | Authentication: Tokens, scopes, and environments. -> ./authentication/
  | Docs MCP: Documentation tools for agents. -> ./docs-mcp/
  | Platform MCP: Live Tradeics workspace tools. -> ./platform-mcp/
  | AI MCP: Assistive AI and model helpers. -> ./ai-mcp/
  | Connect in agents: Cursor, Claude, ChatGPT, custom. -> ./usage-in-agents/
  | Tool conventions: Naming, idempotency, errors. -> ./tool-conventions/
  | Security: Least privilege and write safety. -> ./security/
  | Troubleshooting: Connection and tool failures. -> ./troubleshooting/
  | Agent Skills: Procedural packs beside MCP. -> /guides/agent-skills/

! Prefer HTTPS SDKs for high-volume backends. Prefer MCP when an **agent** should explore or operate under human/policy oversight.

---

# Overview

Source: https://developers.tradeics.com/guides/mcp-server/overview/

Tradeics ships a **catalog of MCP servers**, not a monolithic tools endpoint. Separating Docs, Platform, and AI keeps scopes tight, tool lists navigable, and failure domains isolated.

# Architecture

```text
Agent host (Cursor / Claude / custom)
        │
        ├─ Docs MCP ──────────► Developer hub content (read-only)
        ├─ Platform MCP ─────► REST V2–backed workspace tools
        └─ AI MCP ────────────► Assistive tools / LLM helpers
```

All servers speak **Streamable HTTP**, share the Tradeics bearer auth model, and respect the same tier / ACL ideas as REST. Tools map to curated capabilities — agents never receive raw “call any URL” primitives.

# Choose a server

| If the agent needs to… | Enable | Do not rely on |
| --- | --- | --- |
| Find or cite official docs | Docs MCP | Platform MCP |
| Read/write catalogs, RFXs, POs, partners | Platform MCP | Docs MCP |
| Summarize / classify / run AI helpers | AI MCP | using Platform for inference batches |
| High-volume Chat Completions | [LLM HTTPS API](/guides/ai/llm-api/) | AI MCP alone |

# Relationship to REST and Skills

| Layer | Role |
| --- | --- |
| [REST API V2](/references/rest-api/v2/) | Source of truth for HTTP contracts |
| [Agent Skills](/guides/agent-skills/) | How the agent should reason and cite |
| MCP Servers | What the agent can invoke live |

# Environments

Plan for **staging** and **production** MCP bases (same path suffixes, different hosts). Prefer staging tokens while exploring write tools. See [Versioning & environments](/guides/getting-started/versioning/).

# Contents of this section (fixed IA)

1. Quickstart — connect one server end-to-end  
2. Authentication — shared token model  
3. Per-server pages — Docs / Platform / AI  
4. Connect in agents — host config samples  
5. Tool conventions — stable naming  
6. Security — least privilege  
7. Troubleshooting — ops playbook  

# Next

+ Navigation
  | Quickstart: First successful tool call. -> ../quickstart/
  | Docs MCP: Read-only docs tools. -> ../docs-mcp/
  | Platform MCP: Workspace tools. -> ../platform-mcp/
  | AI MCP: Assistive tools. -> ../ai-mcp/

---

# Platform MCP

Source: https://developers.tradeics.com/guides/mcp-server/platform-mcp/

**Platform MCP** exposes live Tradeics workspace tools — master data, marketplace, source-to-pay, sales, network, and finance posture — backed by [REST API V2](/references/rest-api/v2/) under your token’s scopes.

Pair with the [Tradeics Platform skill](/guides/agent-skills/tradeics-platform/) and [Tradeics API skill](/guides/agent-skills/tradeics-api/).

# Connection

| Field | Value (placeholder) |
| --- | --- |
| Transport | Streamable HTTP |
| URL | `https://mcp.tradeics.example/platform` |
| Auth | Bearer token with `platform:read` / `platform:write` (+ product scopes) |

Transition URL: `https://api.tradeics.example/mcp/` (treat as Platform until per-server hosts cut over).

# Tool surface (structure)

Group tools to mirror REST / docs IA. Fill concrete ids at GA:

| Domain | Example tools (placeholder) | REST anchors |
| --- | --- | --- |
| Master / catalogs | `list_vendors`, `get_item`, `list_vendor_categories` | Master Data |
| Marketplace | `list_catalogs`, `list_products`, `get_product` | Marketplace |
| B2B E-store | `list_stores`, `get_cart`, `create_store_order` | B2B E-store |
| Source to Pay | `list_rfx`, `get_rfx`, `create_rfx_draft`, `list_purchase_orders` | S2P |
| Sales | `list_opportunities`, `list_quotes` | Sales |
| Network | `list_partners`, `get_partner` | Network |
| Finance posture | `list_payments`, `list_invoices`, `list_wallets` | Finance |
| Webhooks / account | `list_webhook_subscriptions`, `get_organization` | Webhooks / Account |

# Safety defaults

- Prefer list/get before create/update.
- Require operator confirmation for writes unless policy auto-approves.
- Never invent tool arguments outside schema.

!! Write tools can affect live commercial workflows. Use staging credentials while developing agent prompts.

# Example prompts

1. “List vendor sub-categories, then propose a sync plan for our PIM.”
2. “Summarize open RFXs — read only.”
3. “Draft (do not submit) an RFX create payload and wait for my OK.”

# Page sections to fill at GA

1. Full tool catalog with schemas  
2. Scope matrix per tool  
3. Idempotency keys for mutating tools  
4. Pagination parameters  

# Next

+ Navigation
  | AI MCP: Assistive tools. -> ../ai-mcp/
  | Security: Write-tool policy. -> ../security/
  | REST API V2: Contract source of truth. -> /references/rest-api/v2/

---

# Quickstart

Source: https://developers.tradeics.com/guides/mcp-server/quickstart/

Connect an AI agent to Tradeics MCP in minutes. Pick **one** server first (usually Docs for read-only, or Platform if you already have an API token), prove a tool call, then add more.

If you already use [Authentication](/guides/getting-started/authentication/) and [REST API V2](/references/rest-api/v2/), this will feel familiar.

# Pick a server

| Start with | URL (placeholder) | Why |
| --- | --- | --- |
| Docs MCP | `https://mcp.tradeics.example/docs` | No workspace side effects |
| Platform MCP | `https://mcp.tradeics.example/platform` | Live data once you have scopes |
| AI MCP | `https://mcp.tradeics.example/ai` | Assistive tools after Platform is solid |

Legacy single-path placeholder (transition): `https://api.tradeics.example/mcp/` — treat as Platform-equivalent until hosts migrate to per-server URLs.

# 1-minute setup

1. Add a new MCP server in your AI tool.
2. Choose transport type: **Streamable HTTP**.
3. Set the URL to your chosen server from the table above.
4. Add the authorization header:

```http
Authorization: Bearer <TRADEICS_MCP_TOKEN>
```

5. Connect. Confirm tools appear for that server only.
6. Run one **read** tool to prove auth (for example docs search, or list catalogs / categories).

Alternatively, pass `?token=<TRADEICS_MCP_TOKEN>` if your host cannot send custom headers. Prefer the `Authorization` header — query tokens leak more easily through logs. URL-encode tokens when using the query form.

!! Early access: tool catalogs grow with REST V2 scopes. Missing a tool? Use the REST reference and [ask support](#crisp-chat-open) to enable the right MCP server for your workspace.

# Suggested first prompts

**Docs MCP**

1. “Search Tradeics docs for pagination and quote the guide path.”

**Platform MCP**

1. “List vendor sub-categories we can use when syncing catalogs.”
2. “Summarize open RFQs that still need supplier responses.”

**AI MCP**

1. “Classify this catalog line into our taxonomy (assistive only).”

# Next

+ Navigation
  | Authentication: Tokens and scopes. -> ../authentication/
  | Connect in agents: Host-specific JSON. -> ../usage-in-agents/
  | Overview: Multi-server architecture. -> ../overview/
  | Agent Skills: Install procedural packs. -> /guides/agent-skills/install/

---

# Security

Source: https://developers.tradeics.com/guides/mcp-server/security/

Treat MCP access like production API access — least privilege, short-lived secrets, and supervised writes.

# Least privilege

| Role | Docs MCP | Platform read | Platform write | AI MCP |
| --- | --- | --- | --- | --- |
| Docs Q&A agent | ✓ | — | — | — |
| Integration engineer | ✓ | ✓ | staging only | optional |
| Operator copilot | ✓ | ✓ | supervised | ✓ |

# Token handling

- Store in secret managers / host secret slots.  
- Never embed in skills, repos, or shared chats.  
- Prefer header auth over `?token=`.  
- Rotate on personnel change and after suspected leak.

# Write safety

1. Default agent prompts to read-only.  
2. Require an explicit confirmation step for mutating tools.  
3. Log tool name, args (redacted), and actor for audits.  
4. Disable write scopes on tokens used in unsupervised loops.

# Network & environments

- Use staging MCP bases for experiments.  
- Separate production tokens from CI smoke tokens.  
- Follow [rate limits](/guides/getting-started/rate-limits/) to avoid locked workspaces.

# Related

+ Navigation
  | Authentication: How tokens are issued. -> ../authentication/
  | Troubleshooting: Auth failures. -> ../troubleshooting/
  | Best practices (skills): Pairing matrix. -> /guides/agent-skills/best-practices/

---

# Tool conventions

Source: https://developers.tradeics.com/guides/mcp-server/tool-conventions/

Stable tool naming and error semantics keep Agent Skills, MCP clients, and REST docs aligned as the catalog grows.

# Naming

| Pattern | Example | Rule |
| --- | --- | --- |
| `{verb}_{resource}` | `list_vendors`, `get_rfx` | Prefer REST-like verbs |
| Server prefix only if required | `docs_search` | Avoid colliding ids across servers |
| No silent renames | — | Deprecate → dual-support → remove |

# Inputs & outputs

- Arguments must match tool JSON Schema; reject unknown fields when strict mode is on.
- Prefer Tradeics REST envelopes where tools wrap HTTP (`error`, `reason`, `data`).
- Pagination: `page` (required, ≥ 1) and optional `page_size` — same as REST guides.

# Errors

| Situation | Tool behavior |
| --- | --- |
| Auth failure | Clear unauthorized error; no partial data |
| Missing scope | Forbidden with scope hint |
| Validation | 422-equivalent message naming the field |
| Rate limit | Retryable signal aligned with REST `429` |

# Idempotency

Mutating tools should accept an optional idempotency key (placeholder name `Idempotency-Key` / `idempotency_key`) once Platform write tools GA.

# Versioning

- Additive tools: non-breaking.  
- Renames / removals: announce in [Platform changes](/changes/) and keep aliases for one release window.  
- Skills must update checklists in the same release.

# Next

+ Navigation
  | Security: Scope and write gates. -> ../security/
  | Platform MCP: Domain tool groups. -> ../platform-mcp/
  | Authoring skills: Keep packs in sync. -> /guides/agent-skills/authoring/

---

# Troubleshooting

Source: https://developers.tradeics.com/guides/mcp-server/troubleshooting/

Diagnose MCP connection and tool failures with a fixed playbook. Expand rows with product-specific codes at GA — keep this symptom → check order.

# Connection

| Symptom | Check |
| --- | --- |
| Server does not appear | Host config JSON validity; restart host |
| Tools list empty | Token present; correct server URL; scopes enabled |
| 401 / unauthorized | Bearer spelling; token rotated; wrong environment |
| 403 / forbidden | Scope missing for that server or tool |
| TLS / network errors | Corporate proxy; allowlist MCP hosts |

# Tool calls

| Symptom | Check |
| --- | --- |
| Validation errors | Args vs schema; required `page` |
| Timeouts | Rate limits; large list pages; retry with backoff |
| Unexpected empty data | Workspace ACL; wrong org token; staging vs prod |
| Write rejected | Missing write scope; confirmation policy |

# Multi-server confusion

- Confirm the agent targeted **Docs vs Platform vs AI** — identical tool names should not collide if configs are separate entries.  
- If using the legacy single URL, expect Platform-only tools.

# Collect for support

1. Agent host + version  
2. MCP server URL (no token)  
3. Tool name and timestamp  
4. Whether REST works with the same token  

[Chat with support](#crisp-chat-open) if blocked after these checks.

# Next

+ Navigation
  | Quickstart: Re-run the happy path. -> ../quickstart/
  | Connect in agents: Host samples. -> ../usage-in-agents/
  | Errors & retries: HTTP semantics. -> /guides/getting-started/errors/

---

# Connect in agents

Source: https://developers.tradeics.com/guides/mcp-server/usage-in-agents/

Wire Tradeics MCP servers into the agents your team already uses. Hosts share Streamable HTTP + bearer auth — only the config shape changes. Prefer enabling **Docs**, **Platform**, and **AI** as separate MCP entries.

# Base fields (every host)

| Field | Docs | Platform | AI |
| --- | --- | --- | --- |
| Transport | Streamable HTTP | Streamable HTTP | Streamable HTTP |
| URL | `https://mcp.tradeics.example/docs` | `https://mcp.tradeics.example/platform` | `https://mcp.tradeics.example/ai` |
| Header | `Authorization: Bearer <TOKEN>` | same | same |

# Cursor

```json
{
  "mcpServers": {
    "tradeics-docs": {
      "url": "https://mcp.tradeics.example/docs",
      "headers": {
        "Authorization": "Bearer ${TRADEICS_MCP_TOKEN}"
      }
    },
    "tradeics-platform": {
      "url": "https://mcp.tradeics.example/platform",
      "headers": {
        "Authorization": "Bearer ${TRADEICS_MCP_TOKEN}"
      }
    },
    "tradeics-ai": {
      "url": "https://mcp.tradeics.example/ai",
      "headers": {
        "Authorization": "Bearer ${TRADEICS_MCP_TOKEN}"
      }
    }
  }
}
```

Put tokens in Cursor secrets or environment — never commit them. After reconnect, ask: “List Tradeics MCP tools grouped by server.”

Also install [Agent Skills](/guides/agent-skills/install/) so the agent knows when to call which server.

# Claude Desktop

Add remote Streamable HTTP entries in `claude_desktop_config.json` for each Tradeics server URL with the same `Authorization` header. Restart, then verify tools appear per server.

# ChatGPT / custom OpenAI agents

1. Create one MCP connector per Tradeics server.  
2. Attach bearer auth.  
3. Enable read tools first; gate write tools by policy.  

Hosts without custom headers may use `?token=` — rotate faster if you do.

# Custom agents (SDK)

```python
# Pseudocode — one session per MCP server
servers = {
    "docs": "https://mcp.tradeics.example/docs",
    "platform": "https://mcp.tradeics.example/platform",
    "ai": "https://mcp.tradeics.example/ai",
}
headers = {"Authorization": f"Bearer {TRADEICS_MCP_TOKEN}"}
# for name, url in servers.items():
#     session = await client.connect(url=url, headers=headers)
#     tools[name] = await session.list_tools()
```

# Safety checklist

- Start with Docs-only; add Platform reads; then writes.  
- Keep tokens out of transcripts and public repos.  
- Apply [rate limits](/guides/getting-started/rate-limits/) and [errors](/guides/getting-started/errors/) policies.  
- Prefer staging credentials when experimenting with writes.

! Stuck connecting? [Chat with support](#crisp-chat-open) — include host name and which server fails.

# Next

+ Navigation
  | Tool conventions: Stable tool ids. -> ../tool-conventions/
  | Troubleshooting: Diagnose connect failures. -> ../troubleshooting/
  | Quickstart: Minimal single-server path. -> ../quickstart/

---

# Authentication

Source: https://developers.tradeics.com/guides/tradeics-cli/authentication/

The CLI authenticates with the same bearer credentials as [REST API V2](/references/rest-api/v2/) and the [MCP Server](/guides/mcp-server/). Prefer **profiles** over pasting keys into every command.

# Login flow (planned)

```bash
# Interactive — stores a named profile in ~/.config/tradeics/config.toml
tradeics login

# Non-interactive — CI / automation
export TRADEICS_API_KEY="..."
tradeics auth status
```

You can also pass a key once:

```bash
tradeics --api-key "$TRADEICS_API_KEY" api get /master-management/v2.0/vendor-sub-category
```

Order of precedence (highest wins):

1. `--api-key` flag
2. `TRADEICS_API_KEY` environment variable
3. Active profile key from config
4. (Optional) device / browser login session when Platform self-serve ships

# Profiles & environments

```bash
tradeics config set --profile staging --api-key "$STAGING_KEY" --base-url https://api.tradeics.example/v2
tradeics config set --profile prod --api-key "$PROD_KEY"

tradeics --profile staging auth status
tradeics --profile prod api get /master-management/v2.0/vendor-sub-category
```

Keep staging and production keys in separate profiles — never reuse production tokens in local agent experiments. See [Versioning & environments](/guides/getting-started/versioning/).

# LLM credentials

LLM commands use the same family of secrets or a dedicated LLM key:

```bash
export TRADEICS_LLM_API_KEY="sk-..."
tradeics llm models list
```

# Logout / rotate

```bash
tradeics logout --profile staging
tradeics auth rotate   # when Platform supports rotation; otherwise rotate via support
```

!! Never commit `~/.config/tradeics/` or `.env` files containing live keys. Treat CLI config like `.ssh`.

# Next

+ Navigation
  | Quickstart: Authenticated happy path. -> ../quickstart/
  | Configuration: Config file layout. -> ../configuration/
  | Platform authentication guide: HTTP headers. -> /guides/getting-started/authentication/

---

# Commands

Source: https://developers.tradeics.com/guides/tradeics-cli/commands/

Planned command groups for `tradeics`. Names are stable enough to document against; flags may grow. Treat anything marked **planned** as subject to polish before GA.

# Global flags

| Flag | Purpose |
| --- | --- |
| `--profile <name>` | Select a named config profile |
| `--api-key <key>` | Override auth for this invocation |
| `--base-url <url>` | Override REST base (default `https://api.tradeics.example/v2`) |
| `--format <table\|json\|yaml>` | Output format |
| `--verbose` / `-v` | Log HTTP method, path, status, latency |
| `--no-color` | Disable ANSI styling |

# Core

| Command | Purpose |
| --- | --- |
| `tradeics version` | Print CLI version and build metadata |
| `tradeics doctor` | Connectivity + auth + TLS diagnostics |
| `tradeics help [command]` | Nested help |
| `tradeics completion bash\|zsh\|fish\|powershell` | Shell autocompletion |

# Auth & config

| Command | Purpose |
| --- | --- |
| `tradeics login` | Interactive credential capture |
| `tradeics logout` | Clear profile session / key |
| `tradeics auth status` | Show active principal (masked) |
| `tradeics config set\|get\|list` | Manage profiles and defaults |

# REST (`api`)

Thin, scriptable wrapper over [REST API V2](/references/rest-api/v2/).

```bash
tradeics api get    <path> [--query k=v]
tradeics api post   <path> --body '{"...":...}' | --file payload.json
tradeics api put    <path> --body ...
tradeics api patch  <path> --body ...
tradeics api delete <path>
```

Convenience aliases (planned as resources expand):

```bash
tradeics master vendor-sub-categories list
tradeics b2b rfqs list --status open
tradeics finance payments get <payment_id>
```

# LLM (`llm`)

Talk to `https://llm.tradeics.example` without hand-rolling HTTP.

```bash
tradeics llm models list
tradeics llm chat --model <id> --message "Summarize this RFQ..."
tradeics llm embed --model <id> --input "catalog line..."
tradeics llm health
```

See [Call the LLM](/guides/ai/llm-api/) and [LLM API Reference](/references/llm-api/v1/).

# Webhooks (`listen` / `trigger`) — planned

```bash
tradeics listen --forward-to https://hooks.example.com/hooks/tradeics
tradeics trigger payment.captured --fixture fixtures/payment.json
```

Mirrors common CLI patterns (Stripe `listen` / `trigger`) for receiver development against a public HTTPS endpoint.

# Docs & agents (`docs`)

```bash
tradeics docs open                    # opens https://developers.tradeics.com
tradeics docs llms                    # prints /llms.txt URL or contents
tradeics docs agent-prompt [--page…]  # copy-ready prompt for Cursor / Claude
```

# MCP helpers — planned

```bash
tradeics mcp url                      # https://api.tradeics.example/mcp/
tradeics mcp doctor                   # probe Streamable HTTP + tools list
```

# Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Usage / validation error |
| `2` | Authentication failure |
| `3` | API / HTTP error (non-2xx) |
| `4` | Network / timeout |
| `5` | Unexpected CLI failure |

# Next

+ Navigation
  | Configuration: Config file and env vars. -> ../configuration/
  | Rate limits: Shared with HTTP clients. -> /guides/getting-started/rate-limits/
  | MCP Servers: Agent alternative to CLI scripting. -> /guides/mcp-server/

---

# Configuration

Source: https://developers.tradeics.com/guides/tradeics-cli/configuration/

Where the CLI stores profiles, how env vars override them, and how to keep CI deterministic.

# Config file (planned)

Default path:

```text
~/.config/tradeics/config.toml          # macOS / Linux
%AppData%\tradeics\config.toml          # Windows
```

Override with `TRADEICS_CONFIG` or `--config <path>`.

Example:

```toml
[default]
base_url = "https://api.tradeics.example/v2"
llm_base_url = "https://llm.tradeics.example/v1"
format = "table"

[profiles.staging]
api_key = "trd_test_..."
base_url = "https://api.tradeics.example/v2"

[profiles.prod]
api_key = "trd_live_..."
```

# Environment variables

| Variable | Purpose |
| --- | --- |
| `TRADEICS_API_KEY` | REST / MCP bearer token |
| `TRADEICS_LLM_API_KEY` | LLM proxy key |
| `TRADEICS_PROFILE` | Default profile name |
| `TRADEICS_BASE_URL` | REST base override |
| `TRADEICS_LLM_BASE_URL` | LLM base override |
| `TRADEICS_CONFIG` | Config file path |
| `NO_COLOR` | Disable color when set |

# CI recommendations

1. Pass secrets via the CI secret store into `TRADEICS_API_KEY` — do not bake profiles into images.
2. Run `tradeics doctor` as a job preface.
3. Prefer `--format json` and stable paths for assertions.
4. Pin CLI version (`tradeics@version`) in release pipelines.
5. Use separate staging keys; never point sandbox jobs at production profiles.

# Telemetry / updates (planned)

- Opt-in version check: `tradeics update check`
- Upgrade in place when package managers allow (`brew upgrade tradeics`, `npm update -g @tradeics/cli`)

# Next

+ Navigation
  | Commands: Full command map. -> ../commands/
  | Install: Get the binary. -> ../install/
  | Versioning & environments: Staging vs prod. -> /guides/getting-started/versioning/

---

# Tradeics CLI

Source: https://developers.tradeics.com/guides/tradeics-cli/

The **Tradeics CLI** (`tradeics`) is the official command-line companion for Tradeics developers — call REST V2, work with the LLM proxy, listen for webhooks, manage profiles, and scaffold integrations without leaving the terminal.

!! The CLI is in active design / early access. These guides define the intended UX and command surface so docs, SDKs, and agents stay aligned while the binary ships. Command availability may expand with each release.

Use the CLI when you want Stripe-style terminal workflows for Tradeics: fast auth, scriptable API calls, local webhook forwarding, and CI-friendly profiles.

+ Navigation
  | Install: macOS, Linux, Windows, and package managers. -> ./install/
  | Authentication: Login, API keys, and profiles. -> ./authentication/
  | Quickstart: First useful commands in under five minutes. -> ./quickstart/
  | Commands: Planned command groups and flags. -> ./commands/
  | Configuration: Config file, envs, and exits codes. -> ./configuration/
  | REST API V2: HTTP contracts the CLI wraps. -> /references/rest-api/v2/
  | API clients: Postman / OpenAPI alongside the CLI. -> /guides/getting-started/api-clients/

! Prefer the CLI for local develop and CI smoke checks. Prefer direct HTTP SDKs or [MCP](/guides/mcp-server/) when an agent or long-running service owns the integration.

---

# Install

Source: https://developers.tradeics.com/guides/tradeics-cli/install/

Install the `tradeics` binary on your machine or CI image. Paths below are the **target** distribution channels — enable them as packages are published.

# Requirements

- macOS 12+, Linux (x86_64 / arm64), or Windows 10+
- Network egress to `https://api.tradeics.example` (and `https://llm.tradeics.example` if you use LLM commands)
- A Tradeics API token ([Authentication](/guides/getting-started/authentication/))

# Recommended installs (planned)

## Homebrew (macOS / Linux)

```bash
brew install tradeics/tap/tradeics
tradeics version
```

## npm (cross-platform wrapper)

```bash
npm install -g @tradeics/cli
tradeics version
```

## Direct binaries

Download the latest release for your OS/arch from the Tradeics CLI releases page (URL publishes with GA), then place `tradeics` on your `PATH`.

```bash
# Example shape once releases are public
curl -fsSL https://cli.tradeics.example/install.sh | sh
tradeics version
```

## Windows

```powershell
winget install Tradeics.CLI
# or
scoop install tradeics
tradeics version
```

## Docker

```bash
docker run --rm -it \
  -e TRADEICS_API_KEY \
  tradeics/cli:latest version
```

# Verify

```bash
tradeics version
tradeics doctor
```

`tradeics doctor` checks connectivity, auth presence, TLS, and tool versions — useful in CI before longer suites.

# Next

+ Navigation
  | Authentication: Login and profiles. -> ../authentication/
  | Quickstart: Run your first commands. -> ../quickstart/

---

# Quickstart

Source: https://developers.tradeics.com/guides/tradeics-cli/quickstart/

Get from zero to a verified Tradeics call in a few minutes once the CLI binary is available.

# 1. Install & check

```bash
tradeics version
tradeics doctor
```

# 2. Authenticate

```bash
export TRADEICS_API_KEY="..."   # or: tradeics login
tradeics auth status
```

# 3. Call REST V2

```bash
# Human-readable table
tradeics api get /master-management/v2.0/vendor-sub-category

# Raw JSON (scripting)
tradeics api get /master-management/v2.0/vendor-sub-category --format json
```

Equivalent to the [First request](/guides/getting-started/first-request/) curl sample — the CLI adds profiles, retries, and consistent exit codes.

# 4. List LLM models

```bash
export TRADEICS_LLM_API_KEY="sk-..."
tradeics llm models list
```

# 5. (Optional) Forward webhooks to your receiver

When webhook forwarding ships:

```bash
tradeics listen --forward-to https://hooks.example.com/tradeics/webhooks
```

Point `--forward-to` at your receiver’s public HTTPS URL (or a secure tunnel URL you control). Design receivers with [Webhooks](/guides/getting-started/webhooks/).

# 6. Ask an agent with docs context

```bash
# Copy an agent-ready prompt that points at llms.txt for this machine's context
tradeics docs agent-prompt --page getting-started/first-request | pbcopy
```

Or open [`/llms.txt`](/llms.txt) / [`/llms-full.txt`](/llms-full.txt) from the developer hub.

# Next

+ Navigation
  | Commands: Full planned surface. -> ../commands/
  | Configuration: Defaults and exit codes. -> ../configuration/
  | First request: Multi-language HTTP samples. -> /guides/getting-started/first-request/

---

# LLM API Reference (V1)

Source: https://developers.tradeics.com/references/llm-api/v1/

# Reference

Tradeics LLM is an **OpenAI-compatible** inference proxy for chat, embeddings, media, and admin-style utility routes.

- **Proxy root:** `https://llm.tradeics.example`
- **OpenAI SDK `base_url`:** `https://llm.tradeics.example/v1`

Scroll an endpoint to load request and response examples in the right panel. Multi-language SDK samples live in [Call the LLM](/guides/ai/llm-api/).

Authenticate with:

```http
Authorization: Bearer <TRADEICS_LLM_API_KEY>
```

or:

```http
x-tradeics-llm-api-key: <TRADEICS_LLM_API_KEY>
```

**Try it with your API client**

<div class="tradeics-client-tools">
  <a class="tradeics-client-pill tradeics-client-pill--postman" href="/static/user/data/collections/llm-api-v1.postman" target="_blank" rel="noopener" title="Import in Postman" data-label="Postman"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-postman.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Postman</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--insomnia" href="/static/user/data/openapi/llm-api-v1.openapi.json" target="_blank" rel="noopener" title="Import in Insomnia" data-label="Insomnia"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-insomnia.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Insomnia</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--bruno" href="/static/user/data/openapi/llm-api-v1.openapi.json" target="_blank" rel="noopener" title="Import in Bruno" data-label="Bruno"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-bruno.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Bruno</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--hoppscotch" href="/static/user/data/openapi/llm-api-v1.openapi.json" target="_blank" rel="noopener" title="Import in Hoppscotch" data-label="Hoppscotch"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-hoppscotch.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Hoppscotch</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--openapi" href="/static/user/data/openapi/llm-api-v1.openapi.json" target="_blank" rel="noopener" title="Download OpenAPI" data-label="OpenAPI"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-openapiinitiative.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">OpenAPI</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--httpie" href="/static/user/data/collections/llm-api-v1.postman" target="_blank" rel="noopener" title="Import in HTTPie" data-label="HTTPie"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/httpie.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">HTTPie</span></a>
</div>

_Download the ⬇️ [Postman collection](/static/user/data/collections/llm-api-v1.postman) or [OpenAPI 3.1](/static/user/data/openapi/llm-api-v1.openapi.json). Live proxy OpenAPI may also be at `https://llm.tradeics.example/openapi.json`. See [API clients](/guides/getting-started/api-clients/)._

+ Navigation
  | Call the LLM: Multi-language examples. -> /guides/ai/llm-api/
  | API clients: Postman, Insomnia, OpenAPI. -> /guides/getting-started/api-clients/
  | AI overview: Where AI fits. -> /guides/ai/overview/
  | REST API V2: Platform data APIs. -> /references/rest-api/v2/
  | AI MCP: Assistive tools for agents. -> /guides/mcp-server/ai-mcp/

# Group Models

Discover which model ids your key can call.

## Catalog [/v1/models]

### List models [GET /v1/models]

Lists model ids you can pass to chat, embeddings, images, and related routes.

+ Request List models (application/json)

    + Tiers: `app`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "object": "list",
            "data": [
                {
                    "id": "tradeics-chat-large",
                    "object": "model",
                    "created": 1718000000,
                    "owned_by": "tradeics"
                },
                {
                    "id": "tradeics-embed-multilingual",
                    "object": "model",
                    "created": 1718000000,
                    "owned_by": "tradeics"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": {
                "message": "Authentication Error, No api key passed in.",
                "type": "auth_error",
                "param": "None",
                "code": "401"
            }
        }
        ```

### Retrieve model [GET /v1/models/{model_id}]

Returns metadata for one model id.

+ Parameters
    + model_id (string, required) - Model id from the catalog

+ Request By id (application/json)

    + Tiers: `app`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "id": "tradeics-chat-large",
            "object": "model",
            "created": 1718000000,
            "owned_by": "tradeics"
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": {
                "message": "The model `unknown` does not exist",
                "type": "invalid_request_error",
                "param": "model",
                "code": "model_not_found"
            }
        }
        ```

# Group Chat

Primary integration path for assistants, RFQ helpers, and classification.

## Completions [/v1/chat/completions]

### Create chat completion [POST /v1/chat/completions]

Creates a chat completion from a list of messages. Set `stream: true` for SSE token streaming.

+ Attributes
    + model (string, required) - Model id from GET /v1/models
    + messages (array, required) - Conversation turns (`system` / `user` / `assistant`)
    + temperature (number, optional) - Sampling temperature
    + max_tokens (number, optional) - Max tokens to generate
    + top_p (number, optional) - Nucleus sampling
    + response_format (object, optional) - e.g. `{ "type": "json_object" }`
    + tools (array, optional) - Tool / function definitions when enabled
    + stream (boolean, optional) - Stream tokens when `true`

+ Request RFQ assistant (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "model": "tradeics-chat-large",
            "messages": [
                {
                    "role": "system",
                    "content": "You help procurement teams evaluate B2B suppliers."
                },
                {
                    "role": "user",
                    "content": "Summarize this RFQ in three bullets."
                }
            ],
            "temperature": 0.2
        }
        ```

+ Request JSON classification (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "model": "tradeics-chat-large",
            "messages": [
                {
                    "role": "system",
                    "content": "Return a JSON object with keys category and confidence."
                },
                {
                    "role": "user",
                    "content": "M8 stainless hex bolt, pack of 500"
                }
            ],
            "temperature": 0,
            "response_format": {
                "type": "json_object"
            }
        }
        ```

+ Request Streaming (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "model": "tradeics-chat-large",
            "messages": [
                {
                    "role": "user",
                    "content": "Draft a short supplier outreach email."
                }
            ],
            "stream": true
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "id": "chatcmpl_01",
            "object": "chat.completion",
            "created": 1718000100,
            "model": "tradeics-chat-large",
            "choices": [
                {
                    "index": 0,
                    "message": {
                        "role": "assistant",
                        "content": "1) Scope 2) Lead time 3) Commercial terms"
                    },
                    "finish_reason": "stop"
                }
            ],
            "usage": {
                "prompt_tokens": 42,
                "completion_tokens": 68,
                "total_tokens": 110
            }
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": {
                "message": "Authentication Error, No api key passed in.",
                "type": "auth_error",
                "param": "None",
                "code": "401"
            }
        }
        ```

+ Response 422 (application/json)

    + Body

        ```
        {
            "detail": [
                {
                    "loc": ["body", "messages"],
                    "msg": "field required",
                    "type": "value_error.missing"
                }
            ]
        }
        ```

# Group Completions

Legacy text-in / text-out completions (prefer Chat Completions for new work).

## Text [/v1/completions]

### Create text completion [POST /v1/completions]

Creates a completion for a raw prompt string.

+ Attributes
    + model (string, required) - Completion-capable model id
    + prompt (string, required) - Input prompt
    + max_tokens (number, optional) - Max tokens to generate
    + temperature (number, optional) - Sampling temperature
    + stop (array, optional) - Stop sequences

+ Request Prompt completion (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "model": "tradeics-chat-large",
            "prompt": "Write a one-line PO acknowledgement:",
            "max_tokens": 64,
            "temperature": 0.3
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "id": "cmpl_01",
            "object": "text_completion",
            "created": 1718000200,
            "model": "tradeics-chat-large",
            "choices": [
                {
                    "text": " We acknowledge PO-2026-118 and will confirm ETA within 24h.",
                    "index": 0,
                    "finish_reason": "stop"
                }
            ],
            "usage": {
                "prompt_tokens": 12,
                "completion_tokens": 18,
                "total_tokens": 30
            }
        }
        ```

# Group Embeddings

Vector embeddings for search, catalog matching, and similarity.

## Vectors [/v1/embeddings]

### Create embeddings [POST /v1/embeddings]

Creates embeddings for one or more input strings (or token arrays when the model supports it).

+ Attributes
    + model (string, required) - Embedding model id
    + input (array, required) - Texts to embed
    + encoding_format (string, optional) - `float` (default) or `base64`
    + dimensions (number, optional) - Output dimensions when the model supports truncation

+ Request Embed catalog lines (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "model": "tradeics-embed-multilingual",
            "input": [
                "stainless steel fasteners M8",
                "industrial chemicals solvent"
            ]
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "object": "list",
            "data": [
                {
                    "object": "embedding",
                    "index": 0,
                    "embedding": [0.012, -0.044, 0.091]
                },
                {
                    "object": "embedding",
                    "index": 1,
                    "embedding": [0.008, 0.021, -0.017]
                }
            ],
            "model": "tradeics-embed-multilingual",
            "usage": {
                "prompt_tokens": 16,
                "total_tokens": 16
            }
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": {
                "message": "Authentication Error, No api key passed in.",
                "type": "auth_error",
                "param": "None",
                "code": "401"
            }
        }
        ```

# Group Images

Image generation for marketing assets, catalog mockups, and assistive previews (when enabled for your key).

## Generations [/v1/images/generations]

### Create image [POST /v1/images/generations]

Generates one or more images from a text prompt.

+ Attributes
    + model (string, required) - Image model id
    + prompt (string, required) - Image description
    + n (number, optional) - Number of images (default `1`)
    + size (string, optional) - e.g. `1024x1024`
    + response_format (string, optional) - `url` or `b64_json`

+ Request Catalog mockup (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "model": "tradeics-image",
            "prompt": "Clean product photo of M12 hex bolts on a white background, B2B catalog style",
            "n": 1,
            "size": "1024x1024"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "created": 1718000300,
            "data": [
                {
                    "url": "https://cdn.tradeics.example/img/gen_01.png"
                }
            ]
        }
        ```

## Edits [/v1/images/edits]

### Edit image [POST /v1/images/edits]

Edits an image with a prompt and optional mask (multipart when uploading files).

+ Attributes
    + model (string, required) - Image edit model id
    + prompt (string, required) - Edit instruction
    + image (string, required) - Source image reference / upload field
    + mask (string, optional) - Mask reference / upload field
    + n (number, optional) - Number of images

+ Request Edit mockup (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "model": "tradeics-image",
            "prompt": "Add a small Tradeics watermark in the corner",
            "image": "https://cdn.tradeics.example/img/gen_01.png",
            "n": 1
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "created": 1718000310,
            "data": [
                {
                    "url": "https://cdn.tradeics.example/img/edit_01.png"
                }
            ]
        }
        ```

# Group Audio

Speech synthesis and transcription for calls, RFQ notes, and accessibility.

## Speech [/v1/audio/speech]

### Create speech [POST /v1/audio/speech]

Turns text into audio (MP3 / other formats depending on model).

+ Attributes
    + model (string, required) - TTS model id
    + input (string, required) - Text to speak
    + voice (string, required) - Voice id (e.g. `alloy`)
    + response_format (string, optional) - `mp3`, `wav`, `opus`
    + speed (number, optional) - Playback speed

+ Request Speak acknowledgement (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "model": "tradeics-tts",
            "input": "Purchase order PO-2026-118 has been confirmed.",
            "voice": "alloy",
            "response_format": "mp3"
        }
        ```

+ Response 200 (application/octet-stream)

    + Body

        ```
        (binary audio payload — mp3/wav/opus depending on response_format)
        ```

## Transcriptions [/v1/audio/transcriptions]

### Create transcription [POST /v1/audio/transcriptions]

Transcribes audio to text (multipart upload in clients; JSON example for proxy-compatible references).

+ Attributes
    + model (string, required) - STT model id
    + file (string, required) - Audio file field / reference
    + language (string, optional) - BCP 47 language hint
    + response_format (string, optional) - `json`, `text`, `verbose_json`

+ Request Transcribe note (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "model": "tradeics-stt",
            "file": "supplier-call.mp3",
            "language": "en",
            "response_format": "json"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "text": "We can ship the fasteners in two weeks at the quoted price."
        }
        ```

## Translations [/v1/audio/translations]

### Create translation [POST /v1/audio/translations]

Transcribes audio and translates into English (OpenAI-compatible translation route).

+ Attributes
    + model (string, required) - STT / translation model id
    + file (string, required) - Audio file field / reference
    + response_format (string, optional) - `json`, `text`

+ Request Translate note (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "model": "tradeics-stt",
            "file": "supplier-call-ar.mp3",
            "response_format": "json"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "text": "We can deliver within fourteen days."
        }
        ```

# Group Moderations

Content policy checks before writing model output into buyer / supplier workflows.

## Checks [/v1/moderations]

### Create moderation [POST /v1/moderations]

Classifies whether input violates content policies.

+ Attributes
    + model (string, optional) - Moderation model id
    + input (string, required) - Text to moderate

+ Request Moderate draft (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "model": "tradeics-moderation",
            "input": "Supplier outreach draft text..."
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "id": "modr_01",
            "model": "tradeics-moderation",
            "results": [
                {
                    "flagged": false,
                    "categories": {
                        "hate": false,
                        "violence": false
                    },
                    "category_scores": {
                        "hate": 0.001,
                        "violence": 0.002
                    }
                }
            ]
        }
        ```

# Group Files

Upload and manage files used by batch jobs, assistants, or fine-tune workflows (when enabled).

## Uploads [/v1/files]

### List files [GET /v1/files]

Lists files owned by your organization / key.

+ Request List files (application/json)

    + Tiers: `app`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "object": "list",
            "data": [
                {
                    "id": "file_01",
                    "object": "file",
                    "bytes": 2048,
                    "created_at": 1718000400,
                    "filename": "catalog-batch.jsonl",
                    "purpose": "batch"
                }
            ]
        }
        ```

### Upload file [POST /v1/files]

Uploads a file for a stated `purpose` (`batch`, `fine-tune`, `assistants`, …).

+ Attributes
    + file (string, required) - Multipart file field
    + purpose (string, required) - Intended use

+ Request Upload batch file (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "file": "catalog-batch.jsonl",
            "purpose": "batch"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "id": "file_01",
            "object": "file",
            "bytes": 2048,
            "created_at": 1718000400,
            "filename": "catalog-batch.jsonl",
            "purpose": "batch"
        }
        ```

### Retrieve file [GET /v1/files/{file_id}]

Returns metadata for one file.

+ Parameters
    + file_id (string, required) - File id

+ Request By id (application/json)

    + Tiers: `app`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "id": "file_01",
            "object": "file",
            "bytes": 2048,
            "created_at": 1718000400,
            "filename": "catalog-batch.jsonl",
            "purpose": "batch"
        }
        ```

### Delete file [DELETE /v1/files/{file_id}]

Deletes a file.

+ Parameters
    + file_id (string, required) - File id

+ Request Delete file (application/json)

    + Tiers: `app`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "id": "file_01",
            "object": "file",
            "deleted": true
        }
        ```

# Group Batches

Async batch inference for high-volume catalog enrichment (when enabled for your key).

## Jobs [/v1/batches]

### List batches [GET /v1/batches]

Lists batch jobs.

+ Request List batches (application/json)

    + Tiers: `app`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "object": "list",
            "data": [
                {
                    "id": "batch_01",
                    "object": "batch",
                    "endpoint": "/v1/chat/completions",
                    "status": "completed"
                }
            ]
        }
        ```

### Create batch [POST /v1/batches]

Creates a batch job from an uploaded `.jsonl` input file.

+ Attributes
    + input_file_id (string, required) - File id with purpose `batch`
    + endpoint (string, required) - Target route, e.g. `/v1/chat/completions`
    + completion_window (string, required) - e.g. `24h`
    + metadata (object, optional) - Free-form labels

+ Request Create chat batch (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "input_file_id": "file_01",
            "endpoint": "/v1/chat/completions",
            "completion_window": "24h",
            "metadata": {
                "job": "catalog-classify-q3"
            }
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "id": "batch_01",
            "object": "batch",
            "endpoint": "/v1/chat/completions",
            "input_file_id": "file_01",
            "status": "validating",
            "completion_window": "24h"
        }
        ```

### Retrieve batch [GET /v1/batches/{batch_id}]

Returns one batch job.

+ Parameters
    + batch_id (string, required) - Batch id

+ Request By id (application/json)

    + Tiers: `app`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "id": "batch_01",
            "object": "batch",
            "status": "completed",
            "output_file_id": "file_out_01",
            "request_counts": {
                "total": 1000,
                "completed": 998,
                "failed": 2
            }
        }
        ```

### Cancel batch [POST /v1/batches/{batch_id}/cancel]

Cancels a batch that is not yet completed.

+ Parameters
    + batch_id (string, required) - Batch id

+ Request Cancel (application/json)

    + Tiers: `app`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "id": "batch_01",
            "object": "batch",
            "status": "cancelling"
        }
        ```

# Group Rerank

Relevance re-ranking for catalog search and RAG pipelines (when enabled).

## Rankings [/v1/rerank]

### Create rerank [POST /v1/rerank]

Scores documents against a query and returns a ranked list.

+ Attributes
    + model (string, required) - Rerank model id
    + query (string, required) - Search query
    + documents (array, required) - Candidate documents
    + top_n (number, optional) - Truncate results

+ Request Rerank SKUs (application/json)

    + Tiers: `app`

    + Body

        ```
        {
            "model": "tradeics-rerank",
            "query": "M12 hex bolt stainless",
            "documents": [
                "M12 hex bolt 50mm zinc",
                "M8 nut stainless",
                "M12 stainless hex bolt 50mm"
            ],
            "top_n": 2
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "model": "tradeics-rerank",
            "results": [
                {
                    "index": 2,
                    "relevance_score": 0.92
                },
                {
                    "index": 0,
                    "relevance_score": 0.71
                }
            ]
        }
        ```

# Group Health

Connectivity checks for gateways, load balancers, and agent readiness probes.

## Liveliness [/health/liveliness]

### Check liveliness [GET /health/liveliness]

Returns a simple alive signal. No API key required.

+ Request Liveliness (application/json)

    + Tiers: `app`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        "I'm alive!"
        ```

## Readiness [/health/readiness]

### Check readiness [GET /health/readiness]

Returns whether the proxy is ready to accept inference traffic (dependencies up).

+ Request Readiness (application/json)

    + Tiers: `app`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "status": "ready",
            "db": true,
            "cache": true,
            "inference": true
        }
        ```

+ Response 503 (application/json)

    + Body

        ```
        {
            "status": "not_ready",
            "db": true,
            "cache": false,
            "inference": true
        }
        ```

---

# REST API Reference (V2)

Source: https://developers.tradeics.com/references/rest-api/v2/

# Reference

The Tradeics REST API **V2** is the current HTTPS surface for ERP, OMS, CRM, and middleware integrations.

**Base URL:** `https://api.tradeics.example/v2/`

**Auth header**

```http
Authorization: Bearer <your_api_key>
Content-Type: application/json
Accept: application/json
```

Scroll any endpoint below to load HTTP request and response examples in the right panel. Multi-language clients live in [First request](/guides/getting-started/first-request/).

**Try it with your API client**

<div class="tradeics-client-tools">
  <a class="tradeics-client-pill tradeics-client-pill--postman" href="/static/user/data/collections/rest-api-v2.postman" target="_blank" rel="noopener" title="Import in Postman" data-label="Postman"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-postman.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Postman</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--insomnia" href="/static/user/data/openapi/rest-api-v2.openapi.json" target="_blank" rel="noopener" title="Import in Insomnia" data-label="Insomnia"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-insomnia.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Insomnia</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--bruno" href="/static/user/data/openapi/rest-api-v2.openapi.json" target="_blank" rel="noopener" title="Import in Bruno" data-label="Bruno"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-bruno.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Bruno</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--hoppscotch" href="/static/user/data/openapi/rest-api-v2.openapi.json" target="_blank" rel="noopener" title="Import in Hoppscotch" data-label="Hoppscotch"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-hoppscotch.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">Hoppscotch</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--openapi" href="/static/user/data/openapi/rest-api-v2.openapi.json" target="_blank" rel="noopener" title="Download OpenAPI" data-label="OpenAPI"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/si-openapiinitiative.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">OpenAPI</span></a>
  <a class="tradeics-client-pill tradeics-client-pill--httpie" href="/static/user/data/collections/rest-api-v2.postman" target="_blank" rel="noopener" title="Import in HTTPie" data-label="HTTPie"><img class="tradeics-client-pill__icon" src="/static/user/images/buttons/icons/httpie.svg" width="16" height="16" alt="" decoding="async" /><span class="tradeics-client-pill__text">HTTPie</span></a>
</div>

_Download the ⬇️ [Postman collection](/static/user/data/collections/rest-api-v2.postman) or [OpenAPI 3.1](/static/user/data/openapi/rest-api-v2.openapi.json) and import into Postman, Insomnia, Bruno, Hoppscotch, or HTTPie. See [API clients](/guides/getting-started/api-clients/)._

**Conventions**

- Prefer **V2** for all new work (`https://api.tradeics.example/v2/`).
- Service modules may include a submodule version (example: `master-management/v2.0`).
- All production traffic uses HTTPS.
- Typical envelope: `{ "error": false, "reason": "listed", "data": {} }`.
- Common statuses: `200`/`201` OK, `400` bad request, `401` unauthorized, `403` forbidden, `404` not found, `422` validation, `429` rate limit, `5xx` retry.

+ Navigation
  | Getting Started: Overview, auth, first request. -> /guides/getting-started/
  | API clients: Postman, Insomnia, OpenAPI. -> /guides/getting-started/api-clients/
  | First request (multi-language): curl, Python, Node, Go, PHP, Java. -> /guides/getting-started/first-request/
  | LLM API: OpenAI-compatible inference at llm.tradeics.example. -> /references/llm-api/v1/
  | B2B Platform guides: Marketplace, S2P, sales. -> /guides/b2b-platform/
  | Finance guides: Pay and wallets. -> /guides/finance/

# Group Master Data

Taxonomy and reference data used across Tradeics B2B Platform. Start here after authentication.

## Catalogs [/master-management/v2.0]

Taxonomy, suppliers, and catalog items under the `master-management` service.

### List vendor categories [GET /vendor-category{?page}{&page_size}]

Returns top-level vendor categories for ERP / PIM taxonomy alignment.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page when supported by your key

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "cat_chem",
                    "name": "Chemicals",
                    "code": "CHEM"
                },
                {
                    "id": "cat_hw",
                    "name": "Hardware",
                    "code": "HW"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### List vendor sub-categories [GET /vendor-sub-category{?page}{&page_size}]

Returns vendor sub-categories for ERP / PIM taxonomy alignment. Ideal first call after authentication.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page when supported by your key

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:read`

    + Body

+ Request List page 2 (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "subcat_chem_01",
                    "name": "Industrial chemicals",
                    "parent_category": "Chemicals",
                    "code": "CHEM-IND"
                },
                {
                    "id": "subcat_fast_02",
                    "name": "Fasteners",
                    "parent_category": "Hardware",
                    "code": "HW-FAST"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

+ Response 403 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_allowed",
            "data": {}
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### List vendors [GET /vendors{?page}{&page_size}{&q}]

Lists suppliers visible to your key.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + q (string, optional) - Free-text name or code filter

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "vnd_9f2a",
                    "name": "Gulf Industrial Supply",
                    "code": "GIS-001",
                    "country": "SA",
                    "status": "active"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### Get vendor [GET /vendors/{id}]

Returns one supplier by Tradeics id.

+ Parameters
    + id (string, required) - Vendor id

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "vnd_9f2a",
                "name": "Gulf Industrial Supply",
                "code": "GIS-001",
                "country": "SA",
                "status": "active",
                "erp_id": "ERP-V-4412"
            }
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### Create vendor [POST /vendors]

Creates a supplier in master data.

+ Attributes
    + name (string, required) - Legal or trading name
    + code (string, required) - Stable supplier code
    + country (string, required) - ISO 3166-1 alpha-2
    + erp_id (string, optional) - External ERP vendor id

+ Request Create supplier (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:write`

    + Body

        ```
        {
            "name": "Gulf Industrial Supply",
            "code": "GIS-001",
            "country": "SA",
            "erp_id": "ERP-V-4412"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "vnd_9f2a",
                "name": "Gulf Industrial Supply",
                "code": "GIS-001",
                "country": "SA",
                "status": "active"
            }
        }
        ```

+ Response 422 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "validation_failed",
            "data": {
                "fields": {
                    "code": "required"
                }
            }
        }
        ```

### Update vendor [PATCH /vendors/{id}]

Updates mutable supplier fields. Omit unchanged keys.

+ Parameters
    + id (string, required) - Vendor id

+ Attributes
    + name (string, optional) - Legal or trading name
    + country (string, optional) - ISO 3166-1 alpha-2
    + status (string, optional) - `active`, `inactive`
    + erp_id (string, optional) - External ERP vendor id

+ Request Patch status (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:write`

    + Body

        ```
        {
            "status": "inactive",
            "erp_id": "ERP-V-4412"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "vnd_9f2a",
                "name": "Gulf Industrial Supply",
                "code": "GIS-001",
                "status": "inactive"
            }
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### Delete vendor [DELETE /vendors/{id}]

Soft-deletes or archives a supplier when policy allows. Prefer `PATCH` status=`inactive` when reversible.

+ Parameters
    + id (string, required) - Vendor id

+ Request Delete supplier (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:write`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "deleted",
            "data": {
                "id": "vnd_9f2a"
            }
        }
        ```

+ Response 409 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "conflict",
            "data": {
                "message": "vendor_in_use"
            }
        }
        ```


### List items [GET /items{?page}{&page_size}{&q}]

Lists catalog items for PIM / ERP sync.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + q (string, optional) - SKU or name filter

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "itm_steel_08",
                    "sku": "STL-M12-50",
                    "name": "M12 hex bolt 50mm",
                    "uom": "EA",
                    "status": "active"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### Get item [GET /items/{id}]

Returns one catalog item by Tradeics id.

+ Parameters
    + id (string, required) - Item id

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "itm_steel_08",
                "sku": "STL-M12-50",
                "name": "M12 hex bolt 50mm",
                "uom": "EA",
                "category_id": "cat_hw",
                "status": "active"
            }
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### Create item [POST /items]

Creates a catalog item for PIM / ERP sync.

+ Attributes
    + sku (string, required) - Stock keeping unit
    + name (string, required) - Display name
    + uom (string, required) - Unit of measure
    + category_id (string, optional) - Vendor category id
    + status (string, optional) - `active`, `inactive` (default `active`)

+ Request Create SKU (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:write`

    + Body

        ```
        {
            "sku": "STL-M12-50",
            "name": "M12 hex bolt 50mm",
            "uom": "EA",
            "category_id": "cat_hw",
            "status": "active"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "itm_steel_08",
                "sku": "STL-M12-50",
                "name": "M12 hex bolt 50mm",
                "uom": "EA",
                "status": "active"
            }
        }
        ```

+ Response 422 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "validation_failed",
            "data": {
                "fields": {
                    "sku": "required"
                }
            }
        }
        ```

### Update item [PATCH /items/{id}]

Updates mutable catalog item fields.

+ Parameters
    + id (string, required) - Item id

+ Attributes
    + name (string, optional) - Display name
    + uom (string, optional) - Unit of measure
    + category_id (string, optional) - Vendor category id
    + status (string, optional) - `active`, `inactive`

+ Request Patch name (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:write`

    + Body

        ```
        {
            "name": "M12 hex bolt 50mm (zinc)",
            "status": "active"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "itm_steel_08",
                "sku": "STL-M12-50",
                "name": "M12 hex bolt 50mm (zinc)",
                "status": "active"
            }
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### Delete item [DELETE /items/{id}]

Archives a catalog item when policy allows.

+ Parameters
    + id (string, required) - Item id

+ Request Delete item (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:write`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "deleted",
            "data": {
                "id": "itm_steel_08"
            }
        }
        ```

+ Response 409 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "conflict",
            "data": {
                "message": "item_referenced_by_products"
            }
        }
        ```

### Create vendor category [POST /vendor-category]

Creates a top-level vendor category.

+ Attributes
    + name (string, required) - Category name
    + code (string, required) - Stable category code

+ Request Create category (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:write`

    + Body

        ```
        {
            "name": "Chemicals",
            "code": "CHEM"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "cat_chem",
                "name": "Chemicals",
                "code": "CHEM"
            }
        }
        ```

### Create vendor sub-category [POST /vendor-sub-category]

Creates a vendor sub-category under a parent category.

+ Attributes
    + name (string, required) - Sub-category name
    + code (string, required) - Stable code
    + parent_category_id (string, required) - Parent category id

+ Request Create sub-category (application/json)

    + Tiers: `user` `app`
    + Scopes: `master:write`

    + Body

        ```
        {
            "name": "Industrial chemicals",
            "code": "CHEM-IND",
            "parent_category_id": "cat_chem"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "subcat_chem_01",
                "name": "Industrial chemicals",
                "parent_category": "Chemicals",
                "code": "CHEM-IND"
            }
        }
        ```


# Group B2B Platform

Marketplace catalogs, B2B e-store storefronts, source-to-pay, sales, and network HTTP routes under V2.

## Marketplace [/b2b-platform/v2.0/marketplace]

Public and network catalog surfaces for buyers and suppliers.

### List catalogs [GET /catalogs{?page}{&page_size}]

Lists catalogs available to your workspace.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `marketplace:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "ctl_net_01",
                    "name": "Verified network catalog",
                    "currency": "USD",
                    "updated_at": "2026-07-10T12:00:00Z"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### List products [GET /products{?page}{&page_size}{&catalog_id}]

Lists sellable products in one or more catalogs.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + catalog_id (string, optional) - Restrict to a catalog

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `marketplace:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "prd_bolt_12",
                    "catalog_id": "ctl_net_01",
                    "sku": "STL-M12-50",
                    "name": "M12 hex bolt 50mm",
                    "unit_price": 0.42,
                    "currency": "USD"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### Get product [GET /products/{id}]

Returns one marketplace product.

+ Parameters
    + id (string, required) - Product id

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `marketplace:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "prd_bolt_12",
                "catalog_id": "ctl_net_01",
                "sku": "STL-M12-50",
                "name": "M12 hex bolt 50mm",
                "unit_price": 0.42,
                "currency": "USD",
                "moq": 100
            }
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### Create product [POST /products]

Publishes a sellable product into a marketplace catalog.

+ Attributes
    + catalog_id (string, required) - Target catalog
    + sku (string, required) - Product SKU
    + name (string, required) - Display name
    + unit_price (number, required) - Major-unit price
    + currency (string, required) - ISO currency code
    + moq (number, optional) - Minimum order quantity

+ Request Create product (application/json)

    + Tiers: `user` `app`
    + Scopes: `marketplace:write`

    + Body

        ```
        {
            "catalog_id": "ctl_net_01",
            "sku": "STL-M12-50",
            "name": "M12 hex bolt 50mm",
            "unit_price": 0.42,
            "currency": "USD",
            "moq": 100
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "prd_bolt_12",
                "catalog_id": "ctl_net_01",
                "sku": "STL-M12-50",
                "status": "active"
            }
        }
        ```

### Update product [PATCH /products/{id}]

Updates price, MOQ, or status on a marketplace product.

+ Parameters
    + id (string, required) - Product id

+ Attributes
    + unit_price (number, optional) - Major-unit price
    + moq (number, optional) - Minimum order quantity
    + status (string, optional) - `active`, `inactive`

+ Request Patch price (application/json)

    + Tiers: `user` `app`
    + Scopes: `marketplace:write`

    + Body

        ```
        {
            "unit_price": 0.39,
            "moq": 200
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "prd_bolt_12",
                "unit_price": 0.39,
                "moq": 200
            }
        }
        ```

### Delete product [DELETE /products/{id}]

Removes a product from the sellable catalog surface.

+ Parameters
    + id (string, required) - Product id

+ Request Delete product (application/json)

    + Tiers: `user` `app`
    + Scopes: `marketplace:write`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "deleted",
            "data": {
                "id": "prd_bolt_12"
            }
        }
        ```

### Create catalog [POST /catalogs]

Creates a marketplace catalog for your workspace.

+ Attributes
    + name (string, required) - Catalog name
    + currency (string, required) - Default ISO currency

+ Request Create catalog (application/json)

    + Tiers: `user` `app`
    + Scopes: `marketplace:write`

    + Body

        ```
        {
            "name": "Network hardware",
            "currency": "USD"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "ctl_net_01",
                "name": "Network hardware",
                "currency": "USD",
                "status": "active"
            }
        }
        ```


## B2B E-store [/b2b-platform/v2.0/estore]

Branded B2B storefronts for direct-buy commerce — distinct from network [Marketplace](#marketplace) listings. Use these routes for store configuration, storefront catalog, carts, and store orders that sync to ERP / OMS.

### List stores [GET /stores{?page}{&page_size}{&status}]

Lists B2B e-stores visible to your workspace.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + status (string, optional) - Filter: `draft`, `live`, `paused`

+ Request List live (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "str_hw_01",
                    "name": "Hardware direct",
                    "slug": "hardware-direct",
                    "currency": "USD",
                    "status": "live"
                }
            ]
        }
        ```

### Get store [GET /stores/{id}]

Returns one e-store configuration.

+ Parameters
    + id (string, required) - Store id

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "str_hw_01",
                "name": "Hardware direct",
                "slug": "hardware-direct",
                "currency": "USD",
                "status": "live",
                "default_catalog_id": "ctl_net_01"
            }
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### Create store [POST /stores]

Creates a B2B e-store (storefront) for your workspace.

+ Attributes
    + name (string, required) - Store display name
    + slug (string, required) - URL slug
    + currency (string, required) - Default ISO currency
    + default_catalog_id (string, optional) - Linked marketplace or private catalog

+ Request Create store (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:write`

    + Body

        ```
        {
            "name": "Hardware direct",
            "slug": "hardware-direct",
            "currency": "USD",
            "default_catalog_id": "ctl_net_01"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "str_hw_01",
                "name": "Hardware direct",
                "slug": "hardware-direct",
                "status": "draft"
            }
        }
        ```

+ Response 422 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "validation_failed",
            "data": {
                "fields": {
                    "slug": "required"
                }
            }
        }
        ```

### Update store [PATCH /stores/{id}]

Updates store branding, catalog link, or publish status.

+ Parameters
    + id (string, required) - Store id

+ Attributes
    + name (string, optional) - Store display name
    + status (string, optional) - `draft`, `live`, `paused`
    + default_catalog_id (string, optional) - Linked catalog
    + currency (string, optional) - Default ISO currency

+ Request Go live (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:write`

    + Body

        ```
        {
            "status": "live"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "str_hw_01",
                "status": "live"
            }
        }
        ```

### Delete store [DELETE /stores/{id}]

Archives a draft or paused store. Live stores with open carts return `409`.

+ Parameters
    + id (string, required) - Store id

+ Request Delete store (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:write`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "deleted",
            "data": {
                "id": "str_hw_01"
            }
        }
        ```

+ Response 409 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "conflict",
            "data": {
                "message": "store_has_open_orders"
            }
        }
        ```

### List storefront products [GET /stores/{id}/products{?page}{&page_size}{&q}]

Lists products visible on a live e-store storefront (resolved from the linked catalog).

+ Parameters
    + id (string, required) - Store id
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + q (string, optional) - SKU or name filter

+ Request List storefront (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "spd_bolt_12",
                    "product_id": "prd_bolt_12",
                    "sku": "STL-M12-50",
                    "name": "M12 hex bolt 50mm",
                    "unit_price": 0.42,
                    "currency": "USD",
                    "moq": 100,
                    "in_stock": true
                }
            ]
        }
        ```

### Get cart [GET /carts/{id}]

Returns a cart for a buyer session or ERP-backed checkout.

+ Parameters
    + id (string, required) - Cart id

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "crt_5501",
                "store_id": "str_hw_01",
                "currency": "USD",
                "status": "open",
                "lines": [
                    {
                        "id": "crl_1",
                        "sku": "STL-M12-50",
                        "quantity": 500,
                        "unit_price": 0.42
                    }
                ],
                "subtotal": 210.00
            }
        }
        ```

### Create cart [POST /carts]

Opens a cart on an e-store for a buyer or partner.

+ Attributes
    + store_id (string, required) - Target e-store
    + partner_id (string, optional) - Buying partner
    + currency (string, optional) - Override store currency when allowed

+ Request Open cart (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:write`

    + Body

        ```
        {
            "store_id": "str_hw_01",
            "partner_id": "ptr_88c2",
            "currency": "USD"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "crt_5501",
                "store_id": "str_hw_01",
                "status": "open",
                "lines": [],
                "subtotal": 0
            }
        }
        ```

### Add cart line [POST /carts/{id}/lines]

Adds a storefront product line to an open cart.

+ Parameters
    + id (string, required) - Cart id

+ Attributes
    + sku (string, required) - Storefront SKU
    + quantity (number, required) - Units to add (must meet MOQ)
    + unit_price (number, optional) - Override when negotiated pricing applies

+ Request Add line (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:write`

    + Body

        ```
        {
            "sku": "STL-M12-50",
            "quantity": 500
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "crl_1",
                "sku": "STL-M12-50",
                "quantity": 500,
                "unit_price": 0.42,
                "line_total": 210.00
            }
        }
        ```

### Update cart line [PATCH /carts/{id}/lines/{line_id}]

Updates quantity on an existing cart line.

+ Parameters
    + id (string, required) - Cart id
    + line_id (string, required) - Cart line id

+ Attributes
    + quantity (number, required) - New quantity

+ Request Patch quantity (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:write`

    + Body

        ```
        {
            "quantity": 1000
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "crl_1",
                "quantity": 1000,
                "line_total": 420.00
            }
        }
        ```

### Delete cart line [DELETE /carts/{id}/lines/{line_id}]

Removes a line from an open cart.

+ Parameters
    + id (string, required) - Cart id
    + line_id (string, required) - Cart line id

+ Request Delete line (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:write`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "deleted",
            "data": {
                "id": "crl_1"
            }
        }
        ```

### List store orders [GET /orders{?page}{&page_size}{&store_id}{&status}]

Lists e-store checkout orders for ERP / OMS sync.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + store_id (string, optional) - Restrict to one store
    + status (string, optional) - Filter: `pending`, `confirmed`, `fulfilled`, `cancelled`

+ Request List confirmed (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "ord_estore_901",
                    "store_id": "str_hw_01",
                    "partner_id": "ptr_88c2",
                    "status": "confirmed",
                    "currency": "USD",
                    "total": 420.00
                }
            ]
        }
        ```

### Get store order [GET /orders/{id}]

Returns one e-store order header and line summary.

+ Parameters
    + id (string, required) - Store order id

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "ord_estore_901",
                "store_id": "str_hw_01",
                "cart_id": "crt_5501",
                "partner_id": "ptr_88c2",
                "status": "confirmed",
                "currency": "USD",
                "total": 420.00,
                "lines": [
                    {
                        "sku": "STL-M12-50",
                        "quantity": 1000,
                        "unit_price": 0.42
                    }
                ]
            }
        }
        ```

### Create store order [POST /orders]

Checks out an open cart into a store order (direct-buy).

+ Attributes
    + cart_id (string, required) - Open cart to checkout
    + reference (string, optional) - Buyer PO / external reference
    + ship_to (string, optional) - Shipping address id or inline label

+ Request Checkout cart (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:write`

    + Body

        ```
        {
            "cart_id": "crt_5501",
            "reference": "BUYER-PO-8841",
            "ship_to": "addr_main"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "ord_estore_901",
                "store_id": "str_hw_01",
                "status": "pending",
                "total": 420.00,
                "currency": "USD"
            }
        }
        ```

+ Response 422 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "validation_failed",
            "data": {
                "fields": {
                    "cart_id": "cart_not_open"
                }
            }
        }
        ```

### Update store order [PATCH /orders/{id}]

Updates store order status for fulfillment sync (`pending` → `confirmed` → `fulfilled` / `cancelled`).

+ Parameters
    + id (string, required) - Store order id

+ Attributes
    + status (string, optional) - `pending`, `confirmed`, `fulfilled`, `cancelled`
    + reference (string, optional) - Buyer PO / external reference

+ Request Confirm order (application/json)

    + Tiers: `user` `app`
    + Scopes: `estore:write`

    + Body

        ```
        {
            "status": "confirmed"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "ord_estore_901",
                "status": "confirmed"
            }
        }
        ```


## Source to Pay [/b2b-platform/v2.0/s2p]

RFX, purchase orders, and related procurement objects.

### List RFXs [GET /rfx{?page}{&page_size}{&status}]

Lists RFQs / RFPs visible to your key.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + status (string, optional) - Filter: `draft`, `open`, `awarded`, `closed`

+ Request List open (application/json)

    + Tiers: `user` `app`
    + Scopes: `s2p:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "rfx_8812",
                    "title": "Q3 fasteners pack",
                    "status": "open",
                    "currency": "USD",
                    "closes_at": "2026-08-01T17:00:00Z"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### Get RFX [GET /rfx/{id}]

Returns one RFX with header fields.

+ Parameters
    + id (string, required) - RFX id

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `s2p:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "rfx_8812",
                "title": "Q3 fasteners pack",
                "status": "open",
                "currency": "USD",
                "line_count": 12,
                "closes_at": "2026-08-01T17:00:00Z"
            }
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### Create RFX [POST /rfx]

Creates an RFX draft. Line details may follow on subsequent update calls.

+ Attributes
    + title (string, required) - RFX title
    + currency (string, required) - ISO currency code
    + closes_at (string, optional) - RFC 3339 close time

+ Request Create draft (application/json)

    + Tiers: `user` `app`
    + Scopes: `s2p:write`

    + Body

        ```
        {
            "title": "Q3 fasteners pack",
            "currency": "USD",
            "closes_at": "2026-08-01T17:00:00Z"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "rfx_8812",
                "title": "Q3 fasteners pack",
                "status": "draft",
                "currency": "USD"
            }
        }
        ```

+ Response 422 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "validation_failed",
            "data": {
                "fields": {
                    "title": "required"
                }
            }
        }
        ```

### Update RFX [PATCH /rfx/{id}]

Updates an RFX draft or open header fields. Award workflows stay separate.

+ Parameters
    + id (string, required) - RFX id

+ Attributes
    + title (string, optional) - RFX title
    + status (string, optional) - `draft`, `open`, `closed`
    + closes_at (string, optional) - RFC 3339 close time

+ Request Patch close time (application/json)

    + Tiers: `user` `app`
    + Scopes: `s2p:write`

    + Body

        ```
        {
            "closes_at": "2026-08-15T17:00:00Z",
            "status": "open"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "rfx_8812",
                "status": "open",
                "closes_at": "2026-08-15T17:00:00Z"
            }
        }
        ```

### Delete RFX [DELETE /rfx/{id}]

Deletes a draft RFX. Open or awarded RFXs return `409` — close them instead.

+ Parameters
    + id (string, required) - RFX id

+ Request Delete draft (application/json)

    + Tiers: `user` `app`
    + Scopes: `s2p:write`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "deleted",
            "data": {
                "id": "rfx_8812"
            }
        }
        ```

+ Response 409 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "conflict",
            "data": {
                "message": "rfx_not_deletable"
            }
        }
        ```


### List purchase orders [GET /purchase-orders{?page}{&page_size}{&status}]

Lists purchase orders for ERP / OMS sync.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + status (string, optional) - Filter: `draft`, `issued`, `received`, `closed`

+ Request List issued (application/json)

    + Tiers: `user` `app`
    + Scopes: `s2p:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "po_2201",
                    "number": "PO-2026-2201",
                    "vendor_id": "vnd_9f2a",
                    "status": "issued",
                    "total": 18420.5,
                    "currency": "USD"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### Get purchase order [GET /purchase-orders/{id}]

Returns one purchase order header.

+ Parameters
    + id (string, required) - Purchase order id

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `s2p:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "po_2201",
                "number": "PO-2026-2201",
                "vendor_id": "vnd_9f2a",
                "status": "issued",
                "total": 18420.5,
                "currency": "USD",
                "erp_id": "ERP-PO-99102"
            }
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### Create purchase order [POST /purchase-orders]

Creates a purchase order draft from an awarded RFX or free-form header.

+ Attributes
    + vendor_id (string, required) - Supplier id
    + currency (string, required) - ISO currency code
    + rfx_id (string, optional) - Source RFX
    + reference (string, optional) - Buyer PO number

+ Request Create PO (application/json)

    + Tiers: `user` `app`
    + Scopes: `s2p:write`

    + Body

        ```
        {
            "vendor_id": "vnd_9f2a",
            "currency": "USD",
            "rfx_id": "rfx_8812",
            "reference": "PO-2026-118"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "po_4410",
                "status": "draft",
                "vendor_id": "vnd_9f2a",
                "reference": "PO-2026-118"
            }
        }
        ```

### Update purchase order [PATCH /purchase-orders/{id}]

Updates PO status or header fields (`draft` → `issued`).

+ Parameters
    + id (string, required) - Purchase order id

+ Attributes
    + status (string, optional) - `draft`, `issued`, `received`, `closed`
    + reference (string, optional) - Buyer PO number

+ Request Issue PO (application/json)

    + Tiers: `user` `app`
    + Scopes: `s2p:write`

    + Body

        ```
        {
            "status": "issued"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "po_4410",
                "status": "issued"
            }
        }
        ```


## Sales [/b2b-platform/v2.0/sales]

Seller-side opportunities and quotes.

### List opportunities [GET /opportunities{?page}{&page_size}{&status}]

Lists sales opportunities in the buyers network.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + status (string, optional) - Filter: `open`, `won`, `lost`

+ Request List open (application/json)

    + Tiers: `user` `app`
    + Scopes: `sales:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "opp_441",
                    "title": "Petrochem plant MRO pack",
                    "status": "open",
                    "buyer_org": "Red Sea Energy",
                    "value": 95000,
                    "currency": "USD"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### List quotes [GET /quotes{?page}{&page_size}{&opportunity_id}]

Lists seller quotes, optionally scoped to an opportunity.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + opportunity_id (string, optional) - Restrict to an opportunity

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `sales:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "qte_112",
                    "opportunity_id": "opp_441",
                    "status": "sent",
                    "total": 91200,
                    "currency": "USD"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### Get quote [GET /quotes/{id}]

Returns one seller quote.

+ Parameters
    + id (string, required) - Quote id

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `sales:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "qte_2201",
                "opportunity_id": "opp_77a1",
                "amount": 12500.00,
                "currency": "USD",
                "status": "sent"
            }
        }
        ```

### Create opportunity [POST /opportunities]

Creates a sales opportunity in the buyers network.

+ Attributes
    + title (string, required) - Opportunity title
    + currency (string, required) - ISO currency code
    + partner_id (string, optional) - Counterparty partner

+ Request Create opportunity (application/json)

    + Tiers: `user` `app`
    + Scopes: `sales:write`

    + Body

        ```
        {
            "title": "Annual fasteners frame",
            "currency": "USD",
            "partner_id": "ptr_88c2"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "opp_77a1",
                "title": "Annual fasteners frame",
                "status": "open",
                "currency": "USD"
            }
        }
        ```

### Update opportunity [PATCH /opportunities/{id}]

Updates opportunity status (`open`, `won`, `lost`) or title.

+ Parameters
    + id (string, required) - Opportunity id

+ Attributes
    + title (string, optional) - Opportunity title
    + status (string, optional) - `open`, `won`, `lost`

+ Request Mark won (application/json)

    + Tiers: `user` `app`
    + Scopes: `sales:write`

    + Body

        ```
        {
            "status": "won"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "opp_77a1",
                "status": "won"
            }
        }
        ```

### Create quote [POST /quotes]

Creates a seller quote for an opportunity.

+ Attributes
    + opportunity_id (string, required) - Parent opportunity
    + amount (number, required) - Quote total in major units
    + currency (string, required) - ISO currency code
    + valid_until (string, optional) - RFC 3339 expiry

+ Request Create quote (application/json)

    + Tiers: `user` `app`
    + Scopes: `sales:write`

    + Body

        ```
        {
            "opportunity_id": "opp_77a1",
            "amount": 12500.00,
            "currency": "USD",
            "valid_until": "2026-09-01T00:00:00Z"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "qte_2201",
                "opportunity_id": "opp_77a1",
                "amount": 12500.00,
                "status": "draft"
            }
        }
        ```

### Update quote [PATCH /quotes/{id}]

Updates quote amount or status (`draft`, `sent`, `accepted`, `rejected`).

+ Parameters
    + id (string, required) - Quote id

+ Attributes
    + amount (number, optional) - Quote total
    + status (string, optional) - `draft`, `sent`, `accepted`, `rejected`

+ Request Send quote (application/json)

    + Tiers: `user` `app`
    + Scopes: `sales:write`

    + Body

        ```
        {
            "status": "sent"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "qte_2201",
                "status": "sent"
            }
        }
        ```


## Network [/b2b-platform/v2.0/network]

Verified trading partners in the business network.

### List partners [GET /b2b-platform/v2.0/network/partners{?page}{&page_size}{&q}]

Lists network partners visible to your workspace.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + q (string, optional) - Name filter

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `network:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "ptr_440",
                    "name": "Red Sea Energy",
                    "role": "buyer",
                    "country": "SA",
                    "status": "verified"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### Get partner [GET /b2b-platform/v2.0/network/partners/{id}]

Returns one network partner.

+ Parameters
    + id (string, required) - Partner id

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `network:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "ptr_440",
                "name": "Red Sea Energy",
                "role": "buyer",
                "country": "SA",
                "status": "verified",
                "erp_id": "ERP-C-8821"
            }
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### Create partner [POST /b2b-platform/v2.0/network/partners]

Invites or registers a network partner for your workspace.

+ Attributes
    + name (string, required) - Partner company name
    + role (string, required) - `buyer`, `supplier`, `both`
    + country (string, optional) - ISO 3166-1 alpha-2

+ Request Invite partner (application/json)

    + Tiers: `user` `app`
    + Scopes: `network:write`

    + Body

        ```
        {
            "name": "Red Sea Trading",
            "role": "buyer",
            "country": "SA"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "ptr_88c2",
                "name": "Red Sea Trading",
                "role": "buyer",
                "status": "pending"
            }
        }
        ```

### Update partner [PATCH /b2b-platform/v2.0/network/partners/{id}]

Updates partner role or status.

+ Parameters
    + id (string, required) - Partner id

+ Attributes
    + role (string, optional) - `buyer`, `supplier`, `both`
    + status (string, optional) - `pending`, `active`, `suspended`

+ Request Activate partner (application/json)

    + Tiers: `user` `app`
    + Scopes: `network:write`

    + Body

        ```
        {
            "status": "active"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "ptr_88c2",
                "status": "active"
            }
        }
        ```


# Group Finance

Tradeics Pay, wallets, and settlement routes under V2.

## Payments [/finance/v2.0/payments]

Payment intents and status for Tradeics Pay.

### List payments [GET /finance/v2.0/payments{?page}{&page_size}{&status}]

Lists payments visible to your workspace.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + status (string, optional) - Filter: `pending`, `captured`, `failed`, `refunded`

+ Request List captured (application/json)

    + Tiers: `user` `app`
    + Scopes: `finance:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "pay_7781",
                    "amount": 18420.5,
                    "currency": "USD",
                    "status": "captured",
                    "po_id": "po_2201"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### Get payment [GET /finance/v2.0/payments/{id}]

Returns one payment by id.

+ Parameters
    + id (string, required) - Payment id

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `finance:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "pay_7781",
                "amount": 18420.5,
                "currency": "USD",
                "status": "captured",
                "po_id": "po_2201",
                "captured_at": "2026-07-12T09:14:22Z"
            }
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### Create payment [POST /finance/v2.0/payments]

Creates a payment intent against an invoice or PO anchor.

+ Attributes
    + amount (number, required) - Major-unit amount
    + currency (string, required) - ISO currency code
    + po_id (string, optional) - Related purchase order
    + invoice_id (string, optional) - Related invoice

+ Request Against PO (application/json)

    + Tiers: `user` `app`
    + Scopes: `finance:write`

    + Body

        ```
        {
            "amount": 18420.5,
            "currency": "USD",
            "po_id": "po_2201"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "pay_7781",
                "amount": 18420.5,
                "currency": "USD",
                "status": "pending",
                "po_id": "po_2201"
            }
        }
        ```

+ Response 422 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "validation_failed",
            "data": {
                "fields": {
                    "amount": "required"
                }
            }
        }
        ```

### Update payment [PATCH /finance/v2.0/payments/{id}]

Updates payment status (for example void a pending intent when policy allows).

+ Parameters
    + id (string, required) - Payment id

+ Attributes
    + status (string, optional) - `pending`, `captured`, `failed`, `refunded`, `void`

+ Request Void pending (application/json)

    + Tiers: `user` `app`
    + Scopes: `finance:write`

    + Body

        ```
        {
            "status": "void"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "pay_5520",
                "status": "void"
            }
        }
        ```


## Wallets [/finance/v2.0/wallets]

In-platform wallets and ledger movements.

### List wallets [GET /finance/v2.0/wallets{?page}{&page_size}]

Lists wallets for your workspace.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `finance:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "wlt_ops_01",
                    "name": "Operating wallet",
                    "currency": "USD",
                    "available": 250000.0,
                    "status": "active"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### List wallet transactions [GET /finance/v2.0/wallets/{id}/transactions{?page}{&page_size}]

Lists ledger movements for one wallet.

+ Parameters
    + id (string, required) - Wallet id
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `finance:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "wtx_901",
                    "wallet_id": "wlt_ops_01",
                    "type": "debit",
                    "amount": 18420.5,
                    "currency": "USD",
                    "reference": "pay_7781",
                    "created_at": "2026-07-12T09:14:22Z"
                }
            ]
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### Create wallet [POST /finance/v2.0/wallets]

Creates a wallet for your workspace in a given currency.

+ Attributes
    + currency (string, required) - ISO currency code
    + label (string, optional) - Display label

+ Request Create wallet (application/json)

    + Tiers: `user` `app`
    + Scopes: `finance:write`

    + Body

        ```
        {
            "currency": "USD",
            "label": "Operating USD"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "wal_3301",
                "currency": "USD",
                "label": "Operating USD",
                "balance": 0
            }
        }
        ```


## Invoices [/finance/v2.0/invoices]

Trade invoices anchored to POs and payments.

### List invoices [GET /finance/v2.0/invoices{?page}{&page_size}{&status}]

Lists invoices for your workspace.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + status (string, optional) - Filter: `draft`, `open`, `paid`, `void`

+ Request List open (application/json)

    + Tiers: `user` `app`
    + Scopes: `finance:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "inv_3301",
                    "number": "INV-2026-3301",
                    "po_id": "po_2201",
                    "status": "open",
                    "total": 18420.5,
                    "currency": "USD"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### Get invoice [GET /finance/v2.0/invoices/{id}]

Returns one invoice.

+ Parameters
    + id (string, required) - Invoice id

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `finance:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "inv_3301",
                "number": "INV-2026-3301",
                "po_id": "po_2201",
                "status": "open",
                "total": 18420.5,
                "currency": "USD",
                "due_at": "2026-08-15T00:00:00Z"
            }
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### Create invoice [POST /finance/v2.0/invoices]

Creates an invoice draft for a partner or PO anchor.

+ Attributes
    + partner_id (string, required) - Bill-to partner
    + currency (string, required) - ISO currency code
    + amount (number, required) - Total in major units
    + purchase_order_id (string, optional) - Related PO

+ Request Create invoice (application/json)

    + Tiers: `user` `app`
    + Scopes: `finance:write`

    + Body

        ```
        {
            "partner_id": "ptr_88c2",
            "currency": "USD",
            "amount": 12500.00,
            "purchase_order_id": "po_4410"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "inv_9102",
                "status": "draft",
                "amount": 12500.00,
                "currency": "USD"
            }
        }
        ```

### Update invoice [PATCH /finance/v2.0/invoices/{id}]

Updates invoice status (`draft` → `open` → `paid` / `void`).

+ Parameters
    + id (string, required) - Invoice id

+ Attributes
    + status (string, optional) - `draft`, `open`, `paid`, `void`
    + amount (number, optional) - Total in major units

+ Request Open invoice (application/json)

    + Tiers: `user` `app`
    + Scopes: `finance:write`

    + Body

        ```
        {
            "status": "open"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "inv_9102",
                "status": "open"
            }
        }
        ```


# Group Webhooks

Subscribe to platform events instead of polling.

## Subscriptions [/webhooks/v2.0/subscriptions]

Outbound webhook destinations for your integration.

### List subscriptions [GET /webhooks/v2.0/subscriptions{?page}{&page_size}]

Lists webhook subscriptions for your key.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `webhooks:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "whs_91",
                    "url": "https://hooks.example.com/tradeics",
                    "events": ["po.issued", "payment.captured"],
                    "status": "active"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### Create subscription [POST /webhooks/v2.0/subscriptions]

Registers a webhook endpoint.

+ Attributes
    + url (string, required) - HTTPS delivery URL
    + events (array, required) - Event names to subscribe to
    + secret (string, optional) - HMAC signing secret

+ Request Create (application/json)

    + Tiers: `user` `app`
    + Scopes: `webhooks:write`

    + Body

        ```
        {
            "url": "https://hooks.example.com/tradeics",
            "events": ["po.issued", "payment.captured"],
            "secret": "whsec_example"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "whs_91",
                "url": "https://hooks.example.com/tradeics",
                "events": ["po.issued", "payment.captured"],
                "status": "active"
            }
        }
        ```

+ Response 422 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "validation_failed",
            "data": {
                "fields": {
                    "url": "required"
                }
            }
        }
        ```

### Get subscription [GET /webhooks/v2.0/subscriptions/{id}]

Returns one webhook subscription.

+ Parameters
    + id (string, required) - Subscription id

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `webhooks:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "whs_101",
                "url": "https://hooks.example.com/tradeics",
                "events": ["rfx.updated", "payment.captured"],
                "status": "active"
            }
        }
        ```

### Update subscription [PATCH /webhooks/v2.0/subscriptions/{id}]

Updates delivery URL, events, or status.

+ Parameters
    + id (string, required) - Subscription id

+ Attributes
    + url (string, optional) - HTTPS delivery URL
    + events (array, optional) - Event names
    + status (string, optional) - `active`, `paused`

+ Request Pause subscription (application/json)

    + Tiers: `user` `app`
    + Scopes: `webhooks:write`

    + Body

        ```
        {
            "status": "paused"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "whs_101",
                "status": "paused"
            }
        }
        ```

### Delete subscription [DELETE /webhooks/v2.0/subscriptions/{id}]

Removes a webhook subscription.

+ Parameters
    + id (string, required) - Subscription id

+ Request Delete subscription (application/json)

    + Tiers: `user` `app`
    + Scopes: `webhooks:write`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "deleted",
            "data": {
                "id": "whs_101"
            }
        }
        ```


### List deliveries [GET /webhooks/v2.0/subscriptions/{id}/deliveries{?page}{&page_size}]

Lists recent delivery attempts for one subscription.

+ Parameters
    + id (string, required) - Subscription id
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `webhooks:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "whd_501",
                    "event": "po.issued",
                    "status": "delivered",
                    "http_status": 200,
                    "delivered_at": "2026-07-12T10:01:00Z"
                }
            ]
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

# Group Account

Workspace control plane for the calling credential — Tradeics is **workspace-centric** (Slack-like):

- A **workspace** is the unique tenant (subscription, subdomain URL, billing, API keys, apps, data).
- **Users** are people who can join one or more workspaces; membership (role) is per workspace.
- Workspace URLs are subdomains of the Tradeics domain (example: `https://acme.tradeics.example`).
- API keys and product data are scoped to the **current workspace** resolved from the bearer token.

## Workspace [/account/v2.0/workspace]

Current workspace bound to your API key (or user session).

### Get current workspace [GET /account/v2.0/workspace]

Returns the workspace tied to your credential, including subdomain URL and subscription summary.

+ Request Me (application/json)

    + Tiers: `user` `app`
    + Scopes: `account:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "ws_acme",
                "name": "Acme Trading",
                "slug": "acme",
                "url": "https://acme.tradeics.example",
                "status": "active",
                "timezone": "Asia/Riyadh",
                "subscription": {
                    "plan": "growth",
                    "status": "active",
                    "renews_at": "2026-08-01T00:00:00Z"
                }
            }
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### Update workspace [PATCH /account/v2.0/workspace]

Updates workspace profile fields visible to integrators. Slug changes (and subdomain URLs) are restricted — contact support when renaming a live workspace.

+ Attributes
    + name (string, optional) - Display name
    + timezone (string, optional) - IANA timezone

+ Request Patch profile (application/json)

    + Tiers: `user` `app`
    + Scopes: `account:write`

    + Body

        ```
        {
            "name": "Acme Trading Co.",
            "timezone": "Asia/Riyadh"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "ws_acme",
                "name": "Acme Trading Co.",
                "slug": "acme",
                "url": "https://acme.tradeics.example",
                "timezone": "Asia/Riyadh"
            }
        }
        ```

## Users [/account/v2.0/users]

Members of the **current workspace**. The same person (user account) can belong to many workspaces with different roles.

### List users [GET /account/v2.0/users{?page}{&page_size}{&status}]

Lists users in the current workspace.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + status (string, optional) - Filter: `active` `invited` `disabled`

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `account:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "usr_91",
                    "email": "ops@acme.example",
                    "name": "Ops Lead",
                    "role": "admin",
                    "status": "active",
                    "joined_at": "2026-01-12T10:00:00Z"
                }
            ]
        }
        ```

### Invite user [POST /account/v2.0/users]

Invites a user into the current workspace (creates membership; user may already exist on other workspaces).

+ Attributes
    + email (string, required) - Invite email
    + role (string, required) - Workspace role: `owner` `admin` `member` `billing` `developer`
    + name (string, optional) - Display name hint

+ Request Invite member (application/json)

    + Tiers: `user` `app`
    + Scopes: `account:write`

    + Body

        ```
        {
            "email": "dev@acme.example",
            "role": "developer",
            "name": "Integrator"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "usr_104",
                "email": "dev@acme.example",
                "role": "developer",
                "status": "invited"
            }
        }
        ```

### Get user [GET /account/v2.0/users/{id}]

Returns a workspace membership for one user.

+ Parameters
    + id (string, required) - User id in this workspace

+ Request By id (application/json)

    + Tiers: `user` `app`
    + Scopes: `account:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "usr_91",
                "email": "ops@acme.example",
                "name": "Ops Lead",
                "role": "admin",
                "status": "active",
                "joined_at": "2026-01-12T10:00:00Z"
            }
        }
        ```

### Update user [PATCH /account/v2.0/users/{id}]

Updates a member's role or status in the current workspace (does not remove them from other workspaces).

+ Parameters
    + id (string, required) - User id

+ Attributes
    + role (string, optional) - Workspace role
    + status (string, optional) - `active` `disabled`

+ Request Change role (application/json)

    + Tiers: `user` `app`
    + Scopes: `account:write`

    + Body

        ```
        {
            "role": "admin"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "usr_91",
                "role": "admin",
                "status": "active"
            }
        }
        ```

### Remove user [DELETE /account/v2.0/users/{id}]

Removes the user from the **current workspace** only. Their Tradeics user account and other workspace memberships remain.

+ Parameters
    + id (string, required) - User id

+ Request Remove membership (application/json)

    + Tiers: `user` `app`
    + Scopes: `account:write`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "deleted",
            "data": {
                "id": "usr_91",
                "workspace_id": "ws_acme"
            }
        }
        ```

## API keys [/account/v2.0/api-keys]

API keys belong to the **current workspace**. Secrets are never returned on list/get — only once on create.

### List API keys [GET /account/v2.0/api-keys{?page}{&page_size}]

Lists API keys for your workspace.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page

+ Request List page 1 (application/json)

    + Tiers: `user` `app`
    + Scopes: `account:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "key_12",
                    "workspace_id": "ws_acme",
                    "name": "ERP middleware",
                    "prefix": "trd_live_****",
                    "status": "active",
                    "created_at": "2026-06-01T08:00:00Z"
                }
            ]
        }
        ```

+ Response 401 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "unauthorized",
            "data": {}
        }
        ```

### Create API key [POST /account/v2.0/api-keys]

Creates a workspace API key. The secret is returned **once** in the create response.

+ Attributes
    + name (string, required) - Label for operators
    + scopes (array, required) - Scope strings

+ Request Create key (application/json)

    + Tiers: `user` `app`
    + Scopes: `account:write`

    + Body

        ```
        {
            "name": "ERP sync",
            "scopes": ["master:read", "master:write", "s2p:read"]
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "key_8a21",
                "workspace_id": "ws_acme",
                "name": "ERP sync",
                "secret": "trc_live_xxxxxxxx",
                "scopes": ["master:read", "master:write", "s2p:read"]
            }
        }
        ```

### Revoke API key [DELETE /account/v2.0/api-keys/{id}]

Revokes a workspace API key immediately.

+ Parameters
    + id (string, required) - API key id

+ Request Revoke key (application/json)

    + Tiers: `user` `app`
    + Scopes: `account:write`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "deleted",
            "data": {
                "id": "key_8a21"
            }
        }
        ```

## Subscription [/account/v2.0/subscription]

Billing / plan metadata for the current workspace.

### Get subscription [GET /account/v2.0/subscription]

Returns the workspace subscription (plan, status, seats when applicable).

+ Request Current plan (application/json)

    + Tiers: `user` `app`
    + Scopes: `account:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "workspace_id": "ws_acme",
                "plan": "growth",
                "status": "active",
                "seats": 25,
                "seats_used": 12,
                "renews_at": "2026-08-01T00:00:00Z"
            }
        }
        ```


# Group Apps & Plugins

Control-plane APIs for **building on Tradeics** — developer apps, App Store listings, installations, and monetization plans. Runtimes call product APIs with **install tokens**; publishers manage apps with **developer** credentials. See [Apps & Plugins guides](/guides/apps-plugins/).

## Developer apps [/apps/v2.0/developer-apps]

Register apps and plugins you will distribute privately or on the App Store.

### List developer apps [GET /apps/v2.0/developer-apps{?page}{&page_size}]

Lists apps owned by your publisher workspace.

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page

+ Request List apps (application/json)

    + Tiers: `app`
    + Scopes: `apps:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "app_rfx_alerts",
                    "slug": "rfx-aging-alerts",
                    "name": "RFX aging alerts",
                    "status": "draft"
                }
            ]
        }
        ```

### Create developer app [POST /apps/v2.0/developer-apps]

Creates a developer app shell (manifest uploaded separately).

+ Attributes
    + name (string, required) - Display name
    + slug (string, required) - Unique slug
    + visibility_default (string, optional) - `private`, `public`, `unlisted`

+ Request Create app (application/json)

    + Tiers: `app`
    + Scopes: `apps:write`

    + Body

        ```
        {
            "name": "RFX aging alerts",
            "slug": "rfx-aging-alerts",
            "visibility_default": "private"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "app_rfx_alerts",
                "slug": "rfx-aging-alerts",
                "status": "draft"
            }
        }
        ```

### Get developer app [GET /apps/v2.0/developer-apps/{id}]

Returns one developer app.

+ Parameters
    + id (string, required) - App id

+ Request By id (application/json)

    + Tiers: `app`
    + Scopes: `apps:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "app_rfx_alerts",
                "slug": "rfx-aging-alerts",
                "name": "RFX aging alerts",
                "status": "draft",
                "latest_version": "0.1.0"
            }
        }
        ```

### Update developer app [PATCH /apps/v2.0/developer-apps/{id}]

Updates app metadata (not the signed manifest — use version upload).

+ Parameters
    + id (string, required) - App id

+ Attributes
    + name (string, optional) - Display name
    + status (string, optional) - `draft`, `active`, `archived`

+ Request Rename (application/json)

    + Tiers: `app`
    + Scopes: `apps:write`

    + Body

        ```
        {
            "name": "RFX aging alerts Pro"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "app_rfx_alerts",
                "name": "RFX aging alerts Pro"
            }
        }
        ```

## Listings [/apps/v2.0/listings]

App Store listing metadata — visibility, copy, and linked app version.

### List listings [GET /apps/v2.0/listings{?page}{&page_size}{&visibility}]

Lists listings for the publisher (or public catalog with catalog scopes).

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + visibility (string, optional) - `public`, `private`, `unlisted`

+ Request List public (application/json)

    + Tiers: `app`
    + Scopes: `apps:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "lst_rfx_01",
                    "app_id": "app_rfx_alerts",
                    "visibility": "private",
                    "pricing": "free",
                    "status": "draft"
                }
            ]
        }
        ```

### Create listing [POST /apps/v2.0/listings]

Creates a Store listing bound to an app.

+ Attributes
    + app_id (string, required) - Developer app id
    + visibility (string, required) - `public`, `private`, `unlisted`
    + pricing (string, required) - `free`, `one_time`, `subscription`, `metered`
    + summary (string, required) - Short Store blurb

+ Request Create private free (application/json)

    + Tiers: `app`
    + Scopes: `apps:write`

    + Body

        ```
        {
            "app_id": "app_rfx_alerts",
            "visibility": "private",
            "pricing": "free",
            "summary": "Alert when RFXs age past your SLA."
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "lst_rfx_01",
                "visibility": "private",
                "pricing": "free",
                "status": "draft"
            }
        }
        ```

### Update listing [PATCH /apps/v2.0/listings/{id}]

Updates listing visibility, pricing model, or copy.

+ Parameters
    + id (string, required) - Listing id

+ Attributes
    + visibility (string, optional) - `public`, `private`, `unlisted`
    + pricing (string, optional) - `free`, `one_time`, `subscription`, `metered`
    + summary (string, optional) - Short Store blurb
    + status (string, optional) - `draft`, `in_review`, `published`, `rejected`

+ Request Submit review (application/json)

    + Tiers: `app`
    + Scopes: `apps:write`

    + Body

        ```
        {
            "status": "in_review",
            "visibility": "public",
            "pricing": "subscription"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "updated",
            "data": {
                "id": "lst_rfx_01",
                "status": "in_review",
                "visibility": "public"
            }
        }
        ```

## Installations [/apps/v2.0/installations]

Org installs of apps — admins install; publishers can list installs of their apps.

### List installations [GET /apps/v2.0/installations{?page}{&page_size}{&app_id}]

Lists installations visible to your key (org admin or publisher).

+ Parameters
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page
    + app_id (string, optional) - Filter by developer app

+ Request List installs (application/json)

    + Tiers: `user` `app`
    + Scopes: `apps:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "ins_901",
                    "app_id": "app_rfx_alerts",
                    "workspace_id": "ws_acme",
                    "status": "active",
                    "plan": "free"
                }
            ]
        }
        ```

### Create installation [POST /apps/v2.0/installations]

Installs an app into a workspace (consent recorded server-side).

+ Attributes
    + app_id (string, required) - App to install
    + workspace_id (string, required) - Target workspace
    + plan_id (string, optional) - Paid plan when required

+ Request Install private (application/json)

    + Tiers: `user` `app`
    + Scopes: `apps:write`

    + Body

        ```
        {
            "app_id": "app_rfx_alerts",
            "workspace_id": "ws_acme",
            "plan_id": "plan_free"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "ins_901",
                "status": "active",
                "scopes": ["s2p:read"]
            }
        }
        ```

### Delete installation [DELETE /apps/v2.0/installations/{id}]

Uninstalls an app and revokes its install token.

+ Parameters
    + id (string, required) - Installation id

+ Request Uninstall (application/json)

    + Tiers: `user` `app`
    + Scopes: `apps:write`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "deleted",
            "data": {
                "id": "ins_901"
            }
        }
        ```

## Plans [/apps/v2.0/plans]

Monetization plans attached to listings (free, one-time, subscription, metered).

### List plans [GET /apps/v2.0/plans{?listing_id}{&page}{&page_size}]

Lists plans for a listing.

+ Parameters
    + listing_id (string, optional) - Restrict to one listing
    + page (number, required) - Page index starting at `1`
    + page_size (number, optional) - Items per page

+ Request List plans (application/json)

    + Tiers: `app`
    + Scopes: `apps:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "listed",
            "data": [
                {
                    "id": "plan_free",
                    "listing_id": "lst_rfx_01",
                    "type": "free",
                    "price": 0,
                    "currency": "USD"
                },
                {
                    "id": "plan_pro_mo",
                    "listing_id": "lst_rfx_01",
                    "type": "subscription",
                    "price": 99.00,
                    "currency": "USD",
                    "interval": "month"
                }
            ]
        }
        ```

### Create plan [POST /apps/v2.0/plans]

Creates a monetization plan for a listing.

+ Attributes
    + listing_id (string, required) - Parent listing
    + type (string, required) - `free`, `one_time`, `subscription`, `metered`
    + price (number, required) - Major-unit price (`0` for free)
    + currency (string, required) - ISO currency
    + interval (string, optional) - `month`, `year` when subscription

+ Request Create subscription (application/json)

    + Tiers: `app`
    + Scopes: `apps:write`

    + Body

        ```
        {
            "listing_id": "lst_rfx_01",
            "type": "subscription",
            "price": 99.00,
            "currency": "USD",
            "interval": "month"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "plan_pro_mo",
                "type": "subscription",
                "price": 99.00
            }
        }
        ```

## AI Builder jobs [/apps/v2.0/ai-builder/jobs]

Start and poll AI-assisted app/plugin scaffolds.

### Create AI Builder job [POST /apps/v2.0/ai-builder/jobs]

Creates a draft app scaffold from a natural-language brief.

+ Attributes
    + brief (string, required) - What the app should do
    + visibility (string, optional) - Suggested `private` / `public`
    + pricing (string, optional) - Suggested pricing model

+ Request Scaffold private app (application/json)

    + Tiers: `app`
    + Scopes: `apps:write`

    + Body

        ```
        {
            "brief": "Private plugin that badges RFXs older than 7 days. Read-only S2P.",
            "visibility": "private",
            "pricing": "free"
        }
        ```

+ Response 201 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "created",
            "data": {
                "id": "job_ai_441",
                "status": "queued"
            }
        }
        ```

### Get AI Builder job [GET /apps/v2.0/ai-builder/jobs/{id}]

Returns scaffold job status and resulting draft app id when complete.

+ Parameters
    + id (string, required) - Job id

+ Request By id (application/json)

    + Tiers: `app`
    + Scopes: `apps:read`

    + Body

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "retrieved",
            "data": {
                "id": "job_ai_441",
                "status": "succeeded",
                "draft_app_id": "app_rfx_alerts",
                "draft_listing_id": "lst_rfx_01"
            }
        }
        ```


# Group AI

Product AI assistants over platform objects. Direct chat / embeddings live on the dedicated LLM host.

+ Navigation
  | LLM API Reference: Chat, embeddings, models. -> /references/llm-api/v1/
  | Call the LLM: Multi-language SDKs. -> /guides/ai/llm-api/
  | AI overview: Where AI fits. -> /guides/ai/overview/

## Helpers [/ai/v2.0/assist]

Document and object helpers that call Tradeics AI behind your org key.

### Summarize RFX [POST /summarize-rfx]

Returns a short summary of an RFX for buyers or sellers. Assistive only — do not auto-award from the result.

+ Attributes
    + rfx_id (string, required) - RFX id to summarize
    + locale (string, optional) - BCP 47 locale, default `en`

+ Request Summarize (application/json)

    + Tiers: `user` `app`
    + Scopes: `ai:write`

    + Body

        ```
        {
            "rfx_id": "rfx_8812",
            "locale": "en"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "completed",
            "data": {
                "rfx_id": "rfx_8812",
                "summary": "Open RFX for fasteners with 12 lines, closing 1 Aug 2026.",
                "bullets": [
                    "12 line items",
                    "Currency USD",
                    "Status open"
                ]
            }
        }
        ```

+ Response 404 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "not_found",
            "data": {}
        }
        ```

### Classify catalog line [POST /classify-item]

Suggests a category / sub-category for a free-text catalog line.

+ Attributes
    + text (string, required) - Item title or description
    + locale (string, optional) - BCP 47 locale, default `en`

+ Request Classify (application/json)

    + Tiers: `user` `app`
    + Scopes: `ai:write`

    + Body

        ```
        {
            "text": "M12 hex bolt 50mm zinc plated",
            "locale": "en"
        }
        ```

+ Response 200 (application/json)

    + Body

        ```
        {
            "error": false,
            "reason": "completed",
            "data": {
                "category_id": "cat_hw",
                "sub_category_id": "subcat_fast_02",
                "confidence": 0.91
            }
        }
        ```

+ Response 422 (application/json)

    + Body

        ```
        {
            "error": true,
            "reason": "validation_failed",
            "data": {
                "fields": {
                    "text": "required"
                }
            }
        }
        ```

---

# RTM API Reference (V1)

Source: https://developers.tradeics.com/references/rtm-api/v1/

# RTM API

Real-time channels for Tradeics event streams will be documented here when generally available.

**Planned endpoint shape:** `wss://rtm.tradeics.example/`

Until then, build integrations with [REST API V2](/references/rest-api/v2/) and schedule or poll syncs for objects in the product guides.

+ Navigation
  | REST API V2: Current HTTP surface. -> /references/rest-api/v2/
  | Getting Started: Auth and first request. -> /guides/getting-started/