Modules

Overview

The Pelcro JavaScript SDK exposes modules on the global window.Pelcro object. Each module provides methods for interacting with specific Pelcro platform features.

All async methods use the callback pattern: (error, data) => {}. On success, error is null and data contains the response. On failure, error contains the error object and data is null.

Pelcro.user.login({ email: "[email protected]", password: "secret" }, (err, data) => {
  if (err) { console.error("Failed:", err); return; }
  console.log("Success:", data);
});

Initialization

Modules become available after the SDK loads. Use boot events to guarantee access:

document.addEventListener("PelcroSiteLoaded", () => {
  const site = Pelcro.site.read();
});

document.addEventListener("PelcroBootComplete", () => {
  if (Pelcro.user.isAuthenticated()) {
    const user = Pelcro.user.read();
  }
});

Site

Provides access to site configuration and settings loaded during SDK initialization.

read

Pelcro.site.read()

Returns the cached site configuration object.

• Returns: Object - Site configuration including products, plans, settings, and paywall rules.

getById

Pelcro.site.getById(callback)

Fetches site configuration from the API. Called automatically during boot.

User

Handles user authentication, registration, profile management, and session state.

read

Pelcro.user.read()

Returns the cached user object.

• Returns: Object - The current user data including id, email, auth_token, subscriptions, addresses, invoices, etc.

isAuthenticated

Pelcro.user.isAuthenticated()

Checks whether a user is currently logged in.

• Returns: Boolean

register

Pelcro.user.register(options, callback)

Registers a new user account.

Events fired: PelcroUserRegistered, PelcroUserLoaded

login

Pelcro.user.login(options, callback)

Authenticates a user with email and password.

Events fired: PelcroUserLoggedIn (with loginType: "email"), PelcroUserLoaded

idpLogin

Pelcro.user.idpLogin(options, callback)

Authenticates a user via an Identity Provider (Google, Facebook, etc.).

Events fired: PelcroUserLoggedIn (with loginType: "IDP"), PelcroUserLoaded

authenticate

Pelcro.user.authenticate(callback)

Re-authenticates the current session using the stored auth token. Called automatically during boot if a token exists.

Events fired: PelcroUserLoggedIn, PelcroUserLoaded

logout

Pelcro.user.logout()

Logs out the current user by clearing the auth token and resetting user state.

Events fired: PelcroUserLogout

update

Pelcro.user.update(options, callback)

Updates the current user profile.

Events fired: PelcroUserUpdated

convert

Pelcro.user.convert(options, callback)

Converts a guest/anonymous user into a registered user by setting a password.

uploadProfilePicture

Pelcro.user.uploadProfilePicture(options, callback)

Uploads a profile picture for the current user.

removeProfilePicture

Pelcro.user.removeProfilePicture(options, callback)

Removes the current user profile picture.

saveToMetaData

Pelcro.user.saveToMetaData(options, callback)

Saves a key-value pair to the user metadata. The key is stored with a metadata_ prefix.

Events fired: PelcroMetadataUpdated

isEntitledTo

Pelcro.user.isEntitledTo(entitlement)

Checks if the user is entitled to a specific content entitlement through their subscriptions.

• Returns: Boolean

hasOrdered

Pelcro.user.hasOrdered()

Checks if the user has any ecommerce orders.

• Returns: Boolean

resendEmailVerification

Pelcro.user.resendEmailVerification(options, callback)

Resends the email verification link.

verifyEmailToken

Pelcro.user.verifyEmailToken(options, callback)

Verifies the user email using the token from the verification link.

requestLoginToken

Pelcro.user.requestLoginToken(options, callback)

Requests a passwordless login token sent to the user email.

verifyLoginToken

Pelcro.user.verifyLoginToken(options, callback)

Verifies a passwordless login token.

location

Pelcro.user.location

Object containing the user detected location: countryCode, countryName, regionCode, city.

Location

Provides IP-based geolocation with session caching.

get

Pelcro.user.location.get(callback)

Fetches the user location from the API. Caches the result in session storage.

Paywall

Controls paywall display, metering, and content restriction logic.

read

Pelcro.paywall.read()

Returns the active paywall configuration for the current page context.

• Returns: Object|null

getProduct

Pelcro.paywall.getProduct()

Returns the product whose paywall rules target the current user and page.

• Returns: Object|null

freeVisitsLeft

Pelcro.paywall.freeVisitsLeft()

Calculates the number of free article views remaining in the current metering period.

• Returns: Number|null

displayPaywall

Pelcro.paywall.displayPaywall(dispatchEvent)

Determines whether the paywall should be displayed. Optionally dispatches PelcroPaywallDisplayed or PelcroPaywallNotDisplayed.

• Returns: Boolean

displayMeterPaywall

Pelcro.paywall.displayMeterPaywall()

Checks if a meter paywall should display. Increments the page view counter before checking.

