This is a tutorial for developers/maintainers of the web page that explains how to integrate Printful Embedded Design Maker in a website.

General workflow how to integrate Printful Design Maker in your website:

1. Register your app in https://developers.printful.com and create authentication tokens to be able to access Printful resources.

2. Authenticate from your app by calling API endpoints with these tokens to gather all needed data for Printful Design Maker.

3. Include our JS file in your website and create Printful Design Maker instance.

4. Get list of created designs, generate mockups and create orders from your website by calling Printful API endpoints.

Printful Developers portal is the place where you can setup OAuth access tokens to be able to access Printful resources.

Log in Printful Developers portal using your Printful login credentials.

You need a private OAuth access token to call most Printful API endpoints.

• To create an access token click on "Add new token" button in the "Tokens" section.
• Set the name, contact info and expiration date of the token.
• Set access level depending on your needs - choose "Account (all stores)" to grant access for an account (all stores) or limit the access level to a single selected store.
• Select scopes for the private token.

See detailed info in the Authentication section of Printful Developers portal to get more info about the scopes and access levels.

To work with Embedded Design Maker, you will need at least one token with "Embedded Designer" extension. You will use this token to get the Nonce token that is needed to open Printful Design Maker instance.

In the "Extensions" section there should be a checkbox "Embedded Design Maker" - once you check it - The access level and Scopes section will set up automatically with the needed values for Embedded Design Maker.

Important - for the Embedded Desing Maker please create 2 separate private tokens for different purposes:

• For development purposes, implementation, testing of new features and products:
  • Private token with the Embedd Desing Maker and “development purposes only” selected.
• For the live environment and production usage please use:
  • Private token with only the Embedd Desing Maker extension selected

If you need additional Scopes for the token, to call some other API endpoints that need additional scopes, you can check them as well and have a single token for multiple needs, but it is possible to create a new token for every single API endpoint as well. More info on what scopes are needed for each endpoint can be found in the Embedded designer related API calls section.

Note - once the token is created the scopes list is fixed and cannot be edited. We suggest to enable all available scopes for the token.

To ensure that Printful will only listen to messages that comes from your domain names and ignore all other, enter your domain name in the "Domains" section.

To get the Nonce token which is used to access the designer iframe session for a specific template, send a POST request authenticated by the access token with the "Embedded Designer" extension to the following endpoint: https://api.printful.com/embedded-designer/nonces.

The endpoint accepts a JSON object with following fields:

The ip_address and user_agent fields may be used to limit the usage of the nonce. If they are present and not null, only a request with a matching IP address/User agent will be permitted with the given nonce.

The response will be a JSON object with a following structure:

{
    "code": 200,
    "result": {
        "nonce": Nonce
    }
}

The Nonce object fields are described in the following table:

The endpoint generation request should be done from the back-end, to not expose the access token to the users.

The nonce will be used to authenticate the iframe session and all actions done in the embedded designer session. With each usage of the nonce, its duration will be extended.

Generating a new nonce for a given external product ID will invalidate the previous nonces generated for the same external product ID.

Saving the template will also invalidate the nonce. To edit the template, a new nonce will need to be generated.

To open the Embedded DesignMaker and create new Embedded template you have to follow these steps.

First thing you need is to include file embed.js in your website. This file contains the Embedded Design Maker Manager PFDesignMaker class definition.
You need to use a script tag to load this class definition from a CDN server to your website:

<script src="https://files.cdn.printful.com/embed/embed.js"></script>

To get the latest version of this file use this URL: https://files.cdn.printful.com/embed/embed.js

After you have included embed.js file in your website, you can create Embedded Design Maker Manager class PFDesignMaker instance.
Here is a simple example, of how to create this instance with all the required params:

this.designMaker = new PFDesignMaker({
    elemId: 'my-designer',
    nonce: 'ec7kkhxcx6ykjlb2718kzzbgu353y7on',
    externalProductId: 'mug-123',
    initProduct: {
        productId: 438,
    },
});

Info about the all possible properties that can be passed while creating this instance object:

