Orders

An order is one submission of a print to a printshop. The studio lists every order under Orders, newest first. An order is made when a print is sent to your printshop: a finished one, or one still being made, which the order waits for. An order placed through the API can also name designs in place of their prints, one per side of the item: it makes a new print of each, which costs no credits, and waits for them.

A print is what gets rendered; an order is one attempt to have it made. The two are separate because attempts can be plural: a printshop refuses, you fix the problem, it goes again. One print can have several orders, and when it was printed stays clear.

One item, several prints

An order is one physical item. A shirt printed on the front and the back is one order holding two prints, each a design committed for its own placement on the same blank: the printshop makes it, ships it and charges for it once. The prints of an item may also be on no blank at all, such as a sign’s two faces, which are one item by being ordered together; such an order goes to the printshop the lead’s design was committed to. The first print is the order’s lead, which the order names when it names one print. Your server places such an order with POST /v1/orders; see Front and back on one item. It is refused, and nothing is ordered, when the prints are on different blanks, some are on a blank and some on none, two are in one placement, or the printshop cannot make them as one item. The studio shows every print of an order, and the files of each.

An order can also name designs in place of their prints, one per side of the item. It then makes a new print of each, which costs no credits, and waits for them as Waiting for prints.

The variant ordered

An order names the variant the shopper chose (variant, a ref of one of its blank’s variants), which every print of the item shares. A variant of another blank is refused (variant_not_of_blank), and so is a retired one (variant_retired). A blank with exactly one variant needs none named; one with several refuses an order naming none (variant_required). The printshop is sent what it needs for that variant: Printful its catalogue variant id, a custom printshop the variant fields it declares (see Printshops).

The order keeps a copy of the variant as it was placed — its options and each field it was sent, with whether the value was the variant’s own, the field’s default or empty — and of the printshop’s name. Editing the variant or the printshop later does not change a placed order. A retry orders the variant its failed order did.

Submitting an order

Your server submits a finished print with its secret key (a connected store, with its integration key), and may name the printshop to send it to. Otherwise it goes to the printshop the design was committed to, else the blank’s, else your default (see Printshops). In the studio, New order under Orders, or Order this print file on a finished print file, does the same: it starts on the printshop the print would go to, and you may choose another. Placing an order needs the permission to create orders. A finished print is never sent by itself: it is ordered only when your server or someone in your workspace submits it.

An order says how many copies it wants: its quantity, 1 unless you give another number when you submit it. The number belongs to the order, not the print, so the same print can be ordered again in a different quantity without rendering it again (see Ordering a design again). The studio shows each order’s quantity.

An order can also carry your own reference for it — your order or order line id — and who it is for and where it ships: a recipient (a name, and optionally an email and a phone) and a shipping address. All three go to the printshop on the job ticket, and a printshop you describe yourself can put them in its emails, requests and file names. The studio shows them on the order, and the orders list can be narrowed to one reference. Several orders can share a reference. The recipient and address are personal data: they are kept with the order and never written to logs. When the customer gave them on the design’s address capture page, a design’s first order takes that answer when its request names neither a recipient nor an address.

An order can be sent without a recipient or an address, so it reaches the printshop quickly, and be given one later; an address can be corrected after it was sent too. That works when the order’s printshop takes address changes, until the order ships, fails or is cancelled, and until the printshop is making it. The printshop is told, and the order says what it made of the change: accepted, refused in the printshop’s own words (the order then keeps the address the printshop has), still being sent, or carried by what had not been sent yet. When you ask the customer from the order (Ask the customer…), the link is for that order: their answer changes it the same way, even when the design is ordered again later, and once the order has shipped, will not be made or its details were erased, the page says so and changes nothing. A link handed out for the design alone changes its newest open order. From your own system, see PATCH /v1/orders/{id}/delivery in the API reference. Each change sends an order.delivery_changed webhook, which never carries the address.

Ordering a design again

A design has one live order: an order of it in any status but failed and cancelled, so one held, waiting for its prints, at its printshop, made, shipped, or whose outcome is unknown, since the printshop may have it. Ordering a design that has one is refused, 409 design_already_ordered, naming the design and its newest live order, and nothing is ordered. That holds whoever placed the first order: a connected store at checkout, an automation, or someone in your workspace, and two orders sent at the same moment place one.