• Returns: Boolean

displayNewsletterPaywall

Pelcro.paywall.displayNewsletterPaywall()

Checks if a newsletter signup paywall should display.

• Returns: Boolean

isArticleRestricted

Pelcro.paywall.isArticleRestricted()

Determines whether the current article is restricted from the user based on their subscription tags, entitlements, and paywall metatags.

• Returns: Boolean

Subscription

Manages the full subscription lifecycle - creation, cancellation, renewal, and plan changes.

create

Pelcro.subscription.create(options, callback)

Creates a new subscription.

Events fired: PelcroSubscriptionCreated

cancel

Pelcro.subscription.cancel(options, callback)

Cancels a subscription.

Events fired: PelcroSubscriptionCanceled (detail includes canceledSubscriptionId)

reactivate

Pelcro.subscription.reactivate(options, callback)

Reactivates a canceled subscription.

Events fired: PelcroSubscriptionReactivated

renew

Pelcro.subscription.renew(options, callback)

Renews an expired subscription.

Events fired: PelcroSubscriptionRenewed

renewGift

Pelcro.subscription.renewGift(options, callback)

Renews a gift subscription.

Note: This method does not fire PelcroSubscriptionRenewed. Only renew() dispatches that event.

change

Pelcro.subscription.change(options, callback)

Changes a subscription to a different plan.

Note: This method does not dispatch any events.

update

Pelcro.subscription.update(options, callback)

Updates subscription properties (suspension, domains, metadata).

Events fired: PelcroSubscriptionUpdated

redeemGift

Pelcro.subscription.redeemGift(options, callback)

Redeems a gift subscription using a gift code.

Events fired: PelcroGiftRedeemed

list

Pelcro.subscription.list()

Returns the current user subscriptions.

• Returns: Array

isSubscribedToSite

Pelcro.subscription.isSubscribedToSite()

Checks if the user has any active non-donation subscription for the current site.

• Returns: Boolean

isSubscribedToPlan

Pelcro.subscription.isSubscribedToPlan(plan)

Checks if the user is subscribed to a specific plan.

• Returns: Boolean

listMembers

Pelcro.subscription.listMembers(options, callback)

Lists members of a group subscription.

inviteMembers

Pelcro.subscription.inviteMembers(options, callback)

Invites members to a group subscription by email.

removeMember

Pelcro.subscription.removeMember(options, callback)

Removes a member from a group subscription.

Plan

Provides plan lookup by ID, IP address, or email domain.

getById

Pelcro.plan.getById(id)

Returns a plan by its ID from the cached product/plan data.

• Returns: Object|null

getPlan

Pelcro.plan.getPlan(options, callback)

Fetches a plan from the API by ID.

getByIP

Pelcro.plan.getByIP(callback)

Returns plans associated with the user IP address. Results are cached in session storage.

getByEmail

Pelcro.plan.getByEmail(options, callback)

Returns plans associated with a user email domain.

Membership

Manages membership-based access control via IP or email domain.

getByIP

Pelcro.membership.getByIP(callback)

Returns memberships associated with the user IP address. Cached in session storage.

getByEmail

Pelcro.membership.getByEmail(options, callback)

Returns memberships associated with a user email domain.

update

Pelcro.membership.update(options, callback)

Updates a membership subscription member address.

Payment Source (Legacy)

Manages legacy Stripe payment sources. For newer integrations, use Payment Method instead.

create

Pelcro.paymentSource.create(options, callback)

Creates a new payment source.

Events fired: PelcroSourceCreated

update

Pelcro.paymentSource.update(options, callback)

Updates a payment source expiration date.

Events fired: PelcroSourceUpdated

Payment Method

Manages payment methods (cards, ACH, wallets) via the modern Payment Methods API.

create

Pelcro.paymentMethod.create(options, callback)

Creates a new payment method.

Events fired: PelcroPaymentMethodCreated

update

Pelcro.paymentMethod.update(options, callback)

Updates a payment method.

Events fired: PelcroPaymentMethodUpdated

list

Pelcro.paymentMethod.list(options, callback)

Lists all payment methods for the current user.

getPaymentMethod

Pelcro.paymentMethod.getPaymentMethod(options, callback)

Retrieves a specific payment method by ID.

deletePaymentMethod

Pelcro.paymentMethod.deletePaymentMethod(options, callback)

Deletes a payment method.

Events fired: PelcroPaymentMethodDeleted

verifyACH

Pelcro.paymentMethod.verifyACH(options, callback)

Verifies an ACH bank account using a micro-deposit verification code.

Events fired: PelcroPaymentMethodUpdated

Invoice

Provides access to user invoices and invoice payment.

list

Pelcro.invoice.list()

Returns the current user invoices from cached data.

• Returns: Array

pay

Pelcro.invoice.pay(options, callback)

