Returns
Retrieves a list of return documents.
Required scopes (one of)
returns.returns_read
returns.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.
60
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.
1
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.
sort=name,metadata.createdAt:desc
A standard query parameter is used to search for specific values.
- Searching for an item by a string property:
q=approvalStatus:PENDING
, whereapprovalStatus
is the name of the string field andPENDING
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)
, wheremixins.returnCustomAttributes.orderQuantity
is the name of a number-based field, and20
is 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
, wherereceived
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
, wherereason.description
is the name of the field that has thenull
value. - Searching for items with an existing property:
q=mixin:exists
, wheremixin
is the name of the field that has thenon null
value. - Searching for items by multiple specific values:
q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494)
, whereid
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
, whereid
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
orq=code:(~EON107 EON106)
- in the case of searching for strings with a space, whereorder._id
is the name of the field andEON107
orEON107 EON106
are its querying regular expressions.
q=approvalStatus:APPROVED
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.
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_manage
returns.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_read
returns.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_manage
returns.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_manage
returns.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_manage
returns.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?