This API specification is available for download as an Open API 3.0 YAML file:
Please configure your clients to use this authentication method to submit user name and password.
To generate a valid JSON Web Token (JWT), just log into the OMT, inspect the browser cookies and use the value of the cookie called 'OMS_IDENTITY' as JWT. Within an UI-client (e.g., Postman) choose "Bearer Token" and just type in a valid JWT.
The permission "View return requests" is required to use the GET endpoints and must be assigned at the requested shop_name organization. The permission "Manage return requests" is required to use the POST endpoints and must be assigned at the requested shop_name organization.
API endpoints, that could be used by the shop.
/shops/{shopName}/orders/{shopOrderNumber}/return-requests
Returns a list of return requests for a given shopName and shopOrderNumber.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
Creates a new return request
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
201 - Created
Response Header | Description |
---|---|
Location | The path to the newly created resource | Format: url |
400 - Bad Request
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
415 - Unsupported Media Type
500 - Internal Server Error An unexpected error occured
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/returnables
Returns a list of returnable order positions. Get the necessary data to enable a client a prepare the creation of a return request.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}
Returns a return request for a given shopName, shopOrderNumber and returnRequestId.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
Replaces the given return request with an updated one
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestId | integer int64 | Required | The return request id | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK Created
400 - Bad Request
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
415 - Unsupported Media Type
500 - Internal Server Error An unexpected error occured
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/approvals
Creates a new approval
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
201 - Created
Response Header | Description |
---|---|
Location | The path to the newly created resource | Format: url |
400 - Bad Request
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
415 - Unsupported Media Type
500 - Internal Server Error An unexpected error occured
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/contact-persons
Returns a list of return request contact persons for a given returnRequestId, shopName and shopOrderNumber.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/custom-attributes
Returns a list of return request custom attributes for a given returnRequestId, shopName, and shopOrderNumber.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
Replaces all earlier custom attributes and returns the new list of custom attributes of a return request for a given returnRequestId, shopName, and shopOrderNumber.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
Create new custom attributes or update existing ones for a return request. Returns the whole new list of custom attributes for this return request.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
201 - Created
400 - Bad Request
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/custom-attributes/{customAttributeId}
Returns a custom attribute of a return request for a given returnRequestId, shopName, and a shopOrderNumber.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | customAttributeId | integer int64 | Required | The id of the custom attribute of the return request | ||
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
Delete a custom attribute for a given returnRequestId, shopName, shopOrderNumber, and a customAttributeId.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | customAttributeId | integer int64 | Required | The id of the custom attribute of the related return request | ||
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/pickup-addresses
Returns a list of return request pickup addresses for a given returnRequestId, shopName and shopOrderNumber.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/positions
Returns a list of return request positions for a given returnRequestId, shopName and shopOrderNumber.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/positions/{returnRequestPositionId}
Returns a return request position for a given returnRequestId, shopName, shopOrderNumber and a returnRequestPositionId.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestPositionId | integer int64 | Required | The return request position id of the related return request | ||
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/positions/{returnRequestPositionId}/custom-attributes
Returns a list of custom attributes of a return request position for a given returnRequestPositionId, shopName, and shopOrderNumber.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestPositionId | integer int64 | Required | The return request position id of the related return request | ||
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
Replaces all earlier custom attributes and returns the new list of custom attributes of a return request position for a given returnRequestPositionId, returnRequestId, shopName, and shopOrderNumber.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestPositionId | integer int64 | Required | The return request position id of the related return request | ||
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
Create new custom attributes or update existing ones for a return request position. Returns the whole new list of custom attributes for this position.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestPositionId | integer int64 | Required | The return request position id of the related return request | ||
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
201 - Created
400 - Bad Request
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/positions/{returnRequestPositionId}/custom-attributes/{customAttributeId}
Returns a custom attribute of a return request position for a given returnRequestPositionId, returnRequestId, shopName, and a shopOrderNumber.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | customAttributeId | integer int64 | Required | The id of the custom attribute of the return request position | ||
in path | returnRequestPositionId | integer int64 | Required | The return request position id of the related return request | ||
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
Delete a custom attribute for a given returnRequestId, shopName, shopOrderNumber, returnRequestPositionId, and a customAttributeId.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | customAttributeId | integer int64 | Required | The id of the custom attribute of the related return request position | ||
in path | returnRequestPositionId | integer int64 | Required | The return request position id of the related return request | ||
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/positions/{returnRequestPositionId}/items
Returns a list of return request position items for a given returnRequestId, shopName and shopOrderNumber.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | returnRequestPositionId | integer int64 | Required | The return request position id of the related return request | ||
in path | returnRequestId | integer int64 | Required | The return request id of the related order | ||
in path | shopOrderNumber | string | Required | The order number of the shop | ||
in path | shopName | string | Required | The shop name |
200 - OK
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
406 - Not Acceptable
/shops/{shopName}/return-reasons
Returns a list of return reasons configured for a given shop.
Location | Name | Format | Default | Example | Description |
---|---|---|---|---|---|
in path | shopName | string | Required | The shop name | ||
in query | type | array | RET | Filter the return reasons by name of 1..n return types |
200 - OK
400 - Bad Request
401 - Unauthorized Authentication information is missing or invalid
403 - Forbidden
404 - Not Found
ContactPerson
: Represents a contact person of the return request from an order of a shop.Link
objects.Link
Intershop Communication AG
John
Doe
0176 12345677
john.doe@intershop.com
0
| Max Length: 2
| Example: en
int64
| Example: 10000
int32
| Example: 400
Error
objects.Error
VALIDATION_EXCEPTION
Attribute XYZ is mandatory
ReadCustomAttribute
: Represents a custom attribute (key/value pair) of a return request from an order of a shop.Link
objects.Link
1
| Max Length: 250
| Example: Example Key
1
| Max Length: 1000
| Example: Example Value
int64
| Example: 10000
ReadPickupAddress
: Represents a pickup address related to the return request from an order of a shop.Link
objects.Link
1
| Max Length: 100
| Example: Intershop Communication AG
1
| Max Length: 50
| Example: John
1
| Max Length: 50
| Example: Doe
1
| Max Length: 100
| Example: Alexstraße
1
| Max Length: 20
| Example: 28
1
| Max Length: 25
| Example: 12053
1
| Max Length: 100
| Example: Berlin
DEU
1
| Max Length: 100
| Example: Berlin
1
| Max Length: 100
| Example: Finanz
1
| Max Length: 100
| Example: 3.Floor
int64
| Example: 10000
ReadReturnRequest
: Represents a return request from a shop.Link
objects.Link
PICKUP
| Possible Values: RETURN
PICKUP
1
| Max Length: 50
| Example: 10901095
0
| Max Length: 255
| Example: The battery is draining quickly
int64
| Example: 10000
date-time
| Example: 2018-02-27T07:15:37.562Z
20180303123
Test Shop US DE
20180303321
Test Supplier US DE
CLOSED
| Possible Values: ACCEPTED
CLOSED
DO_APPROVE
DO_CLOSE
INITIAL
REJECTED
ACCEPTED
| Possible Values: ACCEPTED
IN_APPROVAL
READY_TO_APPROVE
REJECTED
UNKNOWN
ReadReturnRequestItem
: Represents a return request item of a return request from an order of a shop.Link
objects.Link
1
| Max Length: 70
| Example: W88401231AX
int64
| Example: 10000
ReadReturnRequestPosition
: Represents a return request position of a return request from an order of a shop.Link
objects.Link
int32
| Example: 1
1
| Max Length: 50
| Example: 20180303123
RET100
int32
| Example: 1
int64
| Example: 10000
test_product_1
20180303123
ReadCustomAttribute
objects.ReadCustomAttribute
: Represents a custom attribute (key/value pair) of a return request from an order of a shop.Link
objects.Link
1
| Max Length: 250
| Example: Example Key
1
| Max Length: 1000
| Example: Example Value
int64
| Example: 10000
Link
objects.Link
ReturnableDataPosition
objects. Possible order positions / line items to returnReturnableDataPosition
: Order position / line item to returnint32
| Example: 3
int32
| Example: 1
ReturnableDataItem
objects. Further information for each single productReturnableDataItem
: Further information for a single product667002
ReturnableDataProduct
object. Product of a still returnable order position100-0001
Demo Product
ShopReturnReason
: Possible return reason, configured for a IOM shop instanceRET010
return of goods / general
RET
APPROVED
| Possible Values: APPROVED
NOT_APPROVED
Required if 'status' should be NOT_APPROVED.
| Example: The return request reasons are not convincing.
WriteCustomAttribute
: Represents a custom attribute (key/value pair) of a return request from an order of a shop.1
| Max Length: 250
| Example: Example Key
1
| Max Length: 1000
| Example: Example Value
PICKUP
| Possible Values: RETURN
PICKUP
1
| Max Length: 50
| Example: 10901095
0
| Max Length: 255
| Example: The battery is draining quickly
WriteReturnRequestPosition
objects.WriteReturnRequestPosition
: Represents a return request position of a return request from an order of a shop.int32
| Example: 1
1
| Max Length: 50
| Example: 20180303123
RET100
int32
| Example: 1
WriteReturnRequestItem
objects.WriteReturnRequestItem
: Represents a return request item of a return request from an order of a shop.1
| Max Length: 70
| Example: W88401231AX
WriteCustomAttribute
objects.WriteCustomAttribute
: Represents a custom attribute (key/value pair) of a return request from an order of a shop.1
| Max Length: 250
| Example: Example Key
1
| Max Length: 1000
| Example: Example Value
WritePickupAddress
object. Represents a pickup address related to the return request from an order of a shop.1
| Max Length: 100
| Example: Intershop Communication AG
1
| Max Length: 50
| Example: John
1
| Max Length: 50
| Example: Doe
1
| Max Length: 100
| Example: Alexstraße
1
| Max Length: 20
| Example: 28
1
| Max Length: 25
| Example: 12053
1
| Max Length: 100
| Example: Berlin
DEU
1
| Max Length: 100
| Example: Berlin
1
| Max Length: 100
| Example: Finanz
1
| Max Length: 100
| Example: 3.Floor
WriteContactPerson
objects.WriteContactPerson
: Represents a contact person of the return request from an order of a shop.Intershop Communication AG
John
Doe
0176 12345677
john.doe@intershop.com
0
| Max Length: 2
| Example: en
WriteCustomAttribute
objects.WriteCustomAttribute
: Represents a custom attribute (key/value pair) of a return request from an order of a shop.1
| Max Length: 250
| Example: Example Key
1
| Max Length: 1000
| Example: Example Value