Personal Library

Reference - IOM REST API - RMA 2.11

https://support.intershop.com/kb/307N03

Share this document

ReDoc View
Document View

Product Version	4.4
Product To Version
Status	New Labels

This API specification is available for download as an Open API 3.0 YAML file:

intershop-order-management-rma-2.11.yaml

Authentication

Basic Authentication

Please configure your clients to use this authentication method to submit user name and password.

Bearer Token Authentication

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.

Authorization

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 Specification

Introduction

OpenAPI Version: 3.0.1

IOM RMA REST API Version: 2.11

The IOM RMA REST API supports programmatic access to objects related to the Return Merchandise Authorization (RMA) process.

Changelog

Version 2.11

A list of WriteContactPerson can be added to WriteReturnRequest.
Added undocumented refinements to ContactPerson. lastName and emailAddress are required. Optional language follows ISO-639-1.
Changed example of ReadReturnRequest and WriteReturnRequest. type was changed to PICKUP for a more consistent example.
Added undocumented constraint to WriteApproval. comment is required if status should be NOT_APPROVED.

Version 2.10
New endpoint returnables, which returns all positions that can still be returned back.
New endpoint return-reasons, which returns all return reasons that are allowed for the shop.

Shop API

API endpoints, that could be used by the shop.

/shops/{shopName}/orders/{shopOrderNumber}/return-requests

GET: List the return requests

Description

Returns a list of return requests for a given shopName and shopOrderNumber.

Request Body

Request Parameters

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

Response

200 - OK

Array of ReadReturnRequest application/vnd.intershop.return-request.v1+json

401 - Unauthorized Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

POST: Create a return request

Description

Creates a new return request

Request Body

WriteReturnRequest application/vnd.intershop.return-request.v1+json

Request Parameters

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

Response

201 - Created

Response Header	Description
`Location`	The path to the newly created resource \| Format: `url`

400 - Bad Request

ErrorReport application/json

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

GET: List the returnable order positions to prepare the creation of a return request

Description

Returns a list of returnable order positions. Get the necessary data to enable a client a prepare the creation of a return request.

Request Body

Request Parameters

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

Response

200 - OK

ReturnableData application/vnd.intershop.return-request.v1+json

401 - Unauthorized Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}

GET: Get a return request

Description

Returns a return request for a given shopName, shopOrderNumber and returnRequestId.

Request Body

Request Parameters

Location	Name	Format	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

Response

200 - OK

ReadReturnRequest application/vnd.intershop.return-request.v1+json

401 - Unauthorized Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/approvals

POST: Create an approval

Description

Creates a new approval

Request Body

WriteApproval application/vnd.intershop.approval.v1+json

Request Parameters

Location	Name	Format	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

Response

201 - Created

Response Header	Description
`Location`	The path to the newly created resource \| Format: `url`

400 - Bad Request

ErrorReport application/json

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

GET: List the return request contact persons

Description

Returns a list of return request contact persons for a given returnRequestId, shopName and shopOrderNumber.

Request Body

Request Parameters

Location	Name	Format	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

Response

200 - OK

Array of ContactPerson application/vnd.intershop.contact-person.v1+json

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

GET: List the return request custom attributes

Description

Returns a list of return request custom attributes for a given returnRequestId, shopName and shopOrderNumber.

Request Body

Request Parameters

Location	Name	Format	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

Response

200 - OK

Array of ReadCustomAttribute application/vnd.intershop.custom-attribute.v1+json

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

GET: List the return request pickup addresses

Description

Returns a list of return request pickup addresses for a given returnRequestId, shopName and shopOrderNumber.

Request Body

Request Parameters

Location	Name	Format	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

Response

200 - OK

Array of ReadPickupAddress application/vnd.intershop.pickup-address.v1+json

401 - Unauthorized Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/positions

GET: List the return request positions

Description

Returns a list of return request positions for a given returnRequestId, shopName and shopOrderNumber.

Request Body

Request Parameters

Location	Name	Format	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

Response

200 - OK

Array of ReadReturnRequestPosition application/vnd.intershop.return-request-position.v1+json

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}

GET: Get a return request position

Description

Returns a return request position for a given returnRequestId, shopName, shopOrderNumber and a returnRequestPositionId.

Request Body

Request Parameters

Location	Name	Format	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

Response

200 - OK

ReadReturnRequestPosition application/vnd.intershop.return-request-position.v1+json

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

GET: List the return request position items

Description

Returns a list of return request position items for a given returnRequestId, shopName and shopOrderNumber.

Request Body

Request Parameters

