Ctrlk
API documentationIncident managementFeedback
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Returns (Operations)

Endpoints to create, update, and read returns.

List item return jobs

get

Returns the item return jobs matching the given parameters.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
facilityIdstringOptional

facility to filter the results

itemReturnJobScannableCodesstring[]Optional

scannableCodes of the item return job to filter the results

itemReturnScannableCodesstring[]Optional

scannableCodes of the item return to filter the results

itemReturnJobStatusstring[]Optional

ItemReturnJobStatus to filter the results

itemReturnStatusstring[]Optional

ItemReturnStatus of an included ItemReturn to filter the results

searchTermstringOptional

Term by which to search through the fields

startAfterIdstringOptional

entity to start after

anonymizedbooleanOptional

show anonymized entities or not

sizeintegerOptional

number of entities to show

Default: 25
Responses
200

All Item Return Jobs matching the given parameters

application/json

ItemReturnJobs

totalnumberOptional

Total number of found entities for this query

Example: 42
get/api/itemreturnjobs

Create item return job

post

Creates a new item return job.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

ItemReturnJobForCreation

customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]
processRefstringOptional
scannableCodesstring[] · max: 50Optional
shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12
statusstring · enumRequiredPossible values:
tenantOrderIdstringOptional
Responses
200

Created entity

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false
createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z
customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired
lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z
originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]
processRefstringRequired
scannableCodesstring[] · max: 50Optional
shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12
statusstring · enumRequiredPossible values:
tenantOrderIdstringOptional
versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1
post/api/itemreturnjobs

Get item return job

get

Returns an item return job with the provided id.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
itemReturnJobIdstringRequired
Responses
200

Returns Item Return Job with the provided id

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false
createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z
customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired
lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z
originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]
processRefstringRequired
scannableCodesstring[] · max: 50Optional
shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12
statusstring · enumRequiredPossible values:
tenantOrderIdstringOptional
versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1
get/api/itemreturnjobs/{itemReturnJobId}

Call item return job action

post

Applies an action to an Item Return Job. Check ItemReturnJobActionsParameters for available actions.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
itemReturnJobIdstringRequired
Body
or
or
or
or
or
Responses
200

Updated entity

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false
createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z
customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired
lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z
originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]
processRefstringRequired
scannableCodesstring[] · max: 50Optional
shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12
statusstring · enumRequiredPossible values:
tenantOrderIdstringOptional
versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1
post/api/itemreturnjobs/{itemReturnJobId}/actions

List item returns

get

Returns the item returns for a given item return job.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
itemReturnJobIdstringRequired
Responses
200

Get all item returns for a given item return job

application/json

ItemReturn

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2020-02-03T08:45:51.525Z
customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired
lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2020-02-03T09:45:51.525Z
parcelRefsstring[] · max: 50Optional

references the parcel

Example: 672f3f72-b5d3-47c7-941c-9af5348e3cd7
returnFacilityRefstringRequired
scannableCodesstring[] · max: 50Optional
statusstring · enumRequiredPossible values:
tenantOrderIdstringOptionalDeprecated

deprecated: will be automatically deducted from related itemReturnJob

Example: MY_ORDER_ID
get/api/itemreturnjobs/{itemReturnJobId}/itemreturns

Create item return

post

Create a new item return for an item return job

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
itemReturnJobIdstringRequired
Body

AddItemReturnToItemReturnJob

itemReturnJobVersionintegerRequired

Version of the itemReturnJob the itemReturn gets added to

Example: 1
Responses
200

ItemReturnJob containing the newly created item return

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false
createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z
customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired
lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z
originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]
processRefstringRequired
scannableCodesstring[] · max: 50Optional
shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12
statusstring · enumRequiredPossible values:
tenantOrderIdstringOptional
versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1
post/api/itemreturnjobs/{itemReturnJobId}/itemreturns

Get item return

get

Returns a specific item return for a given item return job.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
itemReturnJobIdstringRequired
itemReturnIdstringRequired

id of the item return you want to read

Responses
200

Get a specific item return

application/json

ItemReturn

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2020-02-03T08:45:51.525Z
customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired
lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2020-02-03T09:45:51.525Z
parcelRefsstring[] · max: 50Optional

references the parcel

Example: 672f3f72-b5d3-47c7-941c-9af5348e3cd7
returnFacilityRefstringRequired
scannableCodesstring[] · max: 50Optional
statusstring · enumRequiredPossible values:
tenantOrderIdstringOptionalDeprecated

