WPBay API Documentation

  • Home
  • WPBay API Documentation

Welcome to the WPBay API documentation. If you don’t use the official WPBay SDK, you can build your own integration with the WPBay API. This guide provides detailed technical information on the available endpoints for the WPBay API. These will help with managing license registrations for WPBay products, update products, send analytics details or send contact form data. The API is designed to allow developers to register, validate, and manage product licenses. Each endpoint is documented with its purpose, request parameters, processing logic, and expected responses, including error conditions.

In this first section, we cover the License Registration Endpoint which is responsible for registering a product license using a purchase code. Additional endpoints will be documented in subsequent sections.

1. License Registration Endpoint

Endpoint:
https://wpbay.com/api/purchase/v1/register

HTTP Methods Supported:

  • GET
  • POST

Purpose

This endpoint registers a license for a product by verifying the provided purchase code, site URL, admin email, and API key. It performs various validations, including:

  • API key verification
  • Purchase code structure validation
  • Product ownership confirmation
  • Developer sandbox mode checks (if enabled)
  • License count and duplicate registration checks

If all validations pass, the endpoint inserts a new license record into the database and returns a success message. Otherwise, it returns an appropriate error.

Request Parameters

Required Parameters (as defined in the route registration):

  • purchase_code
    • Type: String
    • Description: The unique purchase code obtained from the purchase transaction.
    • Validation: Must be a non-empty string.
  • site_url
    • Type: String
    • Description: The URL of the site where the product is being registered.
    • Validation: Must be a non-empty string and will be sanitized using esc_url_raw.
  • admin_email
    • Type: String
    • Description: The administrative email address associated with the site.
    • Validation: Must be a non-empty string and is sanitized with sanitize_email.
  • api_key
    • Type: String
    • Description: The API key used to authenticate the request.
    • Validation: Must be provided and corresponds to a valid user via an internal lookup.
  • product_slug
    • Type: String
    • Description: A unique slug identifying the product.
    • Requirement: Mandatory; the function checks for its presence and validates that it matches the product data.
  • wpbay_product_id
    • Type: Integer (optional)
    • Description: An optional parameter to verify that the product ID derived from the purchase code matches the expected product.
  • developer_mode
    • Type: String (typically ‘0’ or ‘1’)
    • Description: When set to ‘1’, this parameter activates developer (sandbox) mode, allowing testing registrations with a developer purchase code.
  • secret_key
    • Type: String (optional)
    • Description: A key required for validating developer mode requests. It is checked against a developer testing purchase code.

Example Request

POST Request Example:

POST https://wpbay.com/api/purchase/v1/register
Content-Type: application/json

{
  "purchase_code": "ABC123-XYZ789-DEF456",
  "site_url": "https://example.com",
  "admin_email": "[email protected]",
  "api_key": "your_api_key_here",
  "product_slug": "MY_PRODUCT",
  "wpbay_product_id": 123,         // optional: product ID
  "developer_mode": "0",           // optional: set to "1" for sandbox testing mode
  "secret_key": ""                 // optional: required if developer_mode is "1"
}

Example Responses

Successful Registration

{
  "success": true,
  "plan_type": "wpbay",
  "message": "License successfully registered."
}

Note: In developer mode, the success message may vary (e.g., “Developer testing license successfully registered.”), and the default plan type remains "wpbay".

Error Responses

  • Missing API Key { "code": "missing_api_key", "message": "You must provide an API key!", "data": { "status": 403 } }
  • Missing Site URL { "code": "missing_site_url", "message": "You must provide a site URL.", "data": { "status": 403 } }
  • Missing Purchase Code { "code": "missing_purchase_code", "message": "You must provide a purchase code.", "data": { "status": 403 } }
  • Invalid API Key / Ownership Issues { "code": "invalid_api_key", "message": "Invalid API key.", "data": { "status": 403 } }
  • License Already Registered { "success": true, "plan_type": "wpbay", "message": "License already registered." }
  • License Limit Reached { "code": "limit_reached", "message": "The maximum license count has been reached for this purchase code.", "data": { "status": 403 } }
  • Database Errors { "code": "db_error", "message": "Failed to register the license in the database due to an unknown error.", "data": { "status": 500 } }

Notes

  • Developer Mode:
    The developer mode allows for sandbox testing with a dedicated developer purchase code. It includes limits on active sandbox licenses and requires that the product slug is pre-registered in the developer’s WPBay dashboard.

2. License Revocation Endpoint

Endpoint:
https://wpbay.com/api/purchase/v1/revoke

HTTP Methods Supported:

  • GET
  • POST

Purpose