Pays an outstanding invoice.

Events fired: PelcroInvoicePaid

Coupon

Utility for extracting coupon codes from URLs.

getFromUrl

Pelcro.coupon.getFromUrl()

Extracts the coupon_code query parameter from the current page URL.

• Returns: String|null

// URL: https://example.com/subscribe?coupon_code=SAVE20
const code = Pelcro.coupon.getFromUrl(); // "SAVE20"

Ecommerce

Manages ecommerce products, SKUs, and order creation.

list

Pelcro.ecommerce.products.list(callback)

Fetches all ecommerce products for the current site.

Events fired: PelcroEcommerceProductsLoaded

read

Pelcro.ecommerce.products.read()

Returns the cached ecommerce products.

getByProductId

Pelcro.ecommerce.products.getByProductId(id)

Finds an ecommerce product by its ID.

getBySkuId

Pelcro.ecommerce.products.getBySkuId(skuId)

Finds a specific SKU by its ID across all cached products.

getSkus

Pelcro.ecommerce.products.getSkus()

Returns all SKUs, filtered by user currency if set.

create

Pelcro.ecommerce.order.create(options, callback)

Creates an ecommerce order.

Events fired: PelcroEcommerceOrderCreated

createSummary

Pelcro.ecommerce.order.createSummary(options, callback)

Creates an order summary (price preview) without charging.

Product

Provides access to the site subscription products and plans with filtering by currency, country, language, and entitlements.

list

Pelcro.product.list()

Returns products filtered by user currency, country, and page language.

listByTarget

Pelcro.product.listByTarget()

Returns products whose paywall targeting rules match the current user and page.

getById

Pelcro.product.getById(id)

Returns a product by its ID.

getByEntitlements

Pelcro.product.getByEntitlements(entitlements)

Returns products that match any of the specified entitlements.

getByMatchingPageTags

Pelcro.product.getByMatchingPageTags()

Returns products whose paywall tags match the current page Open Graph article tags.

Order

Creates subscription order summaries for price previews.

create

Pelcro.order.create(options, callback)

Creates a subscription order summary (not an ecommerce order).

Address

Manages user shipping and billing addresses.

list

Pelcro.address.list()

Returns the current user addresses.

create

Pelcro.address.create(options, callback)

Creates a new address.

Events fired: PelcroAddressCreated

update

Pelcro.address.update(options, callback)

Updates an existing address.

Events fired: PelcroAddressUpdated

Password

Handles password reset flows and password updates.

forgot

Pelcro.password.forgot(options, callback)

Sends a password reset email.

Events fired: PelcroPasswordForgot

reset

Pelcro.password.reset(options, callback)

Resets the user password using a reset token.

Events fired: PelcroPasswordReset

update

Pelcro.password.update(options, callback)

Updates the current user password. Automatically logs the user out after success.

Events fired: PelcroPasswordUpdated, then triggers Pelcro.user.logout()

Newsletter

Manages newsletter subscriptions independently of user accounts.

create

Pelcro.newsletter.create(options, callback)

Creates a new newsletter subscription.

Events fired: PelcroNewsletterCreated

getByEmail

Pelcro.newsletter.getByEmail(email, callback)

Gets newsletter subscription data for an email address.

update

Pelcro.newsletter.update(options, callback)

Updates an existing newsletter subscription.

isSubscribedToNewsletter

Pelcro.newsletter.isSubscribedToNewsletter()

Checks if the current browser has an active newsletter subscription (via cookie).

• Returns: Boolean

Campaign

Retrieves campaign information for marketing and promotional flows.

getByID

Pelcro.campaign.getByID(options, callback)

Fetches a campaign by its numeric ID.

getByKey

Pelcro.campaign.getByKey(options, callback)

Fetches a campaign by its unique key.

Insight

Tracks user analytics events via the Pelcro analytics pipeline.

track

Pelcro.insight.track(eventName, extraProperties)

Sends a custom analytics event.

• Returns: Promise<Boolean> - Resolves to true on success.

Pelcro.insight.track("Subscribed", { plan_id: 123, method: "sdk" });

The SDK automatically tracks certain events internally (subscriptions, newsletter signups, page views for authenticated users). Use this method for custom tracking.

Integrations

Accessed via window.Pelcro.integrations.

getToken

Pelcro.integrations.disqus.getToken(callback)

Retrieves Disqus SSO authentication credentials for the current user. The user must be authenticated.

• Callback: (error, response)
  • response.data.disqus_auth_key - SSO auth key
  • response.data.disqus_public_key - Disqus public key

Pelcro.integrations.disqus.getToken((error, response) => {
  if (error) {
    return console.log("error", error.message);
  }

  const { disqus_auth_key, disqus_public_key } = response.data;
  console.log("disqus_auth_key", disqus_auth_key);
  console.log("disqus_public_key", disqus_public_key);
});