When I became a busboy at my favorite family-owned French restaurant in Rhode Island, I had to learn a lot very quickly. From how to dance around fellow waitstaff while juggling piles of glass, ceramic, and silver to how differently customers could act towards the people serving them. I also saw firsthand how a restaurant survives – from cutting marginal costs (I was once reprimanded for using too long a piece of tape) to taking extra good care of the regular customers who accounted for most of our business. Within a few weeks at the restaurant, I knew most of these customers by name and even which day (or days) they would visit. Years later, as I’ve been building Kyoo, I can see even more clearly that these regulars are actually the lifeblood of most small businesses today.

This came in handy a couple months ago, when our team was approached by ᴅᴏᴍɪɴɪqᴜᴇ ᴀɴꜱᴇʟ ʙᴀᴋᴇʀʏ with a creative concept for offering a subscription model at their bakery. With a shared vision for how this could work and having worked with subscriptions on several e-commerce businesses in the past, this initially sounded like a straightforward feature to build. Upon digging a little deeper, we found that unlike traditional e-commerce businesses, bakeries have strict constraints around freshness, prep time, and day-of inventory that don’t mix well with typical e-commerce order fulfillment.

But bakeries are not alone in this – we also spoke with cafes, farmer’s market stands, breweries, and roving food trucks who confirmed that a more flexible and F&B-friendly subscription model could become a critical feature for growing their businesses. When done right, subscriptions can make revenue and inventory sheets predictable so sellers can confidently plan ahead. But the more we looked, the more we realized that no one had actually built that yet.

In fact, we noticed quite a bit of pain around this lack of subscriptions. A simple search in the Square Seller Community forums yields hundreds of posts about subscriptions including one post from March this year titled “Subscriptions! Why is this so hard!?!?!” The best current recommendations we could find were to create multiple separate item-specific subscription links or to try sending invoices. We decided to take this challenge and use the Square Unboxed Hackathon as a springboard to build something awesome that didn’t exist anywhere else.

DA Quote

What it does

Vibe n’ Subscribe allows Square sellers to leverage the power and convenience of a flexible subscription model to reduce friction for regulars and turn first-timers into for-lifers.

Subscribers are able to select and customize the items they would like to add to their subscription and enter their preferred frequency and subscriber details at checkout. Once the subscription has been confirmed, both customer and seller are notified via email and provided with a secure link to manage their subscription. By logging in, either can easily edit the initial order or unsubscribe if necessary. Sellers can track their active subscribers and subscription metrics using the Subscription Report or view upcoming confirmed orders per-day using the Orders or Items Report.

Here is the end-to-end experience from the customer’s point of view:

  1. Visit the subscription store URL (uses a query param to enter subscription mode and enable one or more active subscription plans)
  2. Add items to cart to customize the desired subscription
  3. Go to checkout and customize subscription preferences by first selecting which day(s) of the week, then choosing a frequency (current offerings include daily, weekly, and monthly) Note: Monthly subscribers can also choose which occurence of a day to have their order fulfilled (e.g. on the 2nd Friday of every month)
  4. Complete checkout with all other necessary subscriber details
  5. Receive verification email with link to manage subscription
  6. Next order is confirmed once the cancellation deadline has passed (seller can specify this deadline in dashboard)
  7. Customer receives a confirmation email which includes an automated calendar reminder with all order details (when using Gmail and Google Calendar)

And from the merchant’s point of view:

  1. Configure subscriptions in Square Dashboard using shortcode in square brackets to name each subscription
  2. Generate custom subscription-specific branded QR codes/URLs in Kyoo’s QR Studio
  3. Track all subscriptions via Subscriptions Report and receive email alerts for new/canceled subscriptions
  4. Ability to manage subscriptions using admin mode
  5. Full visibility into upcoming subscription orders in dashboard reports based on subscription preferences and confirmed orders (includes printed tickets and POS notifications)
  6. Option to customize cancellation deadline (necessary for items with longer lead times)

How we built it

To complete our Vibe n’ Subscribe build, we first specced out the feature with D.A. Bakery and settled on an appropriate scope for what we could accomplish in the given hackathon timeframe. We collaboratively designed the entire feature in Figma, then got to work figuring out how much we could depend on Square’s Subscription API vs. how much we would need to build from scratch. Although the current implementation of Square’s Subscription API is currently geared more towards solo products, membership plans, and invoicing, we agreed its API still contained most of the necessary components for the feature we wanted to build so it soon became the scaffolding for the entire project.

We manually created new subscription plans in Square as if we were a Square Seller setting up different subscription options. Each plan contained a short code within square brackets to act as a reference ID so we could generate unique subscription pages (or in case a seller wanted to offer additional unrelated subscription plans). We then updated the Kyoo QR Studio to generate these links accordingly, including a special wildcard option (?subscription=all) to display all subscription plan options. To retrieve these various subscription plans from Square, we used the Catalog API. We also added permission requests for subscription read, subscription write, and invoice write to properly integrate with tracking each subscription in the Square Subscriptions dashboard.

