Skip to main content

API Reference

Artbase Studio exposes a REST API through Next.js API routes. All endpoints are prefixed with /api/.

Authentication​

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

Authorization: Bearer <supabase-jwt-token>

Products API​

List Products​

GET /api/products

Query parameters:

ParameterTypeDescription
org_idstringFilter by organization
statusstringFilter by status (draft, active, archived)
limitnumberResults per page (default: 20)
offsetnumberPagination offset

Response:

{
  "data": [
    {
      "id": "uuid",
      "title": "Ceramic Vase",
      "description": "Hand-thrown ceramic vase",
      "status": "active",
      "base_price": 85.00,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 42
}

Get Product​

GET /api/products/[id]

Create Product​

POST /api/products

Request body:

{
  "title": "Ceramic Vase",
  "description": "Hand-thrown ceramic vase",
  "base_price": 85.00,
  "product_type_id": "uuid",
  "status": "draft"
}

Update Product​

PATCH /api/products/[id]

Delete Product​

DELETE /api/products/[id]

Orders API​

List Orders​

GET /api/orders

Query parameters:

ParameterTypeDescription
org_idstringFilter by organization
statusstringFilter by status
customer_idstringFilter by customer

Response:

{
  "data": [
    {
      "id": "uuid",
      "order_number": "AB-1234",
      "status": "paid",
      "total_amount": 127.50,
      "platform_fee": 6.38,
      "customer": {
        "email": "customer@example.com",
        "name": "Jane Doe"
      },
      "items": [...]
    }
  ]
}

Get Order​

GET /api/orders/[id]

Ship Order​

POST /api/orders/[id]/ship

Request body:

{
  "carrier": "usps",
  "tracking_number": "9400111899223334445566"
}

Response:

{
  "success": true,
  "order": {
    "id": "uuid",
    "status": "shipped",
    "tracking_number": "9400111899223334445566",
    "shipped_at": "2024-01-20T14:30:00Z"
  }
}

Checkout API​

Create Payment Intent​

POST /api/create-payment-intent

Creates a Stripe Payment Intent for checkout.

Request body:

{
  "items": [
    {
      "product_id": "uuid",
      "variant_id": "uuid",
      "quantity": 2
    }
  ],
  "org_id": "uuid",
  "customer_email": "customer@example.com"
}

Response:

{
  "clientSecret": "pi_xxx_secret_xxx",
  "platformFee": 6.38
}
Platform Fee Calculation

The platform fee is calculated based on the organization's subscription plan. Founding artists receive 0% commission for their first 2 years.

Email Campaigns API​

List Campaigns​

GET /api/campaigns

Get Campaign​

GET /api/campaigns/[id]

Create Campaign​

POST /api/campaigns

Request body:

{
  "name": "Summer Sale Announcement",
  "subject": "Summer Sale - 20% Off Everything!",
  "content": "<html>...</html>",
  "segment_id": "uuid",
  "scheduled_at": "2024-06-01T09:00:00Z"
}

Send Campaign​

POST /api/campaigns/[id]/send

Immediately sends the campaign or queues it for scheduled delivery.

Response:

{
  "success": true,
  "recipients": 1250,
  "campaign_id": "uuid"
}

Channels API​

Connect Etsy​

GET /api/channels/etsy/auth

Initiates OAuth flow with Etsy. Redirects to Etsy authorization page.

Etsy Callback​

GET /api/channels/etsy/callback

Handles OAuth callback, stores encrypted tokens, and links shop to organization.

Connect Gumroad​

POST /api/channels/gumroad/connect

Request body:

{
  "access_token": "gumroad-access-token"
}

Disconnect Channel​

DELETE /api/channels/[channel]/disconnect

Cart Abandonment API​

Capture Email​

POST /api/cart/email

Captures customer email for cart abandonment recovery.

Request body:

{
  "email": "customer@example.com",
  "org_id": "uuid",
  "cart_items": [
    {
      "product_id": "uuid",
      "variant_id": "uuid",
      "quantity": 1,
      "price": 85.00
    }
  ],
  "cart_total": 85.00
}

Webhooks​

Stripe Webhook​

POST /api/webhooks/stripe

Handles Stripe events:

  • checkout.session.completed - Creates order
  • payment_intent.succeeded - Updates order status
  • payment_intent.payment_failed - Handles failed payments

Resend Webhook​

POST /api/webhooks/resend

Handles email events:

  • email.delivered - Tracks delivery
  • email.opened - Tracks opens
  • email.clicked - Tracks link clicks
  • email.bounced - Handles bounces
  • email.complained - Handles spam complaints

Error Responses​

All endpoints return consistent error responses:

{
  "error": "Error message description",
  "code": "ERROR_CODE",
  "details": {}
}

Common HTTP status codes:

CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Missing or invalid token
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
429Too Many Requests - Rate limited
500Internal Server Error

Rate Limiting​

API endpoints are rate-limited:

  • Authenticated requests: 1000/minute
  • Unauthenticated requests: 100/minute
  • Webhook endpoints: 10000/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000