The License Revocation Endpoint is designed to revoke a previously registered license using a purchase code and site URL. It supports both the standard revocation process and a specialized developer (sandbox) mode for testing purposes. In developer mode, the endpoint handles sandbox licenses stored in the user’s configuration, ensuring that only pre-registered product slugs are processed and that developers can safely test license revocation without affecting production data.

Request Parameters

Parameters Declared in Route Registration

  • purchase_code
    • Type: String
    • Description: The unique purchase code to identify the license registration.
    • Validation: Must be a non-empty string.
  • site_url
    • Type: String
    • Description: The URL of the site for which the license is registered.
    • Validation: Must be a non-empty string and is sanitized using esc_url_raw.
  • api_key
    • Type: String
    • Description: The API key used to authenticate and identify the user making the request.
    • Validation: Must be provided and correspond to a valid user.
  • product_slug
    • Type: String
    • Description: A unique slug representing the product.
    • Requirement: Mandatory; the revocation process verifies that this slug is provided.
  • developer_mode
    • Type: String (typically “0” or “1”)
    • Description: When set to “1”, activates developer (sandbox) mode. In this mode, the endpoint processes sandbox licenses stored in user metadata.
  • secret_key
    • Type: String
    • Description: A secret key required to validate developer mode requests. It is checked to ensure that the request is authorized for sandbox testing.

Example Request

POST Request Example:

POST https://wpbay.com/api/purchase/v1/revoke
Content-Type: application/json

{
  "purchase_code": "ABC123-XYZ789-DEF456",
  "site_url": "https://example.com",
  "api_key": "your_api_key_here",
  "product_slug": "MY_PRODUCT",
  "developer_mode": "0",         // Optional: Set to "1" for sandbox revocation
  "secret_key": ""               // Optional: Required if developer_mode is "1"
}

Example Responses

Successful Revocation (Standard Mode)

{
  "success": true,
  "message": "License successfully revoked for site URL: https://example.com"
}

Successful Revocation (Developer/Sandbox Mode)

{
  "success": true,
  "message": "Sandbox license successfully revoked for site URL: https://example.com"
}

Error Responses

  • Missing API Key { "code": "missing_api_key", "message": "You must provide an API key.", "data": { "status": 403 } }
  • Invalid API Key { "code": "invalid_api_key", "message": "Invalid API key.", "data": { "status": 403 } }
  • Missing or Invalid Data
    • If either purchase_code or site_url is empty: { "code": "invalid_data", "message": "Both purchase code and site URL are required.", "data": { "status": 400 } }
    • If product_slug is missing: { "code": "missing_product_slug", "message": "You must provide a product slug.", "data": { "status": 403 } }
  • Developer Mode Errors
    • If no sandbox license is found: { "code": "sandbox_not_found", "message": "No active sandbox license found for the given purchase code and site URL!", "data": { "status": 404 } }
  • Not Allowed { "code": "not_allowed", "message": "You do not own this product", "data": { "status": 400 } }
  • Database Errors
    • On failure to delete the record from the database: { "code": "db_error", "message": "Failed to revoke the license for this site.", "data": { "status": 500 } }
    • If no active license is found: { "code": "not_found", "message": "No active license found for the given purchase code and site URL.", "data": { "status": 404 } }

3. Purchase Code Registration Check Endpoint

Endpoint:
https://wpbay.com/api/purchase/v1/registered

HTTP Methods Supported:

  • GET
  • POST

Purpose

This endpoint is designed to verify whether a given purchase code is currently registered for a specific site URL. It caters to both production and developer (sandbox) scenarios. In production mode, the endpoint validates the purchase code structure, retrieves order details, and confirms that the requester is the owner of the product. In developer mode, it leverages sandbox activation data stored in user metadata to determine if the license is registered in a testing environment.

Request Parameters

Declared in Route Registration

  • purchase_code
    • Type: String
    • Description: The unique purchase code to check registration status.
    • Validation: Must be provided as a non-empty string.
  • site_url
    • Type: String
    • Description: The URL of the site where the license might be registered.
    • Validation: Must be provided as a non-empty string and is sanitized using esc_url_raw.
  • api_key
    • Type: String
    • Description: The API key that authenticates the request.
    • Validation: Must be provided and correspond to a valid user.
  • product_slug
    • Type: String
    • Description: A unique slug representing the product.
    • Requirement: Mandatory; used to confirm product ownership and for sandbox mode validations.
  • developer_mode
    • Type: String (typically “0” or “1”)
    • Description: When set to “1”, activates developer (sandbox) mode. In this mode, sandbox license activations stored in user metadata are checked.
  • secret_key
    • Type: String
    • Description: A secret key required to validate developer mode requests. It is used in conjunction with the developer testing purchase code.