Using Kyoo’s existing order creation flow on the frontend, we were able to use the Square order request object as a reference for the items contained in each subscription. At checkout, instead of offering the typical fulfillment options for subscriptions, we display the selected frequencies for each subscription plan (it currently supports daily, weekly, and monthly with day of week selection for each option) to let the customer choose their preferred frequency.

Upon entering payment details in the Web Payments SDK and pressing “Pay”, we attempt to create the subscription. Before updating the subscription creation state to SUCCESS, we authorize the card on file for $0.01 to ensure the card is valid, then immediately void this charge. Assuming everything clears, we calculate the next pickup time and cancellation deadline based on the time window the merchant has specified (after which a customer can no longer modify their order) then update the subscription data object. All order details are stored in a MySQL database and a new subscription is created in Square using the Subscriptions API. Upon successful subscription creation, emails are sent to both the customer and seller using Mailgun. As part of this build, we added support for full HTML emails so we could send Microdata to create Google Event Reservations, which automatically generates a Google Calendar event with all of the order details. We also plan to add support for this to existing scheduled pickup reminders within our core platform. We initially built a separate working solution to send calendar events which could serve as reminders, but deploying this required hacky workarounds for the Google Oauth integration (we got it working locally and will probably eventually build a more robust version of this).

Based on our conversations with sellers, we knew it would be important to add lots of visibility for sellers to keep track of their upcoming subscriptions. We built a report for sellers to view and analyze all active subscriptions and subscriber information from their Kyoo Dashboard within Order Insights > Subscription Report. Since part of the goal with this feature was to build more predictability into a particularly unpredictable industry, we decided to add specific metrics to this report to track MRR, the total number of subscribers, and the subscription type breakdown. Sellers can also see order history and upcoming orders for each subscription by clicking Manage Subscription to enter admin mode. Buyers can also manage or cancel their subscriptions and receive a confirmation email when a subscription is canceled.

Next, we added a scheduled task that runs every three minutes – it looks for all subscriptions that have passed their cancellation deadline, then creates orders in Square and charges the cards on file. In case a payment fails, we notify both the buyer and seller. We would have loved to use Square Subscriptions with Invoices to collect payments for failed orders, but we received an error here when charging the shared card on file so instead opted for the Orders + Payments API integrations.

Once the order is created (after the deadline has passed and that occurrence of the subscription is confirmed), orders are tracked using our existing Square POS integration so sellers receive new order notifications via printed tickets and POS notifications while customers receive SMS notifications via Twilio with all order status updates (via Square Order Webhooks). All orders are displayed within Kyoo’s existing Daily Order Reports and marked as subscription orders.

Finally, as a cleanup task and to prepare the next upcoming order, we calculate the next pickup time and next cancellation deadline and update the subscription in the database accordingly. In case we are unable to find the next pickup time within the next three months (for example, if the seller is no longer open on that day or in case of a long blackout date range), then the seller and customer are notified and the subscription is automatically canceled. We will eventually update this to a more elegant solution that involves selecting a new pickup date, but there were a lot of edge cases in the world of subscriptions so we tried to prioritize the most important ones for this build.

Challenges we ran into

One major challenge we ran into was overcoming the current limitations with the Subscriptions API since it isn’t necessarily set up for a comprehensive online ordering integration. This obstacle was partly of our own making since we could have tried to rebuild this functionality without using Square’s API. That said, we’re hoping that Square will decide to add a Subscriptions + Orders API integration to make this easier in the future. Current Subscriptions API limitations included:

  • Doesn’t allow for Square Order creation and is unable to link subscriptions to specific items/inventory
  • Unable to use a shared card on file to charge customers when trying to create a Square Subscription (received an error)
  • When manually creating a daily subscriptions plan, we could only use the trial period to select this cadence
  • To be able to correctly send out Square Invoices, it required a $1 minimum so we had to adjust the subscription amount to meet this threshold (for demo purposes only)

The Google Calendar invites feature was also much more difficult to build than we had initially expected because the API was fairly restricted and required authentication for most use cases. Though we did build a small working prototype with the API version, we eventually decided to opt for the email markup version with automatic calendar event creation, but for now this only works when sending/receiving from the same email (until we get special approval from Google...update: we just received Google approval for this but it may take up to 3 weeks to take effect).

