Introduction

With PunchCommerce’s revamped order module, you can securely receive incoming orders from various systems – particularly in cXML format – and forward them seamlessly to your target systems.

Orders are automatically confirmed as received upon receipt. You then have two options:

Retrieval via REST API – you can flexibly integrate the module into your own systems.
Automatic forwarding – e.g. to Shopware 6 or other shop systems.

This significantly reduces manual effort, prevents data transfer errors and makes collaboration with your customers’ e-procurement systems more efficient.

Please note: The functions for defining your own data formats and managing multiple order profiles are currently only available to selected customers under our Enterprise contracts.

Creating an order profile

Order profiles are at the heart of our order module. Here, you can define your own data model and make it available via a REST API. An order profile can be assigned to one or more customers.

Go to the Order Profiles section and click on Create New Order Profile.
Enter a name for your profile.
Upload a cXML file of the OrderRequest type.
Based on the cXML data model, PunchCommerce generates a suggested data model, which you can customise as required.

Sending orders from third-party systems

Procurement systems such as Ariba® or Coupa can be configured so that new orders from your customers are automatically sent as cXML OrderRequest documents to the following address:

https://<instance>.enterprise.punchcommerce.de/api/v1/orders/cxml

The endpoint expects a cXML OrderRequest document in accordance with the specification in Chapter 7 of the cXML Reference Guide.

Important: Orders can only be received for customers to whom you have assigned an order profile. Orders for unknown customers, or customers without a profile, are automatically rejected and are not available for processing via our API.

Example document

<?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.10.57.136" timestamp="2000-08-03T08:49:11+07:00">
  <Header>
    ...
  </Header>
  <Request>
    <OrderRequest>
 <OrderRequestHeader orderID="DO102880" orderDate="2012-08-03T08:49:09+07:00" type="new">
 ...
 </OrderRequestHeader>
      <ItemOut quantity="2" lineNumber="1">
 ...
 </ItemOut>
    </OrderRequest>
  </Request>
</cXML>

Example response

Provided no errors occur whilst processing the order, our system will respond with the following response to confirm receipt. No commercial obligation arises at this stage:

<cXML payloadID="9949494" xml:lang="en" timestamp="1999-03-12T18:39:09-08:00">
  <Response>
    <Status code="200" text="OK"/>
  </Response>
</cXML>

Accessing orders via our REST API

For each order profile, individual access credentials in the form of a token and a URL for our REST API are generated.

List of all orders for a profile

GET {{punchcommerce_host}}/api/v1/profile/{{profile_id}}

Response:

{
  "data": {
    "id": "4a152855-1a26-4059-a637-4d56cc151d9e",
    "name": "adsd",
    "customers": [
 {
 "uuid": "69f14942-178d-4d57-b6d5-fdd9d4aee407",
 "name": "Mraz Inc"
 }
    ],
    "orders": [
 {
 "id": "cb074373-60d9-4c1b-9453-988602da457e",
        "customer_id": "69f14942-178d-4d57-b6d5-fdd9d4aee407",
        "customer": "Mraz Inc",
 "created_at": "2022-10-03T13:21:16.000000Z",
 "link": "https://punchcommerce.local/api/v1/profile/4a152855-1a26-4059-a637-4d56cc151d9e/order/cb074373-60d9-4c1b-9453-988602da457e"
 },
 ...
    ]
  }
}

Order details

The response depends on the data model you have configured for the corresponding order profile in our system.

GET {{punchcommerce_host}}/api/v1/profile/{{profile_id}}/order/{{order_id}}

Example response:

