PrintNowPrintNowDocs

Working with AI Agents

How an AI agent finds and runs PrintNow tools, chooses a store, asks before changes, handles personal data, files, bulk changes and usage limits, and how its work shows in the Activity Log.

You talk to an agent in plain words. It finds the right PrintNow tool, works in the store you name, and asks for your yes before a risky change. Its changes are recorded in the Activity Log.

Asking an Agent for Work

You do not pick tools. Ask for what you want, for example:

  • "How many orders came in last week on the Main store?"
  • "Export the site users who signed up this month."
  • "Add a 10% promo code for spring that ends on May 31."
  • "Mark order 1204 as shipped with tracking number 1Z999."
  • "Raise every business card price by 5% and show me the preview first."

If no tool fits, the agent tells you the task is done in the admin and names the screen.

How an Agent Works

This section is for the AI agent as much as for you. An agent that reads it can work with PrintNow without guessing.

Start of a Session

A session starts with only the always-on tools. The usual first calls are:

  1. whoami: the person, the license, the connection's access, end date and toolsets, and the stores.
  2. stores_list: each store's id, name, type (retail B2C or B2B), URL, culture, currency and time zone.

A session that is idle for 30 minutes ends. The app reconnects on its own, again with only the always-on tools.

Finding and Running Tools

  1. tools_find searches every toolset the connection may use, including toolsets that are not on yet. It returns the best matches, each with the tool name and its inputs. It also names fitting toolsets that this connection does not have.
  2. toolsets_enable with { "on": ["print-store-orders"] } turns toolsets on. toolsets_list shows which are on.
  3. Claude Code loads the new tools at once. Claude (claude.ai) and ChatGPT keep the tool list from the start of the chat. In those apps, run any tool by name with tool_read (read tools) or tool_write (change tools): { "tool": "<name>", "arguments": { … } }. The tool's toolset turns on by itself.

Messages an agent may get, and what they mean:

MessageWhat to do
"X" is not in this connection's toolsets … The person can add it with a new connection code on the AI agents page.Tell the person. They must make a new connection with that toolset.
… makes changes: call it with tool_writeCall it again with tool_write.
… only reads: call it with tool_readCall it again with tool_read.
this connection can only readThe connection is Read only. The person must connect again with Read and write.

The agent can only use PrintNow's named tools. It cannot call admin URLs. See the AI Agent Tool Reference for every tool.

Choosing a Store

  • Every store-level tool needs a storeId from stores_list. There is no default store.
  • A store that is not on the list gives "Store N is not one of this user's stores. Call stores_list."
  • When a request could fit more than one store, the agent asks which store, or the person names it.
  • Some areas are shared by every store on the license. A change there affects all stores: attribute sets, site themes, editor colors, fonts and artwork, and 3D materials.

Dates

Dates without a time zone are read as UTC. Name the time zone when it matters.

Send Only What Changes

For a save tool, send only the fields to change. PrintNow reads the record, keeps the other fields, and saves the whole record. A field that shows a masked value (•••) cannot be sent back: "Refused: … holds a masked value (•••)". Leave it out to keep the stored value.

Storefront Cache

The storefront shows changes within up to 15 minutes. To show them at once, the agent can call cache_clear.

Toolsets

Toolsets are the areas of the admin an agent may use. You choose them when you make the connection code. All toolsets means every toolset your license has. Toolsets your license does not have are hidden.

GroupToolsetShort name
GeneralAll Sitesall-sites
Print StoreStore setupprint-store-setup
Categories, Collections, Tagsprint-store-catalog
Productsprint-store-products
Attribute Setsprint-store-attribute-sets
Pricingprint-store-pricing
Dielinesprint-store-pricing-dielines
4over and Sinalite pricingprint-store-pricing-vendors
Ordersprint-store-orders
Dashboards and Reports (read only)print-store-reports
Contentprint-store-content
Site Themesprint-store-site-themes
Settingsprint-store-settings
Checkout Settingsprint-store-checkout-settings
Shipping Settingsprint-store-shipping-settings
Domain Toolsprint-store-domain-tools
Site Users and Organizationsprint-store-customers
User Groupsprint-store-user-groups
Admin Users and Roles (read only)print-store-admin-users
Print EditorArtwork and Elementsprint-editor-artwork
Colors, Fonts, Layouts, Albumsprint-editor-styles
Editor setupprint-editor-setup
Live Previewsprint-editor-live-previews
Print MISPrint MISprint-mis
Print CADPrint CADprint-cad
Partner AppsPartner Appspartner-apps

Some toolsets show only when your license has the matching screen or feature: Attribute Sets, 4over and Sinalite pricing, Live Previews (3D model viewer), Print MIS and Print CAD.

Confirmations

Changes that are risky or hard to undo ask first. The agent shows what will change and in which store, then waits for your yes. Smaller changes, such as saving a tag or moving a category, run at once. Changes are recorded in the Activity Log whether they asked first or not.

The AI Agent Tool Reference marks the tools that always ask first. Some tools ask only for some inputs, for example when you change a product's Global setting; their description says when.

How you give your yes depends on the app:

AppHow you approve a change
Claude CodePrintNow's prompt opens in the app with a Make this change box. You accept or decline there.
Claude (claude.ai) and ChatGPTThese apps cannot show PrintNow's prompt. The agent shows the preview in the chat and asks. You reply yes, and the agent sends the change with the confirmation it got from the preview.

What the agent gets back when a change is not made:

  • "Not changed: the person said no."
  • "Not changed: no answer from the person." (no answer within 5 minutes)
  • "Not changed: the record changed while the person was deciding. Call again for a new preview."

A yes in the chat only answers the preview the agent just showed. It cannot approve a change that is only made in the admin, lift a usage limit, or widen the connection's access. An agent must never say you agreed when you did not.

Orders

An order status change always asks first. It can email staff and the customer. It can also send the order to OrderDesk, SiteFlow, Sinalite or 4over (a paid vendor order) when the new status is a vendor trigger. Each order save adds an order history row "Updated by AI agent" and fires the order-updated webhook.

Changes Only Made in the Admin

Some changes could send shoppers, data or access outside PrintNow. They get extra care:

Kind of changeExamplesClaude CodeClaude (claude.ai), ChatGPT
Store content and lookContent pages, bulk content updates, redirects and bulk redirects, site theme files, editor themes and styles, checkout styles, translations, and General Settings (including store URL and alternate domain)Asks first, every timePreview and a yes in the chat
Accounts, payments, email and credentialsMerchant accounts, carrier and LTL carrier accounts, the email (SMTP) account and its test email, email notifications, trade vendor emails, adding or saving a site user (any field), a user group's sign-up domain, and any partner app settingAsks first, every timeRefused

When a change is refused, the agent gets: "This change can only be made in the PrintNow admin: it can send data or access outside PrintNow, so AI agents are never allowed to make it. Trying again will not change that." Make these changes in the admin, or from Claude Code. In claude.ai and ChatGPT, a site user's flags can still be changed.

See What an Agent Can Never Do for the areas that are closed to agents in every app.

Personal Data

When an agent reads shoppers' details (site users, orders, exports read into the chat), these values come back masked: names, user names, emails, phone numbers, addresses, ZIP or postal codes, IP addresses, dates of birth, tax IDs, Social Security numbers, and every custom checkout field.

  • The agent can ask for the real values. You must agree first, and then that data goes to your AI provider.
  • Passwords, API keys and other secrets are always masked and never shown. Keys show only their last 4 characters.
  • An export saved as a download link is not masked. The agent asks you first before it exports site users or admin users.
  • Text that shoppers wrote, such as names, order notes and form fields, goes to the agent marked as data, never as instructions. A shopper cannot control the agent by typing commands into a field.

Bulk Changes

Seven tools change many rows in one run: bulk_catalog_update, bulk_pricing_update, bulk_seo_update, bulk_content_update, bulk_redirects, bulk_robots and bulk_order_status_update.

  1. Preview: the agent shows the first 50 rows that will change.
  2. Run: after your yes. Rows run in batches of 50. A run stops after 10 failed rows, and it can be resumed.
  3. Status: the agent can check a run's progress.
  4. Undo: puts the old values back, in reverse order.

Notes:

  • One run can change up to 1,000 rows. A larger job must be split.
  • If a row was changed in the admin after the preview, the run stops before that row.
  • New categories made by bulk_catalog_update cannot be undone.
  • An order status undo restores the statuses, but it cannot unsend emails or vendor orders.
  • A whole bulk run counts as one change toward the daily change limit.

Files

Agents pass files to and from you through short-lived links on mcp.printnow.com. Nothing is attached to the chat.

LinkWhat it is forHow long it worksLimits
Download linkAn export the agent made for you30 minutes after it was made, or 15 minutes after the first download, whichever comes first. Then the file is deleted.One file per link
Upload linkA file you send to the agent for an import1 hourOne file, up to 50 MB

