Commerce API Documentation

Version: 1.0.0 Base URL: https://api.coditect.ai/api/v1/commerce Authentication: JWT Bearer Token (except products endpoints)

Overview

The Commerce API enables the CODITECT multi-product platform with support for:

Product catalog browsing
Shopping cart management
Stripe and Google Pay checkout
Order history
Entitlement verification

Authentication

Most endpoints require JWT authentication. Include the token in the Authorization header:

Authorization: Bearer <jwt_token>

Public Endpoints (no auth required):

GET /products - List products
GET /products/{slug} - Get product details

Authenticated Endpoints:

All cart, checkout, orders, and entitlements endpoints

Products

List Products

Retrieve all active products in the catalog.

GET /products

Authentication: None required

Response: 200 OK

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "slug": "core",
    "name": "CODITECT Core",
    "description": "The complete AI-assisted development framework...",
    "product_type": "base",
    "price_cents": 4900,
    "currency": "usd",
    "billing_interval": "month",
    "features": [
      "130+ specialized AI agents",
      "70+ slash commands",
      "180+ automation skills",
      "Git workflow automation",
      "Context memory system",
      "Session preservation",
      "Multi-tenant isolation",
      "Priority support"
    ],
    "requires": [],
    "subdomain": null,
    "active": true
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "slug": "dms",
    "name": "CODITECT DMS",
    "description": "Document Management System with semantic search...",
    "product_type": "addon",
    "price_cents": 2900,
    "currency": "usd",
    "billing_interval": "month",
    "features": [...],
    "requires": ["core"],
    "subdomain": "dms.coditect.ai",
    "active": true
  }
]

Get Product

Retrieve a specific product by slug.

GET /products/{slug}

Authentication: None required

Path Parameters:

Parameter	Type	Description
`slug`	string	Product slug (e.g., `core`, `dms`, `workflow`, `enterprise`)

Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "slug": "core",
  "name": "CODITECT Core",
  "description": "The complete AI-assisted development framework with intelligent agents, workflow automation, and enterprise-grade tools.",
  "product_type": "base",
  "price_cents": 4900,
  "currency": "usd",
  "billing_interval": "month",
  "features": [
    "130+ specialized AI agents",
    "70+ slash commands",
    "180+ automation skills",
    "Git workflow automation",
    "Context memory system",
    "Session preservation",
    "Multi-tenant isolation",
    "Priority support"
  ],
  "requires": [],
  "subdomain": null,
  "active": true
}

Error Response: 404 Not Found

{
  "detail": "Not found."
}

Cart

Get Cart

Retrieve the current user's shopping cart.

GET /cart

Authentication: Required

Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440010",
  "user_id": "550e8400-e29b-41d4-a716-446655440099",
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "product": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "slug": "core",
        "name": "CODITECT Core",
        "price_cents": 4900
      },
      "quantity": 1,
      "added_at": "2025-12-30T10:00:00Z"
    }
  ],
  "total_cents": 4900,
  "currency": "usd",
  "created_at": "2025-12-30T09:55:00Z",
  "updated_at": "2025-12-30T10:00:00Z"
}

Add Item to Cart

Add a product to the cart.

POST /cart/items

Authentication: Required

Request Body:

{
  "product_slug": "core",
  "quantity": 1
}

Field	Type	Required	Description
`product_slug`	string	Yes	Product slug to add
`quantity`	integer	No	Quantity (default: 1)

Response: 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440011",
  "product": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "slug": "core",
    "name": "CODITECT Core",
    "price_cents": 4900
  },
  "quantity": 1,
  "added_at": "2025-12-30T10:00:00Z"
}

Error Responses:

400 Bad Request - Missing dependency

{
  "error": "Product 'dms' requires: core"
}

400 Bad Request - Product already in cart

{
  "error": "Product already in cart"
}

404 Not Found - Product not found

{
  "error": "Product not found"
}

Remove Item from Cart

Remove a product from the cart.

DELETE /cart/items/{product_id}

Authentication: Required

Path Parameters:

Parameter	Type	Description
`product_id`	uuid	Product UUID to remove

Response: 204 No Content

Error Response: 404 Not Found

{
  "error": "Item not in cart"
}

Clear Cart

Remove all items from the cart.

DELETE /cart

Authentication: Required

Response: 204 No Content

Checkout

Create Checkout Session

Create a Stripe checkout session for the current cart.

POST /checkout