Example with basic setup and default configuration values:

    this.designMaker = new PFDesignMaker({
        elemId: 'my-designer',
        nonce: 'ec7kkhxcx6ykjlb2718kzzbgu353y7on',
        externalProductId: 'mug-123',
        initProduct: {
            productId: 438,
        },
        locale: 'en_US',
        disabledPlacements: [],
        isVariantSelectionDisabled: false,
        disabledColors: [],
        disabledSizes: [],
        preselectedColors: [],
        preselectedSizes: [],
        preselectedProductOptions: {},
        applyImageFromUrl: '',
        useUserConfirmationErrors: false,
        allowOnlyOneColorToBeSelected: false,
        allowOnlyOneSizeToBeSelected: false,
        useEmbroideryPreviewInDesign: false,
        featureConfig: {
            clipart_layers: true,
            file_layers: true,
            text_layers: true,
            embroidery_3d_puff: true,
            has_color_group_inside_labels: false,
            sub_technique_switcher: false,
            has_external_user_file_library: false,
            show_unavailability_info: false,
            custom_external_file_library: false,
            initial_open_view: ''
        },
        livePricingConfig: {
            useLivePricing: false,
            useAccountBasedPricing: false,
            showPricesInPlacementsTabs: true,
            livePricingCurrency: 'USD'
        }
    })

Product info object initProduct can have following properties:

For some products that have 'Unlimited Colors' embroidery technique available (Product containing Unlimited Color option), it is possible to initialise product in designer in full_color mode by passing EMBROIDERY_FULL_COLOR as technique.

Custom styling object style can have following properties and data structure:

Prop name	Type	Description
variables	Object	List of key, value pairs, where the key is any valid CSS property and the value is any valid CSS value. All CSS declarations defined here will be applied to :root selector. There is a list of predefined custom CSS properties. See section Customization for more info
navigation.product.imageIcon	String	Desktop: Mobile: URL for navigation button product icon, if image fails to load, default icon will be used. Image will be resized to 24x24px
navigation.design.imageIcon	String	Mobile: URL for navigation button design icon, if image fails to load, default icon will be used. Image will be resized to 24x24px
navigation.layers.imageIcon	String	Desktop: Mobile: URL for navigation button layers icon, if image fails to load, default icon will be used. Image will be resized to 24x24px
navigation.file.imageIcon	String	Desktop: Mobile: URL for navigation button file icon, if image fails to load, default icon will be used. Image will be resized to 24x24px
navigation.text.imageIcon	String	Desktop: Mobile: URL for navigation button text icon, if image fails to load, default icon will be used. Image will be resized to 24x24px
navigation.clipart.imageIcon	String	Desktop: Mobile: URL for navigation button clipart icon, if image fails to load, default icon will be used. Image will be resized to 24x24px
navigation.fill.imageIcon	String	Desktop: Mobile: URL for navigation button fill icon, if image fails to load, default icon will be used. Image will be resized to 24x24px
(deprecated) background	String	Use --pf-sys-background, see general background related tokens color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation
(deprecated) textColor	String	Use any "on-background" or "on-surface", see neutral colors on background color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation
(deprecated) iconColor	String	Use --pf-sys-icon-on-background, see general background related tokens color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation
(deprecated) link.color	String	Use --pf-sys-link-on-background, see general background related tokens color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation
(deprecated) picker.background	String	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation
(deprecated) layer.background	String	Use --pf-comp-layer-item-surface, see layer color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation
(deprecated) layer.textColor	String	Use --pf-comp-layer-item-on-surface, see layer color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation
(deprecated) layer.iconColor	String	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation

If you have provided a method in onDesignStatusUpdate param - this method is called each time there are some updates regarding design status. To avoid calling this method too often when multiple things change at once - all method calls are debounced with time limit 1000ms - meaning that the design status update message will be sent 1000ms after the last design status change.

Possible events that trigger design status update are:

• Design has been changed compared to how it was opened - in case already saved template is opened
• There are some validation errors, that restrict user from saving the design with current configuration
• List of selected sizes/colors for the product has changed
• List of used placement has changed
• Sub technique switch

FeatureConfig data object 'featureConfig' can have following properties to control witch layer types/designer features are allowed in the Design Maker:

In case has_external_user_file_library is used and ADMIN user needs to open other user designs, then for ADMIN user nonce creation:

• external_customer_id is not used. That way ADMIN user can open and edit design, but file library won't be accessible because that needs external_customer_id.
• external_customer_id is the same as the customer_id that was used to create design. That way ADMIN user is impersonating user and can edit design, and access user's file library.

• This param should be used in case you want to disable specific placements from Design Maker
• disabledPlacements array should contain placementId String values, separated by comma.
• If the param is omitted or is an empty array, then all placements will be available
  • example param values:
    • ['embroidery_chest_left']
    • ['back','sleeve_left','sleeve_right']
    • ['embroidery_left','embroidery_right']
  • If none of the provided Strings match any placementsId of the opened product then this param has no effect - all the placements will be available
• This param will work for both modes "Create new template" and "Edit existing template" mode.
  • In "Edit existing template" mode, if opened template contains any design for the placement that is not hidden, then all the design in that placement will be deleted (after the Save action will be called)
• For technical reasons placement 'embroidery_large_center' will always be hidden, if there is such a placement for the loaded product. This is just a temporary restriction - until the technical reasons will be solved

• This param should be used in case you want to have specific Product colors preselected when opening Design Maker
• preselectedColors array should contain Product color name string values, separated by comma.
• If the param is omitted or is an empty array, default logic will be used.
  • example param values:
    • ['Black Heather','Autumn','Aqua','Mauve']
    • ['Oxblood Black','Heather Raspberry','Heather True Royal']
    • ['Heather True Royal']
  • If none of the provided Strings match any Product color names of the opened product available colors then this param has no effect - default logic will be used instead.
• This param will only work for "Create new template" mode.
• If passed color name is not found in current product config, it will be ignored

• This param should be used in case you want to have specific Product sizes preselected when opening Design Maker
• preselectedSizes array should contain Product size name string values, separated by comma.
• If the param is omitted or is an empty array, default logic will be used.
  • example param values:
    • ['XS','S','M']
    • ['XL']
    • ['2XL','3XL','4XL','5XL']
  • If none of the provided Strings match any Product size names of the opened product available sizes then this param has no effect - default logic will be used instead.
• This param will only work for "Create new template" mode.
• If passed size name is not found in current product config, it will be ignored

• This param should be used in case you want to have preselected product options. This works only if product supports these options and passed values.
• Check Utilising Options to see if product has product options and what kind of values it supports.
• Sometimes default values are null, if thats the case then end-user needs to select product options via Design Maker. End-user can't save design without values in product options. If no values are selected relevant error message is shown that stops user from saving template.
• preselectedProductOptions object has key as product option name and value as product option value. See table for supported product options:

• If wrong key gets passed, it will be ignored.
• If wrong value gets passed, it will be ignored.

• This param should be used in case you want to have specific Product colors disabled for Embedded Design Maker
• disabledColors array should contain Product color name string values, separated by comma.
• If the param is omitted or is an empty array, default logic will be used.
  • example param values:
    • ['Black Heather','Autumn','Aqua','Mauve']
    • ['Oxblood Black','Heather Raspberry','Heather True Royal']
    • ['Heather True Royal']
  • If none of the provided Strings match any Product size names of the opened product available sizes then this param has no effect - default logic will be used instead.
• If passed size name is not found in current product config, it will be ignored

• This param should be used in case you want to have specific Product sizes disabled for Embedded Design Maker
• disabledSizes array should contain Product size string values, separated by comma.
• If the param is omitted or is an empty array, default logic will be used.
  • example param values:
    • ['XS','S','M']
    • ['XL']
    • ['2XL','3XL','4XL','5XL']
  • If none of the provided Strings match any Product sizes of the opened product available sizes then this param has no effect - default logic will be used instead.
• If passed size name is not found in current product config, it will be ignored

If applyImageFromUrl string was provided for the PFDesignMaker instance on new product creation, then image from URL will be added to first design placement without manual interactions from the end user.

• This parameter will work only for new product design creation.
• JPG or PNG image must be available from the passed URL so that can be processed and applied to design.
• Restrictions for the image and URL are noted in Send message - Add image from URL trigger section.
• Image can also be added to design placement while designer is open with setUrlImageLayer message.

When EDM opens up and selected product has no variants available, unavailability overlay with message appears. When this overlay appears, EDM becomes unusable.

When overlay triggers it will also pass an error to onDesignStatusUpdate with string This product isn’t available.

When user selects variant that is currently out of stock or is discontinued, list will appear with all the selected variants that have this issue.

By default, this option is disabled, to enable it set show_unavailability_info to true in Feature Config

With Add image from URL trigger its possible to add images to EDM, but it might be wierd to trigger this method with file selector that is outside EDM, with setting custom_external_file_library to true, when user clicks on any file upload option in EDM, it will trigger onFilePickerRequested hook instead of calling EDM file upload methods.

By combining onFilePickerRequested hook and setUrlImageLayer event, it's possible to show custom file library instead of showing EDM file library

