Reference - IOM SOAP Web Services

1 Introduction

This reference documents the SOAP-API for the Intershop Order Management System (IOM). The listed services are establishing a synchronous communication of business messages between the IOM and order related systems like shops, suppliers or any other business relevant 3rd-party system. 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.

1.1 Glossary

TermDescription
IOMThe abbreviation for Intershop Order Management
SOAP

Simple Object Access Protocol

1.2 References

2 SOAP Web Services

The following list of SOAP services gives an overview of all SOAP web services of the Intershop Order Management.

The services are establishing a synchronous communication of business messages between the IOM and order related systems like shops, suppliers or any other business relevant third-party systems.

ServiceMethodURIRequired PermissionsDescription
AddressServiceaddressService

https://<domain>/webservices/AddressService/v1.0

Note

https://<domain>/webservices/CustomerService/v1.0

Removed since version 2.15

-Dummy-implementation. Returns requested and hard-coded data.
ApprovalServicestoreApprovalResponsehttps://<domain>/webservices/ApprovalService/v1.0Create approval message

Stores an approval for a given order. Approvals can be made for example by a third-party system like a fraud prevention system.In general the order is in pending state and waiting for an approval or reject of one or more open approvals. Conditions for an approval can be configured.

CustomerService

getCustomerContacts

use https://<domain>/webservices/CustomerService/v1.1

Note

https://<domain>/webservices/CustomerService/v1.0

Removed since version 2.15
Deprecated since version 2.2




-

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

Create customer

and

Modify customer data

Stores data of a new customer or updates an existing customer.
storeCustomerContactCreate customer contact history entryStores 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.
ImmaterialOrderStateServicegetDetailedMediaLibraryhttps://<domain>/webservices/ImmaterialOrderStateService/v1.0Order 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.

getMediaLibraryOverviewOrder status web service

Returns information about a digital media library. Digital articles can be e-books, sound files, videos and more. Information like media type and number of ordered articles of the media type can be retrieved.

OrderStateServicegetOrderStateReport

https://<domain>/webservices/OrderStateService/v1.0

Note

Deprecated since version 2.15

Use the REST Order State Service instead.

Order status web service

Returns the state of one or more orders for a given customer. The state of an order can before example in state pending, canceledor delivered.

Please see Reference - IOM Order Statuses for available order states.

OrderServicestoreOrder

https://<domain>/webservices/OrderService/v1.2

Note

https://<domain>/services/OrderService/v1.1

Removed since version 2.15
Deprecated since version 2.2

Create order

Stores a new order of a shop.

RedownloadServicestoreRedownloadhttps://<domain>/webservices/RedownloadService/v1.1-

Requests a further download of a digital product from the supplier of an existing order. The supplier will return a token, e.g., a download link.

ReservationServicereservationAction

https://<domain>/webservices/ReservationService/v1.0

Note

Deprecated since version 2.15

Use the REST ATP Service instead.

The permission depends on the requested action:

  • to cancel a reservation: Cancel order/create cancellation request
  • to release a reservation: Trigger order

Releases or cancels an order.

storeReservation

https://<domain>/webservices/ReservationService/v1.0

Note

Deprecated since version 2.15

Create order

Stores an order marked as reservation.

ReturnServicestoreReturn

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

Note

Since 2.15

For RMA-processes from the view of a shop use the REST RMA API instead.

Cancel order/create cancellation request

Cancels an order. An order can be canceled completely or partially by canceling selected order positions.

returnActionReturn confirmationProcesses 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.

  • if viewable: Approve returns/cancellations
  • if confirmable: Read returns to be confirmed
  • if decidable: Read closed returns

Returns a report about returned orders. Therefor filters to limit data and sort orders can be set.

returnSlipRequestRequest return noteReturns information to create a return note for an order in the next step. One information is for example the reason of return.
ShopServicestoreDispatch

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.

storeResponseCreate receipt message

Announces the acceptance or rejection of an order or parts of an order by the supplier. Previously articles to deliver were assigned to the supplier.

ValidateArticleServicevalidateArticle

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.

3 Field Restrictions and Validations

Several fields have length restrictions. Please see the xsd-files for more details.

