Customer request models

Models for returns, complaints and exchanges. Inspect request details, statuses, refund amounts and the fields accepted by updates.

Data schemas

List customer requests — Response

ApiResponse_list_RequestSummaryData__ · Fields, types and constraints of data accepted or returned by the API.

dataArray <RequestSummaryData > Required: Response example · ApiResponse_list_RequestSummaryData__.

Example: [{"created_at":"2026-01-01T12:00:00Z","customer":{"email":"customer@example.invalid","name":"Example"},"id":"example","number":"example","order_id":"example","order_number":"example","products_value":{"amount":"0.00","currency":"PLN","minor_units":2},"refund":{"amount":{"amount":"0.00","currency":"PLN","minor_units":2},"completed_at":null,"status":"pending","updated_at":"2026-01-01T12:00:00Z","version":1},"resolution_state":"unknown","status":{"id":"example","locale":"en","name":"Example"},"type":"return","updated_at":"2026-01-01T12:00:00Z","version":1}]
metaContextPageMeta ContextMeta PageMeta RequestMeta Required: Response metadata.

Example: {"pagination":{"has_more":false,"limit":20,"next_cursor":null},"request_id":"example"}

Additional fields: No

Get a customer request — Response

ApiResponse_RequestDetailData_ · Fields, types and constraints of data accepted or returned by the API.

dataRequestDetailData Required: Response example · RequestDetailData.

Example: {"created_at":"2026-01-01T12:00:00Z","customer":{"email":"customer@example.invalid","name":"Example"},"id":"example","items":[{"id":"example","name":"Example","order_line_id":"example","product_id":"example","quantity":1,"returned_quantity":1,"sku":"example","total":{"amount":"0.00","currency":"PLN","minor_units":2},"unit_price":{"amount":"0.00","currency":"PLN","minor_units":2},"variant_id":"example","variant_options":[{"name":"Example","value":"example"}]}],"number":"example","order_id":"example","order_number":"example","products_value":{"amount":"0.00","currency":"PLN","minor_units":2},"refund":{"amount":{"amount":"0.00","currency":"PLN","minor_units":2},"completed_at":null,"status":"pending","updated_at":"2026-01-01T12:00:00Z","version":1},"resolution_state":"unknown","status":{"id":"example","locale":"en","name":"Example"},"type":"return","updated_at":"2026-01-01T12:00:00Z","version":1}
metaContextPageMeta ContextMeta PageMeta RequestMeta Required: Response metadata.

Example: {"request_id":"example"}

Additional fields: No

Update the recorded refund amount — Request body

RefundAmountUpdate · Fields, types and constraints of data accepted or returned by the API.

amountStringRequired

Decimal amount encoded as a JSON string; null only where allowed.

minLength: 1maxLength: 64

Constraints

pattern: "^[+-]?(?:[0-9]+(?:\\.[0-9]+)?|\\.[0-9]+)(?:[eE][+-]?[0-9]+)?$"

Example: "0.00"

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 0maximum: 9223372036854775807

Example: 1

reasonStringOptional

Reason recorded for the change.

maxLength: 500

Default: ""

Additional fields: No

Recorded refund information

RefundData · Schema · Customer request models

amountMoneyData nullRequired

Decimal amount encoded as a JSON string; null only where allowed.

Example: {"amount":"0.00","currency":"PLN","minor_units":2}

completed_atString nullRequired

Completion time.

String:format: "date-time"

Example: null

statusStringRequired

Status accepted by this specific operation.

Constraints

enum: ["pending", "completed"]

Example: "pending"

updated_atString nullRequired

Most recent update time.

String:format: "date-time"

Example: "2026-01-01T12:00:00Z"

versionIntegerRequired

Resource version used for concurrency control.

Example: 1

Additional fields: No

Get a customer request — Response

RequestDetailData · Fields, types and constraints of data accepted or returned by the API.

created_atStringRequired

Creation time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

customerRequestCustomerData Required

Customer information recorded for this resource.

Example: {"email":"customer@example.invalid","name":"Example"}

idStringRequired

Resource identifier; preserve it as returned. (RequestDetailData).

Example: "example"

itemsArray <RequestItemData > Required

Items included in the resource.

Example:

[{"id":"example","name":"Example","order_line_id":"example","product_id":"example","quantity":1,"returned_quantity":1,"sku":"example","total":{"amount":"0.00","currency":"PLN","minor_units":2},"unit_price":{"amount":"0.00","currency":"PLN","minor_units":2},"variant_id":"example","variant_options":[{"name":"Example","value":"example"}]}]

numberStringRequired

Human-facing order or request number.

Example: "example"

order_idStringRequired

Related order identifier.

Example: "example"

order_numberStringRequired

Related order number.

Example: "example"

products_valueMoneyData Required

Value of the products in the order.

Example: {"amount":"0.00","currency":"PLN","minor_units":2}

refundRefundData Required

Recorded refund information.

Example:

{"amount":{"amount":"0.00","currency":"PLN","minor_units":2},"completed_at":null,"status":"pending","updated_at":"2026-01-01T12:00:00Z","version":1}

resolution_stateStringRequired

Resolution state of a customer request.

Constraints

enum: ["unknown", "open", "completed", "rejected", "cancelled"]

Example: "unknown"

statusRequestStatusData Required

Status accepted by this specific operation.

Example: {"id":"example","locale":"en","name":"Example"}

typeRequestType Required

Resource type.