Location	Name	Format	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

Response

200 - OK

Array of ReadReturnRequestItem application/vnd.intershop.return-request-item.v1+json

401 - Unauthorized Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

/shops/{shopName}/return-reasons

GET: List the configured return reasons for a given shop

Description

Returns a list of return reasons configured for a given shop.

Request Body

Request Parameters

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

Response

200 - OK

Array of ShopReturnReason application/vnd.intershop.return-request.v1+json

400 - Bad Request

ErrorReport application/json

401 - Unauthorized Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

Request and Response Object Schemata

ContactPerson application/vnd.intershop.contact-person.v1+json

[

ContactPerson: Represents a contact person of the return request from an order of a shop.
{

"links":
array
An array of Link objects.
[
Link
{
- "href":
  string
- "rel":
  string
}
]
"company":
string
The name of the company of the contact person. | Example: Intershop Communication AG
"firstName":
string
The first name of the contact person. | Example: John
"lastName":
string
Required | The last name of the contact person. | Example: Doe
"phoneNumber":
string
The phone number of the contact person. | Example: 0176 12345677
"emailAddress":
string
Required | The email address of the contact person. | Example: john.doe@intershop.com
"language":
string
The preferred correspondence language to answer the contact person (ISO-639-1). | Min Length: 0 | Max Length: 2 | Example: en
"id":
integer
The contact person identifier. | Format: int64 | Example: 10000

}

]

ErrorReport application/json

{

"status":
integer
The HTTP-status code applicable to this problem, expressed as a string value | Format: int32 | Example: 400
"errors":
array
An array of Error objects.
[
Error
{
- "code":
  string
  Required | The code of the error | Example: VALIDATION_EXCEPTION
- "message":
  string
  Required | The message of the error | Example: Attribute XYZ is mandatory
- "value":
  object
  The value which caused the error
}
]

}

ReadCustomAttribute application/vnd.intershop.custom-attribute.v1+json

[

ReadCustomAttribute: Represents a custom attribute (key/value pair) of a return request from an order of a shop.
{

"links":
array
An array of Link objects.
[
Link
{
- "href":
  string
- "rel":
  string
}
]
"key":
string
Required | The key of a custom attribute. | Min Length: 1 | Max Length: 250 | Example: Example Key
"value":
string
Required | The value of a custom attribute. | Min Length: 1 | Max Length: 1000 | Example: Example Value
"id":
integer
The custom attribute identifier. | Format: int64 | Example: 10000

}

]

ReadPickupAddress application/vnd.intershop.pickup-address.v1+json

[

ReadPickupAddress: Represents a pickup address related to the return request from an order of a shop.
{

"links":
array
An array of Link objects.
[
Link
{
- "href":
  string
- "rel":
  string
}
]
"company":
string
The name of the company of the pickup adress. | Min Length: 1 | Max Length: 100 | Example: Intershop Communication AG
"firstName":
string
The first name related to the pickup address. | Min Length: 1 | Max Length: 50 | Example: John
"lastName":
string
Required | The last name related to the pickup address. | Min Length: 1 | Max Length: 50 | Example: Doe
"streetName":
string
Required | The name of the street related to the pickup address. | Min Length: 1 | Max Length: 100 | Example: Alexstraße
"houseNumber":
string
The house number related to the pickup address. | Min Length: 1 | Max Length: 20 | Example: 28
"postCode":
string
Required | The post code related to the pickup address. | Min Length: 1 | Max Length: 25 | Example: 12053
"city":
string
Required | The city name related to the pickup address. | Min Length: 1 | Max Length: 100 | Example: Berlin
"countryCode":
string
Required | The ISO 3166-1 alpha-3 code for the country name related to the pickup address. | Example: DEU
"district":
string
The district related to the pickup address. | Min Length: 1 | Max Length: 100 | Example: Berlin
"additionFirstLine":
string
The first addition line related to the pickup address. | Min Length: 1 | Max Length: 100 | Example: Finanz
"additionSecondLine":
string
The second addition line related to the pickup address. | Min Length: 1 | Max Length: 100 | Example: 3.Floor
"id":
integer
The pickup address identifier. | Format: int64 | Example: 10000

}

]

ReadReturnRequest application/vnd.intershop.return-request.v1+json