3.1 OrderService - Split of Street into Name and Street Number

Note

OrderService 1.0 and 1.1

  1. If a separator #@# is given it will be used for splitting.
    The first part will be used as street name, the second part as street number.
    A missing street number raises a validation exception.
  2. Else a split on digits (\d) will be used.
    The first part will be used as street name, the second part as street number.
    If failed to split at least into 2 parts, the string will be used for the name. The street number will be empty.

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 given separated.

4 Codes

This section describes different codes that can be send to the application or returned within a response.

There are codes needed for almost every web service and may be mapped to codes of communication partners.

There are also codes that are specific to the application and cannot be used across different applications and therefore have to be defined for the particular environment.

4.1 Basic Codes

4.1.1 Countries and Currencies

Country codes are used in format ISO 3166-1 alpha-3 for example DEU.

Currency codes are used in format ISO 4217 for example EUR.

Note

Country and currency codes in other formats are not supported.

4.1.2 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

Payment methods of a communication partner (shop or supplier) can be customized. Thus, it is possible that the values of a partner can be used.

4.1.3 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

Types of VAT of a communication partner (shop or supplier) can be customized. Thus, it is possible that the values of a partner can be used.

4.1.4 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

4.1.5 Carrier Names

Following carrier names are available by default and can be extendedvia project customization.

4.2 ShopService - StoreResponse

StoreResponse announces the acceptance or rejection of an order or parts of an order by the supplier. First, to be delivered articles must be assigned tothe supplier.

4.2.1 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.

LevelCodeDescription
HeadACC

ACCEPTED - Accepted without changes. The supplier accepted the order without changes in material, price,deliverydate and quantity.

HeadAWC

ACCEPTED WITH CHANGES - The supplier has accepted the order but reported changes in material, price, date or quantity.
Additionally cancellations of order positions are included. These cancellations are only added as information because they are created additionally as cancellation or return.

HeadCAN

CANCELLATION - cancellation of the order. Additionally a cancellation of the order will be created.

PositionUNC

UNCHANGED - No changes at the position since last order response.

PositionCHG

CHANGED - There are subsequent changes in quantity,deliverydate or price.

PositionCAN

CANCELED - Cancellation of the related order position. Additionally a cancellation of the order position will be created.

PositionADD

ADDED - Order position was added by the supplier.

Possible combinations for response state in header and order position:

  1. ACCEPTED (ACC) state in header is only allowed when all positions are accepted too.
  2. CANCELED (CAN) state in header is only allowed when allpositions are canceled too.
  3. 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 allComplete cancellation
ADD-Added position-
Header →
Position ↓
ACC
AWC
CAN

4.2.2 Response Types

Every response message should be marked with a type.

Type
Description
INITIALInitial order response. This message needs to contain general information for each position of the original response. Initial order responses are always processed first.
CONTINUOUSChanges in order state can be shown in CONTINUOUS responses.
TEMPORARYAn IOM specific response which sends non-binding information about the order to the shop. This specification is made from the information in the IOM system without requesting the connected suppliers.

4.3 Order Return Codes

Order return codes are used within Web service calls regarding the return management. They cover return types, return reasons and more.

4.3.1 Return Types

The return type groups of the return reasons.

Code

Description

CANCancellation 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

4.3.2 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

4.3.3 Codes for Not Returnable Reasons

This codes are actually not specified, but needed for reverse service and return slip. In case an order cannot be returned the reason should be reported encoded.

4.3.4 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 has to be created at project customization.

4.3.5 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)

4.3.6 Return Actions

Process an action for a return. Actions can be to accept or decline a return.

Code

Description

ACCEPT

Approval accepted and marked as accepted

DECLINE

Approval rejected

4.3.7 Return Action Response

The response for a return action.

Code

Description

ACCEPTRelease of the return is accepted or is signed as "taken notice of"

OK

Response for an action. Action was successful

DECLINE

Releaseof thereturnwas rejected/ declined

4.4 Report Codes

Report codes are used in services that return a report and can be used to control the view of a report.

4.4.1 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

4.4.2 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

4.5 Error Codes

Error codes specifies errors may return on 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.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets