Returns

Retrieving a list of returns

get

Retrieves a list of return documents.


Required scopes (one of)

  • returns.returns_read

  • returns.returns_read_own

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

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

Pattern: ^[a-z][a-z0-9]+$
Query parameters
pageSizeinteger · min: 1 · max: 60Optional

The number of documents being retrieved on one page.

Default: 60
pageNumberinteger · min: 1Optional

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.

Default: 1
sortstringOptional

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=name,metadata.createdAt:desc
qstringOptional

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=approvalStatus:APPROVED
Header parameters
X-Total-CountbooleanOptional

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
application/json
Responseany of
or
get
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
    }
  }
]

Creating a single return entity

post

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

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

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

Pattern: ^[a-z][a-z0-9]+$
Header parameters
saas-tokenstringOptional

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

Body
any ofOptional
all ofOptional

Base schema for a return requested by a customer.

or
all ofOptional

Base schema for returns.

and
or
all ofOptional

Base schema for a return requested by a customer.

and
Responses
201
The resource has been successfully created.
application/json
post
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"
}

Retrieving a single return

get

Retrieves a single return document.


Required scopes (one of)

  • returns.returns_read

  • returns.returns_read_own

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

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

Pattern: ^[a-z][a-z0-9]+$
returnIdstringRequired

Unique identifier of a return.

Responses
200Success
application/json
Responseany of
all ofOptional
and
and
or
all ofOptional

Schema for retrieving returns by an employee.

and
and
get
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
  }
}

Updating a single return

put

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

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

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

Pattern: ^[a-z][a-z0-9]+$
returnIdstringRequired

Unique identifier of a return.

Header parameters
saas-tokenstringOptional

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

Body
any ofOptional
all ofOptional

Base schema for a return requested by a customer.

and
and
or
all ofOptional

Base schema for a return requested by an employee.

and
and
Responses
204
No Content
put
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

Deleting a single return

delete

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

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

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

Pattern: ^[a-z][a-z0-9]+$
returnIdstringRequired

Unique identifier of a return.

Header parameters
saas-tokenstringOptional

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

Responses
204
No Content
delete
DELETE /return/{tenant}/returns/{returnId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Partial updating a single return

patch

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

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

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

Pattern: ^[a-z][a-z0-9]+$
returnIdstringRequired

Unique identifier of a return.

Header parameters
saas-tokenstringOptional

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

Bodyobject · patchRequest[]
opstring · enumRequired

Indicates an operation which should be done on a return. Available operations: add remove and replace

Possible values:
pathstringRequired

Indicates a path for which the value should be applied. For example:/mixins/additionalAttributes/externalId, /approvalStatus, /requestor/customerId

valueone ofOptional

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.

objectOptional
or
stringOptional
Responses
204
No Content
patch
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?