Example usage:

    this.designMaker = new PFDesignMaker({
        elemId: 'my-design-maker',
        nonce: 'ec7kkhxcx6ykjlb2718kzzbgu353y7on',
        featureConfig: {
            custom_external_file_library: true,
        },
        onFilePickerRequested: () => {
            // Logic for opening custom file library
            // Method for picking file from that library
            this.designMaker.sendMessage({
                event: 'setUrlImageLayer',
                imageUrl, // chosen file url
            }); // Call this from the method that chooses the file
        },
    });

To change a locale use locale: 'en_US'

It will translate the EDM UI to selected locale, will also translate warnings and errors returned from onDesignStatusUpdate hook. Possible values: en_US, it_IT, fr_FR, es_ES, de_DE, ja_JP.

Example usage:

    this.designMaker = new PFDesignMaker({
        elemId: 'my-design-maker',
        nonce: 'ec7kkhxcx6ykjlb2718kzzbgu353y7on',
        locale: 'en_US',
    });

To disable variant selection use isVariantSelectionDisabled: true Will still show all possible colors and sizes for a product, but will disable option to select any colors or sizes. Useful if it should not be possible to edit selected colors or sizes when editing previously saved design.

Example usage:

    this.designMaker = new PFDesignMaker({
        elemId: 'my-design-maker',
        nonce: 'ec7kkhxcx6ykjlb2718kzzbgu353y7on',
        isVariantSelectionDisabled: true,
    });

To make it so that customer can select only one color use allowOnlyOneColorToBeSelected: true Useful for using EDM as an order creation tool.

Recommended to use along with "Limit size selection to one"

Example usage:

    this.designMaker = new PFDesignMaker({
        elemId: 'my-design-maker',
        nonce: 'ec7kkhxcx6ykjlb2718kzzbgu353y7on',
        allowOnlyOneColorToBeSelected: true,
    });

To make it so that customer can select only one size use allowOnlyOneSizeToBeSelected: true Useful for using EDM as an order creation tool.

Recommended to use along with "Limit color selection to one"

Example usage:

    this.designMaker = new PFDesignMaker({
        elemId: 'my-design-maker',
        nonce: 'ec7kkhxcx6ykjlb2718kzzbgu353y7on',
        allowOnlyOneSizeToBeSelected: true,
    });

There can be some errors that in regular Designmaker in Printful ask for user feedback to be resolved, for example modal for selecting AOP product stitch color if user did not select one.

In EDM such errors are just passed in onDesignStatusUpdate

But it's possible to enable the modal flow instead of just passing some error to onDesignStatusUpdate with useUserConfirmationErrors: true

Example usage:

    this.designMaker = new PFDesignMaker({
        elemId: 'my-design-maker',
        nonce: 'ec7kkhxcx6ykjlb2718kzzbgu353y7on',
        useUserConfirmationErrors: true,
    });

With useUserConfirmationErrors: false if user has not selected stitch color:

With useUserConfirmationErrors: true if user has not selected stitch color and tries to save design:

To get current design pricing range, use livePricingConfig and onPricingStatusUpdate hook. onPricingStatusUpdate will provide each selected variants price and even include additional placement price.

Available currencies: "USD", "EUR", "JPY", "GBP", "CAD", "AUD", "SEK", "DKK", "NZD", "CHF", "MXN", "HKD", "SGD", "NOK", "PLN", "KRW", "BRL";

Data format returned from onPricingStatusUpdate

export interface PricingInfo {
    discountPercent: number;
    discountedPrice: number;
    discountAmount: number;
    currency: string;
    currencySymbol: string;
    price: number;
    originalPrice: number;
    retailPrice: number;
    basePriceDiscount: number;
    growthPrice: number;
    color: string;
    size: string;
}

Example config:

    this.designMaker = new PFDesignMaker({
        elemId: 'my-design-maker',
        nonce: 'ec7kkhxcx6ykjlb2718kzzbgu353y7on',
        livePricingConfig: {
            useLivePricing: true, // Enables the feature
            useAccountBasedPricing: false, // If true, gets discounts if EDM owner account has Printful Growth enabled
            showPricesInPlacementsTabs: true, // If true, will show prices in placement tabs
            livePricingCurrency: "USD" // Currency to show and use
        },
        onPricingStatusUpdate: (variantPriceList) => { 
            // logic that handles pricing logic
        }
    });

There are some limitations as to what kind of templates EDM can edit.

If a product template is created with https://printful.com, you will not be able to edit or open such templates in EDM.

Templates created with EDM, are not visible in https://printful.com dashboard.

To edit a template follow this flow:

1. Create a template reference on your side (external_product_id)
2. Create a nonce with said externalProductId (More details here), example request:

   POST https://api.printful.com/embedded-designer/nonces
   Authorization: Bearer {token}
   
   Content-Type: application/json
   
   {
       "external_product_id": "myRandomlyGeneratedId1"
   }
   

3. Create the EDM instance, example code:

       this.designMaker = new PFDesignMaker({
        elemId: 'my-designer',
        nonce: 'ec7kkhxcx6ykjlb2718kzzbgu353y7on', // nonce returned from step 2
        externalProductId: 'myRandomlyGeneratedId1', // Your generated ID
        initProduct: {
            productId: 438, // Whatever product you wish to open
        },
    });
   

4. Save design
5. To edit the saved design, create nonce again, but instead of generating new external_product_id, use the same one that was used when initial nonce was created
6. Create a new EDM instance, but now don't add initProduct, example code:

       this.designMaker = new PFDesignMaker({
        elemId: 'my-designer',
        nonce: 'uMZHeuNEYM8nsjqzf0JAFUsglvurf5EA', // nonce returned from step 5
        externalProductId: 'myRandomlyGeneratedId1', // Your previously used id from step 1 ID
    });
   

Now if everything went correctly, EDM should open design that was saved during step 4.

To be able to trigger events in Embedded Design Maker, use public method sendMessage of the PFDesignMaker instance object. Method has only one parameter message type Object. See the example usage of this method - to trigger save design action in Embedded Design Maker:

 this.designMaker.sendMessage({ event: 'saveDesign' });

saveDesign - Call this event to trigger save action on Embedded Design Maker.

• If Design Maker is opened in "Create new template" mode, then save action will create new Embedded Template
• if Design Maker is opened in "Edit existing template" mode then save action will update design for existing template.

Example code

this.designMaker.sendMessage({ event: 'saveDesign' });

Notes

If onTemplateSaved function was provided for the PFDesignMaker instance, and the save action was successful, then onTemplateSaved callback function will be called after triggering saveDesign event.

setUrlImageLayer - Call this event to trigger image adding to active placement on Embedded Design Maker.

• There are limitations to passed URL:
  • URL must point to PNG/JPG image that can be processed from passed string,
  • Max URL length is 1000 characters,
  • Recommended max size for one image dimension is 15k pixels,
  • Image size must be smaller than 50MB,
  • Maximum of 5 file image layers can be applied to one placement.
• Image will be applied to the opened design placement.
• If file can not be processed, a console error will be shown.

Example code

this.designMaker.sendMessage({ event: 'setUrlImageLayer', imageUrl: 'https://picsum.photos/2000' });

Notes

To add image from URL automatically after new product is opened applyImageFromUrl parameter can be used.

The first time image is retrieved it will be saved for future use. When using the same URL for future requests the cached image will be used.

If has_external_user_file_library parameter ("featureConfig" data structure) is used, end user will see file in library.

• Accessibility
  • Color contrast
    • Consideration: When modifying predefined custom CSS properties that are listed below, Printful is not responsible for meeting the accessible color contrast values
    • Solution: Ensure that the custom design system colors meet minimum accessible color contrast. More information about Text has minimum contrast WCAG rule (external link)
• Custom SVG illustrations
  • Consideration: Custom SVG illustrations (e.g. in "not results found" search views) are not customizable and may not look good on every background color
  • Solution: Custom SVG illustrations will work best with a light theme

On light background	On dark background

• Changing container component specific surface color with unpredictable content (e.g. dropdown and popover)
  • Consideration: Almost all container components (e.g. dropdowns and popovers) use the same surface color as the page background, white by default. If you want to change surface color for a specific component (e.g. popover) to be different from page background color, depending on content inside popover, the colors inside popover might not be customizable. In most cases it should be fine, but there could be cases where customization options are limited on component level.
  • Solution: For container components (e.g. dropdowns and popovers) most reliable results will be if the container component surface is the same color as page background color

In the example below, the popover surface and text colors are changed. The toggle switch can't be adjusted for popover specifically

Popover with white surface	Popover with custom surface

• Loading spinner customization
  • Consideration: Currently it's not possible to change colors for the loading spinner
  • Solution: The loading spinner will work best with a light theme

Loading spinner on white background	Loading spinner on dark background

