window.postscript

When the SDK is installed properly, you should be able to reference it using window.postscript.

window.postscript.identify

Identifies a subscriber on your site.

Usage:

window.postscript.identify({
  phone: "555-555-5555"
});

Payload	Description
`{ "phone": "555-555-5555" }`	A JSON payload object to use to identify the subscriber. It must have a `phone` field to look the subscriber up by.

Returns result indicating whether or not a subscriber was found and if so, that they were cookied.

window.postscript.getSubscriberId

Returns a Postscript Subscriber ID if found.

Usage:

window.postscript.getSubscriberId();

window.postscript.event

Fires an event for a subscriber.

Usage:

window.postscript.event('event_name', payload);

Supported Events

Event Name	Description
`page_view`	Fires an event for Subscriber Viewed Product. For use in "Subscriber Viewed Product" automations (i.e. Browse Abandonment).
`add_to_cart`	Fires an event for Product Added to Cart. For use in "Product Added to Cart" automations (i.e. Browse Abandonment).

Payload Properties

Property	Description	Example
`shop_id`	Your Postscript shop_id for your account.	123456
`url`	The URL of the page the event occurred on. This must be a full URL, not a relative URL, including the full domain.	<https://example.myshopify.com/products/red-shoes>
`search_params`	An object representing the query parameters on the current URL.	`{ "variant" : "1935013205" }`
`page_type`	The type of page that the event occurred on.	product
`referrer`	The referrer for the current page. This can be `document.referrer` for most integrations.	<https://example.myshopify.com/collections/shoes>
`resource`	An object representing the product data. See properties below.
`resource.category`	The product type of the current product being viewed or added to cart.	Shoes
`resource.product_title`	The title of the current product.	Basketball Sneakers
`resource.variant_title`	The title of the current variant. If no variant is selected provide first in stock variant title.	Black / 12
`resource.price_in_cents`	The price of the product in cents	6500
`resource.resource_id`	The id of the product	9250252
`resource.resource_type`	This will always be "product"	product
`resource.sku`	The SKU of the current variant being viewed or added to cart, if available.	AF1RED-12
`resource.variant_id`	The SKU of the current variant being viewed or added to cart.	1935013205
`resource.vendor`	The vendor of the product.	Nike

Example Payload

{  
    "shop_id": "123456",  
    "url": "https://example.myshopify.com/products/antique-drawers",  
    "search_params": {  
	    "variant": "123456789"  
	  },  
    "page_type": "product",  
    "referrer": "https://example.myshopify.com/collections/all",  
    "resource": {  
        "category": "Indoor",  
        "product_title" : "Antique Drawers",
        "variant_title" : "60in x 30in",
        "price_in_cents": 25000,  
        "resource_id": 123456789,  
        "resource_type": "product",  
        "sku": null,  
        "variant_id": 987654321,  
        "vendor": "Company 123"  
    }  
}

window.postscript.popups.open

Opens a specified popup programmatically.

Usage:

window.postscript.popups.open(popupId, options);

Parameters

popupId (required): The ID of the popup to open.
options (optional): Configuration for when and how the popup is fired.

Options Properties

Property	Type	Description	Default
`activePopupBehavior`	string	Controls what happens to the currently open popup if a second popup is programmatically triggered. Possible values: `ALWAYS_DISMISS`, `NEVER_DISMISS`, `DISMISS_WHEN_SOFT_CLOSED`.	`ALWAYS_DISMISS`
`respectPopupStatus`	boolean	Determines if the popup respects the status cookie. If `true`, popups previously dismissed won't show again (or will show in the close bubble if soft closed). If `false`, the popup will open regardless of any prior dismissals.	`true`

`activePopupBehavior` Values

ALWAYS_DISMISS: The first popup will be closed, and the programmatic popup will open.
NEVER_DISMISS: The first popup stays open, and the programmatic trigger is ignored.
DISMISS_WHEN_SOFT_CLOSED: The programmatic popup only opens if the first popup was in the close bubble state.

Example

window.postscript.popups.open(123456, {
  activePopupBehavior: 'ALWAYS_DISMISS',
  respectPopupStatus: false
});

window.postscript.popups.find

Finds the most appropriate popup to display based on the current page, user, and other criteria.

Usage:

window.postscript.popups.find(options);

Parameters

options (optional): Criteria used to determine the best popup to show.

Options Properties

Property	Type	Description	Default
`type`	string	Filters results by popup type (`legacy` or `standard`).	`undefined` (returns all)
`triggerType`	string	Filters by trigger type (`Custom` or `Delay`).	`Custom`
`respectPage`	boolean	If `true`, only considers popups allowed on the current page.	`true`
`respectSubscriber`	boolean	If `true`, only considers popups allowed for current subscriber status.	`true`
`respectCountry`	boolean	If `true`, only considers popups allowed in the user's country.	`true`
`respectPlatform`	boolean	If `true`, only considers popups allowed on the current platform.	`true`
`respectStatus`	boolean	If `true`, only considers popups that have not been hard closed.	`true`

Returns

A Promise resolving to the best popup’s ID (number or string) if found, or undefined if no matching popup is available.

Example

window.postscript.popups.find({
  triggerType: 'Custom',
  respectPage: true,
  respectSubscriber: true,
  respectCountry: true,
  respectPlatform: true,
  respectStatus: true
}).then((popupId) => {
  if (popupId) {
    window.postscript.popups.open(popupId);
  }
});

Examples

Show popup on element click

function initializePopup() {
    if (!window.postscript || typeof window.postscript !== "object" ||
        typeof window.postscript.popups?.find !== "function" ||
        typeof window.postscript.popups?.open !== "function") {
        return; // Postscript SDK isn't fully ready
    }

    // Find the best popup to show
    window.postscript.popups.find().then((popupId) => {
        if (!popupId) return;

        function attachClickEvent(button) {
            button.addEventListener("click", function() {
                window.postscript.popups.open(popupId);
            });
        }

        let button = document.getElementById("my_button");

        if (button) {
            attachClickEvent(button);
        } else {
            // Wait for the button to be added to the DOM
            const observer = new MutationObserver((mutations, obs) => {
                button = document.getElementById("my_button");
                if (button) {
                    attachClickEvent(button);
                    obs.disconnect(); // Stop observing once button is found
                }
            });

            observer.observe(document.body, { childList: true, subtree: true });
        }
    });
}

// Check if Postscript SDK is already available
if (window.postscript && typeof window.postscript === "object" &&
    typeof window.postscript.popups?.find === "function" &&
    typeof window.postscript.popups?.open === "function") {
    initializePopup();
} else {
    // Wait for Postscript to be ready
    window.addEventListener("postscriptReady", initializePopup);
}

window.postscript

window.postscript.identify

Usage:

window.postscript.getSubscriberId

Usage:

window.postscript.event

Usage:

Supported Events

Payload Properties

Example Payload

window.postscript.popups.open

Usage:

Parameters

Options Properties

activePopupBehavior Values

Example

window.postscript.popups.find

Usage:

Parameters

Options Properties

Returns

Example

Examples

Show popup on element click

`activePopupBehavior` Values