Example Request

POST Request Example:

POST https://wpbay.com/api/purchase/v1/registered
Content-Type: application/json

{
  "purchase_code": "ABC123-XYZ789-DEF456",
  "site_url": "https://example.com",
  "api_key": "your_api_key_here",
  "product_slug": "MY_PRODUCT",
  "developer_mode": "0",         // Optional: Set to "1" for sandbox mode
  "secret_key": ""               // Optional: Required if developer_mode is "1"
}

Example Responses

Successful Registration Check (Production Mode)

{
  "success": true,
  "status": "exists",
  "message": "This purchase code is registered."
}

Developer Mode Response

  • In developer (sandbox) mode, if a matching sandbox activation is found, a similar success message is returned:
{
  "success": true,
  "status": "exists",
  "message": "This purchase code is registered."
}

Error Responses

  • Missing API Key { "code": "missing_api_key", "message": "You must provide an API key.", "data": { "status": 403 } }
  • Missing Site URL { "code": "missing_site_url", "message": "You must provide a site URL.", "data": { "status": 403 } }
  • Missing Product Slug { "code": "missing_product_slug", "message": "You must provide a product slug.", "data": { "status": 403 } }
  • Missing Purchase Code { "code": "missing_purchase_code", "message": "You must provide a purchase code.", "data": { "status": 403 } }
  • Invalid Purchase Code or Order Data { "code": "invalid_purchase_code", "message": "Invalid order data.", "data": { "status": 400 } }
  • Order Not Available { "code": "order_not_available", "message": "The order has been refunded or is no longer available.", "data": { "status": 400 } }
  • Not Allowed (Product Ownership Mismatch) { "code": "not_allowed", "message": "You do not own this product", "data": { "status": 400 } }
  • Not Found (No Active Registration) { "code": "not_found", "message": "This purchase code is not registered.", "data": { "status": 400 } }

4. Purchase Code Verification Endpoint

Endpoint:
https://wpbay.com/api/purchase/v1/verify

HTTP Methods Supported:

  • GET
  • POST

Purpose

The Purchase Code Verification Endpoint is intended to verify the validity of a purchase code. It checks the provided purchase code against the associated order details and confirms that the requesting user is the owner of the product. This endpoint supports both production and developer (sandbox) modes:

  • Production Mode: Validates the purchase code structure, retrieves order details and confirms product ownership.
  • Developer Mode: Provides a simplified verification pathway for sandbox testing, ensuring that the testing purchase code matches one pre-registered for the product.

On successful verification, the endpoint returns detailed order information including order ID, item ID, product ID, license number, order status, order date, billing email, and customer ID.

Request Parameters

Declared in Route Registration

  • purchase_code
    • Type: String
    • Description: The unique purchase code to be verified.
    • Validation: Must be provided as a non-empty string.
  • api_key
    • Type: String
    • Description: The API key that authenticates the request.
    • Validation: Must be provided and correspond to a valid user.
  • product_slug
    • Type: String
    • Description: A unique slug representing the product.
    • Requirement: Mandatory; used to confirm product ownership and for developer mode validations.
  • developer_mode
    • Type: String (typically “0” or “1”)
    • Description: When set to “1”, activates developer (sandbox) mode. This allows the endpoint to verify testing purchase codes.
  • secret_key
    • Type: String
    • Description: A secret key required to validate developer mode requests. It is checked against a developer testing purchase code.

Example Request

POST Request Example:

POST https://wpbay.com/api/purchase/v1/verify
Content-Type: application/json

{
  "purchase_code": "ABC123-XYZ789-DEF456",
  "api_key": "your_api_key_here",
  "product_slug": "MY_PRODUCT",
  "developer_mode": "0",         // Optional: Set to "1" for sandbox mode
  "secret_key": ""               // Optional: Required if developer_mode is "1"
}

Example Responses

Successful Verification (Production Mode)

{
  "order_id": 1234,
  "order_item_id": 5678,
  "product_id": 910,
  "license_number": "LIC-00123",
  "order_status": "completed",
  "order_date": "2025-02-26 14:30:00",
  "billing_email": "[email protected]",
  "customer_id": 1112
}

Successful Verification (Developer Mode)

{
  "success": true,
  "message": "Developer testing license valid."
}

Error Responses

  • Missing API Key { "code": "missing_api_key", "message": "You must provide an API key.", "data": { "status": 403 } }
  • Missing Product Slug { "code": "missing_product_slug", "message": "You must provide a product slug.", "data": { "status": 403 } }
  • Missing Purchase Code { "code": "missing_purchase_code", "message": "You must provide a purchase code.", "data": { "status": 403 } }
  • Invalid API Key { "code": "invalid_api_key", "message": "Invalid API key.", "data": { "status": 403 } }
  • Invalid Purchase Code { "code": "invalid_purchase_code", "message": "The purchase code format is invalid or missing required order information.", "data": { "status": 400 } }
  • Order Not Available { "code": "order_not_available", "message": "The order has been refunded or is no longer available.", "data": { "status": 400 } }
  • Not Allowed (Product Ownership Mismatch) { "code": "not_allowed", "message": "You do not own this product", "data": { "status": 400 } }

5. Product Update Endpoint

Endpoint:
https://wpbay.com/api/update/v1/updates

HTTP Method:

  • POST

Purpose

The Product Update Endpoint is designed to:

  • Verify the validity of a purchase code and associated product information.
  • Authenticate the requesting user using an API key.
  • Determine whether a product update is available by comparing the client’s current version with the latest version info.
  • Support both standard (production) mode and a developer (sandbox) mode, allowing developers to test update scenarios using a dedicated testing purchase code.

On success, if an update is available (i.e., the current version is older than the latest version), the endpoint returns the update details (such as the new version, download path, and any additional version information). If no update is available, a message stating so is returned.

Request Parameters

Required Parameters (as declared in the route registration)

  • purchase_code
    • Type: String
    • Description: The unique purchase code identifying the product license.
    • Validation: Must be provided and is validated to be a string.
  • product_slug
    • Type: String
    • Description: A unique identifier for the product.
    • Validation: Must be provided and is validated to be a string.
  • product_id
    • Type: String
    • Description: The product’s WPBay ID.
    • Validation: Must be provided and is validated to be a string.
  • version
    • Type: String
    • Description: The current version of the product as installed on the client site.
    • Validation: Must be provided and is validated to be a string.
  • site_url
    • Type: String
    • Description: The URL of the site where the product is installed.
    • Validation: Must be provided and is sanitized using esc_url_raw.
  • product_type
    • Type: String
    • Description: The type or category of the product.
    • Validation: Must be provided and is validated to be a string.
  • api_key
    • Type: String
    • Description: The API key used for authenticating the request.
    • Validation: Must be provided and is validated to be a string.
  • developer_mode
    • Type: String (typically “0” or “1”)
    • Description: Activates developer (sandbox) mode when set to “1”. This mode allows testing with a dedicated testing purchase code.
  • secret_key
    • Type: String
    • Description: A secret key required to authorize developer mode requests.

Example Request

POST Request Example:

POST https://wpbay.com/api/update/v1/updates
Content-Type: application/json

{
  "purchase_code": "ABC123-XYZ789-DEF456",
  "product_slug": "MY_PRODUCT",
  "version": "1.0.0",
  "site_url": "https://example.com",
  "product_type": "plugin",
  "api_key": "your_api_key_here",
  "developer_mode": "0",        // Optional: "1" to activate developer mode
  "secret_key": ""              // Optional: Required if developer_mode is "1"
}

Example Responses

Update Available (Production Mode)

If the current version is older than the latest version, you might receive a response similar to:

{
  "new_version": "1.2.0",
  "download_url": "https://example.com/downloads/my_product_v1.2.0.zip",
  "changelog": "Bug fixes and performance improvements.",
  "release_date": "2025-03-01"
}

No Update Available

If the current version is up-to-date:

{
  "message": "No update available."
}

Developer Mode Successful Verification

For developer mode, if the testing purchase code is valid:

{
  "success": true,
  "message": "Developer testing license valid."
}

Error Responses

  • Missing API Key { "code": "missing_api_key", "message": "You must provide an API key.", "data": { "status": 403 } }
  • Invalid Purchase Code { "code": "invalid_code", "message": "The purchase code format is invalid or missing required data.", "data": { "status": 400 } }
  • Order Not Available { "code": "order_not_available", "message": "The order has been refunded or is no longer available.", "data": { "status": 400 } }
  • Product Ownership Mismatch { "code": "not_allowed", "message": "You do not own this product", "data": { "status": 400 } }
  • No Version Information { "code": "no_version_info", "message": "Could not retrieve version info.", "data": { "status": 500 } }

6. Product Info Endpoint

Endpoint:
https://wpbay.com/api/update/v1/info

HTTP Method:

  • POST

Purpose

