Agentic Gift Shop

Agent API documentation

This API lets approved agents browse products, explain variants and sizing, create personalized previews, build carts, create WooCommerce orders, and send hosted payment links to customers.

No tokens are published here.

Use a token issued separately by the store owner. Do not put live tokens in public prompts, screenshots, or shared docs.

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

Authentication

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

Authorization: Bearer AGS_AGENT_API_TOKEN

catalog:read media:write cart:read cart:write orders:read orders:write payments:write fulfillment:write

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.

For agents

Ask the store owner for a token and use it only in secure tool configuration or secret storage. Never paste live tokens into shared prompts or public docs.

Recommended Agent Flow

Fetch products with GET /products.
Fetch detail with GET /products/{product_id}.
Use personalization.capabilities, sizing, variants, colors, sizes, and print areas to guide the customer.
Generate previews with POST /products/{product_id}/personalization/preview.
Send preview_url to the customer and iterate until approved.
Create a cart with POST /carts.
Add approved personalized items with POST /carts/{cart_id}/items.
Create the order with POST /carts/{cart_id}/order.
Send payment.url to the customer. Do not collect raw card data.
Track order and fulfillment with GET /orders/{order_id}.

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.

Options

personalization.options exposes customer-selectable values such as color and size.

Variants

personalization.schema.variants contains valid supplier combinations. Use it before offering options.

Print Areas

personalization.print_areas and editor.design_areas describe where a gift can be personalized.

Size Guides

sizing.size_guide includes supplier measurements when available. For shirts, ask chest, height, usual size, and fit preference.

Messaging Images

images[].messaging_src is public and safe for Facebook, Instagram, Messenger, and WhatsApp agents to send.

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

Personalization Preview

Messaging agents should preview designs before adding to cart. The preview endpoint accepts selected options and editor layers, then returns an image URL to show the customer.

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.

Carts

Create a cart after the customer has approved a preview. Use the same approved options, print_area, and editor_state.

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}

Orders And Payments

The API does not collect raw card details. It creates a WooCommerce order and returns a hosted payment URL. The customer pays through the existing store checkout and Stripe gateway.

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

Endpoint Reference

Method	Path	Purpose
GET	`/health`	Public health check.
GET	`/auth/whoami`	Check token identity and scopes.
GET	`/products`	List products.
GET	`/products/{product_id}`	Product detail, personalization schema, variants, sizing, supplier data.
POST	`/products/{product_id}/personalization/preview`	Generate a customer-shareable preview image.
POST	`/media`	Upload a customer image for editor layers.
POST	`/carts`	Create cart.
GET/PATCH	`/carts/{cart_id}`	Read or update cart customer/metadata.
POST	`/carts/{cart_id}/items`	Add personalized item.
PATCH/DELETE	`/carts/{cart_id}/items/{item_id}`	Update or remove item.
POST	`/carts/{cart_id}/order`	Create WooCommerce order and payment URL.
GET	`/orders/{order_id}`	Read order, payment, fulfillment, and shipment status.
POST	`/orders/{order_id}/payment-link`	Refresh hosted payment URL.
POST	`/orders/{order_id}/fulfillment/refresh`	Refresh Printify status.

Machine-readable spec: openapi.json.