• Non-customizable cliparts
  • Consideration: When changing page background color, some clipart colors may clash with the background
  • Solution: Cliparts will work best with a light theme

Non-customizable cliparts on white background	Non-customizable cliparts on dark background

Dark mode

When changing to dark mode, use dark color scheme in CSS to make the operating system adjust the user interface (e.g. make scrollbars and native form controls dark)

More info on CSS color-scheme property - https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme

new PFDesignMaker({
    style: {
        variables: {
            'color-scheme': 'dark',
        },
    },
});

Accent color

Change the accent color of user-interface controls (e.g. checkboxes, radio buttons)

More info on CSS accent-color property - https://developer.mozilla.org/en-US/docs/Web/CSS/accent-color

new PFDesignMaker({
    style: {
        variables: {
            'accent-color': '#222222',
        },
    },
});

Example usage

new PFDesignMaker({
    style: {
        variables: {
            '--pf-sys-background': '#222222',
        },
    },
});

If the custom CSS property value references another custom CSS property, you can omit the declaration and the value will be inherited from the referenced property. However, you can override those properties to be more specific.

Note: Following example is not comprehensive and complete and is meant to be used as a starting point to build upon

Light mode	Dark mode

new PFDesignMaker({
    style: {
        variables: {
            '--pf-sys-background': '#0f172a',
            '--pf-sys-background-hsl': '222.22, 47.37%, 11.18%',
            '--pf-sys-neutral-300-on-background': '#64748b',
            '--pf-sys-neutral-400-on-background': '#94a3b8',
            '--pf-sys-neutral-700-on-background': '#e2e8f0',
            '--pf-sys-neutral-800-on-background': '#f1f5f9',
            '--pf-sys-neutral-900-on-background': '#f8fafc',
            '--pf-sys-primary-400-on-background': '#059669',
            '--pf-sys-primary-700-on-background': '#6ee7b7',
            '--pf-sys-border-on-background': '#64748b',
            '--pf-sys-link-on-background': '#93c5fd',
            '--pf-sys-icon-on-background': '#94a3b8',
            '--pf-sys-icon-info-on-background': '#94a3b8',
            '--pf-sys-icon-hover-neutral-700-on-background': '#e2e8f0',
            '--pf-sys-icon-hover-neutral-900-on-background': '#f8fafc',
            '--pf-sys-error-on-background': '#f87171',
            '--pf-sys-success-on-background': '#22c55e',
            '--pf-sys-warning-on-background': '#fcd34d',
            '--pf-sys-hover-border-color-on-background': '#64748b',
            '--pf-sys-hover-box-shadow-on-background': '',
            '--pf-sys-neutral-surface-50': '#1e293b',
            '--pf-sys-neutral-surface-50-hsl': '217.24, 32.58%, 17.45%',
            '--pf-sys-neutral-300-on-surface-50': '#64748b',
            '--pf-sys-neutral-400-on-surface-50': '#94a3b8',
            '--pf-sys-neutral-700-on-surface-50': '#e2e8f0',
            '--pf-sys-neutral-900-on-surface-50': '#f8fafc',
            '--pf-sys-neutral-surface-100': '#334155',
            '--pf-sys-neutral-700-on-surface-100': '#e2e8f0',
            '--pf-sys-neutral-900-on-surface-100': '#f8fafc',
            '--pf-sys-neutral-surface-200': '#475569',
            '--pf-sys-neutral-400-on-surface-200': '#94a3b8',
            '--pf-sys-neutral-900-on-surface-200': '#f8fafc',
            '--pf-sys-neutral-surface-300': '#64748b',
            '--pf-sys-neutral-400-on-surface-300': '#94a3b8',
            '--pf-sys-neutral-900-on-surface-300': '#f8fafc',
            '--pf-sys-neutral-surface-400': '#94a3b8',
            '--pf-sys-neutral-900-on-surface-400': '#f8fafc',
            '--pf-sys-primary-surface-400': '#059669',
            '--pf-sys-primary-surface-700': '#6ee7b7',
            '--pf-sys-primary-on-surface-700': '#134e4a',
            '--pf-sys-error-surface': '#991b1b',
            '--pf-sys-error-on-surface': '#fef2f2',
            '--pf-sys-form-control-indicator-active-surface': '#93c5fd',
            '--pf-sys-form-control-indicator-active-on-surface': '#1e3a8a',
            '--pf-sys-action-button-surface': '',
            '--pf-sys-action-button-on-surface': '#f8fafc',
            '--pf-sys-action-button-hover-surface': '#64748b',
            '--pf-sys-action-button-hover-on-surface': '#f8fafc',
            '--pf-sys-action-button-focus-surface': '',
            '--pf-sys-action-button-focus-on-surface': '#f8fafc',
            '--pf-sys-action-button-selected-surface': '#155e75',
            '--pf-sys-action-button-selected-on-surface': '#ecfeff',
            '--pf-sys-action-button-disabled-surface': '',
            '--pf-sys-action-button-disabled-on-surface': '#94a3b8', 
        },
    },
});