Exports

  • export_get exports site users, admin users, promotion codes, tax rates and inventory.
    • File mode gives a download link. The file is not masked.
    • Rows mode reads the rows into the chat, 100 at a time (up to 500). Personal data is masked unless you agree to show it.
  • Print MIS has its own exports: materials_export, equipment_export and configuration_export.
  • One export can hold up to 50,000 rows. A larger export gives "This export has N rows; the limit for one download is 50,000. Narrow it in the admin, or export there."

Imports

The agent calls upload_start to make an upload link, then runs the import with the file.

ImportFileLargest file
Pricing package (pricing_package_import).pn50 MB
Print MIS materials, equipment, configurations (materials_import, equipment_import, configuration_import).xlsx, in the layout of the matching export20 MB
Product template (product_template_replace).idml50 MB
3D materials (materials_3d_import).zip50 MB
  • An upload link opens Send a file to your AI agent. Choose the file, click Send, then go back to the chat.
  • Upload messages: "A file was already sent with this link.", "The file is larger than 50 MB.", "No file was chosen.", and "This upload link has expired. Ask your AI agent for a new one."
  • An expired download link says "This download has expired. Ask your AI agent to export it again."
  • Claude Code can upload a file itself, without the upload page.
  • A file belongs only to the connection that made it. An uploaded file is deleted once the import uses it. Expired files are deleted within 10 minutes.

Usage Limits

Each connection has limits that stop a runaway agent from reading or changing too much. Normal use does not reach them. The admin itself is never limited.

The limits are currently:

LimitAmountCounted perResetsMessage
Calls at once10 per secondConnectionEvery secondToo many calls at once. Wait 1 second and try again.
Records read per minute5,000ConnectionEvery minuteRead limit for this minute reached. Wait N seconds and try again.
Keep-reading checkAt 10,000 records in a dayConnection12:00 AM UTCClaude Code asks: "The AI agent has read 10,000 records today on this connection. Let it keep reading today?"
Records read per day50,000Connection12:00 AM UTCDaily read limit for this connection reached (50,000 rows). It resets at 12:00 AM UTC (in N hours).
Changes per day2,000Store, across all its connections12:00 AM in the store's time zoneDaily write limit for store ‹name› reached (2,000 changes). It resets at 12:00 AM ‹time zone› (in N hours). Changes can still be made in the admin.
One export50,000 rowsExport—This export has N rows; the limit for one download is 50,000.
  • A record is one row the agent read: one order, one product, one price row. Every read call counts at least 1.
  • At 10,000 records, a no in Claude Code stops reads for the rest of the day. Claude (claude.ai) and ChatGPT cannot ask, so reading stops at 10,000 for the day.
  • A yes in the chat does not lift a limit. The agent should wait for the reset, not retry.
  • Previews, and changes that change nothing, do not count toward the change limit.
  • At the read limit, the always-on tools still work, except exports, uploads and tool_read/tool_write.
  • Large exports work best as download links. Rows read into the chat count toward the read limits.

Other Messages

Messages the agent may get from the admin, and what they mean:

MessageMeaning
This action is not available to AI agents.Only a person can do this in the admin.
AI agents can only change site users, not admins.The user is an admin. Change them in the admin.
This AI agent connection is read only.Connect again with Read and write.
This feature is not part of your license.The license does not have the feature this tool needs.
That item belongs to another store.Use the store the item is in.
You do not have access to ‹screen› in this store.The person's roles do not allow this screen in this store.
Refused: … is uploaded in the admin, not by an AI agent. Leave it out to change the rest.Images such as 3D textures are uploaded in the admin. Send the other fields only.
The admin could not do this (reference …).An error in the admin. Try again later, or contact PrintNow support with the reference.
This connection has ended. Connect again.Make a new connection code and connect again.

Activity Log

Changes an agent makes are in the Activity Log, under your name with the app after it. For example: "User Jane Smith (via Claude) updated product #1204". Claude Code shows as "(via Claude Code (local app))".

  • Turn on Agent activity only to see only the entries agents made.
  • Connections are logged with the type AI Agent Connection: making a code, connecting an app, the app disconnecting, and a revoke. The code and revoke entries are made by you in the admin, so Agent activity only may not show them.
  • What an agent reads (lookups, reports, exports read into the chat) is not logged, the same as when a person views a page.
  • Some changes do not show "(via …)" yet. A pricing package (.pn) import writes no entry. Background jobs an agent starts, such as a 4over feed sync or library import, are logged without the app name.

Tips for Claude (claude.ai) and ChatGPT

  • These apps keep the tool list from the start of the chat. When the agent turns on a toolset mid-chat, it runs those tools through tool_read or tool_write. This works. Starting a new chat also helps.
  • When you stop using a connection, revoke it on the AI agents page. Removing the connector in the app may not end it.

On this page