Building a custom storefront

What a custom storefront means

Instead of using the app’s widget, you read the app’s data and build the UI yourself, so the result matches your site’s design in ways the widget cannot.

When this is useful

You want a dedicated coupon list page rather than a popup
You want to change the popup design substantially
You connect Shopify to an external service and want the coupon list rendered there

Before you start

We cannot answer detailed code questions, because the specifics depend on your theme
This work is chargeable

Please ask the agency you work with.We can also introduce an agency if you would like. Get in touch and let us know.

The rest of this page is written for Shopify agencies and engineers.

Implementation guide

Coupons that have not started yet or have already ended are hidden by the app blocks (theme, account page and checkout) themselves, which check the dates each time they render. The metafield can contain coupons that have not started yet, so if you build your own UI, you must add the same check. See “What your implementation needs to handle” below.

Overview

Discount Deck stores each customer’s coupon data compressed in a Shopify customer metafield. Compression: gzip, then Base64 encoding, with shortened field names.

Metafield

namespace: discount-deck
key: discount-code-list (the same for every extension)
type: json

Example of the stored value

{
  "c": "H4sIAAAAAAAAA6WSzW6DMBCEXyXyGaq1FwL4lqTKoZemooeqVQ8WsailxKAAVaMo..."
}

Requirements

Required library

pako.js, a gzip compression and decompression library.

Setup with npm (React / TypeScript)

npm install pako
npm install --save-dev @types/pako

import * as pako from 'pako';

Run those two commands to install it.

Data flow

Steps on the frontend

Read the compressed value from the metafield
Base64-decode it, then gunzip it
You now have JSON with shortened field names
Leave out coupons that have not started or have ended, then render them (see “What your implementation needs to handle” below)

Data at each stage

1. Compressed data (as stored in the metafield)

This is what you read from the metafield. It is gzipped and Base64-encoded.

{
  "c": "H4sIAAAAAAAAA6WSzW6DMBCEXyXyGaq1FwL4lqTKoZemooeqVQ8WsailxKAAVaMo..."
}

2. Shortened data (after gunzip)

Base64-decoding and gunzipping returns JSON whose field names are shortened. Important: see the key mapping table under Reference for what each shortened key means.

What your implementation needs to handle

After decoding the metafield, the app blocks do the following in the browser. If you build your own UI, please do the same.

Hide coupons that have not started or have ended (required)

A coupon is written to the metafield as soon as it is set to be displayed, even if its start date is still in the future. Right before rendering, keep only the coupons that meet both of these conditions at the current time:

The start date sa is now or earlier
The end date ea is null (no expiry), or now or later

// data is the JSON after gunzip (still using the shortened keys)
const now = Date.now();
const visibleDiscounts = data.d.filter((discount) =>
  new Date(discount.sa).getTime() <= now &&
  (!discount.ea || new Date(discount.ea).getTime() >= now)
);

sa and ea are ISO 8601 strings. Convert them to dates before comparing rather than comparing the strings.

Reading the data

In a theme, read it with Liquid as customer.metafields.discount-deck.discount-code-list. In a customer account extension, read it through the Customer Account API. The app blocks read it the same way
Coupons cannot be read for customers who are not logged in. The app blocks show a prompt to log in instead
When there is no metafield, or no coupons are left after filtering, show a message such as “No available coupons”

Reference

Key mapping

The shortened keys used in the metafield data.

Short key	Original field	Description
p	imagePrefix	Image URL prefix (top level)
d	discounts	Array of discount data
i	id	Discount ID
t	title	Coupon title (used as the coupon code)
ty	typeName	Discount type (shortened)
ao	appliesOncePerCustomer	Applies once per customer (0/1)
ac	allCustomers	Applies to all customers (0/1)
sa	startsAt	Start date and time (ISO 8601)
ea	endsAt	End date and time (ISO 8601, nullable)
ip	imageUrlPc	Desktop image URL (file name only)
is	imageUrlSp	Mobile image URL (file name only)
desc	description	Description
n	note	Notes
vt	valueType	Discount value type (shortened)
p	percentage	Discount rate (inside each coupon; a decimal, `0.1` means 10%)
a	amount	Discount amount
cc	currencyCode	Currency code (shortened; currencies not in the table below keep their original code, such as `KRW`)

Type mapping

Discount type (ty)

Short form	Original type	Description
DCB	DiscountCodeBasic	Basic discount code
DCBX	DiscountCodeBxgy	Buy X Get Y coupon
DCFS	DiscountCodeFreeShipping	Free shipping coupon
DCA	DiscountCodeApp	App-linked coupon

Discount value type (vt)

Short form	Original type	Description
DP	DiscountPercentage	Percentage discount
DA	DiscountAmount	Fixed amount discount

Currency code (cc)

Short form	Original code	Currency
J	JPY	Japanese yen
U	USD	US dollar
E	EUR	Euro
G	GBP	British pound
C	CAD	Canadian dollar
A	AUD	Australian dollar

Discount Deck

MultiLikes

User Tag Plus

LLMs.txt Generator

AI MCP ChatBot

Enterprise plan

Consulting plan

Company

What a custom storefront means

When this is useful

Before you start

Implementation guide

Overview

Metafield

Example of the stored value

Requirements

Required library

Setup with npm (React / TypeScript)

Data flow

Steps on the frontend

Data at each stage

1. Compressed data (as stored in the metafield)

2. Shortened data (after gunzip)

What your implementation needs to handle

Hide coupons that have not started or have ended (required)

Reading the data

Reference

Key mapping

Type mapping

​What a custom storefront means

​When this is useful

​Before you start

​Implementation guide

​Overview

​Metafield

​Example of the stored value

​Requirements

​Required library

​Setup with npm (React / TypeScript)

​Data flow

​Steps on the frontend

​Data at each stage

​1. Compressed data (as stored in the metafield)

​2. Shortened data (after gunzip)

​What your implementation needs to handle

​Hide coupons that have not started or have ended (required)

​Reading the data

​Reference

​Key mapping

​Type mapping

What a custom storefront means

When this is useful

Before you start

Implementation guide

Overview

Metafield

Example of the stored value

Requirements

Required library

Setup with npm (React / TypeScript)

Data flow

Steps on the frontend

Data at each stage

1. Compressed data (as stored in the metafield)

2. Shortened data (after gunzip)

What your implementation needs to handle

Hide coupons that have not started or have ended (required)

Reading the data

Reference

Key mapping

Type mapping