Returns Service

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

The Emporix API Returns Service allows you to manage your returns.

Returns

Creating a single return entity

Creates a single return document with given information. If a return is being created by a customer directly, then the returns.returns_manage_own scope is required. If a return is being created by a tenant employee on behalf of a customer, then the returns.returns_manage scope is required. Note: Depending on a case, a different set of fields is required and allowed.

Required scopes (one of)

  • returns.returns_manage
  • returns.returns_manage_own
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name. Note: The tenant name should always be written in lowercase.

header Parameters
saas-token
string

Customer’s saasToken retrieved when logging in a customer. The header is mandatory for operations done by a customer.

Request Body schema: application/json
Any of:

Base schema for a return requested by a customer.

required
Array of objects (order)

A list of orders that contain items to be returned. All the orders must have the same currency.

required
object

A reason why the return is created. One of the values needs to be provided: code or details.

mixins
object

The field contains mixins values.

object (metadataCore)

Metadata request.

Responses
201

The resource has been successfully created.

400

Resources cannot be created due to an error.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

409

Return with given code already exists.

500

Internal Server Error.

post/{tenant}/returns
Request samples
application/json
{}
Response samples
application/json
{
  • "id": "88b1779c-a8bf-4b94-b1be-b0edd149bba5"
}

Retrieving a list of returns

Retrieves a list of return documents.

Required scopes (one of)

  • returns.returns_read
  • returns.returns_read_own
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name. Note: The tenant name should always be written in lowercase.

query Parameters
pageSize
integer [ 1 .. 60 ]
Default: 60

The number of documents being retrieved on one page.

pageNumber
integer >= 1
Default: 1

The page number to be retrieved, where the size of the pages is specified by the pageSize parameter. The number of the first page is 1.

sort
string

Fields to sort the response data by following the order of the parameters from left to right. Can contain multiple fields in the following format: field name:sort direction, separated by a comma. The colon preceding the sort direction parameter is optional, and the descending order is taken only if it is equal to desc or DESC. The ascending order is assumed in any other case.

Example: sort=sort=name,metadata.createdAt:desc
q
string

A standard query parameter is used to search for specific values.

  • Searching for an item by a string property: q=approvalStatus:PENDING, where approvalStatus is the name of the string field and PENDING is its required value.
  • Searching for items by a number-based property:
    • Searching for items with specific values: q=mixins.returnCustomAttributes.orderQuantity:20
    • Searching for items with values greater than: q=mixins.returnCustomAttributes.orderQuantity:>20
    • Searching for items with values lower than: q=mixins.returnCustomAttributes.orderQuantity:<20
    • Searching for items with values greater than or equal to: q=mixins.returnCustomAttributes.orderQuantity:>=20
    • Searching for items with values lower than or equal to: q=mixins.returnCustomAttributes.orderQuantity:<=20
    • Searching for items within a range of values: q=mixins.returnCustomAttributes.orderQuantity:(>=10 AND <=20), where mixins.returnCustomAttributes.orderQuantity is the name of a number-based field, and 20 is its querying value.
  • Searching for items by a date property. All number-based property queries are also valid for dates. In that case, the date should be placed within double quotes: q=metadataCreatedAt:(>="2021-05-18T07:27:27.455Z" AND <"2021-05-20T07:27:27.455Z")
  • Searching for items by a boolean value: q=received:true, where received is the name of a boolean field, and 'true' is its required value.
  • Searching for items with a non-existing or empty property: q=reason.description:null, where reason.description is the name of the field that has the null value.
  • Searching for items with an existing property: q=mixin:exists, where mixin is the name of the field that has the non null value.
  • Searching for items by multiple specific values: q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494), where id is the name of the field, and strings within a bracket are its required values.
  • Searching for items by multiple fields: q=id:5c3325baa9812100098ff48f code:A705121667, where id and 'code' are the names of fields. All documents that contain the specified values in these fields are returned. Multiple fields separated by spaces can be specified. Multiple values for each field can also be provided in the format presented above.
  • Searching for items with string fields conforming to a regex: q=orders._id:~EON107 or q=code:(~EON107 EON106) - in the case of searching for strings with a space, where order._id is the name of the field and EON107 or EON107 EON106 are its querying regular expressions.
Example: q=q=approvalStatus:APPROVED
header Parameters
X-Total-Count
boolean

To get information how many entities meet the filtering requirements, the X-Total-Count header has been introduced. The header is optional and its default value is false. If the header is provided and it is set to true, then the total count is returned in the X-Total-Count response header. In both cases (X-Total-Count true, false or not provided), the response body has the same format (array of entities). This means that the information about the total count is returned only on demand, provided that the X-Total-Count header is present in a request.

Responses
200

Example response

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

get/{tenant}/returns
Request samples 
Response samples 
application/json
[
  • {
    }
]
Retrieving a single return
Retrieves a single return document.




Required scopes (one of)


    

  • returns.returns_read
    • 

  • returns.returns_read_own
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.
Note: The tenant name should always be written in lowercase.


 
returnId
required
string
Unique identifier of a return.


 
Responses 
200
401
Unauthorized