To order it again on purpose, say so: the request’s reorder: true places the order whatever orders the design has. In the studio, New order for an ordered design says it was already ordered, links that order, and offers Order again. Replacing a failed order, by retrying it or with replacesOrderId, is not a reorder: the failed order is not live.

An Idempotency-Key covers something else: your own request sent again, which is answered with the order the first one placed (see Placing an order safely).

Shipping to your own address

If you send every item on yourself, from your own office or warehouse, keep those addresses in your workspace’s address book and set Deliver orders to to one of them (from your own system, PATCH /v1/settings/tenant’s deliverOrdersTo). Every new order then ships there, and the customer’s recipient and address stay on the order as who it is finally for. An order can say otherwise when it is placed, with shipToAddressId: another saved address, or null for the customer’s address. The order keeps the saved address it ships to as it was then, so changing or removing the address later does not move it, and an order placed without a customer address still ships there.

The printshop is handed only that address as where to ship: on the job ticket, whose recipient is the address’s name, in a printshop you describe yourself, and as an integration’s recipient. A saved address that Deliver orders to names cannot be removed while it is named. Changing the customer’s address on such an order does not ask the printshop, which still ships to your address.

When a customer asks you to erase their personal data, open the order and choose Erase personal data (or, from your own system, see Erasing personal data). It removes the recipient and the address — the customer’s; a saved address the order ships to is yours and stays — and whatever a printshop you describe yourself had them written into, and keeps the order: its print, status, history, quantity and your reference, which is your own order id and is not erased. The order then says when its data was erased. You can do this once the order has shipped, failed or been cancelled, since until then your printshop may still need the address. It cannot be undone, and it does not reach what the printshop was already sent. It needs the Edit permission on orders, which admins have.

The printshop charges for each order it accepts.

Order status

An order records which printshop it went to, the printshop’s own reference for it (Printshop reference), and where it has got to:

• Held — a free workspace’s order past the orders its plan includes this month (a print’s files got without an order count toward them; see Getting a print’s files), or a paid plan’s past its included orders while its order balance is empty. It is accepted and not sent: it goes on at the start of the next month, oldest first while the new month has room, when a free workspace moves to a paid plan, or, on a paid plan, as soon as orders are added to the balance, and then waits for its prints as below. While it is held you can change its address or cancel it, and no printshop is asked. POST /v1/orders answers it 201 with status: "held" and its hold (the reason, the limit and when the month resets), and the order.held and order.released webhooks report it.
• Waiting for prints — placed before its print files were finished. It goes to the printshop on its own once they are. A print file that could not be made fails it, and so do print files not finished within three hours. While it waits you can change its address or cancel it, and no printshop is asked.
• Submitted — recorded, and on its way to the printshop.
• Queued — the printshop has it.
• Printed — the printshop has printed it.
• Shipped — it is on its way.
• Failed — the printshop could not complete it, or its print files could not be made in time.
• Cancelled — the printshop stopped it before making it, as you asked.
• No answer — see below.

Each change is reported to your webhook endpoints, and the order’s History in the studio lists them. A partner printshop reports progress itself. With a printshop you describe yourself, the order is Queued once every delivery step has arrived. After that, the printshop reports on the order’s own page — printed, shipped, or that it will not make it — which a step links to with {order.pageUrl}, or the order is set by hand through the API.

An order set by hand or by its printshop only moves forward: on to Printed or Shipped, or to Failed while it is still open, never back, and never out of Shipped, Failed or Cancelled. An order with no answer can be moved on once you have asked the printshop; only you can do that, not the printshop’s page. Marking an order failed can say why, which the studio shows as its reason; marking it shipped can give its tracking number, and optionally the carrier and a tracking page.

A partner printshop can report an order shipped before it names the shipment. The tracking then reaches the order after it shipped: the order.tracking_added webhook carries it, and the order’s history shows when it arrived. The order does not move again, so no second order.status_changed is sent and nothing that reacts to it shipping runs twice.

Your printshop can correct a shipped order’s tracking from its order page, when it mistyped the number, carrier or link. The order stays shipped: the order.tracking_changed webhook carries the new tracking and the tracking it replaced, and the order’s history shows the correction. Tracking added to an order that shipped without any is an order.tracking_added.

Cancelling an order

