Use the AI sign designer without the customer customiser
Connect a form builder or your own customiser to the AI sign designer API, and get production files for neon, channel letter, and metal cut-out signs.
Use this guide to add the AI sign designer to your store without the Sign Customiser customer customiser. A shopper uploads a logo in your form or in your own customiser. Your server sends the logo to the AI sign designer API. The API gives a preview and the production files: an SVG, an EPS, an Illustrator-compatible PDF and a DXF in millimetres.
This guide has two examples:
- Example 1: a form builder. A Tally form sends each submission to your server. Your server makes a design and sends the files to your team.
- Example 2: your own customiser. Your own customiser for metal cut-out signs shows the AI design to the shopper and adds it to the cart.
The two examples use the same code for neon signs and channel letter signs. Change one value, product_family. See Neon and channel letter signs.
How it works
- The shopper uploads a logo in your form or your customiser.
- Your server declares the file to the API and uploads the file.
- Your server starts a design job. The job holds one credit.
- Your server reads the job until the design is ready.
- Your server gives the preview to the shopper, and the production files to your team or your manufacturer.
The customer customiser sends storefront JavaScript events such as signCustomiserAiLogoCompleted. Without the customer customiser, these events do not occur. Your server reads the job status from the API instead. The job status is the signal that the design is ready.
Before you start
- Read the AI sign designer quickstart. It shows each request with
curl. - Create a key with the
ai_sign_designs:readandai_sign_designs:writescopes. Go to Tools & Settings > API Tokens in the Store. - Make sure that the Store has AI credits. Each design that the AI sign designer delivers uses one credit. A design that fails uses no credit.
- You need a server. The examples use Node.js 20 or later and Express.
The AI sign designer sends the image to external AI image providers to make the design.
Rules for all integrations
- Keep the API key on your server. Never put the key in theme code, in a form or in a browser. Anyone who has the key can spend the credits of the Store.
- Protect the credits. A public form or a public upload button lets anyone start a design. Add spam protection, and set a limit for each shopper and for each day on your server.
- Expect to wait. A design is not ready at once. Read the job again after the number of seconds in
poll_after_seconds. - Expect a busy response. The API limits the number of jobs that a Store can run at the same time. When the limit is full, the API sends 429
ai_sign_design_capacity_reached. Wait for the time inRetry-After, then send the same request with the sameIdempotency-Key. - Give production files only to your team. Show the shopper the PNG preview. Keep the SVG, EPS, PDF and DXF links for your team and your manufacturer.
- Know the size of each file. The DXF is drawn in millimetres at
result.assessed_dimensions. The SVG, EPS and PDF are not drawn at the physical size of the sign. Scale them toresult.assessed_dimensions.
The API client
The two examples use this module. Save it as sign-customiser.mjs on your server. Set the SIGN_CUSTOMISER_API_KEY environment variable to your key.
// sign-customiser.mjsimport { randomUUID } from "node:crypto";import { setTimeout as sleep } from "node:timers/promises";
const API_BASE = process.env.SIGN_CUSTOMISER_API_BASE ?? "https://web.signcustomiser.com";const API_KEY = process.env.SIGN_CUSTOMISER_API_KEY;
// The file types that the AI sign designer accepts, and their size limits.export const SOURCE_TYPES = { "image/png": { extension: ".png", maxBytes: 5_242_880 }, "image/jpeg": { extension: ".jpg", maxBytes: 5_242_880 }, "image/webp": { extension: ".webp", maxBytes: 5_242_880 }, "image/avif": { extension: ".avif", maxBytes: 5_242_880 }, "image/svg+xml": { extension: ".svg", maxBytes: 5_242_880 }, "application/pdf": { extension: ".pdf", maxBytes: 26_214_400 },};
const CONVERSIONS = ["eps", "illustrator_pdf", "dxf"];
export class SignCustomiserError extends Error { constructor(response, problem) { super(problem.detail ?? problem.title ?? `HTTP ${response.status}`); this.status = response.status; this.code = problem.code; this.retryAfterSeconds = Number( response.headers.get("Retry-After") ?? problem.retry_after ?? 30, ); }}
async function callApi(method, path, { body, idempotencyKey } = {}) { const headers = { Accept: "application/json", Authorization: `Bearer ${API_KEY}`, }; if (body !== undefined) headers["Content-Type"] = "application/json"; if (idempotencyKey !== undefined) headers["Idempotency-Key"] = idempotencyKey;
const response = await fetch(new URL(path, API_BASE), { method, headers, body: body === undefined ? undefined : JSON.stringify(body), }); const payload = await response.json(); if (!response.ok) throw new SignCustomiserError(response, payload); return payload.data;}
// Refuse a file that the API cannot accept, before you spend a request.export function checkSource(contentType, byteSize) { const type = SOURCE_TYPES[contentType]; if (!type) return `The AI sign designer does not accept ${contentType} files.`; if (byteSize > type.maxBytes) return "The file is too large."; return null;}
// Declare the file, upload it and start a design job. The job holds one credit.export async function startDesign({ bytes, contentType, productFamily }) { const problem = checkSource(contentType, bytes.byteLength); if (problem) throw new Error(problem);
const source = await callApi("POST", "/api/v3/ai-sign-design-sources", { idempotencyKey: randomUUID(), body: { filename: `logo${SOURCE_TYPES[contentType].extension}`, content_type: contentType, byte_size: bytes.byteLength, }, });
// Use the method and every header of the upload target. const target = source.upload_target; const upload = await fetch(target.url, { method: target.method, headers: target.headers, body: bytes, }); if (!upload.ok) throw new Error(`The upload failed with HTTP ${upload.status}.`);
// Keep the same key and body for each attempt. Then a retry never holds a second credit. const jobKey = randomUUID(); const body = { source_file: { id: source.id }, product_family: productFamily }; for (let attempt = 1; ; attempt += 1) { try { return await callApi("POST", "/api/v3/ai-sign-design-jobs", { idempotencyKey: jobKey, body, }); } catch (error) { const busy = error instanceof SignCustomiserError && error.status === 429; const networkFailure = error instanceof TypeError; if ((!busy && !networkFailure) || attempt === 20) throw error; await sleep((busy ? error.retryAfterSeconds : 5) * 1000); } }}
export function readJob(jobId) { return callApi("GET", `/api/v3/ai-sign-design-jobs/${jobId}`);}
// A delivered design can still convert its EPS, PDF and DXF files.function conversionsRunning(job) { const files = job.result?.files ?? {}; return ["svg", ...CONVERSIONS].some((kind) => ["pending", "processing"].includes(files[kind]?.state), );}
// Read the job until the design failed, or until it is delivered with all its files.export async function waitForDesign(jobId) { for (;;) { const job = await readJob(jobId); if (job.status === "failed") return job; if (job.status === "delivered" && !conversionsRunning(job)) return job; await sleep((job.poll_after_seconds ?? 5) * 1000); }}
// Convert a failed EPS, PDF or DXF again. This is free and uses no credit.// A file with `retryable: false` can never be made, so it is not sent again.export async function retryFailedConversions(job) { const files = job.result?.files ?? {}; const failed = CONVERSIONS.filter( (kind) => files[kind]?.state === "failed" && files[kind].error?.retryable, ); if (failed.length === 0) return job;
await callApi("POST", `/api/v3/ai-sign-design-jobs/${job.id}/exports`, { idempotencyKey: randomUUID(), body: {}, }); return waitForDesign(job.id);}
// The no-login links of the ready files. Give them to your team or your manufacturer.export function readyFiles(job) { const files = job.result?.files ?? {}; const links = {}; for (const kind of ["svg", ...CONVERSIONS, "raster_preview", "face_svg"]) { if (files[kind]?.state === "ready") links[kind] = files[kind].download_url; } return links;}Each download_url needs no API key and no login. Each request to the link sends a new short-lived download, so you can keep the link and use it later.
Example 1: a form builder
In this example, a Tally form collects the logo. Tally sends each submission to your server with a webhook. Your server makes the design and sends the files to your team. The shopper does not need to wait on the page.
1. Make the form
Make a Tally form with these questions. The server finds each question by its label, so use the same labels.
| Label | Question type | Notes |
|---|---|---|
Logo | File upload | Accept one file. |
Sign type | Dropdown | Add the options Neon, Channel letter and Metal cut-out. |
Email | The shopper’s email address. |
2. Add the webhook
- In the form, open Integrations and select Webhooks.
- Set the endpoint URL to
https://your-server.example.com/webhooks/tally. - Add a signing secret. Save the same value in the
TALLY_SIGNING_SECRETenvironment variable on your server.
Tally waits 10 seconds for a 2XX response. If your server does not answer in time, Tally sends the submission again later. Thus, your server answers at once and makes the design after it answers.
3. Receive the submission
// tally-webhook.mjsimport { createHmac, timingSafeEqual } from "node:crypto";import express from "express";import { readyFiles, retryFailedConversions, startDesign, waitForDesign,} from "./sign-customiser.mjs";
// The Tally dropdown options, and the product family of each.const SIGN_TYPES = { Neon: "neon", "Channel letter": "channel_letter", "Metal cut-out": "metal_cut_out",};
// Replace this with a table in your database, so that a restart keeps it.const receivedSubmissions = new Set();
const app = express();app.use(express.json({ limit: "1mb" }));
app.post("/webhooks/tally", (req, res) => { if (!hasValidSignature(req)) return res.sendStatus(401);
const submission = req.body.data; // Tally can send the same submission again. Make one design for each submission only. if (receivedSubmissions.has(submission.submissionId)) return res.sendStatus(200); receivedSubmissions.add(submission.submissionId);
res.sendStatus(200); makeDesign(submission).catch((error) => { console.error(`Submission ${submission.submissionId} failed:`, error); });});
// Tally signs the JSON payload with SHA-256 and your signing secret.function hasValidSignature(req) { const expected = createHmac("sha256", process.env.TALLY_SIGNING_SECRET) .update(JSON.stringify(req.body)) .digest(); const received = Buffer.from(req.get("tally-signature") ?? "", "base64"); return received.length === expected.length && timingSafeEqual(received, expected);}
function field(submission, label) { return submission.fields.find((candidate) => candidate.label === label);}
app.listen(3000);4. Make the design
Add this function to tally-webhook.mjs. It downloads the logo from Tally and starts the design. Then it waits for the files and sends them to your team.
async function makeDesign(submission) { const logo = field(submission, "Logo").value[0]; const signType = field(submission, "Sign type"); const option = signType.options.find((item) => item.id === signType.value[0]); const productFamily = SIGN_TYPES[option.text]; const email = field(submission, "Email").value;
const download = await fetch(logo.url); if (!download.ok) throw new Error(`Tally sent HTTP ${download.status}.`); const bytes = Buffer.from(await download.arrayBuffer());
const job = await startDesign({ bytes, contentType: logo.mimeType, productFamily }); const design = await retryFailedConversions(await waitForDesign(job.id));
if (design.status === "failed") { // No credit is used. Make the design manually, or ask the shopper for a different file. return notifyTeam(`The AI design for ${email} failed: ${design.error.code}`); }
const files = readyFiles(design); const size = design.result.assessed_dimensions; return notifyTeam( [ `New ${option.text} design for ${email} (job ${design.id})`, size ? `Assessed size: ${size.width_cm} × ${size.height_cm} cm` : "No assessed size", `Preview: ${files.raster_preview ?? "none"}`, `SVG: ${files.svg}`, `EPS: ${files.eps ?? "not ready"}`, `PDF: ${files.illustrator_pdf ?? "not ready"}`, `DXF (mm, at the assessed size): ${files.dxf ?? "none"}`, ...design.result.advisories.map((advisory) => `Check: ${advisory.detail}`), ].join("\n"), );}notifyTeam is your own function. It can send an email, a Slack message or a task in your order system. You can also send the preview link to the shopper and ask for approval.
In this example, makeDesign runs in the same process as the webhook. If the process stops, a design that is in progress stops too. For production, put each submission in a queue. Then let a worker make the design.
Other form builders
The same steps apply to other form builders that send a webhook with the uploaded file:
- Make sure that the request comes from the form builder.
- Answer the webhook at once, and make one design for each submission only.
- Download the uploaded file. Some form builders need an API token to download a file. Read the documentation of your form builder.
- Send the bytes to
startDesignwith the media type of the file.
Example 2: your own customiser
In this example, the store has its own customiser for metal cut-out signs. The shopper uploads a logo, sees the AI design, selects a width and adds the sign to the cart. The production files go to the manufacturer after the order.
The browser never calls the Sign Customiser API. It calls two routes on your server:
| Route | What it does |
|---|---|
POST /sign-designs | Receives the logo and starts a design. |
GET /sign-designs/:id | Gives the status and the preview to the browser. |
On Shopify, send these requests through an app proxy or through a server that allows your store’s origin with CORS.
1. Add the server routes
// sign-designs.mjsimport { randomUUID } from "node:crypto";import express from "express";import { SOURCE_TYPES, checkSource, readJob, startDesign } from "./sign-customiser.mjs";
// Change this value to "neon" or "channel_letter" for a different sign.const PRODUCT_FAMILY = "metal_cut_out";
// Replace this with a table in your database.const designs = new Map();
const app = express();
app.post( "/sign-designs", express.raw({ type: Object.keys(SOURCE_TYPES), limit: "25mb" }), (req, res) => { // Add spam protection and a limit for each shopper here. Each design uses one credit. const contentType = req.get("content-type"); const bytes = Buffer.isBuffer(req.body) ? req.body : Buffer.alloc(0); const problem = checkSource(contentType, bytes.length) ?? (bytes.length === 0 ? "Upload a logo." : null); if (problem) return res.status(422).json({ message: problem });
const id = randomUUID(); const design = { jobId: null, failed: false }; designs.set(id, design);
// Answer at once. startDesign waits when the Store has too many jobs. startDesign({ bytes, contentType, productFamily: PRODUCT_FAMILY }) .then((job) => { design.jobId = job.id; }) .catch((error) => { console.error(`Design ${id} did not start:`, error); design.failed = true; });
res.status(202).json({ id }); },);
app.get("/sign-designs/:id", async (req, res) => { const design = designs.get(req.params.id); if (!design) return res.sendStatus(404); if (design.failed) return res.json({ status: "failed" }); if (!design.jobId) return res.json({ status: "queued" });
const job = await readJob(design.jobId); const preview = job.result?.files.raster_preview; const size = job.result?.assessed_dimensions;
// Send only what the shopper needs. Do not send the SVG, EPS, PDF or DXF links. res.json({ status: job.status, jobId: job.id, previewUrl: preview?.state === "ready" ? preview.download_url : null, widthCm: size?.width_cm ?? null, heightCm: size?.height_cm ?? null, });});
app.listen(3000);2. Start the design in the browser
Add this code to your customiser. It sends the file to your server, then reads the status until the design is ready.
async function designFromLogo(file) { const started = await fetch("/sign-designs", { method: "POST", headers: { "Content-Type": file.type }, body: file, }); const { id, message } = await started.json(); if (!started.ok) throw new Error(message);
for (;;) { await new Promise((resolve) => setTimeout(resolve, 3000)); const design = await (await fetch(`/sign-designs/${id}`)).json(); if (design.status === "delivered" || design.status === "failed") return design; }}Show a progress message while the shopper waits. When status is failed, show your own fallback. For example, show a quote form or ask for a different file. The customer customiser does the same with its fallback form.
3. Show the preview and the size
When status is delivered, show previewUrl in an <img> element. Use widthCm and heightCm to keep the shape of the sign when the shopper selects a width.
function heightForWidth(design, widthCm) { if (!design.widthCm || !design.heightCm) return null; return Math.round((widthCm * design.heightCm) / design.widthCm * 10) / 10;}widthCm and heightCm come from assessed_dimensions. This is the size at which the AI sign designer checked the design for manufacturing. It is not a promise that you can make the design at a different size. Use your own rules to check the minimum width of cut details and the price of each size.
4. Add the sign to the cart
Add the design to the cart with the selections of the shopper. This example uses the Shopify Ajax Cart API. Keep the job ID in a property that starts with an underscore. Shopify does not show these properties to the shopper at checkout.
async function addSignToCart({ variantId, design, widthCm, heightCm, material }) { const response = await fetch("/cart/add.js", { method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json" }, body: JSON.stringify({ items: [ { id: variantId, quantity: 1, properties: { "Width (cm)": widthCm, "Height (cm)": heightCm, Material: material, Preview: design.previewUrl, _ai_sign_design_job: design.jobId, }, }, ], }), }); if (!response.ok) throw new Error("The sign was not added to the cart.");}If your theme listens for a cart event, dispatch that event after this request. The customer customiser does not run here, so it does not send signCustomiserProductAddedToCart.
5. Send the files after the order
When your server receives the order, for example with the Shopify orders/create webhook, read the job ID from each line item. Then get the production files.
import { readyFiles, retryFailedConversions, waitForDesign } from "./sign-customiser.mjs";
export async function productionFilesForLineItem(lineItem) { const property = lineItem.properties.find((item) => item.name === "_ai_sign_design_job"); if (!property) return null;
// The shopper can change cart properties. Accept only a job that your server started. // isJobFromYourServer is your own function. It looks for the job ID in your database. if (!(await isJobFromYourServer(property.value))) return null;
const design = await retryFailedConversions(await waitForDesign(property.value)); if (design.status !== "delivered" || !design.result) return null;
return { files: readyFiles(design), assessedDimensions: design.result.assessed_dimensions, advisories: design.result.advisories, };}Send the files and the size of the line item to your manufacturer. Read advisories before you send a design to production.
For metal cut-out signs, the DXF is the cut outline in millimetres. It is drawn at the assessed width, not at the width that the shopper selected. Scale it in your CAD or CAM software by the line item width divided by assessedDimensions.width_cm. For example, scale a design with an assessed width of 50 cm by 1.6 for an 80 cm sign. After you scale it, make sure that the smallest cut details are still large enough for your machine.
Neon and channel letter signs
The two examples work for each product family. Change product_family only. The steps, the credit and the files are the same.
| Sign | product_family | Notes |
|---|---|---|
| LED neon | neon | Read result.display_treatment. When it is drawn, the SVG has the neon tubes as lines and face_svg has the printed face under the tubes. The two files use the same viewBox, so you can put one on the other. The DXF is the outline of each tube at real size, a 1:1 layout template. It is not a cut file. |
| Channel letter | channel_letter | The DXF is the letter outline that a cutter follows. Use the SVG, EPS or PDF as the letter artwork. |
| Metal cut-out | metal_cut_out | The DXF is the cut outline. Use the SVG, EPS or PDF as the artwork. |
GET /api/v3/ai-sign-design-capabilities gives the families that your Store can use in data.product_families. This list can get more values. Make sure that your code accepts a value that it does not know.
If the Store also has a Sign Customiser customiser for the same product, you can send customiser_id in place of product_family. Then the AI sign designer uses the manufacturing settings of that customiser. The key also needs the customisers:read scope.
Only make the files that you need
The job makes an SVG, an EPS, a PDF and a DXF by default. To make only some of them, add output_formats to the job body in startDesign. This example makes the SVG and the DXF only:
const body = { source_file: { id: source.id }, product_family: productFamily, output_formats: ["svg", "dxf"],};The SVG is always made. The EPS, the PDF and the DXF are made from the SVG. To make only the SVG, send ["svg"].
When something fails
| Response or state | What to do |
|---|---|
409 insufficient_credits | Add credits to the Store. Until then, show your fallback to the shopper. |
429 ai_sign_design_capacity_reached | The Store has too many jobs in progress. startDesign waits for the time in Retry-After and sends the same request again. |
429 rate_limited | Your server starts too many jobs in one minute. Wait for the time in Retry-After. |
503 ai_sign_designer_unavailable | The AI sign designer is not available for the Store now. Show your fallback. |
Job status is failed with error.code source_rejected | The AI sign designer could not read the file. No credit is used. Ask the shopper for a different file. |
Job status is failed with error.code design_failed | The AI sign designer did not make a design. No credit is used. Make the design manually. |
files.eps.state, files.illustrator_pdf.state or files.dxf.state is failed and error.retryable is true | retryFailedConversions converts the file again for free. Each job has 3 retries. The SVG stays ready. |
files.dxf.error.code is dxf_size_unknown | The AI sign designer did not assess a size, so it cannot draw the DXF at real size. Convert the SVG to a DXF in your CAD or CAM software. A retry does not help. |
files.dxf.error.code is dxf_not_writable | The outlines of the design cannot become a DXF. Convert the SVG in your CAD or CAM software. A retry does not help. |
See Errors and retries for all error responses.