Most of the user interface changes with system tokens

From lightest (least contrast) to darkest (most contrast) in light theme

These values are also used for all neutrally colored content on all neutral surfaces, if not overridden

Name	Default value	Value type	Description
--pf-sys-neutral-300-on-background	hsl(0, 0%, 89.8%)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral color on background. Used border on background color
--pf-sys-neutral-400-on-background	hsl(0, 0%, 69.41%)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral color on background
--pf-sys-neutral-700-on-background	hsl(0, 0%, 33.33%)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral color on background
--pf-sys-neutral-800-on-background	hsl(0, 0%, 21.57%)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral color on background
--pf-sys-neutral-900-on-background	hsl(0, 0%, 13.33%)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral color on background. Page text color
--pf-sys-neutral-900-on-background-hsl	0, 0%, 13.33%	valid HSL color values, but without hsl() wrapper function	Neutral color on background. Used for CSS color values that require a new value to be generated. Value should derive from --pf-sys-neutral-900-on-background

From lightest (least contrast) to darkest (most contrast) in light theme

Name	Default value	Value type	Description
--pf-sys-neutral-surface-50	hsl(0, 0%, 97.25%)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral surface color
--pf-sys-neutral-surface-50-hsl	0, 0%, 97.25%	valid HSL color values, but without hsl() wrapper function	Neutral surface color for some elements in separate HSL values. Used for CSS color values that require a new value to be generated. Value should derive from --pf-sys-neutral-surface-50
--pf-sys-neutral-300-on-surface-50	--pf-sys-neutral-300-on-background	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral color on neutral surface
--pf-sys-neutral-400-on-surface-50	--pf-sys-neutral-400-on-background	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral color on neutral surface
--pf-sys-neutral-700-on-surface-50	--pf-sys-neutral-700-on-background	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral color on neutral surface
--pf-sys-neutral-900-on-surface-50	--pf-sys-neutral-900-on-background	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral color on neutral surface

From lightest (least contrast) to darkest (most contrast) in light theme

Name	Default value	Value type	Description
--pf-sys-neutral-surface-100	hsl(0, 0%, 95.29%)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral surface color
--pf-sys-neutral-700-on-surface-100	--pf-sys-neutral-700-on-background	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral color on neutral surface
--pf-sys-neutral-900-on-surface-100	--pf-sys-neutral-900-on-background	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral color on neutral surface

From lightest (least contrast) to darkest (most contrast) in light theme

Name	Default value	Value type	Description
--pf-sys-neutral-surface-300	hsl(0, 0%, 89.8%)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral surface color
--pf-sys-neutral-400-on-surface-300	--pf-sys-neutral-400-on-background	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral color on neutral surface
--pf-sys-neutral-900-on-surface-300	--pf-sys-neutral-900-on-background	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Neutral color on neutral surface

From lightest (least contrast) to darkest (most contrast) in light theme

Name	Default value	Value type	Description
--pf-sys-primary-400-on-background	hsl(1.4, 82.61%, 59.41%)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Primary (brand) color on background
--pf-sys-primary-700-on-background	hsl(1.38, 91.6%, 46.67%)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Primary (brand) color on background

Used for interactive form elements - checkbox, radio button, toggle switch

Name	Default value	Value type	Description
--pf-sys-form-control-indicator-active-surface	hsl(207.24, 81.72%, 36.47%)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Active form control indicator surface color
--pf-sys-form-control-indicator-active-on-surface	hsl(0, 0%, 100%)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Color on active form control indicator surface

Use component tokens if the system tokens aren't enough and you want to fine tune the look of a specific component

See also Mobile footer

Name	Default value	Value type	Description
--pf-comp-designer-mobile-footer-surface	--pf-sys-background	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Mobile footer surface color
--pf-comp-designer-mobile-footer-box-shadow	0 -8px 34px 0 hsla(0, 0%, 0%, 0.16)	valid full box-shadow value	Mobile footer shadow on background
--pf-comp-designer-mobile-footer-toolbar-start-gradient	linear-gradient(90deg, hsla(--pf-sys-background-hsl, 1) 0%, hsla(pf-sys(background-hsl), 0) 100%)	valid full linear-gradient function for background property	Mobile footer toolbar start gradient
--pf-comp-designer-mobile-footer-toolbar-end-gradient	linear-gradient(90deg, hsla(--pf-sys-background-hsl, 0) 0%, hsla(pf-sys(background-hsl), 1) 100%)	valid full linear-gradient function for background property	Mobile footer toolbar end gradient

Used for interactive form elements - checkbox, radio button, toggle switch

Name	Default value	Value type	Description
--pf-comp-form-control-indicator-surface	--pf-comp-input-surface	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Form control indicator surface color
--pf-comp-form-control-indicator-border-color	--pf-sys-neutral-400-on-background	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Form control indicator border color on background
--pf-comp-form-control-checked-indicator-surface	--pf-sys-form-control-indicator-active-surface	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Checked form control indicator surface color
--pf-comp-form-control-checked-indicator-on-surface	--pf-sys-form-control-indicator-active-on-surface	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Color on checked form control indicator surface
--pf-comp-form-control-checked-indicator-border-color	--pf-comp-form-control-checked-indicator-surface	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Checked form control indicator border color on background
--pf-comp-form-control-checked-disabled-indicator-surface	hsla(207.24, 81.72%, 36.47%, 0.5)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Checked disabled form control indicator surface color
--pf-comp-form-control-active-indicator-surface	lighten(hsl(207.24, 81.72%, 36.47%), 35%)	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Activated (pressed) form control indicator surface color
--pf-comp-form-control-active-indicator-on-surface	--pf-comp-form-control-checked-indicator-on-surface	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Color on activated (pressed) form control indicator surface
--pf-comp-form-control-active-indicator-border-color	--pf-comp-form-control-checked-indicator-surface	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Activated (pressed) form control indicator border color on background
--pf-comp-form-control-disabled-indicator-surface	--pf-comp-form-control-indicator-surface	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Disabled form control indicator surface color
--pf-comp-form-control-disabled-indicator-border-color	--pf-comp-input-border-color	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Color on disabled form control indicator surface
--pf-comp-form-control-disabled-label-on-surface	--pf-comp-input-disabled-on-surface	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Disabled form control label color on background
--pf-comp-form-control-hover-indicator-box-shadow	inset 0 0 0 3px --pf-comp-input-border-color	valid full box-shadow value	Hovered form control inside border color on form control indicator surface
--pf-comp-form-control-not-unchecked-hover-indicator-box-shadow	inset 0 0 0 0 --pf-comp-input-border-color	valid full box-shadow value	Checked, indeterminate hovered form control inside border color on form control indicator surface
--pf-comp-form-control-error-indicator-border-color	--pf-comp-input-error-border-color	color, valid RGB, RGBA, HSL, HSLA color values and CSS4 Hex notation	Errored form control indicator border color on background

Returns list of Products available in the Printful.

Endpoint: GET https://api.printful.com/products Required scopes: none

Response schema (application/json):

Product schema:

FileType schema:

OptionType schema:

This endpoint is documented in the Catalog API / Get Products section of the public documentation.

Returns list of Catalog Categories available in the Printful.

Endpoint: GET https://api.printful.com/categories Required scopes: none

Response schema (application/json):

Category schema:

The endpoint is documented in the Catalog API / Get Categories section of the public documentation.

Generate Mockups for saved Embedded template

The endpoint creates an asynchronous mockup generation task. Generation result can be retrieved using mockup generation task retrieval endpoint.

Endpoint: POST https://api.printful.com/mockup-generator/create-task/{id} Required scopes: none

Path parameters:

Header parameters:

Request body schema (application/json):

GenerationTaskFile schema:

GenerationTaskFilePosition schema:

Response schema (application/json):

GenerationTask schema:

GenerationTaskMockup schema:

GenerationTaskExtraMockup schema:

GenerationTaskTemplateFile schema:

The endpoint is documented in the Mockup Generator API / Create a mockup generation task section of the public documentation.

Get all Embedded templates

The endpoint returns a list of all templates.

Endpoint: GET https://api.printful.com/product-templates Required scopes: product_templates/read

Query parameters:

Response schema (application/json):

ProductTemplateList schema:

ProductTemplate schema: