Introduction
This reference documents the SOAP API for the Intershop Order Management System (IOM). The listed services establish a synchronous communication of business messages between IOM and order-related systems such as shops, suppliers or any other business-relevant 3rd party systems. The exchange of mass data or processing of the data are not part of this documentation.
This document is primarily intended for all developers implementing a project or working on the core product of IOM.
Glossary
| Term | Description |
|---|---|
| IOM | The abbreviation for Intershop Order Management |
| SOAP | Simple Object Access Protocol |
References
- Concept - IOM SOAP Web Services
- Reference - IOM Database Documentation
- Reference - IOM Order Statuses
- Description of schemas can be found at in the delivery package /doc/SOAP/
SOAP Web Services
The following list provides an overview of all Intershop Order Management SOAP web services:
| Service | Method | URI | Required Permissions | Description |
|---|---|---|---|---|
| ApprovalService | storeApprovalResponse | https://<domain>/webservices/ApprovalService/v1.0 | Create approval message | Stores an approval for a given order. Approvals can be made, for example, by a third-party system such as a fraud prevention system. In general the order is in pending state and waiting for an approval or rejection of one or more open approvals. Conditions for an approval can be configured. |
| CustomerService | getCustomerContacts | https://<domain>/webservices/CustomerService/v1.1 | tbd | Returns the history of all contacts with the customer. A customer contact for example is a phone call or an email in order to change the delivery address of an order. |
| storeCustomer | tbd | Stores data of a new customer or updates an existing customer. | ||
| storeCustomerContact | tbd | Stores a new customer contact for an existing customer. A customer contact for example is a phone call or an email from the customer to change the delivery address of an order. | ||
| ImmaterialOrderStateService | getDetailedMediaLibrary | https://<domain>/webservices/ImmaterialOrderStateService/v1.0 Note Planned removal without replacement for the time being. Will still be supported till the end of 2023. After that, this functionality will no longer be available and will be deleted. | Order status web service | Returns detailed information about articles from the digital media library. Digital articles can be e-books, sound files, videos and more. Information like article name, article number, order number, order date and possible actions can be retrieved. |
| getMediaLibraryOverview | Order status web service | Returns information about a digital media library. Information like media type and number of ordered articles of the media type can be retrieved. | ||
| OrderStateService | getOrderStateReport | https://<domain>/webservices/OrderStateService/v1.0 Note Deprecated since version 2.15 Use the REST Order Service instead. | Order status web service | Returns the state of one or more orders for a given customer. For example, the status of an order can be pending, canceled, or delivered. Please see Reference - IOM Order Statuses for available order states. |
| OrderService | storeOrder | https://<domain>/webservices/OrderService/v1.2 Note https://<domain>/services/OrderService/v1.2 Deprecated since version 3.1 Use the REST Order Service instead. | Create order | Stores a new order of a shop. |
| RedownloadService | storeRedownload | https://<domain>/webservices/RedownloadService/v1.1 Note Planned removal without replacement for the time being. Will still be supported till the end of 2023. After that, this functionality will no longer be available and will be deleted. | - | Requests another download of a digital product from the supplier of an existing order. The supplier will return a token, e.g., a download link. |
| ReservationService | reservationAction | https://<domain>/webservices/ReservationService/v1.0 Note Planned removal without replacement for the time being. Will still be supported till the end of 2023. After that, this functionality will no longer be available and will be deleted. | The permission depends on the requested action:
| Releases or cancels an order. |
| storeReservation | https://<domain>/webservices/ReservationService/v1.0 Note Deprecated since version 2.15 Use the REST Reservation Service instead. | Create order | Stores an order marked as reservation. | |
| ReturnService | storeReturn | https://<domain>/webservices/ReturnService/v1.1 Note Deprecated since version 2.15 Use the REST Communication API instead. | Create return message | Announces the arrival of a return, e.g., at the supplier side. |
| ReverseService | cancelOrder | https://<domain>/webservices/ReverseService/v1.0 | Cancel order/create cancellation request | Cancels an order. An order can be canceled completely or partially by canceling selected order positions. |
| returnAction | Return confirmation | Processes an action for a return. Possible actions may be accepting or declining a return. | ||
| returnReportRequest | The permission depends on the current status [0-viewable, 1-confirmable, 2-decidable] of the return position.
| Returns a report on returned orders. For this purpose, filters can be set to limit the data and sort the orders. | ||
| returnSlipRequest | Request return note | Returns information to create a return note for an order in the next step. One information is for example the reason of return. | ||
| ShopService | storeDispatch | https://<domain>/webservices/ShopService/v1.0 Note Deprecated since version 2.15 Use the REST Communication API instead. | Create delivery message | Announces the shipping of an order/ package by a supplier. Mostly this is done when the package is handed over to a carrier. Attached information can be the name of the carrier and the package tracking number. |
| storeResponse | Create receipt message | Announces the acceptance or rejection of an order or parts of an order by the supplier. Previously, articles to be delivered were assigned to the supplier. | ||
| ValidateArticleService | validateArticle | https://<domain>/webservices/ValidateArticleService/v1.0 | Create order | Validates articles based on rules configured in the application. The validation can be used for example before submitting an order, to check for general availability or expected delivery date. |
Field Restrictions and Validations
Several fields have length restrictions. Please see the XSD files for more details.
OrderService - Split of Street into Name and Street Number
Note
Since OrderService 1.2
The street name and street number can be set using separated fields.
The OrderService tries to split the street into name and street number if not provided separately.
Codes
This section describes different codes that can be sent to the application or returned within a response.
There are codes that are required for almost every web service and can be mapped to codes of communication partners.
There are also codes that are application-specific and cannot be used across different applications and, therefore, have to be defined for the particular environment.
Basic Codes
Countries and Currencies
Country codes are used in format ISO 3166-1 alpha-3, for example DEU.
Note
Payment Methods
For payment methods the following codes are implemented by default.
Code | Description |
|---|---|
NO_PAYMENT | Unknown payment method |
PREPAYMENT | Cash in advance |
CREDITCARD | Credit card - General |
CASH_ON_DELIVERY | Cash on delivery |
ON_ACCOUNT | Invoice purchase |
HIRE_PURCHASE | Hire purchase |
DIRECT_DEBIT | Electronic direct debit |
LEASING | Leasing |
DIRECT_TRANSFER | Immediate transfer |
PAYPAL | PayPal |
VISA | Credit card - Visa |
AMERICAN_EXPRESS | Credit card - American Express |
EURO_CARD | Credit card - Eurocard |
MASTER_CARD | Credit card - MasterCard |
GIROPAY | Giropay |
BILLPAY | BillPay |
IDEAL | iDEAL |
MAESTRO_CARD | Maestro-Card |
Note
Types of Tax
Tax types (VAT) represent a tax rate depending on the selected country. For example the NORMAL_TAX differs in Netherlands (19%) and Sweden (25%).
Code | Description |
|---|---|
NO_TAX | No taxes |
VERY_LOW_TAX | Greatly reduced tax rate |
LOW_TAX | Reduced tax rate |
INTERMEDIATE_TAX | Intermediate tax |
NORMAL_TAX | Normal tax rate |
SERVICE | Tax rate for services |
Note
Charge Types (Fees)
Charge types are fees that can be raised for different kinds of services. The following charge types are provided.
Code | Description |
|---|---|
CODCHARGE | COD Charge - Fee for cash on delivery |
DELIVERYCHARGE | Delivery Charge - Fee for delivery |
HANDLINGCHARGE | Handling Charge - Fee for handling / processing |
PAYMENTCHARGE | Payment Charge - Fee for payment |
Carrier Names
The following carrier names are available by default and can be extended via project customization.
Code | Description |
|---|---|
DHL | www.dhl.com |
DPD | www.dpd.com |
UPS | www.ups.com |
Hermes | www.hermesworld.com |
ShopService - StoreResponse
StoreResponse announces the acceptance or rejection of an order or parts of an order by the supplier. First, articles to be delivered must be assigned to the supplier.
Response
The response state is a combination of a common (header-) state and the states of the several order positions / line items. For this, only defined combinations of status codes are allowed.
| Level | Code | Description |
|---|---|---|
| Head | ACC | ACCEPTED - Accepted without changes. The supplier accepted the order without changes in material, price, delivery date and quantity. |
| Head | AWC | ACCEPTED WITH CHANGES - The supplier has accepted the order but reported changes in material, price, date or quantity. |
| Head | CAN | CANCELLATION - cancellation of the order. Additionally a cancellation of the order will be created. |
| Position | UNC | UNCHANGED - No changes at the position since last order response. |
| Position | CHG | CHANGED - There are subsequent changes in quantity, delivery date or price. |
| Position | CAN | CANCELED - Cancellation of the related order position. Additionally a cancellation of the order position will be created. |
| Position | ADD | ADDED - Order position was added by the supplier. |
Possible combinations for response state in header and order position:
- ACCEPTED (ACC) state in header is only allowed when all positions are accepted too.
- CANCELED (CAN) state in header is only allowed when all positions are canceled too.
- ACCEPTED-WITH-CHANGE (AWC) state in the header has to be reported in every other case.
You can see these rules in the following overview:
| ACC | Standard: Every position is confirmed | Confirmed order positions after initial message | - |
|---|---|---|---|
| UNC | - | Unchanged order positions in following messages | - |
| CHG | - | Changed position(s), e.g., partial cancellation | - |
| CAN | - | Complete cancellation of less order positions than all | Complete cancellation |
| ADD | - | Added position | - |
Header → Position ↓ | ACC | AWC | CAN |
Response Types
Every response message should be marked with a type:
Type | Description |
|---|---|
| INITIAL | Initial order response. This message needs to contain general information for each position of the original response. Initial order responses are always processed first. |
| CONTINUOUS | Changes in order state can be shown in CONTINUOUS responses. |
| TEMPORARY | An IOM-specific response which sends non-binding information about the order to the shop. This specification is created from the information in IOM without requesting the connected suppliers. |
Approval Codes
Approval State
| Code | Description |
|---|---|
APPROVED | The approval was confirmed. |
| APPROVED_WITH_CHANGES | The approval was confirmed with changes. |
NOT_APPROVED | The approval was rejected. |
PENDING | The approval is pending. |
WAITING_FOR_APPROVAL | The approval is waiting for confirmation. |
Order Return Codes
Order return codes are used within web service calls regarding the return management. They cover return types, return reasons and more.
Return Types
The return type groups of the return reasons:
Code | Description |
|---|---|
| CAN | Cancellation of the order before being approved |
RCL | Recall of goods |
INV | Inversion - Customer did not received the goods |
RET | Return in general |
DEF | Defect - Return because of defect goods |
Return Reasons
Return reason codes specify the reason of a return. Every return reason code uses his return type code as prefix. E.g., CAN010 including CAN as return type cancellation.
Code | Description |
|---|---|
CAN | Cancellation |
CAN010 | Cancellation on customer demand |
CAN020 | Cancellation due to EOL (End-Of-Life) |
CAN030 | Payment not received |
CAN031 | Leasing denied |
CAN040 | Payment by installment denied |
CAN050 | Purchase on account denied |
CAN060 | Credit card order without feedback |
CAN070 | Credit card order with foreign credit card |
CAN080 | Cancellation due to suspicion of defraud |
CAN090 | Cancellation due to erroneous pricing |
CAN200 | Cancellation due to distributor switch |
CAN990 | Other reasons |
RCL | Recall |
RCL010 | Cancellation on customer demand |
RCL015 | Cancellation on shop demand |
RCL020 | Cancellation due to EOL (End-Of-Life) |
RCL021 | Cancellation due to missing stock |
RCL023 | Cancellation due to erroneous article assignment |
RCL024 | Cancellation due to missing sales price |
RCL025 | Cancellation due to erroneous pricing |
RCL030 | Erroneous approval |
RCL040 | Approval rejected |
RCL041 | Approval rejected due to EOL (End-Of-Life) |
RCL045 | Payment not received |
RCL050 | Purchase on account denied |
RCL200 | Cancellation due to missing distributor assignment |
RCL300 | Cancellation due to an erroneous order |
RCL400 | Cancellation due to erroneous distributor processes |
RCL980 | Cancellation due to suspicion of defraud |
RCL990 | Other reasons |
INV | Inversion |
INV010 | Refusal of acceptance by consignee |
INV020 | Consignee not met |
INV030 | Wrong shipping address |
INV040 | Loss during shipment |
INV990 | Other reasons |
RET | Return |
RET010 | Return of goods/general |
RET020 | Return of goods because of bad workmanship |
RET030 | Return of goods because of missing product attributes |
RET035 | Return of goods because picture differs from item |
RET040 | Return of goods because of better offer |
RET045 | Return of goods because of inadequate price |
RET046 | Return of goods because of wrong price |
RET050 | Return of goods because delivery time too long |
RET055 | Return of goods because of duplicate delivery |
RET057 | Return of goods because wrong quantity delivered |
RET060 | Defect within return period, DOA (Dead-On-Arrival) |
RET070 | Item incomplete, missing parts |
RET075 | Order incomplete, missing position |
RET080 | Shop delivered wrong item |
RET090 | Distributor delivers wrong item |
RET100 | Transport damage |
RET110 | Return on goodwill |
RET120 | Unauthorized return |
RET130 | Return of stained goods |
RET140 | Return of goods because customer does not like the design |
RET142 | Return of goods because item too large/wide |
RET144 | Return of goods because item too small/tight |
RET145 | Return of goods because item too long |
RET146 | Return of goods because item too short |
RET147 | Return of goods because item squeezes |
RET148 | Return of goods because item has too much compression |
RET149 | Return of goods because item has not enough compression |
RET150 | Return of goods because customer ordered several sizes/colors |
RET160 | Return of goods because customer does not like the material |
RET170 | Return of goods because customer does not like pattern/color |
RET180 | Return of replacement |
RET190 | Return of goods because product does not meet customer's expectations |
RET200 | Return rejected |
RET990 | Other reasons |
DEF | Defect |
DEF010 | DOA (Dead-On-Arrival), replacement through distributor |
DEF020 | DOA (Dead-On-Arrival), credit note from distributor |
DEF030 | DOA (Dead-On-Arrival), replacement through shop |
DEF040 | Credit note with 6 months warranty |
DEF050 | Credit note after 6 months warranty |
DEF060 | Warranty with repair/replacement through distributor |
DEF070 | Warranty with repair/replacement through shop |
DEF080 | Guarantee with credit note |
DEF090 | Guarantee with repair/replacement |
DEF100 | Unauthorized return of defective item |
DEF990 | Other reasons |
Codes for Non-Returnable Reasons
These codes are actually not specified, but required for reverse service and return slip. In case an order cannot be returned, the reason should be reported encoded.
Deduction Classes
Deductions are calculated according to deduction classes. With a deduction of 0% full price is refunded. A deduction of 100% accords to no refund. The reduction codes have to be created at project customization.
Return States
These codes are used within the ReverseService. Currently there is no mapping.
Code | Description |
|---|---|
VIEWABLE | Return for that no action is possible (any longer) |
CONFIRMABLE | Return that should be noticed |
DECIDABLE | Return that should be approved (goodwill) |
Return Actions
Process an action for a return. Actions can be used to accept or decline a return.
Code | Description |
|---|---|
ACCEPT | Approval accepted and marked as accepted |
DECLINE | Approval rejected |
Return Action Response
The response for a return action.
Code | Description |
|---|---|
| ACCEPT | Release of the return is accepted or is signed as "taken notice of" |
OK | Response for an action. Action was successful |
| DECLINE | Release of the return was rejected/ declined |
Report Codes
Report codes are used in services that return a report and can be used to control the view of a report.
Sort Order Property
The sort order property specifies an attribute a sort order should be attached to.
Services | Code | Description |
|---|---|---|
ReturnOrder | BY_ID | Order number as used by the shop |
ReturnOrder | BY_SUPPLIER | Name of the supplier as used by the shop |
ReturnOrder | BY_DATE | Creation date of the order at the shop |
Sort Order Direction
The sort order direction specifies the sort direction of the items of a report.
Services | Code | Description |
|---|---|---|
OrderStateService, ReturnOrder | Asc | Ascending as default |
OrderStateService, ReturnOrder | Desc | Descending |
Error Codes
Error codes specify errors that can occur during web service calls.
Code | Description |
|---|---|
ANOTHER_CANCEL_REQUEST_RUNNING | Another cancel request is already in progress. |
CHOICE_VIOLATION | The schema expects exactly one out of n elements. The error occurs when no element or more than one element is found. |
CONCURRENT_TAXTYPE | The tax type in one unit differs from the tax type of the position. |
FAILED_VALIDATION | A message (which is transformed if necessary and successfully integrated) contains a logical error. |
INCONSISTENT_RETURN_PRICES | For the return both, a reduction and a reduced price, are mentioned. Only one of the two is allowed. |
MESSAGE_BINDING_ERROR | Syntax problem: Transformed message can not be integrated into the platform object. |
MESSAGE_TRANSFORMING_ERROR | Syntax problem: Message can not be transformed into the target format. |
MISSING_ELEMENT | Expected element is missing. |
MISSING_PLANNED_DELIVERY | Planned shipping date is missing. |
MISSING_QUANTITY | Expected amount of a position is missing. |
MISSING_REDUCTION_PRICE | Expected reduction price is missing. |
MISSING_STATE | State of an object is missing (if it was a mandatory field). |
NOT_EXISTING_SHOP_SUPPLIER_COMBINATION | No relationship exists between specified shop and specified supplier. |
RESULT_SIZE_NULL | Warning: The result size is empty. |
RESULT_SIZE_TOO_BIG | The found set of the request exceeds the maximum for the report size. |
SOME_POSITIONS_ALREADY_DISPATCHED | Some positions cannot be canceled - they are already delivered. |
UNAUTHORIZED | The user does not have the permission to perform the planned operation. |
UNKNOWN_ADDRESSTYPE | Address type is unknown. |
UNKNOWN_CARRIER | No carrier with specified name exists. |
UNKNOWN_CHARGETYPE | Charge type is unknown. |
UNKNOWN_COUNTRY | Country code is unknown. |
UNKNOWN_DELIVERYOPTION | The delivery option is unknown or not configured for the requested shop. |
UNKNOWN_DELIVERYTYPE | Delivery type is unknown. |
UNKNOWN_FILTER_FLAG | (Search-) filter is unknown. |
UNKNOWN_ORDER | Order number is unknown. |
UNKNOWN_PAYMENTMETHOD | Payment method is unknown. |
UNKNOWN_REDUCE_REASON | Deduction class is unknown. |
UNKNOWN_RESPONSESTATE | Response state is unknown. |
UNKNOWN_RETURN_REASON | Return reason is unknown. |
UNKNOWN_SHOP | Shop with specified name unknown. |
UNKNOWN_SUPPLIER | Supplier with specified name unknown. |
UNKNOWN_SUPPLIERNAME | Supplier name is unknown. |
UNKNOWN_TAXTYPE | Tax type is unknown. |
USER_BLOCKED | The user is blocked because multiple login tries of this user failed. |
USER_PASSWORD_UNKNOWN | User name and password combination is wrong. Possible reasons: 1. user is unknown, 2. password is wrong |
WRONG_ARTICLEID | More than one position with a specified article ID. |
WRONG_CURRENCY | Currency does not correspond with the shop currency. |
WRONG_POSITION_NUMBER | Relative position number cannot be recognized. |