403
Access forbidden. The caller is not allowed to access this resource.


404
Not found response due to not-existing entity


get/{tenant}/returns/{returnId}
Request samples 
Response samples 
application/json
{
  • "id": "7ba2f2b6-7dc8-45ff-9f20-4e6163c14c2e",
  • "approvalStatus": "PENDING",
  • "received": false,
  • "orders": [
    ],
  • "reason": {
    },
  • "total": {
    },
  • "expiryDate": "2023-04-31T13:18:02.379Z",
  • "metadata": {
    }
}
Updating a single return
Updates a single return document with given information.
If a return is being updated by a customer directly, then the returns.returns_manage_own scope is required.
If a return is being updated by a tenant employee on behalf of a customer, then the returns.returns_manage scope is required.
Note: Depending on a case, a different set of fields is required and allowed.
A customer can change a return only when the return approval status is PENDING.




Required scopes (one of)


    

  • returns.returns_manage
    • 

  • returns.returns_manage_own
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.
Note: The tenant name should always be written in lowercase.


 
returnId
required
string
Unique identifier of a return.


 
header Parameters
saas-token
string
Customer’s saasToken retrieved when logging in a customer. The header is mandatory for operations done by a customer. 


 
Request Body schema: application/json
Any of:
Base schema for a return requested by a customer.


id
string
Unique identifier of a return.


 
required
Array of objects (order) 
A list of orders that contain items to be returned. All the orders must have the same currency. 


 
required
object
A reason why the return is created. One of the values needs to be provided: code or details. 


 
mixins
object
The field contains mixins values.


 
required
object (metadataUpdate) 
Metadata request.


 
Responses 
204
No Content


400
Bad request due to validation, incorrect parameters, etc.


401
Unauthorized


403
Access forbidden. The caller is not allowed to access this resource.


404
Not found response due to not-existing entity


500
Internal Server Error.


put/{tenant}/returns/{returnId}
Request samples 
application/json
{
  • "id": "6369140c5c6de75d9e84c97f",
  • "orders": [
    ],
  • "reason": {
    },
  • "mixins": {
    },
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "code": 0,
  • "status": "string",
  • "message": "string",
  • "details": [
    ]
}
Deleting a single return
Deletes a single return document.
The return can be deleted completely only by an employee, that is a user who has the returns.returns_manage scope granted. A customer, who has the returns.returns_manage_own scope granted, can delete a return only if the return status is PENDING. The return status is changed to CLOSED during the delete operation.




*Required scopes (one of)


    

  • returns.returns_manage
    • 

  • returns.returns_manage_own
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.
Note: The tenant name should always be written in lowercase.


 
returnId
required
string
Unique identifier of a return.


 
header Parameters
saas-token
string
Customer’s saasToken retrieved when logging in a customer. The header is mandatory for operations done by a customer. 


 
Responses 
204
No Content


400
Bad request - a return cannot be deleted because it has an inappropriate status.


401
Unauthorized


403
Access forbidden. The caller is not allowed to access this resource.


500
Internal Server Error.


delete/{tenant}/returns/{returnId}
Request samples 
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Deleting this return is not allowed since it doesn't match all preconditions."
}
Partial updating a single return
Parial update of a single return document with given information.
If a return is being updated by a customer directly, then the returns.returns_manage_own and returns.returns_read_own scope is required.
If a return is being updated by a tenant employee on behalf of a customer, then the returns.returns_manage and returns.returns_read scope is required.
Note: Depending on a case, a different set of fields is allowed.
A customer can change a return only when the return approval status is PENDING.


The patch request consists of set of operation, that should be defined according to RFC-6902 standard




Required scopes (one of)


    

  • returns.returns_manage
    • 

  • returns.returns_manage_own
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.
Note: The tenant name should always be written in lowercase.


 
returnId
required
string
Unique identifier of a return.


 
header Parameters
saas-token
string
Customer’s saasToken retrieved when logging in a customer. The header is mandatory for operations done by a customer. 


 
Request Body schema: application/json
 Array 
op
required
string
Indicates an operation which should be done on a return. Available operations: add remove and replace


 Enum: "add" "remove" "replace"  
path
required
string
Indicates a path for which the value should be applied. For example:/mixins/additionalAttributes/externalId, /approvalStatus, /requestor/customerId


 
object or string
Indicates a value that should be changed or added. The value can be of a primitive type, like string, number, boolean or it can be an object or an array.


 
Responses 
204
No Content


400
Bad request due to validation, incorrect parameters, etc.


401
Unauthorized


403
Access forbidden. The caller is not allowed to access this resource.


404
Not found response due to not-existing entity


500
Internal Server Error.


patch/{tenant}/returns/{returnId}
Request samples 
application/json
[
  • {
    }
]
Response samples 
application/json
{
  • "code": 0,
  • "status": "string",
  • "message": "string",
  • "details": [
    ]
}