Example: "return"

updated_atStringRequired

Most recent update time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

versionIntegerRequired

Resource version used for concurrency control.

Example: 1

Additional fields: No

Get a customer request — Response

RequestItemData · Fields, types and constraints of data accepted or returned by the API.

idStringRequired: Resource identifier; preserve it as returned. (RequestItemData).

Example: "example"
nameStringRequired: Resource name in the relevant context.

Example: "Example"
order_line_idString nullRequired: Related order line identifier.

Example: "example"
product_idStringRequired: Product identifier.

Example: "example"
quantityIntegerRequired: Number of units.

Example: 1
returned_quantityIntegerRequired: Quantity returned for this line.

Example: 1
skuStringRequired: Stock keeping unit code.

Example: "example"
totalMoneyData Required: Total amount.

Example: {"amount":"0.00","currency":"PLN","minor_units":2}
unit_priceMoneyData Required: Price for one unit.

Example: {"amount":"0.00","currency":"PLN","minor_units":2}
variant_idString nullRequired: Product variant identifier.

Example: "example"
variant_optionsArray <shopently_engine__domains__returns__adapters__public_http__requests__schemas__VariantOptionData > Required: Variant options associated with the product or snapshot.

Example: [{"name":"Example","value":"example"}]

Additional fields: No

Status accepted by this specific operation

RequestStatusData · Schema · Customer request models

idStringRequired: Resource identifier; preserve it as returned. (RequestStatusData).

Example: "example"
localeStringRequired: Language selected for this request.

Example: "en"
nameString nullRequired: Resource name in the relevant context.

Example: "Example"

Additional fields: No

List customer request statuses — Response

shopently_engine__domains__returns__adapters__public_http__requests__schemas__StatusDefinitionData · Fields, types and constraints of data accepted or returned by the API.

codeStringRequired: Stable machine-readable code.

Example: "example"
created_atStringRequired: Creation time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"
idStringRequired: Resource identifier; preserve it as returned. (shopently_engine__domains__returns__adapters__public_http__requests__schemas__StatusDefinitionData).

Example: "example"
is_initialBooleanRequired: Whether this is the initial status.

Example: false
localeStringRequired: Language selected for this request.

Example: "en"
nameString nullRequired: Resource name in the relevant context.

Example: "Example"
positionIntegerRequired: Position in the ordered collection.

Example: 1
typeRequestType Required: Resource type.

Example: "return"

Additional fields: No

List customer request statuses — Response

shopently_engine__runtime__public_api_http__responses__models__ApiResponse_list_StatusDefinitionData____2 · Fields, types and constraints of data accepted or returned by the API.

dataArray <shopently_engine__domains__returns__adapters__public_http__requests__schemas__StatusDefinitionData > Required: Response example · shopently_engine__runtime__public_api_http__responses__models__ApiResponse_list_StatusDefinitionData____2.

Example: [{"code":"example","created_at":"2026-01-01T12:00:00Z","id":"example","is_initial":false,"locale":"en","name":"Example","position":1,"type":"return"}]
metaContextPageMeta ContextMeta PageMeta RequestMeta Required: Response metadata.

Example: {"pagination":{"has_more":false,"limit":20,"next_cursor":null},"request_id":"example"}

Additional fields: No

Update customer request status — Request body

RequestStatusUpdate · Fields, types and constraints of data accepted or returned by the API.

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 9223372036854775807

Example: 1

status_idStringRequired

Identifier obtained from the relevant status dictionary.

Constraints

pattern: "^[a-z0-9][a-z0-9_-]{0,62}$"

Example: "example"

Additional fields: No

List customer requests — Response

RequestSummaryData · Fields, types and constraints of data accepted or returned by the API.

created_atStringRequired

Creation time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

customerRequestCustomerData Required

Customer information recorded for this resource.

Example: {"email":"customer@example.invalid","name":"Example"}

idStringRequired

Resource identifier; preserve it as returned. (RequestSummaryData).

Example: "example"

numberStringRequired

Human-facing order or request number.

Example: "example"

order_idStringRequired

Related order identifier.

Example: "example"

order_numberStringRequired

Related order number.

Example: "example"

products_valueMoneyData Required

Value of the products in the order.

Example: {"amount":"0.00","currency":"PLN","minor_units":2}

refundRefundData Required

Recorded refund information.

Example:

{"amount":{"amount":"0.00","currency":"PLN","minor_units":2},"completed_at":null,"status":"pending","updated_at":"2026-01-01T12:00:00Z","version":1}

resolution_stateStringRequired

Resolution state of a customer request.

Constraints

enum: ["unknown", "open", "completed", "rejected", "cancelled"]

Example: "unknown"

statusRequestStatusData Required

Status accepted by this specific operation.

Example: {"id":"example","locale":"en","name":"Example"}

typeRequestType Required

Resource type.

Example: "return"

updated_atStringRequired

Most recent update time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

versionIntegerRequired

Resource version used for concurrency control.

Example: 1

Additional fields: No

Resource type

RequestType · Schema · Customer request models

String

Constraints

enum: ["return", "exchange", "complaint"]

Additional fields: Yes

Variant options associated with the product or snapshot

shopently_engine__domains__returns__adapters__public_http__requests__schemas__VariantOptionData · Schema · Customer request models

nameStringRequired: Resource name in the relevant context.

Example: "Example"
valueStringRequired: Value described by the surrounding schema.

Example: "example"

Additional fields: No