Agent API documentation

Authentication

Every protected request uses bearer-token auth. Tokens are scoped and can be revoked.

Authorization: Bearer AGS_AGENT_API_TOKEN

Access Management

Agent API tokens are issued separately by the store owner. There is no public self-service token dashboard yet. Tokens are generated server-side, saved as hashes, and shown only once when created.

Recommended Agent Flow

1. Fetch products with GET /products.
2. Fetch detail with GET /products/{product_id}.
3. Use personalization.capabilities, sizing, variants, colors, sizes, and print areas to guide the customer.
4. Create a durable draft with POST /design-sessions.
5. Patch choices and editor layers with PATCH /design-sessions/{design_session_id}.
6. Generate previews with POST /design-sessions/{design_session_id}/preview.
7. Send preview_url to the customer and iterate until approved.
8. Approve the exact design with POST /design-sessions/{design_session_id}/approve.
9. Create a cart with POST /carts and include channel_identity for messaging channels.
10. Add the approved design with POST /carts/{cart_id}/items using design_session_id.
11. Estimate shipping with POST /carts/{cart_id}/shipping-options when the customer shares a destination.
12. Create a hosted checkout link with POST /carts/{cart_id}/checkout-link.
13. Send checkout.url to the customer. Do not collect raw card data.
14. Track order and fulfillment with GET /orders/{order_id}.
15. Cancel only with customer confirmation using POST /orders/{order_id}/cancel.

Products, Variants, And Sizing

Product detail responses are self-describing. Agents should use the returned schema instead of hardcoding colors, sizes, print areas, fonts, or valid variants.

curl -H "Authorization: Bearer $AGS_AGENT_API_TOKEN" \
  "https://store.agenticgiftshop.com/wp-json/agentic-gift-shop/v1/agent/products/24"

Personalization Preview

The product preview endpoint is still available for one-off previews. For WhatsApp and other long-running conversations, use design sessions instead so customer choices survive multiple messages and webhook retries.

Personalized previews are rendered from the same official product editor templates used by the product page. Agents may provide a PNG client_preview_data_url exported from that editor, or let the API compose the preview server-side. If the official template cannot be rendered, the API returns an error instead of substituting another image.

curl -X POST \
  -H "Authorization: Bearer $AGS_AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "color": "Heather Kelly",
      "size": "3XL"
    },
    "print_area": "Front side",
    "editor_state": {
      "activePrintArea": "Front side",
      "layers": [
        {
          "type": "text",
          "text": "ELF",
          "x": 0.28,
          "y": 0.38,
          "width": 0.44,
          "height": 0.18,
          "rotation": 0,
          "font": "Inter",
          "fontSize": 9,
          "color": "#ffffff",
          "align": "center"
        }
      ]
    }
  }' \
  "https://store.agenticgiftshop.com/wp-json/agentic-gift-shop/v1/agent/products/24/personalization/preview"

For image layers, upload the image first with POST /media, then use the returned attachment_id in the layer.

Design Concepts

Use this high-level endpoint when a customer asks for generated visual options. The store generates flat artwork server-side, stores it as media, places it into durable draft design sessions, and returns artwork images for customer selection.

curl -X POST \
  -H "Authorization: Bearer $AGS_AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 24,
    "prompt": "three floral print-ready shirt artwork options with pink flowers, warm boutique typography, spring gift feel",
    "count": 3,
    "options": {
      "color": "Pink",
      "size": "M"
    },
    "print_area": "Front side",
    "idempotency_key": "whatsapp-message-id-or-agent-turn-id"
  }' \
  "https://store.agenticgiftshop.com/wp-json/agentic-gift-shop/v1/agent/design-concepts"

Send each design_concepts[].concept_image_url or messaging.image_url to the customer as an image option or carousel. If used_default_options is true, confirm or change the returned defaulted_options before approval/cart. When the customer chooses one, continue with that design_session_id, call /design-sessions/{design_session_id}/preview for the official product proof, approve, add to cart, and create a checkout link.

Editor Layer Contract

Agents personalize gifts by sending the same editor_state shape used by the browser editor. Coordinates are normalized inside the selected printable area, not the whole product image.

{
  "activePrintArea": "Front side",
  "layers": [
    {
      "type": "image",
      "attachment_id": 123,
      "imageName": "floral-stamp.png",
      "x": 0,
      "y": 0,
      "width": 1,
      "height": 1,
      "rotation": 0,
      "removeBackground": false
    },
    {
      "type": "text",
      "text": "Blooming With Love",
      "x": 0.18,
      "y": 0.12,
      "width": 0.64,
      "height": 0.16,
      "rotation": 0,
      "font": "Inter",
      "fontSize": 8,
      "color": "#2f6846",
      "align": "center"
    }
  ]
}

