Returns
Retrieves a list of return documents.
Required scopes (one of)
returns.returns_readreturns.returns_read_own
Your Emporix tenant's name. Note: The tenant name should always be written in lowercase.
^[a-z][a-z0-9]+$The number of documents being retrieved on one page.
60The 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.
1Fields 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.
sort=name,metadata.createdAt:descA standard query parameter is used to search for specific values.
- Searching for an item by a string property:
q=approvalStatus:PENDING, whereapprovalStatusis the name of the string field andPENDINGis 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), wheremixins.returnCustomAttributes.orderQuantityis the name of a number-based field, and20is its querying value.
- Searching for items with specific values:
- 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, wherereceivedis 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, wherereason.descriptionis the name of the field that has thenullvalue. - Searching for items with an existing property:
q=mixin:exists, wheremixinis the name of the field that has thenon nullvalue. - Searching for items by multiple specific values:
q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494), whereidis 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, whereidand '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:~EON107orq=code:(~EON107 EON106)- in the case of searching for strings with a space, whereorder._idis the name of the field andEON107orEON107 EON106are its querying regular expressions.
q=approvalStatus:APPROVEDTo 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.
GET /return/{tenant}/returns HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
[
{
"id": "7ba2f2b6-7dc8-45ff-9f20-4e6163c14c2e",
"approvalStatus": "PENDING",
"received": false,
"orders": [
{
"id": "B1LMYY52",
"items": [
{
"id": "32090",
"name": "T-shirt",
"quantity": 2,
"reason": {
"code": "001",
"details": "It's too small"
},
"unitPrice": {
"value": 1.99,
"currency": "USD"
},
"total": {
"value": 3.98,
"currency": "USD"
}
},
{
"id": "32102",
"name": "Jacket",
"quantity": 15,
"unitPrice": {
"value": 1,
"currency": "USD"
},
"total": {
"value": 15,
"currency": "USD"
}
}
]
}
],
"reason": {
"code": "001",
"details": "The items do not work."
},
"total": {
"value": 18.98,
"currency": "USD"
},
"expiryDate": "2023-04-31T13:18:02.379Z",
"metadata": {
"createdAt": "2023-04-31T13:18:02.379Z",
"modifiedAt": "2023-04-31T13:18:02.379Z",
"version": 1
}
}
]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_managereturns.returns_manage_own
Your Emporix tenant's name. Note: The tenant name should always be written in lowercase.
^[a-z][a-z0-9]+$Customer’s saasToken retrieved when logging in a customer. The header is mandatory for operations done by a customer.
Base schema for a return requested by a customer.
Base schema for returns.
Base schema for a return requested by a customer.
POST /return/{tenant}/returns HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 406
{
"orders": [
{
"id": "B1LMYY52",
"items": [
{
"id": "32090",
"quantity": 2,
"reason": {
"code": "001"
}
},
{
"id": "32102",
"quantity": 15,
"reason": {
"details": "It's too small."
}
}
]
}
],
"reason": {
"code": "001",
"details": "The items do not work."
},
"mixins": {
"customAttributes": {
"attr1": "value1"
}
},
"metadata": {
"mixins": {
"customAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/productCustomAttributesMixIn.v29.json"
}
}
}{
"id": "88b1779c-a8bf-4b94-b1be-b0edd149bba5"
}Retrieves a single return document.
Required scopes (one of)
returns.returns_readreturns.returns_read_own
Your Emporix tenant's name. Note: The tenant name should always be written in lowercase.
^[a-z][a-z0-9]+$Unique identifier of a return.
Schema for retrieving returns by an employee.
GET /return/{tenant}/returns/{returnId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
"id": "7ba2f2b6-7dc8-45ff-9f20-4e6163c14c2e",
"approvalStatus": "PENDING",
"received": false,
"orders": [
{
"id": "B1LMYY52",
"items": [
{
"id": "32090",
"name": "T-shirt",
"quantity": 2,
"reason": {
"code": "001",
"details": "It's too small"
},
"unitPrice": {
"value": 1.99,
"currency": "USD"
},
"total": {
"value": 3.98,
"currency": "USD"
}
},
{
"id": "32102",
"name": "Jacket",
"quantity": 15,
"unitPrice": {
"value": 1,
"currency": "USD"
},
"total": {
"value": 15,
"currency": "USD"
}
}
]
}
],
"reason": {
"code": "001",
"details": "The items do not work."
},
"total": {
"value": 18.98,
"currency": "USD"
},
"expiryDate": "2023-04-31T13:18:02.379Z",
"metadata": {
"createdAt": "2023-04-31T13:18:02.379Z",
"modifiedAt": "2023-04-31T13:18:02.379Z",
"version": 1
}
}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_managereturns.returns_manage_own
Your Emporix tenant's name. Note: The tenant name should always be written in lowercase.
^[a-z][a-z0-9]+$Unique identifier of a return.
Customer’s saasToken retrieved when logging in a customer. The header is mandatory for operations done by a customer.
Base schema for a return requested by a customer.
Base schema for a return requested by an employee.
PUT /return/{tenant}/returns/{returnId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 286
{
"id": "6369140c5c6de75d9e84c97f",
"orders": [
{
"id": "B1LMYY52",
"items": [
{
"id": "32090",
"quantity": 2,
"reason": {
"code": "001"
}
},
{
"id": "32102",
"quantity": 15
}
]
}
],
"reason": {
"code": "001",
"details": "The items do not work."
},
"mixins": {
"customAttributes": {
"attr1": "value1"
}
},
"metadata": {
"version": 1
}
}No content
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_managereturns.returns_manage_own
Your Emporix tenant's name. Note: The tenant name should always be written in lowercase.
^[a-z][a-z0-9]+$Unique identifier of a return.
Customer’s saasToken retrieved when logging in a customer. The header is mandatory for operations done by a customer.
DELETE /return/{tenant}/returns/{returnId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
No content
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_managereturns.returns_manage_own
Your Emporix tenant's name. Note: The tenant name should always be written in lowercase.
^[a-z][a-z0-9]+$Unique identifier of a return.
Customer’s saasToken retrieved when logging in a customer. The header is mandatory for operations done by a customer.
Indicates an operation which should be done on a return. Available operations: add remove and replace
Indicates a path for which the value should be applied. For example:/mixins/additionalAttributes/externalId, /approvalStatus, /requestor/customerId
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.
PATCH /return/{tenant}/returns/{returnId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 77
[
{
"op": "replace",
"path": "/requestor/customerId",
"value": "changedCustomerId"
}
]No content
Was this helpful?