---
title: "Return data model"
url: "https://docs.unified.to/commerce/return/model"
description: "The Return data model object in Unified's Return API: 13 fields, including created_at, updated_at and order_id, with types and enum values."
date: "2026-10-30T17:34:13.489Z"
updated: "2026-10-30T17:34:13.489Z"
---
# Return data model

Updated: October 30, 2026

 View field support, webhooks, and list parameters for each integration on the [Supported Integrations](https://docs.unified.to/commerce/integrations.md) page. 

| Field                         | Type                       | Required | Description                                                                                                                                                                                                                                              |
| ----------------------------- | -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                            | string                     | No       |                                                                                                                                                                                                                                                          |
| created\_at                   | string (date-time)         | No       | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)                                                                                                                                                                                                                 |
| updated\_at                   | string (date-time)         | No       | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)                                                                                                                                                                                                                 |
| order\_id                     | string                     | No       |                                                                                                                                                                                                                                                          |
| status                        | enum                       | No       | Values: REQUESTED, OPEN, APPROVED, REJECTED, CLOSED, CANCELLED, OTHER                                                                                                                                                                                    |
| type                          | string                     | No       |                                                                                                                                                                                                                                                          |
| currency                      | string                     | No       |                                                                                                                                                                                                                                                          |
| total\_refund\_amount         | number                     | No       |                                                                                                                                                                                                                                                          |
| customer\_email               | string                     | No       |                                                                                                                                                                                                                                                          |
| customer\_name                | string                     | No       |                                                                                                                                                                                                                                                          |
| return\_by\_at                | string (date-time)         | No       | (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)                                                                                                                                                                                                                 |
| lineitems                     | CommerceReturnLineitem\[\] | No       |                                                                                                                                                                                                                                                          |
| lineitems\[\].id              | string                     | No       |                                                                                                                                                                                                                                                          |
| lineitems\[\].order\_line\_id | string                     | No       |                                                                                                                                                                                                                                                          |
| lineitems\[\].item\_id        | string                     | No       | (reference to CommerceItem)                                                                                                                                                                                                                              |
| lineitems\[\].sku             | string                     | No       |                                                                                                                                                                                                                                                          |
| lineitems\[\].name            | string                     | No       |                                                                                                                                                                                                                                                          |
| lineitems\[\].quantity        | number                     | No       |                                                                                                                                                                                                                                                          |
| lineitems\[\].refund\_amount  | number                     | No       |                                                                                                                                                                                                                                                          |
| lineitems\[\].reason          | string                     | No       |                                                                                                                                                                                                                                                          |
| lineitems\[\].status          | string                     | No       |                                                                                                                                                                                                                                                          |
| metadata                      | CommerceMetadata\[\]       | No       |                                                                                                                                                                                                                                                          |
| metadata\[\].id               | string                     | No       | The ID of the custom field definition (from the metadata/metadata endpoint).                                                                                                                                                                             |
| metadata\[\].value            | object                     | No       | The field's value, typed by format: DATE as ISO-8601 (YYYY-MM-DD, or YYYY-MM-DDTHH:MM:SSZ for date-times); NUMBER, PRICE and CURRENCY as a number; BOOLEAN and YES\_NO as true/false; MULTIPLE\_SELECT as an array of option values; otherwise a string. |
| metadata\[\].namespace        | string                     | No       |                                                                                                                                                                                                                                                          |
| metadata\[\].format           | enum                       | No       | The data type of the custom field, which determines how value is formatted. Values: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE\_SELECT, MULTIPLE\_SELECT, MEASUREMENT, PRICE, YES\_NO, CURRENCY, URL                                            |
| metadata\[\].extra\_data      | object                     | No       |                                                                                                                                                                                                                                                          |
| metadata\[\].slug             | string                     | No       | The integration's API name (key) of an existing custom field. List valid slugs for this object with the metadata/metadata endpoint; unknown slugs are rejected by the integration.                                                                       |
| metadata\[\].description      | string                     | No       |                                                                                                                                                                                                                                                          |
| metadata\[\].is\_required     | boolean                    | No       |                                                                                                                                                                                                                                                          |

## TypeScript

```typescript
export type CommerceReturn = {
	id?: string;
	created_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	updated_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	order_id?: string;
	status?: 'REQUESTED' | 'OPEN' | 'APPROVED' | 'REJECTED' | 'CLOSED' | 'CANCELLED' | 'OTHER';
	type?: string;
	currency?: string;
	total_refund_amount?: number;
	customer_email?: string;
	customer_name?: string;
	return_by_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	lineitems?: [];
	metadata?: [];
	raw?: any;
} 
```

## Zod

```typescript
import { z } from 'zod';

export const ZodCommerceReturn = z.object({
	id: z.string().optional(),
	created_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	updated_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	order_id: z.string().optional(),
	status: z.enum("REQUESTED", "OPEN", "APPROVED", "REJECTED", "CLOSED", "CANCELLED", "OTHER").optional(),
	type: z.string().optional(),
	currency: z.string().optional(),
	total_refund_amount: z.number().optional(),
	customer_email: z.string().optional(),
	customer_name: z.string().optional(),
	return_by_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	lineitems: z.array().optional(),
	metadata: z.array().optional(),

});
```

## Python

```python
import dataclasses

@dataclasses.dataclass
class CommerceReturnStatus(str, Enum):
	REQUESTED = 'REQUESTED'
	OPEN = 'OPEN'
	APPROVED = 'APPROVED'
	REJECTED = 'REJECTED'
	CLOSED = 'CLOSED'
	CANCELLED = 'CANCELLED'
	OTHER = 'OTHER'

@dataclasses.dataclass
class CommerceReturn:
	id: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	created_at: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	updated_at: Optional[str]
	order_id: Optional[str]
	status: Optional[CommerceReturnStatus]
	type: Optional[str]
	currency: Optional[str]
	total_refund_amount: Optional[int]
	customer_email: Optional[str]
	customer_name: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	return_by_at: Optional[str]
	lineitems: Optional[PropertyCommerceReturnLineitems]
	metadata: Optional[PropertyCommerceReturnMetadata]

```