deprecated: will be automatically deducted from related itemReturnJob

Example: MY_ORDER_ID
get/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}
Deprecated

Delete item return

delete

This part of the API is deprecated. For details, see the API release lifecycle documentation. Delete an item return from an item return job

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
itemReturnJobIdstringRequired
itemReturnIdstringRequired

id of the item return you want to delete

Query parameters
itemReturnJobVersionnumberRequired

version of the item return job to delete the item return for

Responses
200

item return was found and successfully deleted. Updated item return job is returned.

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false
createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z
customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired
lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z
originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]
processRefstringRequired
scannableCodesstring[] · max: 50Optional
shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12
statusstring · enumRequiredPossible values:
tenantOrderIdstringOptional
versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1
delete/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}

Call item return action

post

Applies an action to an Item Return. Check ItemReturnActionsParameters for available actions.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
itemReturnJobIdstringRequired
itemReturnIdstringRequired
Body
or
or
or
or
or
or
Responses
200

Updated entity

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false
createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z
customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired
lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z
originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]
processRefstringRequired
scannableCodesstring[] · max: 50Optional
shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12
statusstring · enumRequiredPossible values:
tenantOrderIdstringOptional
versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1
post/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/actions

Create item return parcel

post

This part of the API is in Beta status. For details, see the API release lifecycle documentation. Returns all parcels for an itemReturn.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
itemReturnJobIdstringRequired

itemReturnJobId

itemReturnIdstringRequired

id of the itemReturn to create a parcel for

Body

ParcelForCreation

carrierProductstringOptional

Desired product of given carrier to choose when ordering a label

Example: EXPRESS
carrierRefstringOptional

references the carrier to be used for sending. Can not be set when creating a parcel for an existing shipment.

customAttributesobjectOptional

Attributes that can be added to the parcel. These attributes cannot be used within fulfillment processes, but it could be useful to have the information carried here.

customProductValuenumberOptional

Set this value if you want to overwrite the calculated product value of the parcel.

Example: 12.5
loadUnitRefsstring[]Optional

Reference to array of load unit Refs

parentRefstringOptional

Reference to the parent container of this parcel

productValuenumberOptional

Monetary value of all goods in this parcel. Needed for sending cross border packages (customs) To be interpreted as money in the currency given under paymentInformation.currency. This value is calculated from the items in the parcel.

Example: 12.5
productValueTypestring · enumOptional

ProductValueType

Example: INSURANCEPossible values:
shortIdstringOptionalExample: AA12-1
statusstring · enumOptional

ParcelStatus

Possible values:
tenantOrderIdstringOptional

Field can be used as a reference number in foreign systems, for example as a reference to the source system's identifier for this order.

Example: R456728546
tenantParcelIdstringOptional

Tenant specific parcel id, needs to be unique for non obsolete or canceled parcel

Example: MY-PARCEL-12345
Responses
201

Create a parcel for an itemReturn

application/json

BaseOperationalContainer

createdstring · date-timeOptional

The date this entity was created at the platform. This value is generated by the service.

Example: 2020-02-03T08:45:51.525Z
lastModifiedstring · date-timeOptional

The date this entity was modified last. This value is generated by the service.

Example: 2020-02-03T09:45:51.525Z
versioninteger · int64Required

The version of the document to be used in optimistic locking mechanisms.

Example: 42
sequenceNumberinteger · int32 · max: 10000Optional

Incremental number to distinguish containers of the same type. Virtual container's sequenceNumber is always 0, non virtual containers are always greater than 0.

Example: 100
anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false
carrierProductstringOptional

Desired product of given carrier to choose when ordering a label

Example: EXPRESS
carrierRefstringRequired

Reference to the carrier this parcel should be send by

Example: cf00e102-34f2-45c1-a846-6a21f384321e
customAttributesobjectOptional

Attributes that can be added to the parcel. These attributes cannot be used within fulfillment processes, but it could be useful to have the information carried here.

customProductValuenumberOptional

Set this value if you want to overwrite the calculated product value of the parcel. This field uses the smallest denomination, e.g. Euro Cents. So a value of 1250 represents 12,50€.

Example: 12.5
documentsRefstringOptional

Reference to the documents collection from this entity

facilityRefstringOptional
idstringRequired

The id of this parcel. It is generated during creation automatically and suits as the primary identifier of the described entity.

Example: 95EWrieX09OmeriXIUbb
loadUnitRefsstring[]Required

Reference to array of load unit Refs

operativeProcessRefstringOptional
processRefstringRequired
productValuenumberOptional

Monetary value of all goods in this parcel. Needed for sending cross border packages (customs) To be interpreted as money in the currency given under paymentInformation.currency. This field uses the smallest denomination, e.g. Euro Cents. So a value of 1250 represents 12,50€.

Example: 1250
productValueTypestring · enumOptional

ProductValueType

Example: INSURANCEPossible values:
shipmentRefstringOptional

The id of this shipment this parcel has been created for.

Example: 95EWrieX09OmeriXIUbb
shortIdstringOptionalExample: AA12-1
statusstring · enumRequired

ParcelStatus

Possible values:
tenantOrderIdstringOptional

Field can be used as a reference number in foreign systems, for example as a reference to the source system's identifier for this order.

Example: R456728546
tenantParcelIdstringOptional

Tenant specific parcel id, needs to be unique for non obsolete or canceled parcel

Example: MY-PARCEL-12345
workflowInformationone ofRequired
or
post/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/parcels

Update returned line items

put

Replace returned line items of an item return of an item return job.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
itemReturnJobIdstringRequired
itemReturnIdstringRequired
Body

ReplaceReturnedLineItems

itemReturnJobVersionintegerRequired

Version of the entity to be changed

Example: 1
Responses
200

The returned line items were successfully updated. Updated item return job is returned.

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false
createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z
customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired
lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z
originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]
processRefstringRequired
scannableCodesstring[] · max: 50Optional
shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12
statusstring · enumRequiredPossible values:
tenantOrderIdstringOptional
versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1
put/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/returnedlineitems

Update returned line item

patch

Patch for a ItemReturn LineItem. This is used to update the returned line item.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
itemReturnJobIdstringRequired
itemReturnIdstringRequired
returnedLineItemIdstringRequired

id of the returnedLineItem

Body

ItemReturnLineItemForUpdate

itemReturnJobVersionintegerRequired

version of the overlaying itemReturnJob

Example: 42
statusstring · enumOptionalPossible values:
Responses
200

Updated ItemReturnJob

application/json

ItemReturnJob

anonymizedbooleanOptional

Indicates if gdpr related data was anonymized

Example: false
createdstring · date-timeOptional

Creation timestamp

Example: 2026-06-17T12:00:00.000Z
customAttributesobject · nullableOptional

Attributes that can be added to this entity. These attributes cannot be used within fulfillment processes, but enable you to attach custom data from your systems to fulfillmenttools entities.

idstringRequired
lastModifiedstring · date-timeOptional

Last modification timestamp

Example: 2026-06-17T12:00:00.000Z
originFacilityRefsstring[] · max: 50RequiredExample: ["0190d6e8-8c3a-7f1b-9d2e-4a6b8c0d1e2f","0190d6e8-9a1b-7c2d-8e3f-5a7b9c1d3e5f"]
processRefstringRequired
scannableCodesstring[] · max: 50Optional
shortIdstringOptional

A short identifier that helps assigning a item return job to a customer. This is automatically created during creation.

Example: AS12
statusstring · enumRequiredPossible values:
tenantOrderIdstringOptional
versionintegerRequired

The version of the document to be used in optimistic locking mechanisms.

Example: 1
patch/api/itemreturnjobs/{itemReturnJobId}/itemreturns/{itemReturnId}/returnedlineitems/{returnedLineItemId}

Get item returns

get

Returns the item returns matching the given parameters.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
searchTermstringOptional

Search term you want to get the corresponding item returns. Search will be performed on multiple fields, including return id, tenant order id, customer name, tenant article ids, artile titles

itemReturnStatusstring[]Optional

ItemReturnStatus of an included ItemReturn to filter the results

itemReturnLineItemStatusstring[]Optional

ItemReturnLineItemStatus of an included itemReturnLineItem to filter the results

sizeintegerOptional

number of entities to show

startAfterIdstringOptional

entity to start after

orderBystringOptional

sorting for the results

anonymizedbooleanOptional

show anonymized entities or not

facilityRefsstring[]Optional

facilities to filter the results

Responses
200

All Item Returns matching the given parameters

application/json

ItemReturns

totalCountnumberRequired

Total number of found entities for this query

Example: 42
get/api/itemreturns

Last updated