{
  "data": {
    "meta": {
 "request_id": "1637737323553.569506334.000002897@IrwnYChEL2oZa48FesaJ62+R18I=",
 "cxml_version": "1.2.044",
 "language": "en-US"
    },
    "order": {
 "total": "17",
 "currency": "EUR",
 "date": "2021-11-23T23:01:59-08:00",
      "reference": "EP686328",
 "version": 1,
 "billing": {
 "company": "FOOBAR GMBH - ACCOUNTS DEPARTMENT",
 "street": "Walter-Flex-Str. 27",
 "postcode": "24000",
 "city": "Hamburg",
 "country": "Germany"
 },
 "shipping": {
 "company": "FOOBAR GMBH",
 "street": "Walter-Flex-Str. 27",
 "postcode": "65428",
 "city": "Rüsselsheim",
 "country": "Germany"
      },
 "items": [
 {
 "index": 1,
 "ordernumber": "FOOBAR_VK-deutsch_up",
 "quantity": 100,
          "name": "FOOBAR Business Card (German)",
 "unit_price": "0.17",
 "unit": "EA"
 }
 ]
    }
  }
}

Forwarding orders

In addition to simply retrieving orders via the REST API, orders can also be automatically forwarded to shop systems. We currently support Shopware 6 in particular. Support for further systems is in the pipeline.

How it works

An order is received (e.g. cXML).
PunchCommerce transforms the data into an internal standard format.
The configured target system (Shopware 6) is supplied via the Admin API.
PunchCommerce takes into account fallbacks for payment methods, delivery methods, currencies and tax rates.

Configuration

Select the target system in the order profile (e.g. Shopware).
Enter access details: URL, Client ID (Access Key), Client Secret.
Test the connection (PunchCommerce checks authentication and loads payment methods, delivery methods, currencies and tax rates).
Configure default values if these cannot be clearly derived from the order.

Result

The order appears directly in the Shopware backend with the prefix PUNCH- in the order number.
Missing products can be ignored or treated as errors, depending on the settings.
The process is transparent: successes and errors are logged in the PunchCommerce interface.

Note: IDs for payment methods or delivery methods that have been deleted in Shopware may trigger errors. Please retest and save the connection in PunchCommerce after making changes in Shopware.

Operation & Quality Assurance

Check the success messages in the PunchCommerce interface regularly.
Keep master data (products, currencies, taxes) up to date.
Define a clear rule for missing products (ignore or abort).

Go-Live Checklist

[ ] Connection test successful
[ ] Payment methods, delivery methods, currencies and tax rates maintained in Shopware
[ ] Additional fields set and saved in PunchCommerce
[ ] cXML sender knows the correct endpoint and authentication
[ ] Process for missing products defined
[ ] Test order successfully created

Frequently Asked Questions (FAQ)

Why are no options visible after refreshing the page? The lists only load after clicking ‘Test’. However, your saved values are retained.

Can I configure multiple target systems? Yes, one target system per profile. Multiple profiles are possible.

Do I have to fill in all the additional fields? No, but it is recommended. Default values make the process more robust.

Why is there ‘PUNCH-’ in the order number? This makes it easy to identify orders from PunchCommerce in the Shopware backend.

How secure is my data? Secrets are stored confidentially; only encrypted connections (HTTPS) are permitted.

Troubleshooting

Connection test fails:
- Is the URL correct? Is it accessible via HTTPS?
- Are the access key and secret correct and have sufficient permissions?
- Is the firewall or proxy blocking POST /api/oauth/token?
Options (payment/shipping/currency/tax) are empty:
- Click ‘Test’; the corresponding entities must exist and be active in Shopware.
Order is rejected in Shopware due to invalid IDs:
- Are old IDs stored in PunchCommerce? Click ‘Test’, select new options, then save.
cXML is received, but products are missing:
- Set the “Ignore non-existent products” option as required by the process. Check product master data in Shopware.
Timeouts:
- Check the network; try again. With large option tables, the first test may take a little longer.

Technical note: The connection test records partial successes. It may be marked as “successful” even though individual option lists have not been loaded. The notes in the results will then provide further details.

Please have the following information to hand when contacting support:

Shopware version & shop URL
Time & error message
Screenshots of the settings (without the secret)
Example of a cXML order (anonymised)

This will enable us to assist you quickly and accurately.

Processing cXML orders (e.g. from SAP Ariba®)