Rename a share link or edit its settings
const url = 'https://api.pixonaut.app/v1/share-links/example';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"designLimit":{"count":50,"period":"day"},"name":"Spring market stand"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://api.pixonaut.app/v1/share-links/example \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "designLimit": { "count": 50, "period": "day" }, "name": "Spring market stand" }'Operation ID: shareLinks.update
Changes a working link’s name or, on a designer link, its design limit and anything it was handed out with, each change audited. The link keeps its id, token and address, so a store’s product page need not change: a visit after the change opens on the new settings, and a design made before keeps what it was made with. A designer link takes every field POST /v1/templates/{id}/designer-links takes, judged as that route judges them, and templateId for the template it opens; what its page shows (the blank and placement, sizes, photos, views, variants, sides, layout and linkedPlacements) is sent whole, and any of it replaces all of it. It is held to the rules a new link is: a side for every placement its blank says an order must print (422 placement_unfilled, naming it), sizes its blank takes (422 variant_row_invalid), a panel layout its blank has (422 unknown_layout), that still fits the blank at the size the link sells (409 layout_out_of_date) and whose canvas is the template’s shape (422 layout_wrong_ratio), and linked sides that print one template (422 linked_templates_differ); its linked groups are kept as a new link keeps them, from its setting or what its blank suggests. Every other field absent is left as it is, and null removes it. Any of them on another kind is refused designer_settings_not_allowed. A name another working link holds is refused share_link_name_taken; a withdrawn or expired link, or one the caller could not have handed out (to a connected store’s integration key, one its store did not hand out), is answered as not found. Nothing is changed when any part is refused.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
The blank it is printed on; with placementId, or a panelLayout.
A designer link’s new design limit; null removes it. Refused design_limit_not_allowed for any other kind.
object
How many designs the link may make in its period.
total counts every design the link made; hour, day and week the last 60 minutes, 24 hours or 7 days, rolling.
How long a designer link works from the change, in days, up to 365; null, until withdrawn. Absent, it keeps its expiry. Refused expiry_fixed_by_state while the link carries state.
The variant the side starts on, by ref: one of variants when it names any.
The view shown first; absent, the side’s first with a photo.
How every side’s form lays out its steps: page, every step on one page, or steps, one step at a time. Absent, each side’s form follows its template’s own form.layout, and is a page when the template names none.
Which of the sides’ placements one design drives, such as a sweater’s sleeves: a preset, or groups of the sides’ placements, a group with a repeat of its own where it repeats apart from the link. The sides of one group print one template. Absent, the groups the blank suggests whose sides print one template; the link keeps the groups it was made with.
object
Whether the shopper may take a placement out of its group and design it on its own. Absent, no.
Groups of your own in place of a preset, each a list of placements, or { placements, repeat } for a group that repeats apart from the link. A mirror left out is the blank’s suggestion, else none.
Placements one design drives, two at least.
object
Whether the placement’s print is mirrored left to right.
The id of one of the blank’s placements.
Placements one design drives, with a repeat of their own: a proof or commit of one of them is held to it.
object
Placements one design drives, two at least.
object
Whether the placement’s print is mirrored left to right.
The id of one of the blank’s placements.
How the group’s design is laid as a repeat, in place of the link’s repeat; null places it once beside a link that repeats.
object
The layouts the shopper may pick, one at least, each once.
Whether the shopper may pick another of modes and another size. Otherwise every design prints as start.
Whether the shopper may place the design once instead (repeat: null). Only with shopperMayChange.
What the design starts as: a repeat in one of modes, or null for placed once, which needs shopperMayTurnOff. A request through the link that names no repeat is made with it.
object
How the tiles are laid: grid lines them up, brick moves every other row along by half a tile, halfDrop moves every other column down by half a tile, and scatter strews them at random places, turns and sizes, arranged by seed.
Which arrangement a scatter draws: another seed is another arrangement of the same tile. Read by scatter only.
The tile’s width in percent of the print area’s width, above 0 and at most 100; the tile keeps the template’s shape. A tile that would print under 10 mm on a side is drawn at 10 mm.
each: every placement is designed on its own. suggested: the groups the blank suggests, such as its sleeves. all: one design drives every placement. Absent with no groups, suggested.
The language a designer link’s page is shown in; null for the workspace’s default. An address copied before that names a language (?lang=) keeps showing it: copy the link’s url again.
The store’s own product photos the design is shown on, in place of the blank’s views.
object
How far the photo’s folds move the design, above 0 and at most 1; absent or null, not at all.
What the menu calls the photo.
The label per customer-facing language, by code: only the languages it has one in. A designer shown in a language left out reads label.
object
The size of the photo the rect is measured in, when it is not the size of the image the url serves; absent, the image’s own.
object
Its height, in pixels.
Its width, in pixels.
Where the print sits in the photo, in the photo’s pixels.
object
Its height, in the photo’s pixels.
Its width, in the photo’s pixels.
From the photo’s left edge, in its pixels.
From the photo’s top edge, in its pixels.
How strongly the photo’s light and shade carry onto the design, from 0 (flat) to 1; absent, the default.
The photo’s address, http or https.
The store’s own name for the way the product is photographed: photos sharing one are one view.
How the design wraps round the product in the photo, a mug or a bottle; absent or null, flat.
object
How far round the product the rect reaches, above 0 and at most 1.
How dark the design turns toward the product’s silhouette, 0 to 1.
The one kind of wrap: an upright round product.
The link’s new name; null removes it. Unique among the workspace’s working links, case aside.
The name of a panel layout of the link’s blankId, in place of placementId: the page draws one design across the layout’s canvas, and each placement it lays out gets its print cut from it, so art runs across the seams. Not with sides or printSizes.
Whether the link’s page draws the placement frame, the ring and corner handles around the shopper’s picture, at rest, as the SDK’s showPlacementFrame does. Absent, the frame shows only while the picture is dragged or sized on the preview.
The blank’s placement it is printed in; with blankId.
Whether the link’s page draws a thin frame around the print area on the product photo, as the SDK’s showPrintAreaFrame does. Absent, no frame.
The sizes the shopper picks from, for a print within its area.
One size in the size menu.
object
The print’s height, in mm.
What the menu calls the size.
The label per customer-facing language, by code: only the languages it has one in. A designer shown in a language left out reads label.
object
The print’s width, in mm.
Whether every side’s design is laid as a repeat of its template, which layouts the shopper may pick, what it starts as, and whether they may change it or turn it off; a linked group with a repeat of its own takes that instead. Absent, each design is placed once and a request through the link naming a repeat is refused. Not with panelLayout.
object
The layouts the shopper may pick, one at least, each once.
Whether the shopper may pick another of modes and another size. Otherwise every design prints as start.
Whether the shopper may place the design once instead (repeat: null). Only with shopperMayChange.
What the design starts as: a repeat in one of modes, or null for placed once, which needs shopperMayTurnOff. A request through the link that names no repeat is made with it.
object
How the tiles are laid: grid lines them up, brick moves every other row along by half a tile, halfDrop moves every other column down by half a tile, and scatter strews them at random places, turns and sizes, arranged by seed.
Which arrangement a scatter draws: another seed is another arrangement of the same tile. Read by scatter only.
The tile’s width in percent of the print area’s width, above 0 and at most 100; the tile keeps the template’s shape. A tile that would print under 10 mm on a side is drawn at 10 mm.
Where a designer link’s page sends the shopper back to, as POST /v1/templates/{id}/designer-links takes it; null removes it, and its state with it. On one of the origins the tenant’s publishable keys are allowed on.
The photo that starts selected, by its place in mockups.
The size that starts selected, by its place in printSizes.
Several sides of one item, a front and a back, each its own template and placement, designed one after the other; then the one-side fields go on each side instead.
object
The blank it is printed on; with placementId, or a panelLayout.
The variant the side starts on, by ref: one of variants when it names any.
The view shown first; absent, the side’s first with a photo.
The side’s own short name, such as front: lowercase letters, digits, - and _, unique within the link.
What the side’s step is called, such as Front.
The label per customer-facing language, by code: only the languages it has one in. A designer shown in a language left out reads label.
object
The store’s own product photos the design is shown on, in place of the blank’s views.
object
How far the photo’s folds move the design, above 0 and at most 1; absent or null, not at all.
What the menu calls the photo.
The label per customer-facing language, by code: only the languages it has one in. A designer shown in a language left out reads label.
object
The size of the photo the rect is measured in, when it is not the size of the image the url serves; absent, the image’s own.
object
Its height, in pixels.
Its width, in pixels.
Where the print sits in the photo, in the photo’s pixels.
object
Its height, in the photo’s pixels.
Its width, in the photo’s pixels.
From the photo’s left edge, in its pixels.
From the photo’s top edge, in its pixels.
How strongly the photo’s light and shade carry onto the design, from 0 (flat) to 1; absent, the default.
The photo’s address, http or https.
The store’s own name for the way the product is photographed: photos sharing one are one view.
How the design wraps round the product in the photo, a mug or a bottle; absent or null, flat.
object
How far round the product the rect reaches, above 0 and at most 1.
How dark the design turns toward the product’s silhouette, 0 to 1.
The one kind of wrap: an upright round product.
The blank’s placement it is printed in; with blankId.
The sizes the shopper picks from, for a print within its area.
One size in the size menu.
object
The print’s height, in mm.
What the menu calls the size.
The label per customer-facing language, by code: only the languages it has one in. A designer shown in a language left out reads label.
object
The print’s width, in mm.
The photo that starts selected, by its place in mockups.
The size that starts selected, by its place in printSizes.
The template’s base id; the link’s own when absent.
The size the side sells, as a value of each option its blank’s print areas change with ({"Size": "XL"}): its proofs and designs are made at that size, and a request naming another is refused. Only on a blank whose print areas change with its size; absent, the shopper’s request names the size.
object
The blank’s variants offered, by ref; empty or absent, all.
The blank’s views the side is shown in; empty or absent, all.
What a designer link carries back to its returnUrl; null removes it. Setting one makes the link one shopper’s visit again: it works for 24 hours from the change.
A designer link’s template, by base id: the one a link with one side opens, and a side naming none. Sent with what the page shows; absent, the link keeps its template.
The size the side sells, as a value of each option its blank’s print areas change with ({"Size": "XL"}): its proofs and designs are made at that size, and a request naming another is refused. Only on a blank whose print areas change with its size; absent, the shopper’s request names the size.
object
The blank’s variants offered, by ref; empty or absent, all.
The blank’s views the side is shown in; empty or absent, all.
Examples
Example
{ "designLimit": { "count": 50, "period": "day" }, "name": "Spring market stand"}Naming, keeping and limiting share links: A link's name
{ "name": "Spring market stand"}Responses
Section titled “Responses”The link as it now stands
object
The brand the link’s page is drawn in; null for the workspace’s default, whichever that is when it opens.
The member who handed it out; null when no member did.
object
The secret key or connected store that handed the link out.
object
sk for a secret key, ik for a connected store; null once the key is gone.
The key’s label, or the store’s; null once the key is gone.
How many designs a designer link may make; null for none.
object
How many designs the link may make in its period.
total counts every design the link made; hour, day and week the last 60 minutes, 24 hours or 7 days, rolling.
At the limit, when the link makes designs again; null below it, and for a total limit.
The designs the limit counts now: one per side approved, in the rolling window.
How many designs a designer link made, one per side approved; null for any other kind.
When the link stops working; null for one that never does.
When its page last opened, to the hour; null for never.
The language the link’s page is shown in, which its url names as ?lang=<locale>; null when it names none, and the page is shown in the workspace’s default language.
The workspace’s name for the link.
Whether a designer link’s page draws the placement frame around the shopper’s picture at rest; false for every other link.
Whether a designer link’s page draws the print area’s frame; false for every other link.
Who handed it out: member; key, a secret key or connected store (createdByKey, null for a key the deployment configures); auto, sent with an order to a custom printshop.
What the link is about; null once it no longer exists.
object
The subject’s name: a template’s name; for a design, the name of its template; for an order, its external reference, null when it has none.
object
The blank its sides are printed on; null for none.
object
Whether the link carries one shopper’s visit (state).
The host its page sends a shopper back to; null for none.
One entry per side, one for a link with one.
object
The sizes its menu offers; empty for none.
object
object
object
The printshop the order went to; null for none.
object
What keeps the page from opening for now: template_paused (it opens again once the template is live), printshop_disconnected; null for nothing.
A designer link’s address, which it keeps: it sits on a store’s page until withdrawn. It carries ?lang=<locale> when the link names a locale. Null for every other kind, whose address is shown once, and for a designer link made before addresses were kept until it is regenerated.
Examples
Example
{ "brandId": null, "createdAt": 1760000000000, "createdBy": { "name": "Alexandra Lind", "userId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" }, "createdByKey": null, "designLimit": { "count": 50, "period": "day", "reopensAt": null, "used": 7 }, "designs": 212, "expiresAt": null, "id": "shl_9a8b7c6d5e4f3a2b1c0d9e8f", "kind": "designer", "lastOpenedAt": 1760400000000, "locale": null, "mayDecide": false, "name": "Spring market stand", "placementFrame": false, "printAreaFrame": false, "returnUrl": null, "source": "member", "subject": { "label": "Student sign", "meta": { "blank": null, "carriesVisit": false, "returnHost": null, "sides": [ { "key": null, "label": null, "printSizes": [ { "heightMm": 297, "label": "A3", "widthMm": 420 } ] } ], "type": "template" }, "warning": null }, "subjectId": "graduation-sign", "url": "https://app.pixonaut.example/h/design/EXAMPLE_designer_link_token_not_a_real_one"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: design_limit_not_allowed, designer_settings_not_allowed, return_url_not_https, return_url_off_store, state_needs_return_url, expiry_fixed_by_state, invalid_input
object
Examples
design_limit_not_allowed
{ "error": "design_limit_not_allowed"}designer_settings_not_allowed
{ "error": "designer_settings_not_allowed"}expiry_fixed_by_state
{ "error": "expiry_fixed_by_state"}invalid_input
{ "error": "invalid_input"}return_url_not_https
{ "error": "return_url_not_https"}return_url_off_store
{ "error": "return_url_off_store"}state_needs_return_url
{ "error": "state_needs_return_url"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: unauthorized
object
Examples
unauthorized
{ "error": "unauthorized"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: origin_forbidden, feature_disabled
object
The feature the tenant does not have. Always sent with feature_disabled.
Examples
feature_disabled
{ "error": "feature_disabled", "feature": "api"}origin_forbidden
{ "error": "origin_forbidden"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: not_found, subject_not_found
object
Examples
not_found
{ "error": "not_found"}subject_not_found
{ "error": "subject_not_found"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: share_link_name_taken, layout_out_of_date
object
The link holding the name. Always sent with share_link_name_taken.
Always sent with layout_out_of_date.
Examples
layout_out_of_date
{ "error": "layout_out_of_date", "reason": "string"}share_link_name_taken
{ "error": "share_link_name_taken", "holderId": "string"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: share_link_name_too_long, unknown_placement, print_size_illegal, placement_unfilled, variant_row_invalid, unknown_layout, layout_wrong_ratio, linked_templates_differ, payload_too_large
object
Sent with payload_too_large.
The size’s place in the side’s menu. Always sent with print_size_illegal.
Always sent with payload_too_large.
The longest name a link may have. Always sent with share_link_name_too_long.
Always sent with placement_unfilled.
With print_size_illegal: too_large: larger than the placement takes. print_size_not_area: smaller than a placement printed across its whole area. wrong_ratio: further from the template’s shape than its tolerance allows. Always sent with print_size_illegal, placement_unfilled, variant_row_invalid, layout_wrong_ratio. With print_size_illegal: one of too_large, print_size_not_area, wrong_ratio.
The side’s key; null on a link with one side. Always sent with print_size_illegal.
Examples
layout_wrong_ratio
{ "error": "layout_wrong_ratio", "reason": "string"}linked_templates_differ
{ "error": "linked_templates_differ"}payload_too_large
{ "error": "payload_too_large", "maxBytes": 0}placement_unfilled
{ "error": "placement_unfilled", "placement": "string", "reason": "string"}print_size_illegal
{ "error": "print_size_illegal", "index": 0, "reason": "too_large", "side": "string"}share_link_name_too_long
{ "error": "share_link_name_too_long", "maxLength": 0}unknown_layout
{ "error": "unknown_layout"}unknown_placement
{ "error": "unknown_placement"}variant_row_invalid
{ "error": "variant_row_invalid", "reason": "string"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Refused: db_error. A request that failed unexpectedly answers as text instead.
object
Examples
db_error
{ "error": "db_error"}Headers
Section titled “Headers”Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.
Questions? Write to [email protected].