Reference - IOM REST API - RMA 2.10


Product Version

2.15

Product To Version


Status

final

Download Specification 

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

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 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 Json Web Token (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.10

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.

GET
/shops/{shopName}/return-reasons List the configured return reasons for a given shop

Request Path

/shops/{shopName}/return-reasons

Description

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

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathshopNamestringRequired | The shop name
in querytypearrayFilter the return reasons by name of 1..n return types | Example: RET

Response

200 - OK

Array of ShopReturnReason application/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
}
]

400 - Bad Request

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
    }
    ]
}

401 - Unauthorized

Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

POST
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/approvals Create an approval

Request Path

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

Description

Creates a new approval

Request Body

WriteApproval application/json{
  • "status":
    string
    Required | The status of the approval. | Example: APPROVED | Possible Values: APPROVEDNOT_APPROVED
  • "comment":
    string
    The comment for the approval. | Example: The return request reasons are not convincing.
}

Request Parameters

LocationNameFormatDescription
in pathreturnRequestIdintegerRequired | The return request id of the related order | Format: int64
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{
  • "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
    }
    ]
}

401 - Unauthorized

Authentication information is missing or invalid

403 - Forbidden

415 - Unsupported Media Type

500 - Internal Server Error

An unexpected error occured
GET
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/contact-persons List the return request contact persons

Request Path

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

Description

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

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathreturnRequestIdintegerRequired | The return request id of the related order | Format: int64
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

Array of 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
}
]

401 - Unauthorized

Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

GET
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId} Get a return request

Request Path

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

Description

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

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathreturnRequestIdintegerRequired | The return request id of the related order | Format: int64
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

ReadReturnRequest application/json{
  • "links":
    array
    An array of Link objects.
    [
    Link:
    {
    • "href":
      string
    • "rel":
      string
    }
    ]
  • "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
  • "id":
    integer
    The return request identifier. | Format: int64 | Example: 10000
  • "creationDate":
    string
    The date when the return request was created. | Format: date-time
  • "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
}

401 - Unauthorized

Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

GET
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/returnables List the returnable order positions to prepare the creation of a return request

Request Path

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

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

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

Response

200 - OK

ReturnableData application/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
      }
    }
    ]
}

401 - Unauthorized

Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

GET
/shops/{shopName}/orders/{shopOrderNumber}/return-requests List the return requests

Request Path

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

Description

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

Request Body

--

Request Parameters

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

Response

200 - OK

Array of ReadReturnRequest application/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: 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
  • "id":
    integer
    The return request identifier. | Format: int64 | Example: 10000
  • "creationDate":
    string
    The date when the return request was created. | Format: date-time
  • "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
}
]

401 - Unauthorized

Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

POST
/shops/{shopName}/orders/{shopOrderNumber}/return-requests Create a return request

Request Path

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

Description

Creates a new return request

Request Body

WriteReturnRequest 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
  • "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
    }
  • "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
    }
    ]
}

Request Parameters

LocationNameFormatDescription
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{
  • "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
    }
    ]
}

401 - Unauthorized

Authentication information is missing or invalid

403 - Forbidden

415 - Unsupported Media Type

500 - Internal Server Error

An unexpected error occured
GET
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/pickup-addresses List the return request pickup addresses

Request Path

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

Description

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

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathreturnRequestIdintegerRequired | The return request id of the related order | Format: int64
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

Array of ReadPickupAddress application/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
}
]

401 - Unauthorized

Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

GET
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/custom-attributes List the return request custom attributes

Request Path

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

Description

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

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathreturnRequestIdintegerRequired | The return request id of the related order | Format: int64
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

Array of ReadCustomAttribute application/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
}
]

401 - Unauthorized

Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

GET
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/positions/{returnRequestPositionId}/items List the return request position items

Request Path

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

Description

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

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathreturnRequestPositionIdintegerRequired | The return request position id of the related return request | Format: int64
in pathreturnRequestIdintegerRequired | The return request id of the related order | Format: int64
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

Array of ReadReturnRequestItem application/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
}
]

401 - Unauthorized

Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

GET
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/positions/{returnRequestPositionId} Get a return request position

Request Path

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

Description

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

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathreturnRequestPositionIdintegerRequired | The return request position id of the related return request | Format: int64
in pathreturnRequestIdintegerRequired | The return request id of the related order | Format: int64
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

ReadReturnRequestPosition application/json{
  • "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
}

401 - Unauthorized

Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

GET
/shops/{shopName}/orders/{shopOrderNumber}/return-requests/{returnRequestId}/positions List the return request positions

Request Path

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

Description

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

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathreturnRequestIdintegerRequired | The return request id of the related order | Format: int64
in pathshopOrderNumberstringRequired | The order number of the shop
in pathshopNamestringRequired | The shop name

Response

200 - OK

Array of ReadReturnRequestPosition application/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
}
]

401 - Unauthorized

Authentication information is missing or invalid

403 - Forbidden

404 - Not Found

406 - Not Acceptable

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