[

ReadReturnRequest: Represents a return request from a shop.
{

"links":
array
An array of Link objects.
[
Link
{
- "href":
  string
- "rel":
  string
}
]
"type":
string
Required | The type that specifies the return request. | Example: PICKUP | Possible Values: RETURNPICKUP
"rmaNumber":
string
The actual number of the return request. | Min Length: 1 | Max Length: 50 | Example: 10901095
"comment":
string
The comment of the return request. | Min Length: 0 | Max Length: 255 | Example: The battery is draining quickly
"id":
integer
The return request identifier. | Format: int64 | Example: 10000
"creationDate":
string
The date when the return request was created. | Format: date-time | Example: 2018-02-27T07:15:37.562Z
"shopOrderNumber":
string
The order number as used by the shop. | Example: 20180303123
"shopName":
string
The name of the shop. | Example: Test Shop US DE
"supplierOrderNumber":
string
The order number as used by the supplier. | Example: 20180303321
"supplierName":
string
The name of the supplier. | Example: Test Supplier US DE
"status":
string
The technical status of the return request. | Example: CLOSED | Possible Values: ACCEPTEDCLOSEDDO_APPROVEDO_CLOSEINITIALREJECTED
"businessStatus":
string
The business status of the return request. | Example: ACCEPTED | Possible Values: ACCEPTEDIN_APPROVALREADY_TO_APPROVEREJECTEDUNKNOWN

}

]

ReadReturnRequestItem application/vnd.intershop.return-request-item.v1+json

[

ReadReturnRequestItem: Represents a return request item of a return request from an order of a shop.
{

"links":
array
An array of Link objects.
[
Link
{
- "href":
  string
- "rel":
  string
}
]
"productSerialNumber":
string
Required | The serial number of the product. | Min Length: 1 | Max Length: 70 | Example: W88401231AX
"id":
integer
The return request item identifier. | Format: int64 | Example: 10000

}

]

ReadReturnRequestPosition application/vnd.intershop.return-request-position.v1+json

[

ReadReturnRequestPosition: Represents a return request position of a return request from an order of a shop.
{

"links":
array
An array of Link objects.
[
Link
{
- "href":
  string
- "rel":
  string
}
]
"positionNumber":
integer
Required | The posistion number as used by the shop. | Format: int32 | Example: 1
"productNumber":
string
Required | The product number as used by the shop. | Min Length: 1 | Max Length: 50 | Example: 20180303123
"reason":
string
Required | The reason for the return. | Example: RET100
"quantity":
integer
Required | The quantity of the related product by the shop. | Format: int32 | Example: 1
"id":
integer
The return request position identifier. | Format: int64 | Example: 10000
"productName":
string
The product name as used by the shop. | Example: test_product_1
"supplierProductNumber":
string
The article number as used by the supplier. | Example: 20180303123

}

]

ReturnableData application/vnd.intershop.return-request.v1+json

{

"links":
array
An array of Link objects.
[
Link
{
- "href":
  string
- "rel":
  string
}
]
"positions":
array
Required | An array of ReturnableDataPosition objects. Possible order positions / line items to return
[
ReturnableDataPosition: Order position / line item to return
{
- "positionNumber":
  integer
  Required | Order position number as used by the shop | Format: int32 | Example: 3
- "quantity":
  integer
  Required | Maximum return quantity | Format: int32 | Example: 1
- "items":
  array
  An array of ReturnableDataItem objects. Further information for each single product
  [
  ReturnableDataItem: Further information for a single product
  {
  "productSerialNumber":
  string
  Required | Serial number of the item to return | Example: 667002
  }
  ]
- "product":
  object
  Required | A ReturnableDataProduct object. Product of a still returnable order position
  {
  "number":
  string
  Required | Shop specific product number, if not available the the IOM internal product number | Example: 100-0001
  "name":
  string
  Required | Short name of the product | Example: Demo Product
  }
}
]

}

ShopReturnReason application/vnd.intershop.return-request.v1+json

[

ShopReturnReason: Possible return reason, configured for a IOM shop instance
{

"name":
string
Required | Name of return reason / name of the enum constant (see ReturnReasonDefDO) | Example: RET010
"description":
string
Description of return reason | Example: return of goods / general
"type":
string
Name of return type / name of the enum constant (see ReturnTypeDefDO) | Example: RET

}

]

WriteApproval application/vnd.intershop.approval.v1+json

{

"status":
string
Required | The status of the approval. | Example: APPROVED | Possible Values: APPROVEDNOT_APPROVED
"comment":
string
The comment for the approval. Required if 'status' should be NOT_APPROVED. | Example: The return request reasons are not convincing.

}

WriteReturnRequest application/vnd.intershop.return-request.v1+json

{

"type":
string
Required | The type that specifies the return request. | Example: PICKUP | Possible Values: RETURNPICKUP
"rmaNumber":
string
The actual number of the return request. | Min Length: 1 | Max Length: 50 | Example: 10901095
"comment":
string
The comment of the return request. | Min Length: 0 | Max Length: 255 | Example: The battery is draining quickly
"positions":
array
Required | An array of WriteReturnRequestPosition objects.
[
WriteReturnRequestPosition: Represents a return request position of a return request from an order of a shop.
{
- "positionNumber":
  integer
  Required | The posistion number as used by the shop. | Format: int32 | Example: 1
- "productNumber":
  string
  Required | The product number as used by the shop. | Min Length: 1 | Max Length: 50 | Example: 20180303123
- "reason":
  string
  Required | The reason for the return. | Example: RET100
- "quantity":
  integer
  Required | The quantity of the related product by the shop. | Format: int32 | Example: 1
- "items":
  array
  An array of WriteReturnRequestItem objects.
  [
  WriteReturnRequestItem: Represents a return request item of a return request from an order of a shop.
  {
  "productSerialNumber":
  string
  Required | The serial number of the product. | Min Length: 1 | Max Length: 70 | Example: W88401231AX
  }
  ]
}
]
"pickupAddress":
object
A WritePickupAddress object. Represents a pickup address related to the return request from an order of a shop.
{
- "company":
  string
  The name of the company of the pickup adress. | Min Length: 1 | Max Length: 100 | Example: Intershop Communication AG
- "firstName":
  string
  The first name related to the pickup address. | Min Length: 1 | Max Length: 50 | Example: John
- "lastName":
  string
  Required | The last name related to the pickup address. | Min Length: 1 | Max Length: 50 | Example: Doe
- "streetName":
  string
  Required | The name of the street related to the pickup address. | Min Length: 1 | Max Length: 100 | Example: Alexstraße
- "houseNumber":
  string
  The house number related to the pickup address. | Min Length: 1 | Max Length: 20 | Example: 28
- "postCode":
  string
  Required | The post code related to the pickup address. | Min Length: 1 | Max Length: 25 | Example: 12053
- "city":
  string
  Required | The city name related to the pickup address. | Min Length: 1 | Max Length: 100 | Example: Berlin
- "countryCode":
  string
  Required | The ISO 3166-1 alpha-3 code for the country name related to the pickup address. | Example: DEU
- "district":
  string
  The district related to the pickup address. | Min Length: 1 | Max Length: 100 | Example: Berlin
- "additionFirstLine":
  string
  The first addition line related to the pickup address. | Min Length: 1 | Max Length: 100 | Example: Finanz
- "additionSecondLine":
  string
  The second addition line related to the pickup address. | Min Length: 1 | Max Length: 100 | Example: 3.Floor
}
"contactPersons":
array
An array of WriteContactPerson objects.
[
WriteContactPerson: Represents a contact person of the return request from an order of a shop.
{
- "company":
  string
  The name of the company of the contact person. | Example: Intershop Communication AG
- "firstName":
  string
  The first name of the contact person. | Example: John
- "lastName":
  string
  Required | The last name of the contact person. | Example: Doe
- "phoneNumber":
  string
  The phone number of the contact person. | Example: 0176 12345677
- "emailAddress":
  string
  Required | The email address of the contact person. | Example: john.doe@intershop.com
- "language":
  string
  The preferred correspondence language to answer the contact person (ISO-639-1). | Min Length: 0 | Max Length: 2 | Example: en
}
]
"customAttributes":
array
An array of WriteCustomAttribute objects.
[
WriteCustomAttribute: Represents a custom attribute (key/value pair) of a return request from an order of a shop.
{
- "key":
  string
  Required | The key of a custom attribute. | Min Length: 1 | Max Length: 250 | Example: Example Key
- "value":
  string
  Required | The value of a custom attribute. | Min Length: 1 | Max Length: 1000 | Example: Example Value
}
]

}

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.

Authentication

Basic Authentication

Bearer Token Authentication

Authorization

API Specification

Changelog

Version 2.11

Version 2.10

Description

Request Body

Request Parameters

Response

Description

Request Body

Request Parameters

Response

Description

Request Body

Request Parameters

Response

Description

Request Body

Request Parameters

Response

Description

Request Body

Request Parameters

Response

Description

Request Body

Request Parameters

Response

Description

Request Body

Request Parameters

Response

Description

Request Body

Request Parameters

Response

Description

Request Body

Request Parameters

Response

Description

Request Body

Request Parameters

Response

Description

Request Body

Request Parameters

Response

Description

Request Body

Request Parameters

Response