Sitewai
Loading…

Sitewai Agent API — Docs

This page describes how AI agents can discover your shop and create draft/pending orders safely without storing credentials. All calls are draft-only (no direct charges).

1) Discovery via Meta Tags

Agents can read <meta> tags in your storefront’s <head> to learn what they can do and how to call the API.

<!-- Agent discovery (advanced) -->
<meta name="ai:version" content="1">
<meta name="ai:shop" content='{"name":"Demo Store","platform":"shopify"}'>
<meta name="ai:sitemap" content="https://www.sitewai.com/api/sitewai/{domain}">
<meta name="ai:checkout-requirements" content="https://www.sitewai.com/api/sitewai/{domain}/requirements">
<meta name="ai:capabilities" content='{"features":["list-products","select-variant","create-draft-order","send-invoice"]}'>
<meta name="ai:actions" content='[
  {"id":"products.sitemap","method":"GET","url":"/api/sitewai/{domain}"},
  {"id":"checkout.create","method":"POST","url":"/api/checkout/create",
   "schema":"https://www.sitewai.com/schemas/checkout-create@v1.json",
   "x-require-headers":[
     {"name":"Idempotency-Key","type":"uuid","description":"Unique per request. Reuse with identical body to safely retry."},
     {"name":"Content-Type","value":"application/json"}
   ]}
]'>
<!-- Auth: public mode (no bearer). Draft-only scope. -->
<meta name="ai:auth" content='{"modes":["public"],"public_scope":"draft-only"}'>
<meta name="ai:rate-limit" content='{"rpm":10,"burst":20,"headers":true}'>
<meta name="ai:docs" content="https://www.sitewai.com/docs">
<!-- Store owner legal; merchant’s privacy/terms should live on the store domain -->
<meta name="ai:platform.privacy" content="https://yourdomainexample.com/privacy">
<meta name="ai:platform.terms" content="https://yourdomainexample.com/terms">

For Shopify or WooCommerce, agents can also query a machine-readable requirements document:
https://www.sitewai.com/api/sitewai/{domain}/requirements

2) Endpoints

  • GET /api/sitewai/{domain} — Product sitemap (per-domain).
  • GET /api/sitewai/{domain}/requirements — Field hints, headers, rate limits, retry policy, and examples.
  • POST /api/checkout/create — Create a draft (Shopify) or pending order (Woo) and return an invoice URL.

Notes per platform

  • Shopify: variantId is required. Draft orders do not reserve stock.
  • WooCommerce: creates a pending order and returns a payment URL.

3) Request Schema

JSON Schema: https://www.sitewai.com/schemas/checkout-create@v1.json

{
  "domain": "your-shop.example",
  "productId": "platform-product-id",
  "variantId": "platform-variant-id",  // required on Shopify
  "qty": 1,
  "customer": {
    "email": "buyer@example.com",
    "name": "Name Lastname",
    "phone": "+1...",
    "address1": "Street 1234",
    "address2": "Apt 5",
    "city": "City",
    "province": "State",
    "zip": "90210",
    "country": "US"
  },
  "sendEmail": true
}

4) Required Headers

  • Idempotency-Key (UUID): required on every POST /api/checkout/create call. Use a new UUID per unique request. Reuse with the same body to safely retry.
  • Content-Type: application/json

5) Rate Limits & Retries

  • Default: 10 rpm, burst 20. Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After.
  • Suggested retry policy (transient errors only): exponential backoff, base 500ms, max 3 attempts. Retry on 408/502/503/504/522/524. Do not retry on 400/401/403/404/409/422.

6) Error Model

{
  "ok": false,
  "error": "validation_error|request_error",
  "code": "string",
  "message": "string",
  "retryable": false,
  "traceId": "req_...",
  "timestamp": "ISO-8601"
}

Common codes: missing_idempotency_key, variant_required_for_shopify, product_not_found_for_domain, shopify_draft_error, woo_order_error, idempotency_key_mismatch, rate_limited, abuse_guard_email.

7) Examples

