PrintNowPrintNowDocs

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 answers 415).
  • 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 answers 406.
  • The HTTP status is always 200. The outcome is the code of 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>:

ElementContains
<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

RequestResponseUse
ProfileRequestProfileResponseDiscover what PrintNow supports.
PunchOutSetupRequestPunchOutSetupResponseStart (create) or resume (edit) a punchout session; returns the URL to send the buyer to.
OrderRequestStatus onlySubmit 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:

FlowNeedsBuyer sees
productOne of ItemNumber, ModelNumber or IntegrationIdThat product, open in the editor.
categoryCategoryIdThat category, to choose a product from.

Send product identifiers or a category, not both (400 otherwise).

Setup extrinsics

ExtrinsicRequiredMeaning
FlowYesproduct or category.
ItemNumber / ModelNumber / IntegrationIdFor productIdentifies the product.
CategoryIdFor categoryThe category to browse.
UsePricingNotrue (lowercase) to price the design with PrintNow pricing (product flow).
ConfigIdOn editThe session to resume: the ConfigId from the order message.
EditorParam.<name>No, repeatableA 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">:

  1. An existing customer on the storefront with the contact's email address is used;
  2. otherwise a customer account is created from the contact's name and email;
  3. 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 ConfigId extrinsic;
  • the BuyerCookie;
  • the BrowserFormPost URL;
  • 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:

ValueEffect on the tagged imageExample
A numberSwaps it to that image id.EditorParam.Logo = 1234
true / falseShows 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 extrinsicPresentValue
ConfigIdAlwaysThe session id. Send it back to edit.
ProofUrlAlwaysDownload link for the proof PDF.
ThumbnailUrlAlwaysProduct thumbnail image.
ProductIdAlwaysPrintNow product id.
ItemNumber / ModelNumber / IntegrationIdWhen set on the productThe product's identifiers.
StandardSize or CustomSizeWith PrintNow pricingSize name, or W x H.
ColorsWith PrintNow pricingColor/pages selection.
One per pricing option, named after the optionWith PrintNow pricingThe selected value.
WeightWith PrintNow pricing, when above 0Calculated weight.
EditorParam.<name>One per editor parameter sent at setupIts 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: true when visible, false when hidden;
  • recolor: original,current pairs 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,123456 means 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:

  1. Customer: found or created from <Contact>, as for punchout.
  2. Order: created with the storefront's first order status.
  3. Totals: from <Total>, <Tax> and <Shipping>; the item subtotal is the total minus tax and shipping.
  4. Addresses: billing from <BillTo>, shipping from <ShipTo> (the billing address when there's none).
  5. Items: each <ItemOut> becomes an order item. When its SupplierPartID is a PrintNow product and its ConfigId extrinsic 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.
  6. Files: print-file generation starts.
  7. Webhook: order_created fires.

Address extrinsics

Optional extrinsics on a <PostalAddress>:

ExtrinsicMeaning
CustomerCompanyCompany name for the address (otherwise the <Address> name).
CustomerNameContact name (otherwise <DeliverTo> is split into first and last name).
IsResidentialtrue, 1 or yes for a residential address (affects shipping rates).

Status codes

CodeMeaning
200Processed.
400Invalid request: a flow/product/category mix-up, missing data, an invalid EditorParam name, or a customer that couldn't be created.
401Bad credentials: API token/key, PrintNow's DUNS, or no storefront matching <From>.
403Your account doesn't include cXML.
404Punchout session not found on an edit, or its BuyerCookie, BrowserFormPost URL or API token doesn't match the create.
406Not a readable cXML document (empty, or not in the http://tempuri.org/cXML namespace).
415Content-Type isn't application/xml.
429Rate limit exceeded; wait for the HTTP Retry-After header.
501Request type or operation not supported.

Handles a cXML ProfileRequest, PunchOutSetupRequest (create or edit) or OrderRequest.

POST
/cxml

Request Body

application/xml

The cXML request envelope.

body*string

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&quot; 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>"

On this page