The purpose of this endpoint is to:

  • Validate the provided purchase code and associated parameters.
  • Authenticate the requester via an API key.
  • Determine if the purchase code is valid and that the user is authorized to access the product information.
  • Return detailed product information which typically includes product metadata, update details, and other relevant information.

The endpoint supports two modes of operation:

  • Developer Mode (Sandbox): Allows developers to test using a designated testing purchase code. It verifies that the product slug is pre-registered in the developer’s metadata or that the developer is the owner of the product.
  • Standard Production Mode: Validates the purchase code structure, retrieves order details, confirms the order status, and checks that the product ownership matches the requester.

Request Parameters

Declared in Route Registration

  • purchase_code
    • Type: String
    • Description: The unique purchase code associated with the product license.
    • Validation: Required; must be a non-empty string.
  • product_slug
    • Type: String
    • Description: A unique identifier for the product, used to fetch product-specific information.
    • Validation: Required; must be a non-empty string.
  • product_id
    • Type: String
    • Description: WPBay product ID.
    • Validation: Required; must be a non-empty string.
  • site_url
    • Type: String
    • Description: The URL of the site where the product is installed.
    • Validation: Required; must be a non-empty string and is sanitized using esc_url_raw.
  • product_type
    • Type: String
    • Description: The category or type of the product (e.g., plugin, theme).
    • Validation: Required; must be a non-empty string.
  • api_key
    • Type: String
    • Description: The API key used for authenticating the request.
    • Validation: Required; must be a non-empty string.
  • developer_mode
    • Type: String (typically “0” or “1”)
    • Description: When set to “1”, activates developer (sandbox) mode. In this mode, the endpoint validates the testing purchase code against pre-registered product slugs.
  • secret_key
    • Type: String
    • Description: A secret key required to authenticate developer mode requests.

Example Request

POST Request Example:

POST https://wpbay.com/api/update/v1/info
Content-Type: application/json

{
  "purchase_code": "ABC123-XYZ789-DEF456",
  "product_slug": "MY_PRODUCT",
  "site_url": "https://example.com",
  "product_type": "plugin",
  "api_key": "your_api_key_here",
  "developer_mode": "0",         // Optional: "1" to activate developer mode
  "secret_key": ""               // Optional: Required if developer_mode is "1"
}

Example Responses

Successful Response

If the request is validated and the product information is retrieved successfully, the response might look like:

{
  "name": "My Product",
  "version": "1.2.0",
  "description": "A detailed description of My Product.",
  "changelog": "List of updates and improvements...",
  "download_url": "https://example.com/downloads/my_product_v1.2.0.zip",
  "author": "Product Author",
  "support_url": "https://example.com/support"
}

Error Responses

  • Missing API Key { "code": "missing_api_key", "message": "You must provide an API key.", "data": { "status": 403 } }
  • Invalid API Key { "code": "invalid_api_key", "message": "Invalid API key.", "data": { "status": 403 } }
  • Invalid Purchase Code { "code": "invalid_code", "message": "The purchase code format is invalid or missing required data.", "data": { "status": 400 } }
  • Order Not Available { "code": "order_not_available", "message": "The order has been refunded or is no longer available.", "data": { "status": 400 } }
  • Not Allowed (Product Ownership Mismatch) { "code": "not_allowed", "message": "You do not own this product", "data": { "status": 400 } }
  • No Product Information { "code": "no_product_info", "message": "Could not retrieve product info.", "data": { "status": 500 } }

7. Documentation Download Endpoint

Endpoint:
https://wpbay.com/api/update/v1/docs_download

HTTP Method:

  • GET

Purpose

The purpose of this endpoint is to provide secure access to product documentation downloads. It:

  • Retrieves the product based on the provided product ID.
  • Checks if the product exists.
  • Retrieves the documentation file path from the product’s metadata.
  • Serves the file directly using an internal file-serving function if available.

If any of these checks fail (e.g., if the product does not exist or no documentation is available), the endpoint returns an appropriate error message.

Request Parameters

Required Parameters

  • product_id
    • Type: Numeric
    • Description: The unique identifier of the product from which the documentation is to be downloaded.
    • Validation: Must be provided and is validated as a numeric value.

Processing Flow

  1. Product Retrieval:
    • The endpoint retrieves the product_id from the request.
    • If the product is not found, an error is returned.
  2. Documentation Path Retrieval:.
    • If the documentation path is empty or not set, an error is returned indicating that the documentation download is not available.
  3. File Serving:
    • The file is then served directly to the client, with appropriate HTTP headers for a file download.

Example Request

GET Request Example:

GET https://wpbay.com/api/update/v1/docs_download?product_id=123

Parameters:

  • product_id: 123

Example Responses

Successful Documentation Download

  • Behavior:
    If the product exists and the documentation file is available, the file is served directly to the client. The HTTP response will contain the file’s contents along with appropriate headers (such as Content-Type and Content-Disposition), prompting the user to download or open the file. There is no JSON response in this case.

Error Responses

  • Invalid Product { "code": "invalid_product", "message": "Invalid product.", "data": { "status": 403 } }
  • Documentation Not Available { "code": "no_download", "message": "Documentation download not available.", "data": { "status": 404 } }

8. Feedback Submit Endpoint

Endpoint:
https://wpbay.com/api/feedback/v1/submit

HTTP Methods Supported:

  • GET
  • POST

Purpose

The purpose of the Feedback Submit Endpoint is to allow users to submit feedback about a product. This feedback may include reasons for deactivation, issues, or suggestions for improvements. Key features include:

  • Authentication: Verifies the request via an API key and ensures the user owns the product.
  • Purchase Code Validation: Validates the purchase code structure and order details.
  • Product Ownership Verification: Confirms that the user submitting feedback is the owner of the product.
  • Feedback Storage: Inserts feedback details into a dedicated database table for future review.
  • Developer Mode Exclusion: If the feedback is submitted for a testing (developer mode) product slug or using a developer testing purchase code, the endpoint does not record the feedback.

Request Parameters

Required Parameters

  • purchase_code
    • Type: String
    • Description: The purchase code associated with the product license.
    • Validation: Must be provided and a non-empty string.
  • product_slug
    • Type: String
    • Description: A unique identifier for the product, used to verify product ownership and matching.
    • Validation: Must be provided and a non-empty string.
  • reason
    • Type: String
    • Description: A brief reason for submitting the feedback (e.g., why the product is being deactivated or issues encountered).
    • Validation: Required; must be provided as a string. If the reason exceeds 252 characters, it will be truncated.
  • site_url
    • Type: String
    • Description: The URL of the site where the product is installed.
    • Validation: Must be provided and is sanitized to ensure a valid URL.
  • api_key
    • Type: String
    • Description: The API key for authenticating the request.
    • Validation: Must be provided as a non-empty string.
  • details
    • Type: String
    • Description: Additional details or comments about the feedback.
    • Validation: Optional; if provided, must be a string.
  • developer_mode
    • Type: String (expected values: "0" or "1")
    • Description: Activates developer mode when set to "1". In this mode, feedback is not stored.
  • secret_key
    • Type: String
    • Description: A secret key used to validate developer mode requests.
    • Validation: Optional; required if developer_mode is "1".

Example Request

POST Request Example:

POST https://wpbay.com/api/feedback/v1/submit
Content-Type: application/json

{
  "purchase_code": "ABC123-XYZ789-DEF456",
  "product_slug": "MY_PRODUCT",
  "reason": "I encountered performance issues.",
  "details": "The product slows down the site under heavy load.",
  "site_url": "https://example.com",
  "api_key": "your_api_key_here",
  "developer_mode": "0",           // Optional: "1" for developer mode
  "secret_key": ""                 // Optional: Required if developer_mode is "1"
}

Example Responses

Successful Feedback Submission

{
  "success": true,
  "message": "Feedback successfully submitted."
}

Developer Mode or Testing Mode Feedback

  • Testing Mode:
    If the product slug is pre-registered as a testing mode slug: { "success": true, "message": "We don't record usage of testing mode slugs." }
  • Developer Mode:
    If the request is made in developer mode: { "success": true, "message": "Developer mode feedback is not stored." }

Error Responses

  • Missing API Key { "code": "missing_api_key", "message": "You must provide an API key.", "data": { "status": 403 } }
  • Invalid API Key { "code": "invalid_api_key", "message": "Invalid API key.", "data": { "status": 403 } }
  • Missing Purchase Code { "code": "missing_purchase_code", "message": "You must provide a purchase code.", "data": { "status": 403 } }
  • Missing Product Slug { "code": "missing_product_slug", "message": "You must provide a product slug.", "data": { "status": 400 } }
  • Missing Reason { "code": "missing_reason", "message": "You must provide a reason for deactivation.", "data": { "status": 400 } }
  • Invalid Purchase Code or Order Data { "code": "invalid_code", "message": "Invalid purchase code structure or order data.", "data": { "status": 400 } }
  • Order Not Available { "code": "order_not_available", "message": "The order has been refunded or is no longer available.", "data": { "status": 400 } }
  • Product Slug Mismatch { "code": "invalid_product_slug", "message": "Product slug does not match.", "data": { "status": 403 } }
  • Not Allowed (Ownership Mismatch) { "code": "not_allowed", "message": "You do not own this product.", "data": { "status": 400 } }
  • Database Error { "code": "db_error", "message": "Failed to store feedback in the database.", "data": { "status": 500 } }

9. Analytics Submit Endpoint

Endpoint:
https://wpbay.com/api/analytics/v1/submit

HTTP Methods Supported:

  • GET
  • POST

Purpose

The Analytics Submit Endpoint is designed to:

  • Collect Analytics Data: Accept an array of event data containing details such as event names, timestamps, WordPress version, PHP version, SDK version, and the active theme.
  • Authenticate and Validate: Ensure that the request is from an authenticated user who owns the licensed product by validating the API key, purchase code, and product slug.
  • Store Event Data: Insert each analytics event into the WPBay analytics database table for further analysis.
  • Developer Mode Handling: In developer mode, analytics events are not stored, allowing for testing without affecting production data.

Request Parameters

Declared in Route Registration

  • purchase_code
    • Type: String
    • Description: The unique purchase code for the licensed product.
    • Validation: Required; must be a non-empty string.
  • product_slug
    • Type: String
    • Description: A unique identifier for the product, used to confirm product ownership.
    • Validation: Required; must be a non-empty string.
  • events
    • Type: Array
    • Description: An array of event objects. Each event object should contain:
      • event_name (String)
      • timestamp (Numeric, Unix timestamp)
      • wp_version (String)
      • php_version (String)
      • sdk_version (String)
      • theme (String)
    • Validation: Required; must be an array.
  • site_url
    • Type: String
    • Description: The URL of the site where the product is installed.
    • Validation: Required; must be a non-empty string.
  • api_key
    • Type: String
    • Description: The API key used to authenticate the request.
    • Validation: Required; must be a non-empty string.
  • developer_mode
    • Type: String (expected values: "0" or "1")
    • Description: Activates developer mode when set to "1". In this mode, analytics events are not stored.
  • secret_key
    • Type: String
    • Description: A secret key required to validate developer mode requests.

Example Request

POST Request Example:

POST https://wpbay.com/api/analytics/v1/submit
Content-Type: application/json

{
  "purchase_code": "ABC123-XYZ789-DEF456",
  "product_slug": "MY_PRODUCT",
  "events": [
    {
      "event_name": "activation",
      "timestamp": 1677628800,
      "wp_version": "5.8",
      "php_version": "7.4",
      "sdk_version": "1.0.0",
      "theme": "Twenty Twenty-One"
    },
    {
      "event_name": "update_check",
      "timestamp": 1677715200,
      "wp_version": "5.8",
      "php_version": "7.4",
      "sdk_version": "1.0.0",
      "theme": "Twenty Twenty-One"
    }
  ],
  "site_url": "https://example.com",
  "api_key": "your_api_key_here",
  "developer_mode": "0",         // Optional: "1" for developer mode
  "secret_key": ""               // Optional: Required if developer_mode is "1"
}

Example Responses

Successful Analytics Submission

{
  "success": true,
  "message": "Analytics events successfully submitted."
}

Developer Mode Analytics

If the request is made in developer mode:

{
  "success": true,
  "message": "Developer mode analytics data is not stored."
}

Error Responses

  • Missing API Key { "code": "missing_api_key", "message": "You must provide an API key.", "data": { "status": 403 } }
  • Invalid API Key { "code": "invalid_api_key", "message": "Invalid API key.", "data": { "status": 403 } }
  • Missing Purchase Code { "code": "missing_purchase_code", "message": "You must provide a purchase code.", "data": { "status": 403 } }
  • Missing Product Slug { "code": "missing_product_slug", "message": "You must provide a product slug.", "data": { "status": 400 } }
  • Missing Events Data { "code": "missing_events", "message": "You must provide event data.", "data": { "status": 400 } }
  • Missing Site URL { "code": "missing_site_url", "message": "You must provide a site URL.", "data": { "status": 400 } }
  • Invalid Purchase Code Structure or Order Data { "code": "invalid_code", "message": "Invalid purchase code structure or order data.", "data": { "status": 400 } }
  • Product Slug Mismatch { "code": "invalid_product_slug", "message": "Product slug does not match.", "data": { "status": 403 } }
  • Not Allowed (Ownership Mismatch) { "code": "not_allowed", "message": "You do not own this product.", "data": { "status": 400 } }
  • Database Error { "code": "db_error", "message": "Failed to store some analytics events in the database.", "data": { "status": 500 } }

10. Upgrade List Endpoint

Endpoint:
https://wpbay.com/api/upgrade/v1/list

HTTP Method:

  • POST

Purpose

The Upgrade List Endpoint provides a list of available upgrade options for a given product. It works by:

  • Retrieving the Base Product: Using details by product ID.
  • Formatting Upgrade Options: Constructing a list of upgrade options with details such as the upgrade ID, pricing, subscription period, and additional attributes (e.g., license count and plan type).
  • Returning the Data: If one or more upgrade options exist, they are returned in a structured JSON response; otherwise, an error is returned.

Request Parameters

Required Parameters

  • product_id
    • Type: Numeric
    • Description: The unique identifier of the product for which upgrade options are to be listed.
    • Validation: Must be numeric.
  • api_key
    • Type: String
    • Description: The API key used to authenticate the request.
    • Validation: Must be a non-empty string.

Example Request

POST Request Example:

POST https://wpbay.com/api/upgrade/v1/list
Content-Type: application/json

{
  "product_id": 123,
  "api_key": "your_api_key_here"
}

Example Responses

Successful Response

If upgrade options are available, the response might look like:

{
  "success": true,
  "data": [
    {
      "id": 456,
      "name": "Monthly Access",
      "payment_price": "20",
      "display_price": "20$ / Monthtly",
      "subscription_price": "20",
      "one_time_fee": "0",
      "subscription_interval": "1",
      "subscription": "Monthtly",
      "license_count": "1",
      "plan_type": "basic"
    },
    {
      "id": 457,
      "name": "Yearly Access",
      "payment_price": "200",
      "display_price": "200$ / Yearly",
      "subscription_price": "200",
      "one_time_fee": "0",
      "subscription_interval": "1",
      "subscription": "Yearly",
      "license_count": "1",
      "plan_type": "premium"
    }
  ]
}

Error Response

If no upgrade options are found:

{
  "code": "no_upgrades_found",
  "message": "No upgrade options available.",
  "data": { "status": 404 }
}

Or if the product ID is invalid:

{
  "code": "invalid_product_id",
  "message": "Invalid product ID.",
  "data": { "status": 404 }
}

11. Contact Form Submission Endpoint

Endpoint:
https://wpbay.com/api/contact/v1/submit

HTTP Method:

  • POST

Purpose

The Contact Form Submission Endpoint enables users to send contact form messages about a product. The endpoint:

  • Validates Input: Ensures that all required fields (API key, product slug, first name, last name, email, request type, summary, and message) are provided.
  • Authenticates the Request: Verifies the API key to confirm the identity of the sender.
  • Verifies Product Ownership: Attempts to locate the product using the provided product slug. If not found in published products, it checks against pre-registered testing slugs.
  • Email Routing: Retrieves the email address of the product author and sends an email containing the submitted contact information and message.
  • Provides Feedback: Returns a success message if the email is sent; otherwise, it returns an error.

Request Parameters

Required Parameters

  • api_key
    • Type: String
    • Description: API key for authenticating the request.
  • product_slug
    • Type: String
    • Description: Unique slug identifier of the product. Used to verify product ownership.
  • first_name
    • Type: String
    • Description: Sender’s first name.
  • last_name
    • Type: String
    • Description: Sender’s last name.
  • email
    • Type: String (email)
    • Description: Sender’s email address. Must be a valid email.
  • request_type
    • Type: String
    • Description: Type of request (e.g., inquiry, support, feedback).
  • summary
    • Type: String
    • Description: A brief subject or summary of the request.
  • message
    • Type: String
    • Description: Detailed message content.

Example Request

POST Request Example:

POST https://wpbay.com/api/contact/v1/submit
Content-Type: application/json

{
  "api_key": "your_api_key_here",
  "product_slug": "MY_PRODUCT",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "request_type": "Support",
  "summary": "Issue with product activation",
  "message": "I am experiencing difficulties activating the product on my site. Please advise."
}

Example Responses

Successful Response

{
  "success": true,
  "message": "Your message has been sent successfully."
}

Error Responses

  • Missing Fields: { "code": "missing_fields", "message": "All fields are required.", "data": { "status": 400 } }
  • Invalid API Key: { "code": "invalid_api_key", "message": "Invalid API key.", "data": { "status": 403 } }
  • Invalid Product Slug: { "code": "invalid_product_slug", "message": "Invalid product slug.", "data": { "status": 400 } }
  • Invalid Author: { "code": "invalid_author", "message": "Product author not found.", "data": { "status": 400 } }
  • Email Failed: { "code": "email_failed", "message": "Failed to send email.", "data": { "status": 500 } }