cXML
Connect e-procurement platforms and print MIS systems to PrintNow with cXML: punchout sessions where buyers design products on your storefront, and order submission.
Endpoint
POST https://api.printnow.com/cxml, not under /api/v2/.
- Send the cXML document as the body with
Content-Type: application/xml(anything else answers415). - The root element must be in the namespace
http://tempuri.org/cXML(<cXML xmlns="http://tempuri.org/cXML" ...>). A document PrintNow can't read as cXML answers406. - The HTTP status is always
200. The outcome is thecodeof the response envelope's<Status>element (see Status codes).
Credentials
cXML doesn't use the Authorization header. The credentials go in the envelope's <Header>:
| Element | Contains |
|---|---|
<From> | The storefront: a <Credential> whose domain and <Identity> match the storefront's Punchout ID Type and Punchout ID set in the admin. |
<To> | PrintNow: domain="DUNS" with identity 157519294. |
<Sender> | Your API token as <Identity> and API key as <SharedSecret>, with domain="api.printnow.com". The same pair you use for the REST API. |
<Header>
<From><Credential domain="NetworkID"><Identity>AN01000000001</Identity></Credential></From>
<To><Credential domain="DUNS"><Identity>157519294</Identity></Credential></To>
<Sender>
<Credential domain="api.printnow.com">
<Identity>YOUR_API_TOKEN</Identity>
<SharedSecret>YOUR_API_KEY</SharedSecret>
</Credential>
</Sender>
</Header>Common Punchout ID Types: DUNS (a DUNS number such as 123456789), NetworkID (an Ariba Network id such as AN01000000001), or a custom domain identifying your procurement system.
cXML calls count toward the same rate limit as the REST API.
Request types
| Request | Response | Use |
|---|---|---|
ProfileRequest | ProfileResponse | Discover what PrintNow supports. |
PunchOutSetupRequest | PunchOutSetupResponse | Start (create) or resume (edit) a punchout session; returns the URL to send the buyer to. |
OrderRequest | Status only | Submit an order. |
ProfileRequest
Returns two transactions, both at https://api.printnow.com/cxml: PunchOutSetupRequest (options operationAllowed: create edit, and Flow, UsePricing, ItemNumber, ModelNumber, IntegrationId, CategoryId) and OrderRequest.
Punchout sessions
A PunchOutSetupRequest with operation="create" starts a session; the response's StartPage URL opens the storefront for the buyer.
Flows
The Flow extrinsic decides where the buyer lands:
| Flow | Needs | Buyer sees |
|---|---|---|
product | One of ItemNumber, ModelNumber or IntegrationId | That product, open in the editor. |
category | CategoryId | That category, to choose a product from. |
Send product identifiers or a category, not both (400 otherwise).
Setup extrinsics
| Extrinsic | Required | Meaning |
|---|---|---|
Flow | Yes | product or category. |
ItemNumber / ModelNumber / IntegrationId | For product | Identifies the product. |
CategoryId | For category | The category to browse. |
UsePricing | No | true (lowercase) to price the design with PrintNow pricing (product flow). |
ConfigId | On edit | The session to resume: the ConfigId from the order message. |
EditorParam.<name> | No, repeatable | A value for the editor, returned on the order message (see Editor parameters). |
The buyer
The end user comes from the request's <Contact role="endUser">:
- An existing customer on the storefront with the contact's email address is used;
- otherwise a customer account is created from the contact's name and email;
- without a contact, a temporary customer is created.
Creating a customer fires the customer_created webhook.
Editing a session
operation="edit" reopens a session, but only when all of these match the original create, otherwise it answers 404:
- the
ConfigIdextrinsic; - the
BuyerCookie; - the
BrowserFormPostURL; - the API token in
<Sender>.
Nothing else is needed: Flow, product identifiers, UsePricing and Contact are ignored on an edit. The editor reopens the saved design with the buyer's changes.
Editor parameters
Editor parameters pass values into the Print Editor on a create request: swap a tagged image, show or hide it, or recolor it from the storefront's palette. Their values come back on the order message, so they also carry your own identifiers through the session.
Naming. Send each as an extrinsic named EditorParam.<name>, for example EditorParam.Background. The EditorParam. prefix is case-insensitive; <name> is case-sensitive and must exactly match the tag of an image in the product template to affect the design.
What the value does:
| Value | Effect on the tagged image | Example |
|---|---|---|
| A number | Swaps it to that image id. | EditorParam.Logo = 1234 |
true / false | Shows or hides it. | EditorParam.Badge = false |
from,to pairs separated by ; | Recolors it: each from color in its color map becomes to. | EditorParam.Background = Red,Blue;White,Black |
Colors are palette color names or hex values (with or without #), case-insensitive. Both colors of a pair must be in the storefront's palette, or the pair is ignored. A pair recolors a color-map entry when its from matches the original artwork color or the current one.
Your own values. A name that matches no tagged image has no effect in the editor and comes back unchanged, so EditorParam.correlationId round-trips your own id. Only EditorParam. extrinsics come back; other extrinsics don't.
Reserved names are refused with 400, as is an empty name (EditorParam.), case-insensitively: productid, epi, epw, tpsc, token, cru, s, uid, qty.
Create only. On an edit, editor parameters are checked for reserved names and then ignored: the original parameters aren't re-applied, and you can't supply a new value (such as a new correlation id).
The order message
When the buyer finishes, PrintNow posts a PunchOutOrderMessage back to the setup request's BrowserFormPost URL, as a browser form field named cxml-urlencoded. The BuyerCookie comes back unchanged.
Each design is one ItemIn: quantity is the ordered quantity, SupplierPartID the PrintNow product id, Description the product's short description, UnitOfMeasure is EA, and UnitPrice and the header Total are included when PrintNow pricing is used.
| ItemIn extrinsic | Present | Value |
|---|---|---|
ConfigId | Always | The session id. Send it back to edit. |
ProofUrl | Always | Download link for the proof PDF. |
ThumbnailUrl | Always | Product thumbnail image. |
ProductId | Always | PrintNow product id. |
ItemNumber / ModelNumber / IntegrationId | When set on the product | The product's identifiers. |
StandardSize or CustomSize | With PrintNow pricing | Size name, or W x H. |
Colors | With PrintNow pricing | Color/pages selection. |
| One per pricing option, named after the option | With PrintNow pricing | The selected value. |
Weight | With PrintNow pricing, when above 0 | Calculated weight. |
EditorParam.<name> | One per editor parameter sent at setup | Its value now (below). |
Returned editor parameter values. Every EditorParam.<name> sent on the create comes back on each ItemIn under the same name. A name the editor matched carries its current value, reflecting the buyer's changes; any other name carries the original value:
- image swap: the current image id;
- show/hide:
truewhen visible,falsewhen hidden; - recolor:
original,currentpairs separated by;, covering the image's whole color map (not just the pairs sent). Each color is a palette name when it's in the palette, otherwise bare hex without#:Red,123456means the buyer picked a color outside the palette. The value can differ from what you sent even when nothing changed.
Orders
An OrderRequest creates the order in PrintNow:
- Customer: found or created from
<Contact>, as for punchout. - Order: created with the storefront's first order status.
- Totals: from
<Total>,<Tax>and<Shipping>; the item subtotal is the total minus tax and shipping. - Addresses: billing from
<BillTo>, shipping from<ShipTo>(the billing address when there's none). - Items: each
<ItemOut>becomes an order item. When itsSupplierPartIDis a PrintNow product and itsConfigIdextrinsic links to a punchout session, the session's PrintNow pricing (size, color, turnaround, options) is attached; otherwise an external product is recorded from the part id and description. - Files: print-file generation starts.
- Webhook:
order_createdfires.
Address extrinsics
Optional extrinsics on a <PostalAddress>:
| Extrinsic | Meaning |
|---|---|
CustomerCompany | Company name for the address (otherwise the <Address> name). |
CustomerName | Contact name (otherwise <DeliverTo> is split into first and last name). |
IsResidential | true, 1 or yes for a residential address (affects shipping rates). |
Status codes
| Code | Meaning |
|---|---|
200 | Processed. |
400 | Invalid request: a flow/product/category mix-up, missing data, an invalid EditorParam name, or a customer that couldn't be created. |
401 | Bad credentials: API token/key, PrintNow's DUNS, or no storefront matching <From>. |
403 | Your account doesn't include cXML. |
404 | Punchout session not found on an edit, or its BuyerCookie, BrowserFormPost URL or API token doesn't match the create. |
406 | Not a readable cXML document (empty, or not in the http://tempuri.org/cXML namespace). |
415 | Content-Type isn't application/xml. |
429 | Rate limit exceeded; wait for the HTTP Retry-After header. |
501 | Request type or operation not supported. |
Handles a cXML ProfileRequest, PunchOutSetupRequest (create or edit) or OrderRequest.
Request Body
application/xml
The cXML request envelope.
Response Body
application/xml
curl -X POST "https://api.printnow.com/cxml" \ -H "Content-Type: application/xml" \ -d '<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.014/cXML.dtd">
<cXML xml:lang="en-US" payloadID="93369535150910.4821@procurement.example.com" timestamp="2000-08-03T08:49:11+07:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://tempuri.org/cXML">
<Header>
<From>
<Credential domain="NetworkID">
<Identity>AN01000000001</Identity>
</Credential>
</From>
<To>
<Credential domain="DUNS">
<Identity>157519294</Identity>
</Credential>
</To>
<Sender>
<Credential domain="api.printnow.com">
<Identity>YOUR_API_TOKEN</Identity>
<SharedSecret>YOUR_API_KEY</SharedSecret>
</Credential>
</Sender>
</Header>
<Request>
<OrderRequest>
<OrderRequestHeader orderID="DO102880" orderDate="2012-08-03T08:49:09+07:00" type="new">
<Contact role="endUser">
<Name>Demo User</Name>
<Email>demo.user@domain.com</Email>
</Contact>
<Total>
<Money currency="USD">61608.81</Money>
</Total>
<ShipTo>
<Address isoCountryCode="US" addressID="1000467">
<Name xml:lang="en">Acme, Inc.</Name>
<PostalAddress name="default">
<DeliverTo>John Q. Smith</DeliverTo>
<DeliverTo>Buyers Headquarters</DeliverTo>
<Street>123 Main Street</Street>
<City>Mountain View</City>
<State isoStateCode="US-CA">CA</State>
<PostalCode>94089</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
<Email name="default">john_smith@acme.com</Email>
<Phone name="work">
<TelephoneNumber>
<CountryCode isoCountryCode="US">1</CountryCode>
<AreaOrCityCode>800</AreaOrCityCode>
<Number>5555555</Number>
</TelephoneNumber>
</Phone>
</Address>
</ShipTo>
<BillTo>
<Address isoCountryCode="US" addressID="12">
<Name xml:lang="en">Acme Accounts Payable</Name>
<PostalAddress name="default">
<Street>124 Union Street</Street>
<City>San Francisco</City>
<State isoStateCode="US-CA">CA</State>
<PostalCode>94128</PostalCode>
<Country isoCountryCode="US">United States</Country>
</PostalAddress>
<Phone name="work">
<TelephoneNumber>
<CountryCode isoCountryCode="US">1</CountryCode>
<AreaOrCityCode>415</AreaOrCityCode>
<Number>6666666</Number>
</TelephoneNumber>
</Phone>
</Address>
</BillTo>
<LegalEntity>
<IdReference domain="CompanyCode" identifier="CH01">
<Description>SAP AG</Description>
</IdReference>
</LegalEntity>
<OrganizationalUnit>
<IdReference domain=" PurchasingOrganization" identifier="SCP">
<Description> SCPM Purchasing Org </Description>
</IdReference>
</OrganizationalUnit>
<OrganizationalUnit>
<IdReference domain=" PurchasingGroup" identifier="0001">
<Description> PGP Buyer </Description>
</IdReference>
</OrganizationalUnit>
<Shipping>
<Money currency="USD">10.00</Money>
<Description xml:lang="en-US">FedEx 2-day</Description>
</Shipping>
<Tax>
<Money currency="USD">1.5</Money>
<Description xml:lang="en">CA State Tax</Description>
</Tax>
<Payment>
<PCard number="1234567890123456" expiration="2015-03-12"/>
</Payment>
</OrderRequestHeader>
<ItemOut quantity="2" lineNumber="1">
<ItemID>
<SupplierPartID>5808324</SupplierPartID>
<SupplierPartAuxiliaryID>E000028901</SupplierPartAuxiliaryID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="USD">55.00</Money>
<Modifications>
<Modification>
<OriginalPrice>
<Money currency = "USD">50.00</Money>
</OriginalPrice>
<AdditionalCost>
<Money currency = "USD">5</Money>
</AdditionalCost>
<ModificationDetail endDate = "2013-11-30T10:15:00-08:00" name = "Royalties" startDate = "2012-08-03T10:15:00-08:00">
<Description xml:lang = "en-US">Charge for Royalties</Description>
</ModificationDetail>
</Modification>
</Modifications>
</UnitPrice>
<Description xml:lang="en">Laptop Computer Notebook Pentium® II processor w/AGP, 300 MHz, with 12.1" TFT XGA Display</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">43171801</Classification>
<URL>http://www.supplier.com/Punchout.asp</URL>
<Extrinsic name="ExtDescription">Enhanced keyboard</Extrinsic>
</ItemDetail>
<Distribution>
<Accounting name="DistributionCharge">
<AccountingSegment id="7720">
<Name xml:lang="en-US">Account</Name>
<Description xml:lang="en-US">Office Supplies</Description>
</AccountingSegment>
<AccountingSegment id="610">
<Name xml:lang="en-US">Cost Center</Name>
<Description xml:lang="en-US">Engineering Management</Description>
</AccountingSegment>
</Accounting>
<Charge>
<Money currency="USD">20.00</Money>
</Charge>
</Distribution>
</ItemOut>
<ItemOut quantity="1" lineNumber="2">
<ItemID>
<SupplierPartID>5555</SupplierPartID>
</ItemID>
</ItemOut>
<ItemOut quantity="1" lineNumber="3">
<ItemID>
<SupplierPartID>5821</SupplierPartID>
</ItemID>
<ItemDetail>
<UnitPrice>
<Money currency="USD">61522.31</Money>
</UnitPrice>
<Description>N/A</Description>
<UnitOfMeasure>EA</UnitOfMeasure>
<Classification domain="UNSPSC">12345678</Classification>
<Extrinsic name="ConfigId">3E1F142F-B12A-4BD4-936A-0081BAA3847F</Extrinsic>
</ItemDetail>
</ItemOut>
</OrderRequest>
</Request>
</cXML>'"<?xml version=\"1.0\" encoding=\"utf-8\"?>\r\n<!DOCTYPE cXML SYSTEM \"http://xml.cxml.org/schemas/cXML/1.2.059/cXML.dtd\">\r\n<cXML xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" payloadID=\"638368633753082368.5436.1559214762@api.printnow.com\" timestamp=\"2023-11-29T14:02:55-05:00\" xmlns=\"http://tempuri.org/cXML\">\r\n <Response>\r\n <Status code=\"401\" text=\"Unauthorized\" />\r\n </Response>\r\n</cXML>"Webhooks
Get notified when orders and customers change, instead of polling. Subscribe a URL to an event and PrintNow POSTs the changed order or customer to it each time the event happens. This is also how the Zapier integration works.
AI Agents
Connect Claude, ChatGPT or Claude Code to your PrintNow admin and let it do admin work for you, within the access you choose.