What a write also does
AI agents: read /llms.txt; add .md to any page URL. This page as Markdown: /concepts/side-effects.md. Index of every page and the rules for every call: /llms.txt. Guides and concepts in one file: /llms-full.txt. OpenAPI: /openapi.json.
A change made through the API is the same change as one made in the web app. It runs the same rules and has the same effects. Plan for those effects before you automate a change.
Effects that leave YoPrint
Section titled “Effects that leave YoPrint”These can’t be undone from YoPrint. Treat them with the most care.
| Operation | What it also does |
|---|---|
| Sending order details, a payment reminder or an approval reminder (sales order actions) | Emails the customer. |
| Creating an approval, unless you ask to send it later | Emails the customer. |
| Sending an approval to the customer | Emails the customer. |
| Sending a message on an order, or a message template | Emails or texts the recipients. |
| Changing a shipment’s status, on an order synced from Shopify | Can fulfil the order in Shopify. |
| Buying a shipping label | Spends the team’s money with the carrier. |
| Deleting a sales order that has GoShippo labels | Asks Shippo to refund them. |
| Removing a package that has a GoShippo label | Asks GoShippo to void the label and refund it. GoShippo or the carrier can refuse, and YoPrint doesn’t report a refusal. |
| Charging a card through a payment gateway | Charges the customer’s card. |
| Refunding through a payment gateway | Refunds the customer’s card. |
| Changing a published order’s lines, invoices, payments or dates, on a team connected to QuickBooks | Can queue a sync to QuickBooks. |
Messages count toward the team’s email limits. Going over them blocks the whole team’s email. See Limits.
A message on a sales order or quote goes only to that order’s own recipients. Naming a recipient of another record is refused with 422 (participant_not_on_record), and nothing is sent. A recipient’s email address can’t be changed in place either (422, participant_email_immutable): add the new address as a new recipient.
Some operations don’t email, even if you might expect them to: recording a payment through the API doesn’t send a receipt. A payment link isn’t a link sent to the customer either: it allocates payments you received to the order’s invoices.
Effects inside YoPrint
Section titled “Effects inside YoPrint”| When you… | YoPrint also… |
|---|---|
| Add, change or remove order lines | Recalculates the order’s totals, deposit and balance, and rebalances its payments across its invoices. With Auto Invoice on, it also updates the order’s invoice. |
| Delete a sales order or quote | Moves it to the trash, where it can be restored. Deletes its jobs, invoices and shipments, moves a published order’s payments to the customer’s store credit (not on Shopify orders), releases its stock, and fires order.deleted or quote.deleted, drafts included. |
| Publish a sales order or quote | Works out its stock status, and fires order.created or quote.created. |
| Lower a line’s quantity, or delete a line or an order | Releases the stock held for it. |
| Change a published order | Records the change in the order’s history. |
| Change a status | Records it in history and fires the matching status webhook. |
| Record a payment | Logs it in the order’s activity, updates the customer’s totals, and fires the payment webhooks. |
| Change a published order, or its jobs, invoices, shipments, payments or approvals | Refreshes the Customer Portal pages the customer has open, when they can see the order there. This is a live update in the browser, not an email. |
| Create or change a customer or contact | Fires the customer or contact webhook. A new customer is assigned to you. |
Changes are recorded under the API key’s user (your name), just as if you made them directly in the web app.
Webhooks fire for API changes too
Section titled “Webhooks fire for API changes too”Every webhook fires whether the change came from the web app, the API or an AI app. If your integration both changes YoPrint and listens to its webhooks, it will receive events for its own changes. Recognize them, for example by the record’s id, so you don’t react to your own write in a loop. See Receive events with webhooks.
Drafts are quiet
Section titled “Drafts are quiet”A new sales order or quote starts as a draft. While it’s a draft:
- Edits aren’t recorded in the order’s history.
order.createdandquote.createdhaven’t fired yet.- You can’t record payments or buy labels on it.
Publishing it starts all of that. See Draft or published.