Gallery API Reference

The Artbase Gallery API provides endpoints for multi-artist shopping, curation, order fulfillment, and analytics. All endpoints follow RESTful conventions and return JSON responses.

Base URL

https://gallery.artbase.studio/api/gallery

Authentication

Gallery APIs use different authentication methods depending on the endpoint type:

Endpoint Type	Auth Method	Header
Public (cart, checkout, orders)	None	-
Artist APIs	Supabase Auth	Authorization: Bearer <token>
Admin APIs	Supabase Auth + RLS	Authorization: Bearer <token>

Response Format

All API responses follow this structure:

Success Response

{
  "success": true,
  "data": { /* endpoint-specific data */ }
}

Error Response

{
  "error": "Error message describing what went wrong"
}

Rate Limiting

Gallery APIs are rate-limited to prevent abuse:

• Public endpoints: 100 requests per minute per IP
• Authenticated endpoints: 500 requests per minute per user

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Error Codes

Status Code	Meaning
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid authentication
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

API Sections

Shopping & Checkout

Endpoints for browsing, cart management, and purchasing:

• Cart Management - Add/remove items, manage shopping cart
• Checkout - Payment processing with Stripe Connect
• Orders - Order tracking and status

Artist APIs

Endpoints for artists to manage their gallery presence:

• Artist Orders - View and fulfill gallery orders
• Artist Analytics - Performance metrics and insights

Admin APIs

Platform administration endpoints (requires admin role):

• Collections - Curate product collections
• Spotlights - Feature artists
• Analytics - Gallery-wide metrics

Attribution & Marketing

• Referral Tracking - Track artist referrals (30-day window)
• Newsletter - Subscription management

Key Concepts

Multi-Artist Orders

Gallery orders can contain items from multiple artists. The system:

1. Groups cart items by artist
2. Creates a single payment intent with transfer group
3. Splits payment to each artist's Stripe Connect account
4. Allows per-artist fulfillment and tracking

Fee Structure

Gallery uses transparent pricing:

• Artist receives: 88% of product price
• Gallery commission: 12% of product price
• Stripe fees: 2.9% + $0.30 (added to customer total)

Example: $100 product

• Customer pays: ~$115.20
• Artist receives: $88.00
• Gallery receives: $12.00
• Stripe receives: ~$3.20

Attribution Window

When users visit the gallery and then purchase from an artist's individual store within 30 days:

• Artist keeps 100% of sale (minus Stripe fees)
• Gallery tracks but doesn't take commission
• Encourages direct artist relationships

Order Statuses

Gallery orders have cascading statuses:

Status	Description
pending	Payment not yet processed
paid	Payment succeeded, awaiting fulfillment
processing	At least one artist is preparing items
partially_shipped	Some artists have shipped
shipped	All artists have shipped
delivered	All items delivered
cancelled	Order cancelled before shipment

Webhooks

Gallery supports webhooks for real-time notifications:

Stripe Webhooks

• payment_intent.succeeded - Payment completed
• transfer.created - Artist payout initiated
• account.updated - Artist Connect account status change

PostGrid Webhooks (Future)

• letter.delivered - Physical mail delivered
• letter.returned - Mail returned to sender

Testing

Test Mode

All endpoints support test mode via Stripe test keys. Use test credit cards:

Card: 4242 4242 4242 4242
Exp: Any future date
CVC: Any 3 digits

Sample Data

The development database includes seed data:

• 5 sample artists with Connect accounts
• 3 curated collections
• 20 gallery-eligible products
• Sample orders in various statuses

SDKs & Integration

JavaScript/TypeScript

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  'https://your-project.supabase.co',
  'your-anon-key'
);

// Add item to cart
const { data, error } = await supabase
  .from('gallery_cart_items')
  .insert({
    session_id: sessionId,
    product_id: productId,
    quantity: 1,
  });

cURL Examples

Each endpoint documentation includes cURL examples for testing.

Next Steps

🛒 Checkout API

Process multi-artist payments

📦 Artist Orders API

Manage order fulfillment

🎨 Curation API

Curate collections and spotlights