When it came to designing the ordering flow, we faced quite a predicament. We needed to make sure the feature solved the initial highly specific use case for bakery ordering while also remaining flexible enough to be used by other types of businesses. We wanted to make sure the same feature could be used to set up a “routine” daily order (e.g. daily coffee or workplace lunch), schedule a weekly subscription box (e.g. CSA box or farmer’s market pickup), or set up an X-of-the-month club (e.g. beer-of-the-month at breweries or pie-of-the-month at bakeries). To accommodate different lead time requirements, we added a flexible cancellation deadline and allowed support for different frequencies based on Square’s Subscription feature. We soon found that different frequencies required different daily scheduling so for now we decided to only support daily, weekly, and monthly, but with additional customization around which day(s) and which week(s) to schedule fulfillment.

Finally, one of the biggest challenges we faced was scope creep – since there are approximately 12 gajillion possible iterations and extensions of this feature, we had to practice extreme restraint and ruthlessly prioritize what we wanted to build. For example, while it would have been awesome to also allow pickup times, we decided to limit complexity around scheduling specific time windows so we default all pickup times to the store’s opening time – we plan to add pickup time selection as a fast follow update. See the “What’s next” section below for the partial list of the tempting avenues we resisted.

Accomplishments that we're proud of

We were proud to take on what felt like a challenging problem with a large problem space. We managed to find a good balance between adding new features and prioritizing the most important functionality to come away with something that feels like a viable solution.

As with most new features we build, we were proud to put our merchants first – we put our own opinions aside and took the time to do bottom-up market research to spec and build something that would actually be useful. Instead of simply copying from existing subscription models designed more for the e-commerce scenario, we started from the core problem and worked backwards from there. By taking this more creative approach, we found ways to build this feature to accommodate various business types. Working closely with our merchants allowed us to focus on solving the subtle but very real pain points like setting deadlines to allow proper lead time and helping forgetful customers remember their fulfillment dates – solved by choosing an easy-to-remember day of the month (1st, 2nd, 3rd, or last) and by sending out calendar invites in the confirmation email.

We also dove headfirst into new territory by using the unfamiliar Subscriptions API and worked together as a team to figure it all out. Despite these unknown elements, we maintained a spirit of fun throughout without worrying too much about end results or feeling limited by the API.

What we learned

The first lesson we learned was that subscription models, though popular and widely used today, are still a major undertaking and become especially difficult when trying to solve for pickup fulfillments (as opposed to delivered subscriptions). The cacophony of reminders, texts, calendar invites, and phone calls needed to get this working properly makes subscription home deliveries look like a piece of cake.

We also learned how to use some new technologies – 1) the Square Subscriptions/Invoices APIs with all the benefits (and limitations); 2) how to use shared cards on file saved from the Web Payments SDK when building for a long-term delayed ordering scenario 3) how airlines and ticketing agencies use Gmail’s developer tools like Event Reservations with Microdata to create those cool email header items and auto-generate calendar invites; 4) how to send nicely formatted Mailgun messages using either raw HTML or dynamically-filled templates.

Finally, we learned more about what we need to build in the future to create more dynamic subscription models that can run on autopilot without causing additional confusion. Most of these enhancements are centered around giving both customers and sellers more advanced subscription management and communication tools – these updates (see What’s next section below) will make the commitment of a subscription more flexible and intuitive for the customer, while helping to automate the process of inventory management, cancellation deadlines, and order fulfillment for the seller.

What's next for Vibe n’ Subscribe

We are excited to release this feature to the public – we plan to add a few more finishing touches then will roll it out for bakeries, food trucks, cafes, catering companies, farmer’s markets, florists and more.

Though we didn’t have much extra time on this project, we will soon be adding time-based inventory, initially focussing on per-day inventory which should be enough for most use cases.

We will also expand the subscription management options to allow customers to temporarily pause, delay, and skip orders (as opposed to simply canceling).

We will also give customers the ability through the My Subscriptions page to edit or update their credit card (especially as a more elegant solution when no future open dates are found).

Eventually, we want to build an integrated checkout where customers can subscribe to certain items while simultaneously completing one-time purchases for the rest.

A popular request has also been the ability to gift the initial phase of a subscription so we’re currently planning to use the initial “trial” phase in the subscriptions API to keep track of these giftable offerings.

While the current implementation focuses on the pickup fulfillment scenario, it will be relatively easy to expand this to accommodate other fulfillment types like delivery and curbside.

We will also allow sellers to customize the text messages that go out to customers using the following four message types:

  • Customer subscribed
  • Last chance cancellation reminder
  • Pickup reminder
  • Ready for pickup

We also plan to add time-specific subscriptions to improve the ordering experience for the routine-centric daily subscribers (e.g. a daily shot of espresso).

Finally, we will integrate this feature with our existing item/category lead time feature to better calculate the first possible fulfillment in a more fine-grained way.

There are many more improvements to be made, but overall, we are quite close to having a production-ready feature that solves the basic use case for F&B subscriptions and we can’t wait to see how sellers begin using this feature in creative and unexpected ways.

Built With

Share this project: