DOCSEARCHbyAlgolia
Submit Docs

Lightfunnels GraphQL API Documentation

website·Indexed 34 days ago

https://developer.lightfunnels.com/

Developer documentation for the Lightfunnels GraphQL API, providing guides and endpoint references for managing funnels, products, orders, customers, bundles, and collections. Includes detailed information on authentication, authorization scopes, webhooks, pagination, and the development of embedded apps and app charges.

Tokens
23K
Snippets
168
Records
205
Agent score
56%

What's inside Lightfunnels

  1. Manage account alerts and alert types

    The Alert type provides information about system notifications sent to the account. Each alert contains a unique identifier (id, uid), timestamps, and a type defined by the AlertType enum.
    enum AlertType {
  FIRST_SELL
  FUNNEL_BUILDER_TOUR
  PAGE_BUILDER_TOUR
  BADGE_ACQUIRED
  ACHIEVEMENT
  FAKE_PRICE_RED_FLAG
  FAKE_PRICE_WARNING
  ACCOUNT_SETUP
  ONBOARDING
  CREATE_STORE
  ADD_STORE_PRODUCT
}

  2. Handle product files and tags

    Products can be associated with File and Tag objects. The File type provides metadata about uploaded assets (path, key, size), while the Tag type provides a simple title for product categorization.

  3. Query product details using the Product type

    The Product type is used to retrieve comprehensive details about a product. Key fields include basic identification (id, _id, uid), pricing (price, compare_at_price), content (title, slug, description), and associations like variants, options, images, and reviews.
    query productsQuery($first: Int, $after: String, $query: String!){
	products(query: "order_by:id order_dir:desc", after: "WzVE4OTA5LDEe/4OTA5XQ==", first: 10){
		edges{
			node{
				id
				_id
				title
				price
				thumbnail{
					path(version: version1)
				}
				created_at
				# Add other desired Product fields here
			}
		}
	}
}

  4. Access customer client and device details

    The ClientDetails type provides information about the device and browser the customer used to place the order, including their IP address.
    type ClientDetails {
  ip: String!
  device: String
  user_agent: String
}

  5. Understand how Lightfunnels embeds apps

    When a merchant opens your app from the Lightfunnels admin, it is loaded inside an iframe. Lightfunnels provides context via URL query parameters. These parameters are hints and are not signed; they must not be used as credentials to grant access. Authentication must still be handled via OAuth.
    https://yourapp.com/?account_id={{account_uid}}&iframe=true

  6. Reference account integrations

    The Integration type provides details about third-party platforms connected to the account.
    type Integration implements Node {
	id: ID!
	platform: String!
	label: String!
	details: IntegrationDetails
}

scalar IntegrationDetails

  7. Understand Lightfunnels app charging constraints

    When implementing charges for Lightfunnels apps, keep the following constraints and recommendations in mind:

    • One Active Charge: An app can have only one active charge per user account at any given time.
    • Automatic Deactivation: Activating a new charge automatically deactivates any previous charges associated with that user's account.
    • Free Trials: It is highly recommended to include a free trial period to improve the user experience.

  8. Authenticate requests using Lightfunnels OAuth2

    Lightfunnels uses the OAuth2 protocol to protect private resources. To interact with the API, your application must obtain a unique access token for each account it accesses. This token identifies the account and determines the allowed actions based on the granted scopes. The access token is permanent and should be stored securely in your database for use in all subsequent API requests.

  9. Order object fields reference

    The Order object contains comprehensive details about a customer's purchase, including financial totals, customer information, and tracking metadata. All monetary values are expressed as floating-point numbers in the order's currency.

  10. Fetch subsequent pages of data

    To retrieve the next page of results, follow this continuation logic:

    1. Check the hasNextPage boolean in the pageInfo object of the current response. If false, stop fetching.
    2. If true, extract the endCursor from the pageInfo object.
    3. Execute the next query, passing the endCursor value into the after parameter.
    {
  "query": "...",
  "variables": {
    "query": "order_by:id order_dir:desc",
    "first": 25,
    "after": "[endCursor from previous response]"
  }
}

  11. Troubleshoot and manage Lightfunnels OAuth tokens

    Keep the following constraints and security requirements in mind when implementing authentication:

    • One-time use: The authorization code is valid for a single use. If a request fails or you need to re-test, the user must go through the consent screen again.
    • Secret Security: The client_secret is private and must never be exposed in client-side code or shared.
    • Token Persistence: Access tokens are permanent; store them in your database to avoid repeated authorization flows.

  12. Exchange authorization code for an access token

    After a user accepts permissions, Lightfunnels redirects them to your redirect_uri with an authorization code in the query string. To exchange this code for a permanent access token, send a POST request to https://api.lightfunnels.com/oauth/access_token with a JSON body containing your client_id, client_secret, and the received code.
    const getOAuthToken = async () => {
  const clientId = 'client_id';
  const clientSecret = 'client_secret';
  const tokenUrl = 'https://api.lightfunnels.com/oauth/access_token';

  try {
    const response = await fetch(tokenUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        client_id: clientId,
        client_secret: clientSecret,
        code: 'the authorization code from the query string'
      })
    });

    if (!response.ok) {
      throw new Error(`Error: ${response.status} ${response.statusText}`);
    }

    const data = await response.json();
    return data.access_token;
  } catch (error) {
    console.error('OAuth request failed:', error);
    return null;
  }
};