Plugin API

The Plugin API allows WooCommerce and Shopify stores to generate product descriptions and blog posts directly from your e-commerce platform, without logging into the XC Scribe web application. Content is generated on demand and billed against your organization's XCT balance.

Getting an API Key

API keys are managed in the Settings page under the API Keys section (available to organization admins).

1. Navigate to Settings > API Keys.
2. Click Create API Key and give it a name (e.g., "WooCommerce Plugin").
3. Copy the generated key immediately -- it will not be shown again.

All API keys use the xc_ prefix (e.g., xc_a1b2c3d4e5f6...). Each key is tied to your organization.

Authentication

Every request to the Plugin API must include your API key in the Authorization header as a Bearer token:

Authorization: Bearer xc_your_api_key_here

Requests without credentials receive a 403 Forbidden response. Invalid or inactive API keys receive a 401 Unauthorized response.

Endpoints

All endpoints are under /api/v1/plugin/.

Check Status

Verify that your API key is valid and check your current balance.

Endpoint: GET /api/v1/plugin/status

Example:

curl https://api.xcscribe.com/api/v1/plugin/status \
  -H "Authorization: Bearer xc_your_api_key_here"

Response:

{
  "plan_tier": "free",
  "total_balance": "50.0000",
  "active_integrations": ["woocommerce"]
}

Field	Type	Description
plan_tier	string	Your subscription tier (free, starter, pro, etc.)
total_balance	string	Remaining XCT balance
active_integrations	string[]	Integration types with active plugin projects

---

Generate Product Description

Generate an AI-powered product description for a single product.

Endpoint: POST /api/v1/plugin/generate-description

Request body:

Field	Type	Required	Description
source	string	Yes	Integration type: woocommerce or shopify
product_title	string	Yes	The product name
product_category	string	No	Product category
product_attributes	object	No	Product attributes (size, color, material, etc.)
product_images	string[]	No	List of product image URLs
current_description	string	No	Existing description to improve upon
language	string	No	Target language code (default: en)
tone	string	No	Writing tone (default: professional)
custom_instructions	string	No	Additional instructions for the AI

Example:

curl -X POST https://api.xcscribe.com/api/v1/plugin/generate-description \
  -H "Authorization: Bearer xc_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "woocommerce",
    "product_title": "Organic Cotton T-Shirt",
    "product_category": "Clothing",
    "product_attributes": {
      "material": "100% organic cotton",
      "sizes": "S, M, L, XL"
    },
    "language": "en",
    "tone": "professional"
  }'

Response:

{
  "content": "Crafted from 100% certified organic cotton, this premium t-shirt...",
  "tokens_used": 350,
  "xct_cost": "1.0500",
  "remaining_balance": "48.9500"
}

Field	Type	Description
content	string	The generated product description
tokens_used	int	Total AI tokens consumed
xct_cost	string	XCT deducted for this generation
remaining_balance	string	Your remaining XCT balance

---

Generate Blog Post

Generate a blog post related to your products or store.

Endpoint: POST /api/v1/plugin/generate-blog

Request body:

Field	Type	Required	Description
source	string	Yes	Integration type: woocommerce or shopify
topic	string	Yes	The blog post topic or title
product_title	string	No	Related product for context
product_category	string	No	Related product category for context
language	string	No	Target language code (default: en)
tone	string	No	Writing tone (default: professional)
custom_instructions	string	No	Additional instructions for the AI

Example:

curl -X POST https://api.xcscribe.com/api/v1/plugin/generate-blog \
  -H "Authorization: Bearer xc_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "woocommerce",
    "topic": "5 Benefits of Organic Cotton Clothing",
    "product_title": "Organic Cotton T-Shirt",
    "product_category": "Clothing",
    "language": "en",
    "tone": "conversational"
  }'

Response:

{
  "content": "# 5 Benefits of Organic Cotton Clothing\n\nOrganic cotton is more than...",
  "tokens_used": 820,
  "xct_cost": "2.4600",
  "remaining_balance": "46.4900"
}

The response format is the same as the generate-description endpoint.

Billing

All plugin-generated content is billed in XCT (XC Tokens) against your organization's balance. The cost depends on the AI model tier and the length of the generated content.

• Free accounts use Claude Sonnet 4.5 at the PREMIUM tier rate.
• If your balance is insufficient, the API returns a 402 Payment Required response.
• Check your remaining balance at any time with the GET /api/v1/plugin/status endpoint.
• Top up your balance or upgrade your plan at app.xcscribe.com/settings/billing.

For more details on how XCT billing works, see Billing & Usage.

Error Responses

Status	Description
401	Invalid or inactive API key
402	Insufficient XCT balance or subscription expired
403	No credentials provided
422	Invalid request body (missing required fields)
429	Rate limit exceeded
500	Internal server error