Integration APIs

API reference for third-party integrations including Lemon Squeezy and Google Docs

Integration APIs

This section covers the API endpoints for third-party integrations, including Lemon Squeezy for payments and Google Docs for document management.

Lemon Squeezy API

Base URL

https://your-domain.com/api/lemon

Authentication

Include your Lemon Squeezy API key in the headers:

Authorization: Bearer <lemon_squeezy_api_key>

Products

List Products

GET /api/lemon/products

Get a list of available products.

Response

{
  products: Array<{
    id: string;
    name: string;
    slug: string;
    price: number;
    currency: string;
    status: 'draft' | 'published';
    createdAt: string;
    updatedAt: string;
  }>;
  meta: {
    currentPage: number;
    totalPages: number;
    totalItems: number;
  };
}

Get Product

GET /api/lemon/products/:id

Get details of a specific product.

Orders

Create Order

POST /api/lemon/orders

Create a new order.

Request Body

{
  productId: string;
  variantId?: string;
  customerId?: string;
  email: string;
  name?: string;
  billingAddress?: {
    country: string;
    [key: string]: string;
  };
  metadata?: Record<string, any>;
}

Response

{
  order: {
    id: string;
    orderId: string;
    status: 'pending' | 'paid' | 'failed';
    total: number;
    currency: string;
    checkoutUrl: string;
    createdAt: string;
  };
}

Get Order

GET /api/lemon/orders/:id

Get order details.

Subscriptions

List Subscriptions

GET /api/lemon/subscriptions

Get a list of subscriptions.

Query Parameters

{
  customerId?: string;
  status?: 'active' | 'cancelled' | 'expired';
  page?: number;
  limit?: number;
}

Response

{
  subscriptions: Array<{
    id: string;
    customerId: string;
    status: 'active' | 'cancelled' | 'expired';
    productId: string;
    variantId: string;
    renewsAt: string;
    endsAt?: string;
    createdAt: string;
  }>;
  meta: {
    currentPage: number;
    totalPages: number;
    totalItems: number;
  };
}

Webhooks

Webhook Events

POST /api/lemon/webhooks

Handle Lemon Squeezy webhook events.

Event Types

  • order_created
  • order_paid
  • subscription_created
  • subscription_updated
  • subscription_cancelled
  • subscription_payment_success
  • subscription_payment_failed

Webhook Payload

{
  event: string;
  data: {
    id: string;
    type: string;
    attributes: Record<string, any>;
  };
  meta: {
    eventName: string;
    timestamp: string;
  };
}

Google Docs API

Base URL

https://your-domain.com/api/docs

Authentication

Include a valid session token in the headers:

Authorization: Bearer <session_token>

Documents

List Documents

GET /api/docs/documents

Get a list of accessible documents.

Query Parameters

{
  folderId?: string;
  pageSize?: number;
  pageToken?: string;
  orderBy?: 'modifiedTime' | 'createdTime';
}

Response

{
  documents: Array<{
    id: string;
    name: string;
    mimeType: string;
    createdTime: string;
    modifiedTime: string;
    webViewLink: string;
    thumbnailLink?: string;
  }>;
  nextPageToken?: string;
}

Get Document

GET /api/docs/documents/:id

Get document details and content.

Response

{
  document: {
    id: string;
    name: string;
    body: {
      content: Array<{
        paragraph?: {
          elements: Array<{
            textRun?: {
              content: string;
              style?: Record<string, any>;
            };
          }>;
        };
      }>;
    };
    revisionId: string;
    suggestionsViewMode?: 'DEFAULT_FOR_CURRENT_ACCESS' | 'SUGGESTIONS_INLINE' | 'PREVIEW_WITHOUT_SUGGESTIONS';
  };
}

Create Document

POST /api/docs/documents

Create a new document.

Request Body

{
  name: string;
  content?: string;
  folderId?: string;
  permissions?: Array<{
    role: 'owner' | 'writer' | 'reader';
    type: 'user' | 'group' | 'domain' | 'anyone';
    emailAddress?: string;
  }>;
}

Update Document

PATCH /api/docs/documents/:id

Update document content.

Request Body

{
  requests: Array<{
    insertText?: {
      text: string;
      location: {
        index: number;
      };
    };
    deleteContentRange?: {
      range: {
        startIndex: number;
        endIndex: number;
      };
    };
    updateParagraphStyle?: {
      range: {
        startIndex: number;
        endIndex: number;
      };
      paragraphStyle: Record<string, any>;
    };
  }>;
}

Permissions

Update Permissions

POST /api/docs/documents/:id/permissions

Update document permissions.

Request Body

{
  permissions: Array<{
    role: 'owner' | 'writer' | 'reader';
    type: 'user' | 'group' | 'domain' | 'anyone';
    emailAddress?: string;
  }>;
  sendNotificationEmail?: boolean;
}

Error Handling

Both APIs use standard HTTP status codes and a consistent error format:

{
  error: {
    code: string;
    message: string;
    details?: Record<string, any>;
  };
}

Common Error Codes:

| Code | Description | |------|-------------| | unauthorized | Invalid or missing API key | | not_found | Resource not found | | invalid_request | Invalid request parameters | | rate_limited | Too many requests | | integration_error | Third-party API error |

Examples

Processing Payments

import { createOrder } from '@/lib/payments';

async function processPayment(productId: string, customerData: any) {
  try {
    const order = await createOrder({
      productId,
      email: customerData.email,
      name: customerData.name,
      metadata: {
        userId: customerData.id,
        plan: 'premium',
      },
    });

    return order;
  } catch (error) {
    console.error('Payment processing error:', error);
    throw error;
  }
}

Managing Documents

import { createDocument, updatePermissions } from '@/lib/docs';

async function createSharedDocument(data: any) {
  try {
    const doc = await createDocument({
      name: data.name,
      content: data.content,
      permissions: [
        {
          role: 'writer',
          type: 'user',
          emailAddress: data.collaborator,
        },
      ],
    });

    return doc;
  } catch (error) {
    console.error('Document creation error:', error);
    throw error;
  }
}

Best Practices

  1. Error Handling

    • Implement proper error handling
    • Log errors for debugging
    • Provide clear error messages

  2. Security

    • Use environment variables for API keys
    • Validate input data
    • Implement proper access control

  3. Performance

    • Cache responses when possible
    • Use pagination for large datasets
    • Implement rate limiting

  4. Integration Management

    • Monitor API usage
    • Handle webhooks reliably
    • Keep dependencies updated

Related Resources