# Agent Instructions — Pin Market

This file provides instructions for AI agents, shopping assistants and automated clients interacting with Pin Market.

Store URL: https://pinmarket.pl

Pin Market is an online store selling welding table accessories, including welding pins, stops, clamps and related tooling for welding table systems.

## Agent Usage Rules

AI agents may use this website to:

- discover products,
- search the catalog,
- compare product variants,
- read product descriptions, prices and availability,
- prepare cart or checkout actions where supported,
- answer buyer questions using public store data.

Agents must not complete a payment or place an order without explicit buyer approval.

## Read-Only Product Access

Public product and collection data can be accessed without authentication.

### Product endpoints

- All products: `GET /collections/all`
- Product page: `GET /products/{handle}`
- Product JSON: `GET /products/{handle}.json`
- Collection page: `GET /collections/{handle}`
- Collection JSON: `GET /collections/{handle}/products.json`
- Search products: `GET /search?q={query}&type=product`

### Store metadata

- Sitemap: `GET /sitemap.xml`
- Agent instructions: `GET /agents.md`

## Universal Commerce Protocol / MCP

If available, the store exposes agent-facing commerce endpoints.

### Discovery

`GET https://pinmarket.pl/.well-known/ucp`

Agents should call this endpoint first to confirm available capabilities, supported protocol versions, payment handlers and service endpoints.

### MCP endpoint

`POST https://pinmarket.pl/api/ucp/mcp`

Content type:

`application/json`

Agents should use the MCP `tools/list` method to discover available tools and schemas before making tool calls.

## Typical Agent Flow

1. Discover store capabilities with `GET /.well-known/ucp`.
2. Search the catalog for products matching the buyer’s intent.
3. Read product details, variants, price and availability.
4. Create or update a cart only when the buyer requests it.
5. Start checkout only after the buyer confirms the intended order.
6. Complete checkout only after explicit buyer approval.

## Buyer Context

When supported, agents should provide buyer context, including:

- `context.address_country`
- `context.currency`
- preferred language
- shipping destination

This helps return accurate availability, prices, taxes and shipping options.

## Checkout and Payment

Checkout requires human approval.

Agents must not:

- submit payment without explicit buyer consent,
- store or process payment card data directly,
- bypass buyer confirmation,
- place an order without clear confirmation from the buyer.

If payment approval is required, the agent should pause and ask the buyer to confirm.

## Rate Limits

Agents should respect rate limits.  
If the server returns `429 Too Many Requests`, the agent should back off and retry later.

## Store Policies

- Privacy policy: https://pinmarket.pl/policies/privacy-policy
- Terms of service: https://pinmarket.pl/policies/terms-of-service
- Refund policy: https://pinmarket.pl/policies/refund-policy
- Shipping policy: https://pinmarket.pl/policies/shipping-policy
- Contact: https://pinmarket.pl/pages/contact

## Platform

Pin Market is built on Shopify.