Written by Tom Carden.

Two months ago we launched Square Market, the online storefront for neighborhood businesses everywhere. Since launch, our item pages have allowed merchants and visitors alike to share their favorite items with their friends and followers on Twitter, Facebook and Pinterest. This feature allows merchants to reach more customers and helps buyers to find interesting items faster, wherever they are browsing.

While sites like Twitter and Facebook generate a ton of traffic and many people have strong followings there, we also know that people like to run their own websites, blogs and Tumblrs where they can go into more depth and focus on what’s most important to them. We’ve heard from both merchants and Square Market visitors that they’d like to share items on these sites too. Today we’re announcing a new item embedding feature to help make that happen.

What It Does

Our embedding script turns links like these:

Getting Started

All the HTML you need to embed a single item is included in the embed widget on Square Market item pages. To get started:

1. Click the <> embed icon, found alongside our existing sharing icons:

2. Copy and paste the HTML into your own site:

3. There is no step 3! You can use the preview to see what your embedded item will look like in your page:


If you prefer to write the HTML yourself, simply:

  1. Add a link to the item you’re interested in.
  2. Add class=”sq-market-embed” to the link.
  3. Include the Square Market embed.js script in your page.

You only need to include the embed.js script once. With some knowledge of HTML, CSS and JavaScript it’s possible to create a custom layout and even a full embedded storefront.

We’ve written several Square Market embedding examples that you’re free to adapt for your own site. You can explore the samples on our square-market-embeds github project.

What Item Embedding Does

The code we give you to add an item to your page does two things: it includes a normal HTML link to your chosen item and it includes a script tag which replaces the link with an iframe containing the full content of the item.

For example, if you include a link to Jamais deux sans trois pourpre orange from La Valise d’Alice:

<a href="https://squareup.com/market/la-valise-dalice/jamais-deux-sans-trois-pourpre-orange"
Jamais deux sans trois pourpre orange from La Valise d'Alice on Square Market

And the Square Market embed script:

<script src="https://cdn.sq-api.com/market/embed.js" id="sq-embed-js" charset="utf-8"></script>


Here’s my checklist for any new project:

  1. Make it work.
  2. Make it work right.
  3. Make it work fast.

To make it work, we had a few different options. Conventionally, when services offer an embedding feature they usually do it with an img, an iframe or a link and a script. We chose the latter. Behind the scenes we use an iframe to achieve the desired functionality, but we chose the script to keep things as flexible as possible.

For example, in future we might want to optimize the case where a page contains many items. With a script approach we’ll be able to do that without asking people to change their existing embeds. With an iframe approach we’d be committing to serving those exact iframes forever (or risk breaking external sites). We want to add new features and respond to your feedback quickly; the script approach enables that most effectively.

To make it work right, we made sure that the script we ask you to add is small, served securely over SSL, and works across a wide range of devices and browsers. The embed uses a responsive design, so it adapts to the window size of the device you’re using and is legible across mobile, tablet and desktop browsers.

Lastly, to make it work fast, we’re serving the embed.js and images from a CDN. We also made a special template just for the embed that doesn’t require all of our shopping-cart and checkout functionality, so it’s served quickly and can be cached more aggressively.

The combined requirement of SSL and CDN means we’re serving the script from a new domain, cdn.sq-api.com. You can count on us to keep this domain highly available so it won’t affect the quality of your site.


This is version 1.0 of the item embedding feature, we’d love to hear from you about how you’re using it. If it doesn’t meet your needs or live up to your expectations for content you include on your own site, please let us know that too. For specific help or bug reports, please contact our Help Center. For general feedback on the feature and anything outlined in this blog post, feel free to use the comments below this post.

Square Corner Blog

Buying and selling sound like simple things - and they should be. Somewhere along the way, they got complicated. At Square, we're working hard to make commerce easy for everyone.


Square Engineering

Written by

The official account for @Square Engineering.

Square Corner Blog

Buying and selling sound like simple things - and they should be. Somewhere along the way, they got complicated. At Square, we're working hard to make commerce easy for everyone.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade