{
  "openapi": "3.0.0",
  "info": {
    "title": "Pocketsflow Public API",
    "version": "1.0.0",
    "description": "Comprehensive public API for managing your Pocketsflow account. Create products, manage customers, handle webhooks, publish content, and more - all programmatically. Use your API key to authenticate all requests.",
    "contact": {
      "name": "Pocketsflow Developer Support",
      "email": "support@pocketsflow.com"
    },
    "termsOfService": "https://pocketsflow.com/terms",
    "license": {
      "name": "Proprietary",
      "url": "https://pocketsflow.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.pocketsflow.com",
      "description": "Production API Server"
    },
    {
      "url": "http://localhost:6060",
      "description": "Development Server (for testing)"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Enter your Pocketsflow API key (format: pk_live_... or pk_test_...)"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          },
          "code": {
            "type": "string",
            "description": "Error code"
          }
        }
      }
    }
  },
  "security": [
    {
      "apiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Products",
      "description": "Create and manage your digital products and subscriptions"
    },
    {
      "name": "Checkout",
      "description": "Create checkout sessions for your products"
    },
    {
      "name": "Orders",
      "description": "View and manage customer orders and sales"
    },
    {
      "name": "Customers",
      "description": "Access and manage your customer base"
    },
    {
      "name": "Refunds",
      "description": "Process and manage order refunds"
    },
    {
      "name": "Subscriptions",
      "description": "Manage recurring subscriptions and billing"
    },
    {
      "name": "Discounts",
      "description": "Create and manage discount codes and promotions"
    },
    {
      "name": "Upsells",
      "description": "Configure post-purchase upsell offers"
    },
    {
      "name": "Reviews",
      "description": "Access and manage product reviews and ratings"
    },
    {
      "name": "Posts",
      "description": "Create and manage newsletter email campaigns"
    },
    {
      "name": "Subscribers",
      "description": "Manage your newsletter email subscribers"
    },
    {
      "name": "Link in Bio",
      "description": "Manage your creator page and social links"
    },
    {
      "name": "Images",
      "description": "Upload and manage product and content images"
    },
    {
      "name": "Webhooks",
      "description": "Configure webhooks to receive real-time event notifications"
    },
    {
      "name": "Account",
      "description": "Access your account information and settings"
    },
    {
      "name": "Partners",
      "description": "Become a Pocketsflow partner, refer users, and earn commissions"
    }
  ],
  "paths": {
    "/products": {
      "get": {
        "summary": "List all products",
        "description": "Retrieve a list of all your products",
        "tags": [
          "Products"
        ],
        "responses": {
          "200": {
            "description": "List of products"
          },
          "401": {
            "description": "Unauthorized - Invalid API key"
          }
        }
      },
      "post": {
        "summary": "Create a product",
        "description": "Create a new digital product",
        "tags": [
          "Products"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "price"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Product name (required)"
                  },
                  "price": {
                    "type": "number",
                    "description": "Product price (required)"
                  },
                  "description": {
                    "type": "string",
                    "description": "Product description"
                  },
                  "subtitle": {
                    "type": "string",
                    "description": "Product subtitle"
                  },
                  "published": {
                    "type": "boolean",
                    "default": true,
                    "description": "Whether product is published"
                  },
                  "slug": {
                    "type": "string",
                    "description": "Product slug for URL"
                  },
                  "thumbnail": {
                    "type": "string",
                    "description": "Thumbnail image URL"
                  },
                  "images": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Product images"
                  },
                  "payWant": {
                    "type": "boolean",
                    "default": false,
                    "description": "Enable pay-what-you-want pricing"
                  },
                  "minPrice": {
                    "type": "number",
                    "description": "Minimum price for pay-what-you-want"
                  },
                  "maxPrice": {
                    "type": "number",
                    "description": "Maximum price for pay-what-you-want"
                  },
                  "showSales": {
                    "type": "boolean",
                    "default": true,
                    "description": "Show sales count"
                  },
                  "showReviews": {
                    "type": "boolean",
                    "default": true,
                    "description": "Show reviews"
                  },
                  "refundPolicy": {
                    "type": "string",
                    "description": "Refund policy text"
                  },
                  "hasFirstName": {
                    "type": "boolean",
                    "default": false,
                    "description": "Collect customer first name"
                  },
                  "hasLastName": {
                    "type": "boolean",
                    "default": false,
                    "description": "Collect customer last name"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Product created successfully"
          },
          "400": {
            "description": "Invalid request parameters"
          }
        }
      }
    },
    "/products/{id}": {
      "get": {
        "summary": "Get product by ID",
        "description": "Retrieve a specific product by its ID",
        "tags": [
          "Products"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Product ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Product details"
          },
          "404": {
            "description": "Product not found"
          }
        }
      },
      "post": {
        "summary": "Update product",
        "description": "Update an existing product",
        "tags": [
          "Products"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Product ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "price": {
                    "type": "number"
                  },
                  "active": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Product updated successfully"
          },
          "404": {
            "description": "Product not found"
          }
        }
      },
      "delete": {
        "summary": "Delete product",
        "description": "Delete a product",
        "tags": [
          "Products"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Product ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Product deleted successfully"
          },
          "404": {
            "description": "Product not found"
          }
        }
      }
    },
    "/customers": {
      "get": {
        "summary": "List all customers",
        "description": "Retrieve a list of all your customers. Filter by email, limit, and offset.",
        "tags": [
          "Customers"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "email",
            "schema": {
              "type": "string"
            },
            "description": "Filter customers by email address"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 100
            },
            "description": "Number of customers to return"
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Number of customers to skip"
          }
        ],
        "responses": {
          "200": {
            "description": "List of customers"
          }
        }
      }
    },
    "/customers/{id}": {
      "get": {
        "summary": "Get customer by ID",
        "description": "Retrieve a specific customer by their ID",
        "tags": [
          "Customers"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Customer ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Customer details"
          },
          "404": {
            "description": "Customer not found"
          }
        }
      }
    },
    "/orders": {
      "get": {
        "summary": "List all orders",
        "description": "Retrieve a list of all your orders with pagination and filters",
        "tags": [
          "Orders"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "startDate",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Filter orders from this date (ISO 8601)"
          },
          {
            "in": "query",
            "name": "endDate",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Filter orders until this date (ISO 8601)"
          },
          {
            "in": "query",
            "name": "productId",
            "schema": {
              "type": "string"
            },
            "description": "Filter orders by product ID"
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "type": "integer",
              "default": 1
            },
            "description": "Page number for pagination"
          },
          {
            "in": "query",
            "name": "pageSize",
            "schema": {
              "type": "integer",
              "default": 20
            },
            "description": "Number of orders per page"
          }
        ],
        "responses": {
          "200": {
            "description": "List of orders with pagination info",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "orders": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "_id": {
                            "type": "string"
                          },
                          "buyerEmail": {
                            "type": "string"
                          },
                          "gross": {
                            "type": "number"
                          },
                          "net": {
                            "type": "number"
                          },
                          "taxes": {
                            "type": "number"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "product": {
                            "type": "object"
                          },
                          "customer": {
                            "type": "object"
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "totalCount": {
                          "type": "integer"
                        },
                        "totalPages": {
                          "type": "integer"
                        },
                        "currentPage": {
                          "type": "integer"
                        },
                        "pageSize": {
                          "type": "integer"
                        },
                        "hasMore": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "summary": "Get order by ID",
        "description": "Retrieve a specific order by its ID",
        "tags": [
          "Orders"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Order ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Order details"
          },
          "404": {
            "description": "Order not found"
          }
        }
      }
    },
    "/reviews": {
      "get": {
        "summary": "List product reviews",
        "description": "Retrieve reviews for your products. Filter by product ID.",
        "tags": [
          "Reviews"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "productId",
            "schema": {
              "type": "string"
            },
            "description": "Filter reviews by product ID"
          }
        ],
        "responses": {
          "200": {
            "description": "List of reviews"
          }
        }
      }
    },
    "/discounts": {
      "get": {
        "summary": "List all discounts",
        "description": "Retrieve a list of all your discount codes",
        "tags": [
          "Discounts"
        ],
        "responses": {
          "200": {
            "description": "List of discounts"
          }
        }
      },
      "post": {
        "summary": "Create a discount",
        "description": "Create a new discount code",
        "tags": [
          "Discounts"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "code",
                  "value",
                  "mainProductIds"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Discount name"
                  },
                  "code": {
                    "type": "string",
                    "description": "Discount code - what customers enter at checkout"
                  },
                  "value": {
                    "type": "number",
                    "description": "Discount value"
                  },
                  "valueType": {
                    "type": "string",
                    "enum": [
                      "percentage",
                      "fixed"
                    ],
                    "default": "percentage",
                    "description": "Discount type (defaults to percentage)"
                  },
                  "mainProductIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Product IDs this discount applies to (required)"
                  },
                  "active": {
                    "type": "boolean",
                    "default": true,
                    "description": "Whether discount is active"
                  },
                  "expiration": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Expiration date (ISO 8601)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Discount created successfully"
          }
        }
      }
    },
    "/discounts/{id}": {
      "get": {
        "summary": "Get discount by ID",
        "description": "Retrieve a specific discount by its ID",
        "tags": [
          "Discounts"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Discount ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Discount details"
          },
          "404": {
            "description": "Discount not found"
          }
        }
      },
      "put": {
        "summary": "Update discount",
        "description": "Update an existing discount",
        "tags": [
          "Discounts"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Discount ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "value": {
                    "type": "number"
                  },
                  "active": {
                    "type": "boolean"
                  },
                  "expiresAt": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Discount updated successfully"
          }
        }
      },
      "delete": {
        "summary": "Delete discount",
        "description": "Delete a discount code",
        "tags": [
          "Discounts"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Discount ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Discount deleted successfully"
          }
        }
      }
    },
    "/discounts/validate": {
      "post": {
        "summary": "Validate discount code",
        "description": "Check if a discount code is valid",
        "tags": [
          "Discounts"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "Discount code"
                  },
                  "productId": {
                    "type": "string",
                    "description": "Product ID to check if discount applies"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Discount is valid"
          },
          "404": {
            "description": "Discount code not found or invalid"
          }
        }
      }
    },
    "/upsells": {
      "get": {
        "summary": "List all upsells",
        "description": "Retrieve a list of all your upsell configurations",
        "tags": [
          "Upsells"
        ],
        "responses": {
          "200": {
            "description": "List of upsells"
          }
        }
      },
      "post": {
        "summary": "Create an upsell",
        "description": "Create a new upsell offer",
        "tags": [
          "Upsells"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "mainProductIds",
                  "upsellProductId",
                  "upsellPrice"
                ],
                "properties": {
                  "mainProductIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Product IDs that trigger this upsell (required)"
                  },
                  "upsellProductId": {
                    "type": "string",
                    "description": "Product ID to offer as upsell (required)"
                  },
                  "upsellPrice": {
                    "type": "number",
                    "description": "Upsell price (required)"
                  },
                  "name": {
                    "type": "string",
                    "description": "Upsell name"
                  },
                  "offer": {
                    "type": "string",
                    "description": "Offer headline text"
                  },
                  "upsellDescription": {
                    "type": "string",
                    "description": "Upsell description shown to customer"
                  },
                  "primaryButtonText": {
                    "type": "string",
                    "description": "Primary button text (e.g., 'Yes, add this!')"
                  },
                  "secondaryButtonText": {
                    "type": "string",
                    "description": "Secondary button text (e.g., 'No thanks')"
                  },
                  "active": {
                    "type": "boolean",
                    "default": true,
                    "description": "Whether upsell is active"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Upsell created successfully"
          }
        }
      }
    },
    "/upsells/{id}": {
      "get": {
        "summary": "Get upsell by ID",
        "description": "Retrieve a specific upsell by its ID",
        "tags": [
          "Upsells"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Upsell ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Upsell details"
          }
        }
      },
      "put": {
        "summary": "Update upsell",
        "description": "Update an existing upsell",
        "tags": [
          "Upsells"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Upsell ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "active": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upsell updated successfully"
          }
        }
      },
      "delete": {
        "summary": "Delete upsell",
        "description": "Delete an upsell offer",
        "tags": [
          "Upsells"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Upsell ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Upsell deleted successfully"
          }
        }
      }
    },
    "/subscriptions": {
      "get": {
        "summary": "List all subscriptions",
        "description": "Retrieve a list of all active subscriptions",
        "tags": [
          "Subscriptions"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "canceled",
                "paused"
              ]
            },
            "description": "Filter subscriptions by status"
          }
        ],
        "responses": {
          "200": {
            "description": "List of subscriptions"
          }
        }
      }
    },
    "/subscriptions/{id}": {
      "get": {
        "summary": "Get subscription by ID",
        "description": "Retrieve a specific subscription by its ID",
        "tags": [
          "Subscriptions"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Subscription ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription details"
          }
        }
      }
    },
    "/subscriptions/{id}/cancel": {
      "post": {
        "summary": "Cancel a subscriber's subscription",
        "description": "Immediately cancels an active subscription in Stripe and marks the subscriber as canceled. `{id}` is the Stripe subscription ID (`sub_…`) delivered on `customer.subscription.*` webhook events.",
        "tags": [
          "Subscriptions"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "example": "sub_1Nz..."
            },
            "description": "Stripe subscription ID of the subscriber to cancel"
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription canceled successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "subscription": {
                      "type": "object",
                      "description": "The canceled Stripe subscription object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Subscription not found"
          }
        }
      }
    },
    "/subscriptions/{id}/pause": {
      "post": {
        "summary": "Pause a subscriber's subscription",
        "description": "Pauses payment collection on an active subscription (`pause_collection: void`) and marks the subscriber inactive. `{id}` is the Stripe subscription ID (`sub_…`).",
        "tags": [
          "Subscriptions"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "example": "sub_1Nz..."
            },
            "description": "Stripe subscription ID of the subscriber to pause"
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription paused successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "subscription": {
                      "type": "object",
                      "description": "The paused Stripe subscription object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Subscription not found"
          }
        }
      }
    },
    "/subscriptions/{id}/resume": {
      "post": {
        "summary": "Resume a paused subscription",
        "description": "Resumes a paused subscription in Stripe and marks the subscriber active again. `{id}` is the Stripe subscription ID (`sub_…`).",
        "tags": [
          "Subscriptions"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "example": "sub_1Nz..."
            },
            "description": "Stripe subscription ID of the subscriber to resume"
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription resumed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "subscription": {
                      "type": "object",
                      "description": "The resumed Stripe subscription object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Subscription not found"
          }
        }
      }
    },
    "/webhooks": {
      "get": {
        "summary": "List all webhooks",
        "description": "Retrieve a list of all your webhook endpoints",
        "tags": [
          "Webhooks"
        ],
        "responses": {
          "200": {
            "description": "List of webhooks"
          }
        }
      },
      "post": {
        "summary": "Create a webhook",
        "description": "Create a new webhook endpoint to receive events",
        "tags": [
          "Webhooks"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url",
                  "events"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Webhook endpoint URL (must be HTTPS)"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "order.completed",
                        "order.refunded",
                        "product.created",
                        "product.updated",
                        "product.deleted",
                        "review.created",
                        "customer.created",
                        "customer.subscription.updated",
                        "customer.subscription.deleted",
                        "invoice.payment_succeeded",
                        "invoice.payment_failed",
                        "invoice.created",
                        "invoice.upcoming",
                        "payment_intent.succeeded",
                        "payment_intent.payment_failed",
                        "customer.subscription.trial_will_end",
                        "customer.subscription.pause",
                        "customer.subscription.resumed"
                      ]
                    },
                    "description": "List of events to subscribe to (required)"
                  },
                  "description": {
                    "type": "string",
                    "description": "Optional description"
                  },
                  "active": {
                    "type": "boolean",
                    "description": "Whether webhook is active"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook created successfully"
          }
        }
      }
    },
    "/webhooks/{id}": {
      "get": {
        "summary": "Get webhook by ID",
        "description": "Retrieve a specific webhook by its ID",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Webhook ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook details"
          }
        }
      },
      "put": {
        "summary": "Update webhook",
        "description": "Update an existing webhook",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Webhook ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "description": {
                    "type": "string"
                  },
                  "active": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook updated successfully"
          }
        }
      },
      "delete": {
        "summary": "Delete webhook",
        "description": "Delete a webhook endpoint",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Webhook ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook deleted successfully"
          }
        }
      }
    },
    "/webhooks/{id}/test": {
      "post": {
        "summary": "Test webhook",
        "description": "Send a test event to the webhook endpoint",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Webhook ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Test event sent successfully"
          }
        }
      }
    },
    "/users/me": {
      "get": {
        "summary": "Get current user information",
        "description": "Retrieve information about the authenticated user, including account details, subdomain, test mode status, and whether the account has sales. Use this to get the user's subdomain for constructing product URLs.",
        "tags": [
          "Account"
        ],
        "responses": {
          "200": {
            "description": "User information retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "userId": {
                      "type": "string",
                      "description": "Unique user identifier"
                    },
                    "email": {
                      "type": "string",
                      "format": "email",
                      "description": "User email address"
                    },
                    "subdomain": {
                      "type": "string",
                      "description": "User's subdomain (use for constructing product URLs: https://{subdomain}.pocketsflow.com/...)"
                    },
                    "testMode": {
                      "type": "boolean",
                      "description": "Whether account is in test mode"
                    },
                    "hasSales": {
                      "type": "boolean",
                      "description": "Whether account has any sales"
                    },
                    "createdFirstProduct": {
                      "type": "boolean",
                      "description": "Whether user has created their first product"
                    },
                    "stripeAccountId": {
                      "type": "string",
                      "description": "Connected Stripe account ID"
                    },
                    "stripeAccountStatus": {
                      "type": "string",
                      "description": "Stripe account onboarding status"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid API key"
          },
          "404": {
            "description": "User not found"
          }
        }
      }
    },
    "/creator-pages": {
      "get": {
        "summary": "Get your Link in Bio page",
        "description": "Retrieve your Link in Bio page configuration and content",
        "tags": [
          "Link in Bio"
        ],
        "responses": {
          "200": {
            "description": "Link in Bio page details"
          }
        }
      },
      "post": {
        "summary": "Update Link in Bio page",
        "description": "Update your Link in Bio page settings and content",
        "tags": [
          "Link in Bio"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "Page title"
                  },
                  "bio": {
                    "type": "string",
                    "description": "Bio text"
                  },
                  "profileImage": {
                    "type": "string",
                    "description": "Profile image URL"
                  },
                  "theme": {
                    "type": "string",
                    "description": "Theme color"
                  },
                  "links": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "title": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "order": {
                          "type": "number"
                        }
                      }
                    },
                    "description": "List of links to display"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Link in Bio page updated successfully"
          }
        }
      }
    },
    "/creator-pages/links": {
      "post": {
        "summary": "Add link to Link in Bio page",
        "description": "Add a new link to your Link in Bio page",
        "tags": [
          "Link in Bio"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title",
                  "url"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "Link title"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Link URL"
                  },
                  "order": {
                    "type": "number",
                    "description": "Display order"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Link added successfully"
          }
        }
      }
    },
    "/creator-pages/links/{id}": {
      "put": {
        "summary": "Update link",
        "description": "Update a link on your Link in Bio page",
        "tags": [
          "Link in Bio"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Link ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "order": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Link updated successfully"
          }
        }
      },
      "delete": {
        "summary": "Delete link",
        "description": "Remove a link from your Link in Bio page",
        "tags": [
          "Link in Bio"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Link ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Link deleted successfully"
          }
        }
      }
    },
    "/newsletters/posts": {
      "get": {
        "summary": "List all posts",
        "description": "Retrieve a list of all your newsletter posts",
        "tags": [
          "Posts"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string",
              "enum": [
                "draft",
                "published"
              ]
            },
            "description": "Filter posts by status"
          }
        ],
        "responses": {
          "200": {
            "description": "List of posts"
          }
        }
      },
      "post": {
        "summary": "Create a post",
        "description": "Create a new newsletter post",
        "tags": [
          "Posts"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title",
                  "content"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "Post title"
                  },
                  "content": {
                    "type": "string",
                    "description": "Post content"
                  },
                  "excerpt": {
                    "type": "string",
                    "description": "Post excerpt"
                  },
                  "coverImage": {
                    "type": "string",
                    "description": "Cover image URL"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Post tags"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "published"
                    ],
                    "description": "Post status"
                  },
                  "publishAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Schedule publish date"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Post created successfully"
          }
        }
      }
    },
    "/newsletters/posts/{id}": {
      "get": {
        "summary": "Get post by ID",
        "description": "Retrieve a specific post by its ID",
        "tags": [
          "Posts"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Post ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Post details"
          }
        }
      },
      "put": {
        "summary": "Update post",
        "description": "Update an existing post",
        "tags": [
          "Posts"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Post ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "excerpt": {
                    "type": "string"
                  },
                  "coverImage": {
                    "type": "string"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "published"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Post updated successfully"
          }
        }
      },
      "delete": {
        "summary": "Delete post",
        "description": "Delete a newsletter post",
        "tags": [
          "Posts"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Post ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Post deleted successfully"
          }
        }
      }
    },
    "/newsletters/posts/{id}/send": {
      "post": {
        "summary": "Send post to subscribers",
        "description": "Send a post to all subscribers",
        "tags": [
          "Posts"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Post ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Post published successfully"
          }
        }
      }
    },
    "/newsletters/send": {
      "post": {
        "summary": "Send email",
        "description": "Send an email to up to 100 recipients programmatically. Requires a verified sender email (configure it in Newsletters → Settings). The email is sent with your standard footer, physical address, and unsubscribe link, and is recorded as a sent post (source: api).",
        "tags": [
          "Posts"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "to",
                  "subject"
                ],
                "properties": {
                  "to": {
                    "oneOf": [
                      {
                        "type": "string",
                        "format": "email"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "format": "email"
                        },
                        "minItems": 1,
                        "maxItems": 100
                      }
                    ],
                    "description": "A recipient email address, or an array of 1-100 addresses"
                  },
                  "subject": {
                    "type": "string",
                    "description": "Email subject line"
                  },
                  "html": {
                    "type": "string",
                    "description": "HTML body of the email. Required unless `text` is provided."
                  },
                  "text": {
                    "type": "string",
                    "description": "Plain-text body. Used as the text alternative; if `html` is omitted, a simple HTML body is generated from it."
                  },
                  "fromName": {
                    "type": "string",
                    "description": "Sender display name. Defaults to your newsletter settings' default from name."
                  },
                  "replyTo": {
                    "type": "string",
                    "format": "email",
                    "description": "Reply-to address. Defaults to your configured reply-to (or sender) email."
                  },
                  "preview": {
                    "type": "string",
                    "description": "Inbox preview text"
                  }
                }
              },
              "example": {
                "to": [
                  "customer@example.com"
                ],
                "subject": "Your weekly update",
                "html": "<p>Hi there — here's what's new this week.</p>",
                "fromName": "Acme Studio",
                "replyTo": "hello@acme.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email sent",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "ID of the recorded email post"
                    },
                    "accepted": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "format": "email"
                      },
                      "description": "Recipients the email was sent to"
                    },
                    "status": {
                      "type": "string",
                      "example": "sent"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error (invalid recipients, missing subject/body, ...)"
          },
          "401": {
            "description": "Unauthorized - Invalid API key"
          },
          "403": {
            "description": "Sender email not verified (error code EMAIL_SENDER_NOT_VERIFIED)"
          },
          "502": {
            "description": "No emails could be sent (error code EMAIL_SEND_FAILED)"
          }
        }
      }
    },
    "/newsletters/subscribers": {
      "get": {
        "summary": "List all subscribers",
        "description": "Retrieve a list of all your newsletter subscribers",
        "tags": [
          "Subscribers"
        ],
        "responses": {
          "200": {
            "description": "List of subscribers"
          }
        }
      }
    },
    "/newsletters/subscribers/{id}": {
      "get": {
        "summary": "Get subscriber by ID",
        "description": "Retrieve a specific subscriber by their ID",
        "tags": [
          "Subscribers"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Subscriber ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Subscriber details"
          }
        }
      },
      "delete": {
        "summary": "Remove subscriber",
        "description": "Remove a subscriber from your list",
        "tags": [
          "Subscribers"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Subscriber ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Subscriber removed successfully"
          }
        }
      }
    },
    "/images": {
      "post": {
        "summary": "Upload image",
        "description": "Upload an image file. Returns the image URL that can be used in products, posts, etc.",
        "tags": [
          "Images"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Image file to upload"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Image uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "description": "CDN URL of the uploaded image"
                    },
                    "id": {
                      "type": "string",
                      "description": "Image ID"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List all images",
        "description": "Retrieve a list of all your uploaded images",
        "tags": [
          "Images"
        ],
        "responses": {
          "200": {
            "description": "List of images"
          }
        }
      }
    },
    "/images/{id}": {
      "delete": {
        "summary": "Delete image",
        "description": "Delete an uploaded image",
        "tags": [
          "Images"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Image ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Image deleted successfully"
          }
        }
      }
    },
    "/refunds": {
      "post": {
        "summary": "Create a refund",
        "description": "Process a refund for an order",
        "tags": [
          "Refunds"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "orderId"
                ],
                "properties": {
                  "orderId": {
                    "type": "string",
                    "description": "Order ID to refund"
                  },
                  "amount": {
                    "type": "number",
                    "description": "Partial refund amount (optional, defaults to full refund)"
                  },
                  "reason": {
                    "type": "string",
                    "description": "Refund reason"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Refund processed successfully"
          }
        }
      },
      "get": {
        "summary": "List all refunds",
        "description": "Retrieve a list of all refunds",
        "tags": [
          "Refunds"
        ],
        "responses": {
          "200": {
            "description": "List of refunds"
          }
        }
      }
    },
    "/refunds/{id}": {
      "get": {
        "summary": "Get refund by ID",
        "description": "Retrieve a specific refund by its ID",
        "tags": [
          "Refunds"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Refund ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Refund details"
          }
        }
      }
    },
    "/checkout/sessions": {
      "post": {
        "summary": "Create checkout session",
        "description": "Create a checkout session for a product. Returns a URL to redirect customers to complete their purchase.",
        "tags": [
          "Checkout"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "productId",
                  "successUrl",
                  "cancelUrl"
                ],
                "properties": {
                  "productId": {
                    "type": "string",
                    "description": "Product ID to purchase"
                  },
                  "successUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Redirect URL after successful payment"
                  },
                  "cancelUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Redirect URL if payment is canceled"
                  },
                  "customerEmail": {
                    "type": "string",
                    "format": "email",
                    "description": "Customer email, attached to the resulting order and webhook payload."
                  },
                  "discountCode": {
                    "type": "string",
                    "description": "Discount code to apply"
                  },
                  "metadata": {
                    "type": "object",
                    "description": "Custom metadata for the checkout"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Checkout session created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Checkout session ID"
                    },
                    "url": {
                      "type": "string",
                      "description": "Checkout URL"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/partners": {
      "post": {
        "summary": "Become a partner",
        "description": "Register as a Pocketsflow partner. You'll receive a unique referral code to share. When users sign up using your code, you earn commissions on their sales.",
        "tags": [
          "Partners"
        ],
        "responses": {
          "201": {
            "description": "Partner created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "_id": {
                      "type": "string"
                    },
                    "userId": {
                      "type": "string"
                    },
                    "referralCode": {
                      "type": "string",
                      "example": "PF-a1b2c3d4"
                    },
                    "commissionRate": {
                      "type": "number",
                      "example": 20
                    },
                    "active": {
                      "type": "boolean"
                    },
                    "totalSignups": {
                      "type": "number"
                    },
                    "totalSales": {
                      "type": "number"
                    },
                    "totalRevenue": {
                      "type": "number"
                    },
                    "totalCommission": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Already a partner"
          }
        }
      },
      "get": {
        "summary": "Get my partner profile",
        "description": "Retrieve your partner profile including referral code and denormalized stats.",
        "tags": [
          "Partners"
        ],
        "responses": {
          "200": {
            "description": "Partner profile"
          },
          "404": {
            "description": "Not a partner"
          }
        }
      }
    },
    "/partners/register-referral": {
      "post": {
        "summary": "Register a referral signup",
        "description": "Call this after a user signs up through a partner's referral link. Sets the referral code on the authenticated user and increments the partner's signup count.",
        "tags": [
          "Partners"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "referralCode"
                ],
                "properties": {
                  "referralCode": {
                    "type": "string",
                    "example": "PF-a1b2c3d4",
                    "description": "The partner's referral code from the signup link"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Referral registered successfully"
          },
          "400": {
            "description": "Missing referralCode, user already has a referral, or self-referral"
          },
          "404": {
            "description": "Invalid or inactive referral code"
          }
        }
      }
    },
    "/partners/referrals": {
      "get": {
        "summary": "Get referred users",
        "description": "List all users who signed up using your referral code. Each user includes their sales count and total revenue.",
        "tags": [
          "Partners"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "page",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of referred users with sales stats"
          },
          "404": {
            "description": "Not a partner"
          }
        }
      }
    },
    "/partners/referrals/sales": {
      "get": {
        "summary": "Get sales from referred users",
        "description": "Get all sales generated by users who signed up through your referral code.",
        "tags": [
          "Partners"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "page",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of sales from referred users"
          },
          "404": {
            "description": "Not a partner"
          }
        }
      }
    },
    "/partners/stats": {
      "get": {
        "summary": "Get partner stats",
        "description": "Get live-computed aggregated stats: total signups, total sales, total revenue, and total commission earned based on your commission rate.",
        "tags": [
          "Partners"
        ],
        "responses": {
          "200": {
            "description": "Aggregated partner stats",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "referralCode": {
                      "type": "string",
                      "example": "PF-a1b2c3d4"
                    },
                    "commissionRate": {
                      "type": "number",
                      "example": 20
                    },
                    "totalSignups": {
                      "type": "number"
                    },
                    "totalSales": {
                      "type": "number"
                    },
                    "totalRevenue": {
                      "type": "number"
                    },
                    "totalCommission": {
                      "type": "number"
                    },
                    "active": {
                      "type": "boolean"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not a partner"
          }
        }
      }
    }
  }
}