Skip to main content

Sales Order API

1. Overview

Jakamo Sales Orders (SO) API is an XML-based REST API over HTTPS. The SO API is for querying incoming sales orders from the SO API and sending an order confirmation back to the customer via Jakamo. When implemented, the result resembles the “EDI” connection between a customer company and a supplier company. SO API can be used to receive sales orders from multiple customer companies that use Jakamo via one integration.

See the user guide instructions to Orders application on Orders User Guide page.

You may also find the FAQ regading SO integration here: SO Technical FAQ

1.1 Requirements how to get started

Request demo accounts from Jakamo Support Team ( to create a SO integration from your system.

There are two similar Jakamo environments available for you: the test environment and the production environment.

Technical capabilities needed

  • Basic knowledge of ERP programming and REST API
  • Ability to authenticate (basic authentication) and GET order data from the Jakamo SO API
  • Ability to create a comprehensive mapping to import purchase order data
  • Ability to import purchase orders (as sales orders) to the ERP
  • Ability to extract order confirmation from the ERP and create an OrderResponse (UBL XML)
  • Ability to POST OrderResponse to the Jakamo SO API
  • Ability to handle Jakamo message queue (incoming messages)

1.2 Steps to go to production

The transition from the Jakamo test environment to the Jakamo production environment requires the following actions:

1. Production account establishment in Jakamo.

Create the Jakamo production account via the registration page. Please ensure that there is only one production account existing for your company in Jakamo (avoid creating a double account).

4. Sales order integration activation.

Sales order integration activation for the Jakamo production account. Ask Jakamo Support Team ( to activate the SO integration for you in the production environment. After the integration is available in the Jakamo production account, the Integrations page appears in the dropdown menu in the Jakamo user interface. The integrations setting page are available for company admin users.

3. Integration credentials creation.

Create integration credentials (SO integration authentication credentials) in the Jakamo production account on the Integrations page under Integration Credentials. Determine a cryptic username and password. Please ensure using different usernames and passwords in each enabled integration in use.

4. User and company mappings configuration in Jakamo.

Define user and company mappings on the Jakamo Integrations page.

5. Message endpoint configuration.

Change messages’ endpoint configurations from demo to production (see Jakamo SO API endpoints).

6. Everything is ready!

You are now ready to receive orders from your customers and confirm them via Jakamo!

2. Authorization

The API uses basic authentication as an authentication method. The username and password for the API are set inside the Jakamo account in the Integrations settings with the CHANGE CREDENTIALS functionality. If you have multiple integrations enabled in your Jakamo account, please use different credentials for each integration.

3. SO API endpoints

Jakamo environmentHTTP requestJakamo API endpoint
Test environmentGET
Test environmentPOST
Test environmentPUT{order_id}
Production environmentGET
Production environmentPOST
Production environmentPUT{order_id}

4. SO API request-response messages

Jakamo Sales Order API will return the HTTP response status code and in some cases additional information in the response body. A successfully posted message will return the HTTP response status code 200 OK. If there is an error and a message is not posted to the API, Jakamo API will return 400 Bad Requests or 500 Internal Server Errors.

The table below presents the most common responses from Jakamo Sales Order API.

HTTP response status codeResponse bodyAdditional information
200 OKMessage is successfully posted to Jakamo SO API.
400 Bad RequestAuthentication failed.Authentication failed because of an incorrect username or password or incorrect authentication method. Make sure you use the integration credentials defined in Jakamo “Integrations” and basic authentication as an authentication method.
400 Bad RequestIncorrect order responseMissing mandatory element. Review your OrderResponse message and check that all mandatory information is there. Check that the mandatory element is not empty. Read more here:
400 Bad RequestCannot find order.OrderResponse/OrderReference/ID element value does not match an existing purchase order. Check that the order you are trying to confirm is in Jakamo.
400 Bad RequestNo customer mapping foundMissing mapping in OrderResponse/BuyerCustomerParty/Party/PartyIdentification/ID. Check that there is a mapping between this identifier and the customer company account on the Jakamo Integrations page.
400 Bad RequestErrors in SellerContact element. Missing mapping?Missing mapping in OrderResponse/SellerSupplierParty/SellerContact/ID. Check that there is a mapping between this identifier and your company's Jakamo user on the Jakamo Integrations page.
400 Bad RequestLineItem missing QuantityQuantity element is incorrect or missing from OrderResponse/OrderLine/LineItem. Check that there is quantity in OrderResponse/OrderLine/LineItem/Quantity.
400 Bad RequestPrice\PriceAmount is required.The price element is incorrect or missing from OrderResponse/OrderLine/LineItem. Check that there is price information on OrderResponse/OrderLine/LineItem/Price.
500 Internal Server ErrorA generic error message, is given when no more specific message is suitable. For example, messages do not follow the UBL structure.

5. Handling incoming message queue

See the general Jakamo API queue handling instructions from incoming message queue handling page.

All incoming messages come to the same endpoint and they can be fetched from the queue by HTTP GET to the endpoint.

The SO API will return messages from the queue one message at a time. Running multiple GET requests would always return the same message if the message is not cleared from the queue. The oldest undeleted message in the queue will be returned first. Incoming messages can be Order (UBL) and optionally OrderChange (UBL) messages.

After processing the incoming message (validate, save it on the disk, parse, import, etc.), the message should be cleared from the queue. All incoming messages contain a value in the “X-Acknowledge-Uri” header. Simply HTTP POST to that address to remove the message from the queue. No message body content is needed when sending a POST request to remove the message from the queue. SO API will return HTTP response code 200 OK and body message <Info>Message cleared from the queue</Info> if your request was correct.

6. The sales order intake and order confirmation process in Jakamo

Here is presented the basic sales order intake and order confirmation process in Jakamo from a technical perspective. Below can be found all the requests explained more in detail with example messages. See a user instructions to Order-to-delivery process on Orders User Guide page.

6.1 Retrieving the new order

The supplier can retrieve customer orders from Jakamo SO API with an HTTP GET request. Order can be retrieved directly to the supplier’s ERP system or the integration platform where the order message can be translated and forwarded into the ERP.

6.2 Confirm the order

The supplier can confirm the order by sending the confirmation information to Jakamo with an OrderResponse message with an HTTP POST request. The order can be confirmed as the customer had requested, or the supplier can propose a change to the original quantities, prices, and delivery dates.

If the order is confirmed as requested, the order will have the status “Confirmed” in Jakamo. Order is confirmed in Jakamo when the customer’s requested order details and the supplier’s confirmed order details match. If the supplier proposes a change to delivery details, the order will have the status “Waiting for customer action” in Jakamo. In this case, the proposed changes must be accepted by the customer before the order can achieve “Confirmed” status. If the customer rejects the order confirmation, the order will need to reconfirm. In this case, the order status in Jakamo is ”Waiting for supplier confirmation”.

Example: Sending an order confirmation to Jakamo (HTTP POST)
<OrderResponse xmlns="urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:xsi="" xsi:schemaLocation="urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2 urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2 cac urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2 cbc ">
<cbc:Note>Additional info to header.</cbc:Note>
<cbc:Name>Test Supplier Ltd.</cbc:Name>
<cbc:Name>Customer Company AB</cbc:Name>
<cbc:Note>Additional info to order row.</cbc:Note>
<cbc:Quantity unitCode="PCS">100.00</cbc:Quantity>
<cbc:Quantity unitCode="PCS">100.00</cbc:Quantity>
<cbc:PriceAmount currencyID="EUR">120.00</cbc:PriceAmount>
<cbc:Name>HEX HEAD SCREW M16x80mm</cbc:Name>

6.2.1 Simple confirmation

Supplier can also use the simple confirmation endpoint to to approve the customer's new order, or to approve any changes by the customer to an existing order. Jakamo-Confirm-Url is contained in the Order message headers when it is retrieved from the queue. Order can be approved by supplier and order updated to be “Confirmed” in Jakamo by doing HTTP POST to that Jakamo-Confirm-Url address. This will update the order status to be “Confirmed” and update the order line confirmed values to match customer’s requested values.

Simple confirmation request also accepts parameters, given in message body. The following table lists available parameters.

Parameter nameDescription
NoteText. Text given as a Note parameter will appear as an addition to the usual automatically created order confirmation comment in comments section of the order.
EmphasizeOriginalAgreedDetailsBoolean. Not currently supported in SO integrations.

6.3 Supplier updates the order

You may easily do this by just sending a new OrderResponse with updated details. If for example you notice that you cannot deliver goods as originally planned, just update the details in your OrderResponse.

6.4 Customer updates the order

The customer can change the order (typically customer may change ordered quantities, prices or delivery dates) by posting OrderChange message to Jakamo. This OrderChange message can be restricted or allowed to pass to the sales order API queue by the supplier.

If the OrderChange message is allowed to pass to the SO API queue, the OrderChange message can be retrieved from the Jakamo SO API with HTTP GET. If the OrderChange message is restricted to pass to the SO API queue, the supplier will get notified that they have the order waiting for supplier confirmation in Jakamo, and the order confirmation process is handled manually in the Jakamo user interface.

6.5 Customer cancels the order

Customer can cancel the entire order or some of the order lines with OrderChange message or with StatusMessage. Cancelling can be done by setting the ordered quantity to zero or using LineStatusCode “Cancelled”. In Jakamo, the order or order line will achieve the status “Cancelled”. Customer can cancel the entire order with StatusMessage “Cancelled”.

6.6 Sending "Delivered" information

Supplier can infom when order or order line is delivered by sending "Delivered" StatusMessage to Jakamo. This will update order or order line status in Jakamo as "Delivered"

Example: Sending "Delivered" status information to Jakamo (HTTP PUT)

6.7 Empty queue

If the SO API queue is empty, the Jakamo SO API will return a status 200 OK and body message No more messages available if there are no new orders, order changes or status messages available.

7. UBL schemas and message mapping

OrderResponse message implementation package include OrderResponse message mapping form and cardinality, UBL subset documentation for OrderResponse, OrderResponse message schemas and XML examples.

Order message implementation package is available for you for example to view the Order message content. This package include Order message mapping form and cardinality, UBL subset documentation for Order, Order message schemas and more XML examples.

8. User and company mapping in the Jakamo integration settings

Mapping configurations to identify buyer and supplier in the Jakamo are made in the Jakamo user interface on the Integrations page. Integrations settings are available for you after the integration is activated for you in the Jakamo test environment and Jakamo production environment by Jakamo. See Jakamo's general integration mappings instructions from User Guide.

8.1 User mapping - Map your ERP users to your Jakamo users

ERP users who make order confirmations must have personal accounts in Jakamo. Person has to have some identifier (string) in the ERP, and it will be transferred in the OrderResponse XML data (OrderResponse/SellerSupplierParty/SellerContact/ID). This ERP identifier must be linked to the Jakamo user so that Jakamo can identify the message sender. The SO integration requires passing this user information in the XML data when making order confirmation. ERP identifier for a user can be for example an email address, a series of numbers, or a combination of numbers and letters, like the seller ID in the ERP.

Create required user mappings on the Integrations page. From that page can be found all the integrations in use. Under the User Strings, click ADD USER and create user mappings between Jakamo users and users in the ERP system. To be able to add a mapping, the user has to have a personal user account in Jakamo.

  • User identifier refers to the identifier string coming in OrderResponse/SellerSupplierParty/SellerContact/ID. Jakamo account refers to the users account in Jakamo.
  • Jakamo account dropdown includes the users who has their user accounts established in Jakamo.

DefaultUser can be left unselected. DefaultUser tick box can be selected if retrieved Order wanted to be confirmed without checking or changing any values by posting only confirmation with Order’s Jakamo-Confirm-Url. The confirmation information is then used by DefaultUser.

8.2 Customer mapping - Map your ERP customers to Jakamo companies

A relationship with the customer company in Jakamo has to be established before any messages can be received or sent via Jakamo. Customer has to have some identifier (string) in the ERP, and it will be transferred in the OrderResponse XML data (OrderResponse/BuyerCustomerParty/PartyIdentification/ID). This ERP identifier must be linked to the Jakamo company so that Jakamo can identify the message party.

Create company mappings on the Integrations page. From that page can be found all the integrations in use. Under the Company Strings, click ADD COMPANY and create a mapping between your ERP company (a customer) and the Jakamo relationship. To be able to add a mapping, the relationship with that company has to exist in Jakamo.

  • Company identifier refers to the identifier string coming in OrderResponse/BuyerCustomerParty/Party/PartyIdentification/ID. Jakamo company refers to the customer account that wants to be mapped to this customer identifier.
  • Jakamo company dropdown menu include a list of customer companies your account have relation established in Jakamo.

If you want to create special routing rules, fill in the external information fields when creating a new company mapping. External information fields are following:

  • External identifier: Fill in the identifier your customer sends to you via their Order. Define whether it is the external identifier customer's buyer customer party identifier or seller supplier party identifier.

  • External mapping field:

    • Buyer customer party: If external identifier is customer's buyer customer party identifier, select this.
    • Seller supplier party: If external identifier is customer's seller supplier party identifier, select this.
  • Compound rule member: If you want to create compound rule by using both buyer customer party identifier and seller supplier party identifier at the same time, select this and create the other half of the compound pair as an own mapping. If mapping is part of the compound mapping, it means that for the compound rule to be fulfilled, the second mapping condition must also be fulfilled.

See detailed instructions for external mappings in sales order integration and example from the User Guide.

Help & Support

Didn't you find what you were looking for? Send an email to Jakamo support ( and we will help you.