Share links

A share link opens one hosted page about one thing to whoever holds it: a designer for a template, a proof page, address capture or a correction for a design, an order status or printshop page for an order. Members hand links out from the studio, your server hands them out with a secret key, and a connected store’s plugin hands them out with its integration key. A member hands out only what they hold themselves; a printshop page needs printshops:update.

A store’s designer link

POST /v1/templates/{id}/designer-links hands out a hosted designer with what the store sells the template on. Its layout fixes how the designer’s form lays out its steps, on every side of the link: page, every step on one page, or steps, one step at a time, as the SDK’s layout does on the store’s own page. Without it each side’s form follows its template’s own layout, and is a page when the template sets none. A designer link from POST /v1/share-links carries no store options, and always follows the template.

A link with sides on a blank may link them: one design then drives the placements of a group, such as a sweater’s sleeves, each still printed at its own print area. linkedPlacements takes a preset (each, suggested for the groups the blank suggests, or all) or groups of the sides’ placements with whether each is mirrored, and designSeparately, whether the shopper may take a placement out of its group. Without it the link links the groups the blank suggests whose sides print one template. The link keeps the groups it was made with; its page reads each side’s group, and a proof of a linked side sends it as linked.

A link may lay every side’s design as a repeat of its template. repeat names the modes the shopper may pick, the start the design opens as (a repeat in one of them, or null for placed once), shopperMayChange, whether they may pick another layout and size, and shopperMayTurnOff, whether they may place the design once instead. A link through a panelLayout takes none. A proof or commit through the link that names no repeat is made with its start; one naming a repeat the link does not offer, or null where the shopper may not turn it off, is refused. Without repeat, the link’s designs are placed once.

A group of the link’s own groups may carry a repeat apart from the link’s: written { "placements": [...], "repeat": {...} } in place of a list of placements, its sides are held to that repeat, and null places them once beside a link that repeats. A sweater’s back and sleeves can so tile while its front, in no group, is placed once. The page reads each side’s repeat where its group carries one.

Editing a designer link

PATCH /v1/share-links/{id} changes a designer link without a new address, so the store’s product page keeps working. It takes every field the mint takes, judged the same way, and templateId for the template it opens. What the page shows (the blank and placement, sizes, photos, views, variants, sides and layout) is sent whole: any of it replaces all of it. Every other field absent is left as it is, and null removes it; expiresInDays counts from the change. The next visit opens on the new settings, and a design made before keeps what it was made with. GET /v1/share-links/{id}/designer answers what the link was handed out with, to start an edit from. Each edit that changes something is recorded in the audit log as share_link.edited, with the fields it changed.

How a link unfurls

Pasted into a chat app or a mail client, a link to a hosted page unfurls with a preview card, by your workspace’s white label. While your pages carry “Powered by Pixonaut”, the card is Pixonaut’s. On a plan that lets you turn the mark off, and once you have, the card is drawn in the brand the link’s page is drawn in: its logo, when it is a PNG or JPEG, and its name on its accent colour, and the preview’s title is the brand’s name. Nothing in it names Pixonaut. The card follows the link as it is when the preview is fetched, so changing a brand changes the card of every link drawn in it; a chat app that already showed a link may keep the card it fetched then.

Links to the studio and to these docs unfurl with Pixonaut’s card.

Finding a link

GET /v1/share-links lists the links that still work, of the kinds the caller may manage, newest first, at most 100 a page. A busy store can hand out thousands of one-visit designer links, so the list narrows:

• kind, and subjectId for the links about one template, design or order.
• source: member for links members handed out, key for any secret key or connected store, a key’s id for that key’s or store’s alone, and auto for the link a custom printshop is sent with each order.
• createdBy=me for the caller’s own.
• carriesVisit=true for the links that carry one shopper’s visit (a store’s state), false for the rest.
• expiresWithin=<days> for the links ending soon, neverExpires=true for those that never do.
• q: text a link’s name, its subject’s name, its id, or the member or key that handed it out holds, case aside.
• sort=expires for the soonest to end first, those that never do last.

The same read answers counts: how many links of each kind, from each source (each key or store named, with members and printshop orders), and carrying a visit, each counted under every filter but its own, so a filter’s choices say what choosing them would show.

What a row says

Beside what the link is, each row says:

• source, and createdByKey: the secret key or connected store that handed it out, by id, name and kind.
• lastOpenedAt: when its page last opened, to the hour; null for never.
• subject.meta: for a designer link, its blank, each side’s sizes, whether it carries a visit and the host it returns its shopper to; a design’s status; an order’s status and printshop.
• subject.warning: template_paused when its template is paused (the link opens again once it is live), printshop_disconnected when its order’s printshop was disconnected.
• On a designer link, designs, how many it made, and designLimit with used and reopensAt, counted as the limit counts them.

Withdrawing links

DELETE /v1/share-links/{id} withdraws one link. POST /v1/share-links/revoke withdraws several: with ids, up to 100, each answered revoked or not_found (unknown, already withdrawn, or not the caller’s to manage); with createdByKeyId, every working link one key or store handed out, answered with the count. The key keeps working and may hand out new links; disconnecting a store withdraws its links with it.

Each link withdrawn, whichever way, is recorded as a share_link.revoked event, and a link given a new address (POST /v1/share-links/{id}/regenerate) as share_link.regenerated, so a store that kept a link’s address hears by webhook that it no longer opens. The event names the link, its kind, subject and name, and who changed it; never its address. A connected store’s endpoint hears of the links its own keys handed out. A link reaching its expiry, and the links a disconnected store takes with it, record nothing.