If your customer cancels before the item is made, your server asks the printshop to stop it with POST /v1/orders/{id}/cancel. The order is Cancelled once the printshop says it stopped it. A printshop that has begun the order, or that cannot stop orders, leaves it as it is, and you ask the printshop yourself. An order cannot be marked cancelled by hand: that would stop nothing at the printshop. A cancelled order is final, and a refund is your store’s to make.

Your customer’s order status page

An order status link, handed out from the order in the studio, opens a page where your customer follows the order: where it has got to, its tracking once shipped, and when each step happened. The page re-reads the order every minute while it is open, and says when it last did. It never shows the printshop, its reference, why an order failed, or the recipient and address.

A failed order, or one with no answer, tells the customer to contact you. If you submit a failed order again, the page follows the new order, so the customer sees it move on, with its tracking, without a new link. It follows the order that took the failed one’s place by the same rule as submitting again: a retry of it, or a later order of the same print, copies and reference. An order of other copies or under another reference is a separate order with its own link.

A failed order is a state, not an error

A printshop may turn an order down — out of stock, a problem with the order details. The order is recorded as Failed with the reason, rather than thrown away, so you can see it and act.

A printshop that is briefly unreachable while Pixonaut checks on an order has not refused anything, and does not fail the order.

No answer

If the printshop never answered the submission, Pixonaut cannot know what it did. It may have accepted the order and be making it now. The studio shows this as No answer: “The printshop did not answer, so it may be making this order. Ask the printshop before submitting again.”

It is not a failure, and submitting again could make the product twice.

Once you have asked the printshop, settle it with what it told you. On the order’s page, Mark failed says the printshop does not have it, after which you can submit it again; Mark submitted says it does, and takes the printshop’s order number if it gave you one, so the order is followed from then on. Either asks what the printshop told you, which the audit log keeps with who settled it. You need permission to update orders. A connected store can settle it the same way with PATCH /v1/orders/{id}, and nothing else about an order on your live workspace. An order with no answer that the printshop has given its reference for can also be cancelled.

Submitting again

Submit again creates a new order for the same print; it never changes the old one, and the new order records which one it replaces and wants the same quantity, reference, recipient and address. It goes to the printshop the failed order went to, or is sent to another blank (below). It is allowed only when the failed order:

• is the newest order of its quantity, reference and variant for its print (a later order of another quantity, under another reference or of another variant, is a different job, not this one placed again; one that only corrects the address counts as this one, fixed),
• has not been submitted again already, and
• never reached the printshop.

An order that failed because a print file of it could not be made renders that print file again: the same print file, under the same id, from the design revision it was made from, however the design changed since. The new order waits for it, as an order placed before its print files were finished does, and goes to the printshop once it is ready; if it fails again, so does the order, which can be submitted again in turn. A print file that is still rendering is waited for in the same way. The order’s canRetry says whether submitting it again would be accepted.

A failed order the printshop has on record may still be made there, so ask the printshop before ordering it again. An order with no answer can never be submitted again this way.

Sending a failed order to another blank

When the printshop cannot make an order, it can be sent to another blank of the workspace, at that blank’s printshop: a reroute. Nothing moves: the failed order keeps its blank, and the blank keeps its printshop. The new order replaces the failed one under the rules above, and the failed order’s printshop is not asked.

The prints are not made again, so each must fit the placement it goes to: its trim size within that placement’s largest print, width against width and height against height, and made by the placement’s print method. A print goes to the placement with its own placement’s name; when the blank has none, you pick one it fits. Each placement takes one print. You pick the variant of the new blank, suggested from the order’s own options, and the new printshop is sent its own fields for it.

In the studio, Submit again offers Send to another blank, which lists the blanks the order fits on first and says why the rest do not. Through the API, GET /v1/orders/{id}/reroute-targets lists them, and POST /v1/orders/{id}/retry with reroute sends the order. The order.rerouted webhook names both blanks, variants and printshops.

Order again with changes on a failed order in the studio replaces it with a new order that wants something else: another number of copies, reference, recipient, address or printshop. The new order still records which one it replaces, and is allowed under the same rules.

Ordering a print again through the API is a different thing: it replaces nothing and is always allowed.

Delivery to the printshop

For a printshop you describe yourself, the order page also shows Delivery to the printshop: each step — an email, a request to the shop, an upload to the shop’s server — with its status (Waiting, Delivered or Failed) and its tries. Each step is retried on its own. See Set up a printshop.

Related

• Design to order
• Webhooks guide