Document Properties
Kbid
2964N1
Last Modified
20-Jun-2023
Added to KB
21-Sep-2020
Public Access
Everyone
Status
Online
Doc Type
References
Product
  • IOM 3.0
  • IOM 3.1
  • IOM 3.2
  • IOM 3.3
  • IOM 3.4
  • IOM 3.5
  • IOM 3.6
  • IOM 3.7
  • IOM 4.0
  • IOM 4.1
  • IOM 4.2
  • IOM 4.3
  • IOM 4.4
  • IOM 4.5
  • IOM 4.6
  • IOM 4.7
  • IOM 5.0
Reference - IOM REST API - RMA 2.9.0.0
Document View


Download Specification 

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

API Specification

Introduction
OpenAPI Version: none
IOM RMA REST API Version: 2.9.0.0

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

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

LocationNameFormatDefaultExampleDescription
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

Array of ReadReturnRequest application/json

401 - Unauthorized Authentication information is missing or invalid

Response HeaderDescription
WWW-Authenticate

403 - Forbidden

404 - Not Found

406 - Not Acceptable

POST: Create a return request

Description

Creates a new return request

Request Body

--

Request Parameters

LocationNameFormatDefaultExampleDescription
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

201 - Created

Response HeaderDescription
LocationThe path to the newly created resource | Format: url

400 - Bad Request

ErrorReport application/json

401 - Unauthorized Authentication information is missing or invalid

Response HeaderDescription
WWW-Authenticate

403 - Forbidden

415 - Unsupported Media Type

500 - Internal Server Error An unexpected error occured

/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

LocationNameFormatDefaultExampleDescription
in pathreturnRequestIdinteger int64Required | The return request id of the related order
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

ReadReturnRequest application/json

401 - Unauthorized Authentication information is missing or invalid

Response HeaderDescription
WWW-Authenticate

403 - Forbidden

404 - Not Found

406 - Not Acceptable

/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

LocationNameFormatDefaultExampleDescription
in pathreturnRequestIdinteger int64Required | The return request id of the related order
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

Array of ContactPerson application/json

401 - Unauthorized Authentication information is missing or invalid

Response HeaderDescription
WWW-Authenticate

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

LocationNameFormatDefaultExampleDescription
in pathreturnRequestIdinteger int64Required | The return request id of the related order
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

Array of ReadCustomAttribute application/json

401 - Unauthorized Authentication information is missing or invalid

Response HeaderDescription
WWW-Authenticate

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

LocationNameFormatDefaultExampleDescription
in pathreturnRequestIdinteger int64Required | The return request id of the related order
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

Array of ReadPickupAddress application/json

401 - Unauthorized Authentication information is missing or invalid

Response HeaderDescription
WWW-Authenticate

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

LocationNameFormatDefaultExampleDescription
in pathreturnRequestIdinteger int64Required | The return request id of the related order
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

Array of ReadReturnRequestPosition application/json

401 - Unauthorized Authentication information is missing or invalid

Response HeaderDescription
WWW-Authenticate

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

LocationNameFormatDefaultExampleDescription
in pathreturnRequestPositionIdinteger int64Required | The return request position id of the related return request
in pathreturnRequestIdinteger int64Required | The return request id of the related order
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

ReadReturnRequestPosition application/json

401 - Unauthorized Authentication information is missing or invalid

Response HeaderDescription
WWW-Authenticate

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

LocationNameFormatDefaultExampleDescription
in pathreturnRequestPositionIdinteger int64Required | The return request position id of the related return request
in pathreturnRequestIdinteger int64Required | The return request id of the related order
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

Array of ReadReturnRequestItem application/json

401 - Unauthorized Authentication information is missing or invalid

Response HeaderDescription
WWW-Authenticate

403 - Forbidden

404 - Not Found

406 - Not Acceptable

Request and Response Object Schemata
ContactPerson application/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
    }
    ]
  • "id":
    integer
    The contact person identifier. | Format: int64 | Example: 10000
  • "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
    The last name of the contact person. | Example: Doe
  • "phoneNumber":
    string
    The phone number of the contact person. | Example: 0176 12345677
  • "emailAddress":
    string
    The email address of the contact person. | Example: john.doe@intershop.com
  • "language":
    string
    The preferred correspondence language to answer the contact person. | Example: english
}
]
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 | Exception / Error code | Example: VALIDATION_EXCEPTION
    • "message":
      string
      Required | Exception / Error message | Example: Attribute XYZ is mandatory
    • "value":
      object
      Value which caused the exception / error
    }
    ]
}
ReadCustomAttribute application/json[
{
  • "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
  • "links":
    array
    An array of Link objects.
    [
    Link
    {
    • "href":
      string
    • "rel":
      string
    }
    ]
  • "id":
    integer
    The custom attribute identifier. | Format: int64 | Example: 10000
}
]
ReadPickupAddress application/json[
{
  • "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
  • "links":
    array
    An array of Link objects.
    [
    Link
    {
    • "href":
      string
    • "rel":
      string
    }
    ]
  • "id":
    integer
    The pickup address identifier. | Format: int64 | Example: 10000
}
]
ReadReturnRequest application/json[
{
  • "type":
    string
    Required | The type that specifies the return request. | Example: RETURN | 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
  • "links":
    array
    An array of Link objects.
    [
    Link
    {
    • "href":
      string
    • "rel":
      string
    }
    ]
  • "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-27T09:15:37.562+02:00
  • "shopOrderNumber":
    string
    The order number as used by the shop. | Example: 20180303_123
  • "shopName":
    string
    The name of the shop. | Example: Test Shop US DE
  • "supplierOrderNumber":
    string
    The order number as used by the supplier. | Example: 20180303_321
  • "supplierName":
    string
    The name of the supplier. | Example: Test Supplier US DE
  • "status":
    string
    The status of the return request. | Example: accepted
}
]
ReadReturnRequestItem application/json[
{
  • "productSerialNumber":
    string
    Required | The serial number of the product. | Min Length: 1 | Max Length: 70 | Example: W88401231AX
  • "links":
    array
    An array of Link objects.
    [
    Link
    {
    • "href":
      string
    • "rel":
      string
    }
    ]
  • "id":
    integer
    The return request item identifier. | Format: int64 | Example: 10000
}
]
ReadReturnRequestPosition application/json[
{
  • "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: 20180303_123
  • "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
  • "links":
    array
    An array of Link objects.
    [
    Link
    {
    • "href":
      string
    • "rel":
      string
    }
    ]
  • "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: 20180303_123
}
]
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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.