Authentication: Required

Request Body:

{
  "success_url": "https://coditect.ai/checkout/success",
  "cancel_url": "https://coditect.ai/checkout/cancel"
}

Field	Type	Required	Description
`success_url`	string	Yes	Redirect URL after successful payment
`cancel_url`	string	Yes	Redirect URL if user cancels

Response: 200 OK

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "session_id": "cs_live_a1b2c3d4e5f6..."
}

Error Responses:

400 Bad Request - Empty cart

{
  "error": "Cart is empty"
}

400 Bad Request - Missing dependency

{
  "error": "Product 'dms' requires 'core'. Please add CODITECT Core to your cart."
}

Google Pay Checkout

Process a Google Pay payment token.

POST /checkout/google-pay

Authentication: Required

Request Body:

{
  "payment_token": "eyJzaWduYXR1cmUiOiJNRVVDSVFD..."
}

Field	Type	Required	Description
`payment_token`	string	Yes	Google Pay payment token

Response: 200 OK

{
  "order_id": "550e8400-e29b-41d4-a716-446655440020",
  "status": "completed",
  "message": "Payment successful"
}

Error Responses:

400 Bad Request - Payment failed

{
  "error": "Payment processing failed",
  "details": "Card declined"
}

Checkout Success

Handle post-payment redirect from Stripe.

GET /checkout/success?session_id={session_id}

Authentication: Required

Query Parameters:

Parameter	Type	Description
`session_id`	string	Stripe checkout session ID

Response: 200 OK

{
  "order_id": "550e8400-e29b-41d4-a716-446655440020",
  "status": "completed",
  "products": ["core", "dms"],
  "total_cents": 7800,
  "currency": "usd"
}

Orders

List Orders

Retrieve all orders for the current user.

GET /orders

Authentication: Required

Response: 200 OK

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440020",
    "status": "completed",
    "total_cents": 7800,
    "currency": "usd",
    "items": [
      {
        "product_slug": "core",
        "product_name": "CODITECT Core",
        "price_cents": 4900,
        "quantity": 1
      },
      {
        "product_slug": "dms",
        "product_name": "CODITECT DMS",
        "price_cents": 2900,
        "quantity": 1
      }
    ],
    "created_at": "2025-12-30T10:15:00Z",
    "completed_at": "2025-12-30T10:15:30Z"
  }
]

Get Order

Retrieve a specific order by ID.

GET /orders/{id}

Authentication: Required

Path Parameters:

Parameter	Type	Description
`id`	uuid	Order UUID

Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440020",
  "status": "completed",
  "total_cents": 7800,
  "currency": "usd",
  "items": [
    {
      "product_slug": "core",
      "product_name": "CODITECT Core",
      "price_cents": 4900,
      "quantity": 1
    }
  ],
  "stripe_payment_intent_id": "pi_3abc123...",
  "created_at": "2025-12-30T10:15:00Z",
  "completed_at": "2025-12-30T10:15:30Z"
}

Error Response: 404 Not Found

{
  "detail": "Not found."
}

Entitlements

List Entitlements

Retrieve all active entitlements for the current user.

GET /entitlements

Authentication: Required

Response: 200 OK

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440030",
    "product_slug": "core",
    "product_name": "CODITECT Core",
    "status": "active",
    "granted_at": "2025-12-30T10:15:30Z",
    "expires_at": "2026-01-30T10:15:30Z",
    "order_id": "550e8400-e29b-41d4-a716-446655440020"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440031",
    "product_slug": "dms",
    "product_name": "CODITECT DMS",
    "status": "active",
    "granted_at": "2025-12-30T10:15:30Z",
    "expires_at": "2026-01-30T10:15:30Z",
    "order_id": "550e8400-e29b-41d4-a716-446655440020"
  }
]

Get Entitlement

Check entitlement for a specific product.

GET /entitlements/{slug}

Authentication: Required

Path Parameters:

Parameter	Type	Description
`slug`	string	Product slug

Response: 200 OK - Has entitlement

{
  "id": "550e8400-e29b-41d4-a716-446655440030",
  "product_slug": "core",
  "product_name": "CODITECT Core",
  "status": "active",
  "granted_at": "2025-12-30T10:15:30Z",
  "expires_at": "2026-01-30T10:15:30Z",
  "has_access": true
}

Response: 200 OK - No entitlement

