Developer Documentation

curl https://storeapi.globalringai.com/api/v1/products

# By category
curl "https://storeapi.globalringai.com/api/v1/products?category=Software"

# By keyword
curl "https://storeapi.globalringai.com/api/v1/products?q=keycap"

# In-stock only
curl "https://storeapi.globalringai.com/api/v1/products?in_stock=true"

Authorization: Bearer ${THESTORE_BUYER_TOKEN}

{
  "error": {
    "code": "not_found",
    "message": "Product not found"
  }
}

# 1. Browse products (no auth)
curl https://storeapi.globalringai.com/api/v1/products

# 2. Create a session
curl -X POST -H "Authorization: Bearer tsk_..." \
  https://storeapi.globalringai.com/api/v1/sessions

# 3. Add to cart (use session_id from step 2 and copy a product id/tspn from step 1)
curl -X POST -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "TSPN-...", "quantity": 1}' \
  https://storeapi.globalringai.com/api/v1/sessions/{session_id}/cart/items

# 4. Checkout
curl -X POST -H "Authorization: Bearer tsk_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "buyer@example.com"}' \
  https://storeapi.globalringai.com/api/v1/sessions/{session_id}/checkout

# Response includes checkout_url — open in browser to pay

// Product
{"id", "tspn", "name", "type", "price", "price_currency", "price_formatted",
 "description", "category", "stock", "stock_status", "in_stock"}

// Cart
{"session_id", "items": [{"product_id", "name", "price", "price_currency",
 "price_formatted", "quantity", "subtotal"}],
 "total", "price_currency", "total_formatted", "item_count"}

// Checkout
{"order_id", "checkout_url", "total", "total_formatted"}

// Order
{"order_id", "email", "total", "price_currency", "total_formatted", "status",
 "items": [{"product_id", "name", "price", "price_currency",
 "price_formatted", "quantity", "subtotal", "subtotal_formatted"}],
 "created_at"}

# 1. Create checkout session
curl -X POST -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [{"product_id": "PRODUCT_ID", "quantity": 2}],
    "customer_email": "agent@example.com"
  }' \
  https://storeapi.globalringai.com/acp/v1/checkout_sessions

# 2. After reviewing the authoritative quote, complete without a token
curl -X POST -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://storeapi.globalringai.com/acp/v1/checkout_sessions/{id}/complete

# Response: status "awaiting_payment", checkout_url for Stripe
# Payment confirmed asynchronously via webhook

                      ┌──────────────────┐
        Digital items  │ ready_for_payment │  Physical items
        ──────────────►│                  │◄────────────────
                       └────────┬─────────┘   (after address
                                │              provided)
                 ┌──────────────┼──────────────┐
                 │              │              │
       signed approval     no token        cancel
                 │              │              │
                 ▼              ▼              ▼
            completed    awaiting_payment   canceled
                              │
                         webhook confirms
                              │
                              ▼
                          completed

{
  "line_items": [                    // required, at least 1
    {"product_id": "...", "quantity": 1}
  ],
  "customer_email": "...",           // optional
  "customer_name": "...",            // optional
  "currency": "usd"                 // optional, default "usd"
}

{
  "line_items": [...],               // optional, replaces items
  "fulfillment_address": {           // optional, for physical goods
    "name": "...", "line1": "...", "line2": "...",
    "city": "...", "state": "...", "zip": "...", "country": "..."
  },
  "selected_fulfillment": "express", // optional: "standard" ($5) or "express" ($15)
  "customer_email": "...",           // optional
  "customer_name": "..."             // optional
}

{
  "id": "uuid",
  "status": "ready_for_payment",
  "line_items": [{"product_id", "name", "description",
                  "quantity", "unit_price", "currency"}],
  "fulfillment_address": null | {...},
  "fulfillment_options": [
    {"id": "standard", "label": "Standard Shipping (5-7 days)", "cost": 500, "currency": "usd"},
    {"id": "express", "label": "Express Shipping (2-3 days)", "cost": 1500, "currency": "usd"}
  ],
  "selected_fulfillment": null | "standard" | "express",
  "customer_email": "...",
  "customer_name": "...",
  "totals": {"subtotal": 999, "tax": 0, "shipping": 0, "total": 999, "currency": "usd"},
  "order_id": null,
  "checkout_url": null,
  "created_at": "2026-...",
  "expires_at": "2026-..."   // 1 hour from creation
}

Signature: hex(HMAC-SHA256(request_body, secret))

# 1. Discover capabilities
curl https://storeapi.globalringai.com/.well-known/ucp

# 2. Browse the canonical catalog and copy the selected variant's id/tspn
curl -H "Authorization: Bearer ***" \
  "https://storeapi.globalringai.com/api/v1/products?in_stock=true"

# 3. Create session using that canonical variant identifier
curl -X POST -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [{"product_id": "TSPN-...", "quantity": 1}],
    "customer_email": "agent@example.com"
  }' \
  https://storeapi.globalringai.com/ucp/v1/checkout-sessions

# 4. Add shipping (physical good)
curl -X PUT -H "Authorization: Bearer tsk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fulfillment_address": {"line1": "123 Main St", "city": "Portland", "state": "OR", "zip_code": "97201", "country": "US"},
    "selected_fulfillment": "standard"
  }' \
  https://storeapi.globalringai.com/ucp/v1/checkout-sessions/{id}

# 5. After reviewing the quote, create secure Stripe Checkout
curl -X POST -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://storeapi.globalringai.com/ucp/v1/checkout-sessions/{id}/complete

GET /.well-known/ucp

{
  "version": "1.0",
  "name": "The Store",
  "description": "A cyberpunk e-commerce store...",
  "services": [{"type": "checkout", "base_url": "/ucp/v1/checkout-sessions"}],
  "capabilities": [
    "checkout.create", "checkout.update",
    "checkout.complete", "checkout.cancel",
    "fulfillment.address", "fulfillment.options"
  ]
}

claude mcp add --scope user --transport http thestore \
  https://storemcp.globalringai.com/ \
  --header 'Authorization: Bearer ${THESTORE_BUYER_TOKEN}'

# 1. Place your Ed25519 public key PEM in the TAP keys directory:
#    $TAP_KEYS_DIR/my-agent.pem

# 2. Enable TAP on the server:
#    TAP_ENABLED=true TAP_KEYS_DIR=/app/tap-keys

# 3. Sign your request with these headers:
Signature-Input: sig1=("@method" "@target-uri" "content-type");\
  created=1709000000;keyid="my-agent";alg="ed25519";\
  nonce="unique-value-123"
Signature: sig1=:base64-ed25519-signature:

# Signature base (one line per component + params):
"@method": POST
"@target-uri": https://storeapi.globalringai.com/api/v1/orders
"content-type": application/json
"@signature-params": ("@method" "@target-uri" "content-type");\
  created=1709000000;keyid="my-agent";alg="ed25519";nonce="abc123"