Design Sessions

A design session is a durable personalized line-item draft. It stores the product, selected variant options, print area, editor layers, generated preview, and customer approval state. Agents should add approved design sessions to cart instead of rebuilding personalization from chat memory.

POST /design-sessions
GET /design-sessions/{design_session_id}
PATCH /design-sessions/{design_session_id}
POST /design-sessions/{design_session_id}/preview
POST /design-sessions/{design_session_id}/approve

curl -X POST \
  -H "Authorization: Bearer $AGS_AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "design_session_id": "design_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "quantity": 1
  }' \
  "https://store.agenticgiftshop.com/wp-json/agentic-gift-shop/v1/agent/carts/cart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/items"

Carts

Create a cart after the customer has approved a preview. The preferred path is to add an approved design_session_id; the API will preserve the exact options, print area, editor layers, preview, and approval hash.

channel_identity is writable on cart creation. WhatsApp, Messenger, Instagram DM, SMS, and similar agents should send it on POST /carts so the paid order can later be found by the same channel identity.

curl -X POST \
  -H "Authorization: Bearer $AGS_AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_identity": {
      "channel": "messenger",
      "channel_instance_id": "FACEBOOK_PAGE_ID",
      "channel_user_id": "PAGE_SCOPED_ID_FROM_MESSENGER",
      "display_name": "Customer Name"
    }
  }' \
  "https://store.agenticgiftshop.com/wp-json/agentic-gift-shop/v1/agent/carts"

{
  "channel_identity": {
    "channel": "instagram",
    "channel_instance_id": "INSTAGRAM_PROFESSIONAL_ACCOUNT_ID",
    "channel_user_id": "INSTAGRAM_SCOPED_CUSTOMER_ID",
    "display_name": "Customer Name"
  }
}

POST /carts
GET /carts/{cart_id}
PATCH /carts/{cart_id}
POST /carts/{cart_id}/items
PATCH /carts/{cart_id}/items/{item_id}
DELETE /carts/{cart_id}/items/{item_id}
POST /carts/{cart_id}/items/{item_id}/revision
POST /carts/{cart_id}/items/{item_id}/revision/commit

Shipping Options

Estimate store-branded shipping options after the cart has approved personalized items. The API intentionally abstracts fulfillment providers; agents should quote the returned labels, costs, and transit guidance without naming suppliers.

Shipping methods are product-specific. A mug may return Standard, Priority, and Express, while a poster, tee, cap, or tote may only return Standard for the same destination. Agents must quote only the options returned for the exact cart.

curl -X POST \
  -H "Authorization: Bearer $AGS_AGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": {
      "country": "US",
      "region": "CA",
      "city": "San Francisco",
      "postal_code": "94107"
    }
  }' \
  "https://store.agenticgiftshop.com/wp-json/agentic-gift-shop/v1/agent/carts/cart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/shipping-options"

Conversation Debug

The API exposes read-only WhatsApp conversation history for support and agent debugging. These endpoints help a supervisor inspect customer messages, outbound responses, active cart state, checkout links, recent actions, and where a handoff stalled.

GET /conversations
GET /conversations/{conversation_id}
GET /conversations/{conversation_id}/messages?limit=200
GET /conversations/{conversation_id}/state

Orders And Payments

The preferred messaging handoff is a hosted checkout link. The agent builds and personalizes the cart, then sends a signed browser URL so the customer fills contact, shipping, billing, and payment details in WooCommerce checkout.

POST /carts/{cart_id}/order
POST /carts/{cart_id}/checkout-link
POST /orders/{order_id}/payment-link
GET /orders/{order_id}
POST /orders/{order_id}/fulfillment/refresh
POST /orders/{order_id}/cancel

ACP Test Adapter

ACP runs beside the production WooCommerce checkout. For the MVP, agents still use the Agent API to personalize products and build a cart, then create an ACP checkout session from that cart. Agents with ACP UI can render this response as a native or embedded checkout review, then use continue_url for hosted WooCommerce payment.

ACP Base URL:
https://store.agenticgiftshop.com/wp-json/agentic-gift-shop/v1/acp

curl -X POST \
  -H "Authorization: Bearer $AGS_AGENT_API_TOKEN" \
  -H "Idempotency-Key: $UUID" \
  -H "API-Version: 2026-04-17" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      { "id": "cart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }
    ],
    "currency": "usd",
    "capabilities": {},
    "metadata": {
      "agent_cart_id": "cart_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }' \
  "https://store.agenticgiftshop.com/wp-json/agentic-gift-shop/v1/acp/checkout_sessions"

Endpoint Reference

Machine-readable spec: openapi.json.