{
  "product_slug": "workflow",
  "has_access": false,
  "message": "No active entitlement for this product"
}

Check Entitlement (Query)

Alternative endpoint to check entitlement via query parameter.

GET /entitlements/check?product={slug}

Authentication: Required

Query Parameters:

Parameter	Type	Description
`product`	string	Product slug to check

Response: 200 OK

{
  "product_slug": "core",
  "has_access": true,
  "expires_at": "2026-01-30T10:15:30Z"
}

Products Reference

Product	Slug	Type	Price	Requires
CODITECT Core	`core`	base	$49/mo	-
CODITECT DMS	`dms`	addon	$29/mo	core
Workflow Analyzer	`workflow`	addon	$19/mo	core
Enterprise Bundle	`enterprise`	bundle	$149/mo	-

Product Types:

base - Standalone product (no dependencies)
addon - Requires a base product
bundle - Includes multiple products

Error Codes

HTTP Code	Description
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request (validation error, missing dependency)
401	Unauthorized (missing or invalid token)
403	Forbidden (insufficient permissions)
404	Not Found
500	Internal Server Error

Rate Limits

Endpoint Category	Limit
Products (public)	100 requests/minute
Cart operations	30 requests/minute
Checkout	10 requests/minute
Orders/Entitlements	60 requests/minute

Webhooks

Stripe webhooks are handled at:

POST /api/v1/commerce/webhooks/stripe

Events Processed:

checkout.session.completed - Creates order and entitlements
invoice.paid - Extends entitlements for subscriptions
customer.subscription.deleted - Revokes entitlements

SDK Usage

Python Example

import requests

BASE_URL = "https://api.coditect.ai/api/v1/commerce"
TOKEN = "your_jwt_token"

headers = {"Authorization": f"Bearer {TOKEN}"}

# List products
products = requests.get(f"{BASE_URL}/products").json()

# Add to cart
requests.post(
    f"{BASE_URL}/cart/items",
    json={"product_slug": "core"},
    headers=headers
)

# Checkout
checkout = requests.post(
    f"{BASE_URL}/checkout",
    json={
        "success_url": "https://myapp.com/success",
        "cancel_url": "https://myapp.com/cancel"
    },
    headers=headers
).json()

print(f"Redirect to: {checkout['checkout_url']}")

# Check entitlement
entitlement = requests.get(
    f"{BASE_URL}/entitlements/core",
    headers=headers
).json()

if entitlement.get("has_access"):
    print("User has access to CODITECT Core")

cURL Examples

# List products (no auth)
curl https://api.coditect.ai/api/v1/commerce/products

# Get cart
curl -H "Authorization: Bearer $TOKEN" \
  https://api.coditect.ai/api/v1/commerce/cart

# Add to cart
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_slug": "core"}' \
  https://api.coditect.ai/api/v1/commerce/cart/items

# Check entitlement
curl -H "Authorization: Bearer $TOKEN" \
  https://api.coditect.ai/api/v1/commerce/entitlements/core

Changelog

v1.0.0 (2025-12-30)

Initial release
Products API (list, detail)
Cart API (get, add, remove, clear)
Checkout API (Stripe, Google Pay)
Orders API (list, detail)
Entitlements API (list, detail, check)

Last Updated: 2025-12-30 API Version: 1.0.0 Implementation: ADR-014 Commerce Product Catalog Architecture

Overview​

Authentication​

Products​

List Products​

Get Product​

Cart​

Get Cart​

Add Item to Cart​

Remove Item from Cart​

Clear Cart​

Checkout​

Create Checkout Session​

Google Pay Checkout​

Checkout Success​

Orders​

List Orders​

Get Order​

Entitlements​

List Entitlements​

Get Entitlement​

Check Entitlement (Query)​

Products Reference​

Error Codes​

Rate Limits​

Webhooks​

SDK Usage​

Python Example​

cURL Examples​

Changelog​

v1.0.0 (2025-12-30)​

Overview

Authentication

Products

List Products

Get Product

Cart

Get Cart

Add Item to Cart

Remove Item from Cart

Clear Cart

Checkout

Create Checkout Session

Google Pay Checkout

Checkout Success

Orders

List Orders

Get Order

Entitlements

List Entitlements

Get Entitlement

Check Entitlement (Query)

Products Reference

Error Codes

Rate Limits

Webhooks

SDK Usage

Python Example

cURL Examples

Changelog

v1.0.0 (2025-12-30)