cURL

# Create a draft/pending order
curl -X POST "https://www.sitewai.com/api/checkout/create" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "domain":"your-shop.example",
    "productId":"PRODUCT_ID",
    "variantId":"VARIANT_ID",
    "qty":1,
    "customer":{"email":"buyer@example.com"},
    "sendEmail":true
  }'

HTTP Response (success)

HTTP/1.1 200 OK
Idempotent-Replay: false

{
  "ok": true,
  "status": "invoice_sent",
  "id": "ci_abc123",
  "draftId": "do_987",
  "url": "https://.../invoice/...",
  "emailed": true,
  "stockConfirmed": false,
  "note": "Shopify/Woo pending does not reserve stock",
  "traceId": "req_...",
  "timestamp": "..."
}

8) Privacy & Terms

Sitewai provides the API and integration docs. The merchant is the controller for purchase data. Link your platform legal here:

  • Docs (this page): https://www.sitewai.com/docs
  • Platform privacy: https://www.sitewai.com/privacy
  • Platform terms: https://www.sitewai.com/terms
  • Merchant privacy/terms should be published on the shop domain.

9) Changelog

  • v1 — Public “draft-only” flow, idempotency via header, Shopify/Woo support, machine-readable requirements, JSON Schema.

10) Platform setup — Shopify (Admin API access token)

You’ll create a custom app in Shopify Admin and grant minimal scopes. The token is used server-side by Sitewai to create draft orders and (optionally) to sync products.

  1. Log in as the store owner to Shopify Admin.
  2. Go to Settings → Apps and sales channels → Develop apps. If disabled, enable custom app development.
  3. Click Create an app (e.g., “Sitewai Integration”). Open the app → Configuration → Admin API integration → Configure.
  4. Grant minimum scopes:
    • Draft orders: read_draft_orders + write_draft_orders (required)
    • Products: read_products (recommended if you let Sitewai sync products)
    • Optional: read_customers if you plan to enrich customer data later (not required to create drafts).
  5. Save, then click Install app. Confirm.
  6. In API credentials, click “Reveal Admin API access token”. Copy it once — Shopify won’t show it again.
  7. In Sitewai → Integration:
    • Shop domain: your-shop.myshopify.com
    • Admin API access token: paste the value
    • API version: align with your target (Sitewai defaults to 2025-04 unless overridden)

Security tips

  • Never paste the Admin token in theme code or client-side JS. It lives only on the server.
  • Grant only the scopes you need. Rotate the token if compromised.
  • Keep your store on HTTPS; avoid exposing admin endpoints publicly.

Troubleshooting

  • 401/403: scope missing (e.g., write_draft_orders) or token invalid.
  • 422/404: invalid variantId or product not found for the configured domain.
  • Rate limited: respect X-RateLimit-* and back off per retry policy.

11) Platform setup — WooCommerce (REST API keys)

WooCommerce uses REST API keys (Consumer Key & Secret). Sitewai calls the API server-to-server to create a pending order and return a payment URL.

  1. Log in to WordPress Admin with an account that has Administrator role.
  2. Go to WooCommerce → Settings → Advanced → REST API and click Add key.
  3. Set a description (e.g., “Sitewai”), pick the user (store owner), and set Permissions = Read/Write. Click Generate API key.
  4. Copy the Consumer Key and Consumer Secret. You won’t be able to see the secret again.
  5. In Sitewai → Integration, enter:
    • Base URL: https://yourstore.com (no trailing slash)
    • Consumer Key and Consumer Secret

Required settings

  • Pretty permalinks: WordPress → Settings → Permalinks → avoid “Plain”. Use “Post name” or similar so /checkout/order-pay/{id} works.
  • HTTPS: recommended for production; some hosts block REST over HTTP.

Troubleshooting

  • 401/403: keys invalid or permissions not Read/Write; user lacks Admin role.
  • 404 on order-pay: check permalinks and base URL correctness.
  • Rate limited / host firewall: allowlist your server IP or use HTTPS.