Fake Product Return & Refund API

Q: Can a return quantity exceed the ordered quantity?

No. Every line chooses returnQuantity between 1 and its own orderedQuantity, so generated return quantities never exceed what was ordered.

Q: How is the refund amount calculated?

Line refunds sum to subtotalMinor; the rounded percentage restocking fee is subtracted to produce estimatedMinor, which becomes actual only when refunded.

Q: Are the tracking values valid for a real carrier?

No. RET-... identifiers and the example.com tracking URL are explicitly fictional fixtures.

MOCK DATA

Generate coherent product returns with bounded line quantities, exact refund arithmetic, reverse shipments and status-specific timelines.

Generated test data for fixtures and development

Base URL: /api/returns
Category: Commerce & Finance
Capabilities: 1 route Seedable
Last updated: July 29, 2026

GET /api/returns Generate bounded fictional product-return lifecycles Returns a list

Live requestRuns against the public API

No key required

GET/api/returns?status=received&reason=damaged&minItems=2&maxItems=4&count=6&seed=42

Request parameters

status

Pin the exact return/reverse-shipment lifecycle state.

reason

Pin the fictional return reason.

currencydefault USD

Currency for all integer minor-unit amounts.

minItemsdefault 1

Minimum distinct return lines.

maxItemsdefault 3

Maximum distinct return lines; must be ≥ minItems.

restockingFeeRatedefault 0

Percentage fee, converted once to rounded integer minor units.

from

Earliest creation time. With only from, to resolves 30 elapsed days later; with neither, defaults 30 UTC days before today.

to

Latest creation time. With only to, from resolves 30 elapsed days earlier; with neither, defaults to today's UTC end.

Advanced response options7 options

countdefault 10

How many records to generate (1–100).

seed

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

fields

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

exclude

Return all fields except these (comma-separated).

formatdefault json

Response format: json envelope, ndjson (one record per line) or csv.

prettydefault false

Pretty-print the JSON response.

unwrapdefault false

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples 15 params · 15 fields · 3 examples

Code samples Ready-to-copy requests in 4 languages

curl JavaScript Python PHP

curl "https://randomapi.dev/api/returns?status=received&reason=damaged&minItems=2&maxItems=4&count=6&seed=42"

const res = await fetch("https://randomapi.dev/api/returns?status=received&reason=damaged&minItems=2&maxItems=4&count=6&seed=42");
const { data, meta } = await res.json();

import requests

data = requests.get("https://randomapi.dev/api/returns?status=received&reason=damaged&minItems=2&maxItems=4&count=6&seed=42").json()["data"]

$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/returns?status=received&reason=damaged&minItems=2&maxItems=4&count=6&seed=42"
), true);
$data = $json["data"];

Parameters Route-specific request inputs 8

Parameter	Type	Default & allowed	Description
`status`	enum	allowed: requested \| approved \| inTransit \| received \| refunded \| rejected \| cancelled example: received	Pin the exact return/reverse-shipment lifecycle state.
`reason`	enum	allowed: damaged \| wrongItem \| notAsDescribed \| changedMind \| duplicate example: damaged	Pin the fictional return reason.
`currency`	enum	default: USD allowed: USD \| EUR \| DKK \| GBP example: DKK	Currency for all integer minor-unit amounts.
`minItems`	int	default: 1 allowed: 1 – 4 example: 2	Minimum distinct return lines.
`maxItems`	int	default: 3 allowed: 1 – 4 example: 4	Maximum distinct return lines; must be ≥ minItems.
`restockingFeeRate`	float	default: 0 allowed: 0 – 20 example: 10	Percentage fee, converted once to rounded integer minor units.
`from`	date	example: 2026-06-01	Earliest creation time. With only from, to resolves 30 elapsed days later; with neither, defaults 30 UTC days before today.
`to`	date	example: 2026-06-30T23:59:59.999Z	Latest creation time. With only to, from resolves 30 elapsed days earlier; with neither, defaults to today's UTC end.

status enum

Pin the exact return/reverse-shipment lifecycle state.

example: status=received

reason enum

Pin the fictional return reason.

allowed: damaged | wrongItem | notAsDescribed | changedMind | duplicate

example: reason=damaged

currency enum

Currency for all integer minor-unit amounts.

default: USD

allowed: USD | EUR | DKK | GBP

example: currency=DKK

minItems int

Minimum distinct return lines.

default: 1

allowed: 1 – 4

example: minItems=2

maxItems int

Maximum distinct return lines; must be ≥ minItems.

default: 3

allowed: 1 – 4

example: maxItems=4

restockingFeeRate float

Percentage fee, converted once to rounded integer minor units.

default: 0

allowed: 0 – 20

example: restockingFeeRate=10

from date

Earliest creation time. With only from, to resolves 30 elapsed days later; with neither, defaults 30 UTC days before today.

example: from=2026-06-01

to date

Latest creation time. With only to, from resolves 30 elapsed days earlier; with neither, defaults to today's UTC end.

example: to=2026-06-30T23:59:59.999Z

Universal parameters Shared response and formatting options 7

Parameter	Type	Default & allowed	Description
`count`	int	default: 10 allowed: 1 – 100 example: 3	How many records to generate (1–100).
`seed`	int	example: 42	Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).
`fields`	list	example: id,returnNumber	Return only these fields (comma-separated). Mutually exclusive with 'exclude'.
`exclude`	list	example: events	Return all fields except these (comma-separated).
`format`	enum	default: json allowed: json \| ndjson \| csv example: csv	Response format: json envelope, ndjson (one record per line) or csv.
`pretty`	boolean	default: false example: true	Pretty-print the JSON response.
`unwrap`	boolean	default: false example: true	Drop the envelope: return the raw array/object without data/meta wrapper.

count int

How many records to generate (1–100).

default: 10

allowed: 1 – 100

example: count=3

seed int

Deterministic output: the same seed always returns the same records. Omit for random (the used seed is echoed in meta.seed).

example: seed=42

fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=id,returnNumber

exclude list

Return all fields except these (comma-separated).

example: exclude=events

format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json

allowed: json | ndjson | csv

example: format=csv

pretty boolean

Pretty-print the JSON response.

default: false

example: pretty=true

unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false

example: unwrap=true

Response schema Fields returned in each record 15

Field	Type	Description	Example
`id`	string	Distinct fictional return ID.	ret_930ac8204f00_00
`returnNumber`	string	Human-readable fictional RET number.	RET-ABCD2345
`orderId`	string	Synthetic related order ID.	ord_demo
`status`	string	Requested reverse-logistics/refund status.	received
`reason`	string	damaged \| wrongItem \| notAsDescribed \| changedMind \| duplicate.	damaged
`currency`	string	USD \| EUR \| DKK \| GBP.	DKK
`createdAt`	string (ISO 8601)	Request creation inside from/to.	2026-06-10T08:00:00.000Z
`updatedAt`	string (ISO 8601)	Exactly the final lifecycle event timestamp.	2026-06-12T08:00:00.000Z
`approvedAt` nullable	string (ISO 8601)	Present from approved through refunded.	2026-06-10T10:00:00.000Z
`rejectedAt` nullable	string (ISO 8601)	Present only when rejected.	null
`cancelledAt` nullable	string (ISO 8601)	Present only when cancelled.	null
`items`	object[]	One to four return lines with ordered/returned quantities and exact line refund.	[{"orderLineId":"line_demo","productId":"prd_demo","name":"Demo USB Hub","orderedQuantity":2,"returnQuantity":1,"unitPriceMinor":10000,"lineRefundMinor":10000}]
`refund`	object	Exact subtotal, fee, estimate, actual amount and nullable refundedAt.	{"subtotalMinor":10000,"restockingFeeRate":10,"restockingFeeMinor":1000,"estimatedMinor":9000,"refundedMinor":0,"refundedAt":null}
`reverseShipment` nullable	object	Generic label/transit/received data from approved onward.	{"status":"inTransit","trackingNumber":"RET-ABCD2345","trackingUrl":"https://returns.example.com/track/RET-ABCD2345","shippedAt":"2026-06-11T08:00:00.000Z","receivedAt":null}
`events`	object[]	Chronological branch-correct lifecycle events.	[{"status":"requested","message":"Fictional return request created","createdAt":"2026-06-10T08:00:00.000Z"}]

id string

Distinct fictional return ID.

example: ret_930ac8204f00_00

returnNumber string

Human-readable fictional RET number.

example: RET-ABCD2345

orderId string

Synthetic related order ID.

example: ord_demo

status string

Requested reverse-logistics/refund status.

example: received

reason string

damaged | wrongItem | notAsDescribed | changedMind | duplicate.

example: damaged

currency string

USD | EUR | DKK | GBP.

example: DKK

createdAt string (ISO 8601)

Request creation inside from/to.

example: 2026-06-10T08:00:00.000Z

updatedAt string (ISO 8601)

Exactly the final lifecycle event timestamp.

example: 2026-06-12T08:00:00.000Z

approvedAt string (ISO 8601) nullable

Present from approved through refunded.

example: 2026-06-10T10:00:00.000Z

rejectedAt string (ISO 8601) nullable

Present only when rejected.

example: null

cancelledAt string (ISO 8601) nullable

Present only when cancelled.

example: null

items object[]

One to four return lines with ordered/returned quantities and exact line refund.

example: [{"orderLineId":"line_demo","productId":"prd_demo","name":"Demo USB Hub","orderedQuantity":2,"returnQuantity":1,"unitPriceMinor":10000,"lineRefundMinor":10000}]

refund object

Exact subtotal, fee, estimate, actual amount and nullable refundedAt.

example: {"subtotalMinor":10000,"restockingFeeRate":10,"restockingFeeMinor":1000,"estimatedMinor":9000,"refundedMinor":0,"refundedAt":null}

reverseShipment object nullable

Generic label/transit/received data from approved onward.

example: {"status":"inTransit","trackingNumber":"RET-ABCD2345","trackingUrl":"https://returns.example.com/track/RET-ABCD2345","shippedAt":"2026-06-11T08:00:00.000Z","receivedAt":null}

events object[]

Chronological branch-correct lifecycle events.

example: [{"status":"requested","message":"Fictional return request created","createdAt":"2026-06-10T08:00:00.000Z"}]

Documented examples

Build-generated requests and complete responses 3

Received damaged returns /api/returns?status=received&reason=damaged&minItems=2&maxItems=4&count=6&seed=42

GET /api/returns?status=received&reason=damaged&minItems=2&maxItems=4&count=6&seed=42

{
  "data": [
    {
      "id": "ret_a958016cfb6a5c85_00",
      "returnNumber": "RET-6X3LT355KA",
      "orderId": "ord_bd6c73a25ddf2abd",
      "status": "received",
      "reason": "damaged",
      "currency": "USD",
      "createdAt": "2026-07-13T19:28:10.615Z",
      "updatedAt": "2026-07-16T10:28:10.615Z",
      "approvedAt": "2026-07-15T07:28:10.615Z",
      "rejectedAt": null,
      "cancelledAt": null,
      "items": [
        {
          "orderLineId": "line_863c1d1cff87_1",
          "productId": "prd_28448a0b56b8",
          "name": "Fixture Desk Lamp",
          "orderedQuantity": 4,
          "returnQuantity": 1,
          "unitPriceMinor": 18805,
          "lineRefundMinor": 18805
        },
        {
          "orderLineId": "line_316010d14615_2",
          "productId": "prd_edf3629ff11d",
          "name": "Demo Coffee Grinder",
          "orderedQuantity": 4,
          "returnQuantity": 1,
          "unitPriceMinor": 15679,
          "lineRefundMinor": 15679
        },
        {
          "orderLineId": "line_95cf565312cf_3",
          "productId": "prd_80233652f69e",
          "name": "Testing Interfaces",
          "orderedQuantity": 4,
          "returnQuantity": 3,
          "unitPriceMinor": 1041,
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

Refunded DKK returns with a fee /api/returns?status=refunded&currency=DKK&restockingFeeRate=10&count=8&seed=17

GET /api/returns?status=refunded&currency=DKK&restockingFeeRate=10&count=8&seed=17

{
  "data": [
    {
      "id": "ret_755abf24f73252bc_00",
      "returnNumber": "RET-D5HNBLLNGS",
      "orderId": "ord_f6ba578fe3996848",
      "status": "refunded",
      "reason": "notAsDescribed",
      "currency": "DKK",
      "createdAt": "2026-07-14T19:08:44.521Z",
      "updatedAt": "2026-07-19T22:08:44.521Z",
      "approvedAt": "2026-07-16T03:08:44.521Z",
      "rejectedAt": null,
      "cancelledAt": null,
      "items": [
        {
          "orderLineId": "line_6772197c4b91_1",
          "productId": "prd_746615d4e907",
          "name": "Example Rain Jacket",
          "orderedQuantity": 4,
          "returnQuantity": 4,
          "unitPriceMinor": 31739,
          "lineRefundMinor": 126956
        },
        {
          "orderLineId": "line_77920f6091bc_2",
          "productId": "prd_03e645cb54d9",
          "name": "Fixture Desk Lamp",
          "orderedQuantity": 5,
          "returnQuantity": 5,
          "unitPriceMinor": 44139,
          "lineRefundMinor": 220695
        }
      ],
      "refund": {
        "subtotalMinor": 347651,
        "restockingFeeRate": 10,
        "restockingFeeMinor": 34765,
        "estimatedMinor": 312886,
        "refundedMinor": 312886,
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

Rejected requests created in June /api/returns?status=rejected&from=2026-06-01&to=2026-06-30&count=5&seed=8

GET /api/returns?status=rejected&from=2026-06-01&to=2026-06-30&count=5&seed=8

{
  "data": [
    {
      "id": "ret_c5a0ad10ec498125_00",
      "returnNumber": "RET-SPJWA26Q74",
      "orderId": "ord_78dd634067d45aaa",
      "status": "rejected",
      "reason": "notAsDescribed",
      "currency": "USD",
      "createdAt": "2026-06-25T21:44:56.991Z",
      "updatedAt": "2026-06-27T08:44:56.991Z",
      "approvedAt": null,
      "rejectedAt": "2026-06-27T08:44:56.991Z",
      "cancelledAt": null,
      "items": [
        {
          "orderLineId": "line_4418bc8e6c2e_1",
          "productId": "prd_d0e0e37de56f",
          "name": "Demo Coffee Grinder",
          "orderedQuantity": 2,
          "returnQuantity": 2,
          "unitPriceMinor": 19540,
          "lineRefundMinor": 39080
        }
      ],
      "refund": {
        "subtotalMinor": 39080,
        "restockingFeeRate": 0,
        "restockingFeeMinor": 0,
        "estimatedMinor": 39080,
        "refundedMinor": 0,
        "refundedAt": null
      },
      "reverseShipment": null,
      "events": [
        {
          "status": "requested",
          "message": "Fictional return request created",
          "createdAt": "2026-06-25T21:44:56.991Z"
        },
    …
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Generates fictional product-return and refund fixtures for return-merchandise dashboards, customer portals and reverse-logistics tests. Every returned quantity is positive and no greater than its ordered quantity. Line refund minor units equal returnQuantity × unitPriceMinor, and all line values sum exactly into the refund object.

A percentage restockingFeeRate is converted once to integer minor units; estimatedMinor = subtotalMinor - restockingFeeMinor. Only status=refunded moves that exact estimate into refundedMinor and sets refundedAt; all other states retain a zero actual refund.

Lifecycle events are chronological and branch explicitly for rejected/cancelled requests. Approved and later states include a generic reverse-shipment object; shipping and receipt dates appear only when reached. Tracking uses a fictional RET-... value and reserved returns.example.com, with no carrier or commerce-vendor compatibility claim.

Use it for

Populate return-merchandise and refund administration screens
Test partial-quantity and restocking-fee arithmetic
Exercise reverse-shipment and every terminal return state

Frequently asked questions

Practical answers about this endpoint 4

Can a return quantity exceed the ordered quantity?

No. Every line chooses returnQuantity between 1 and its own orderedQuantity, so generated return quantities never exceed what was ordered.

How is the refund amount calculated?

Line refunds sum to subtotalMinor; the rounded percentage restocking fee is subtracted to produce estimatedMinor, which becomes actual only when refunded.

Which states include reverse-shipment dates?

Approved creates a label without shipping dates, inTransit adds shippedAt, and received/refunded add receivedAt in chronological order.

Are the tracking values valid for a real carrier?

No. RET-... identifiers and the example.com tracking URL are explicitly fictional fixtures.

Standards & references

Primary sources behind the contract

RFC 2606 — Reserved Top Level DNS Names

Useful next tools in the catalog

Fake Order Data API MOCK DATA

Internally consistent fake orders with exact line-item totals, currency precision, lifecycle dates, payment state and generic tracking fixtures.

Fake Shipment Tracking API MOCK DATA

Coherent fake shipment tracking fixtures with status-specific nullable dates, chronological events, fictional carriers and country/date filters.

Fake Transaction Data API MOCK DATA

Fake account transactions with realistic merchants, weighted statuses and currency-correct amounts — filter by type, status, amount range and date window.

Fake Product Data API MOCK DATA

Fake e-commerce products with category-themed names, prices in real currencies (whole yen for JPY), valid EAN-13 barcodes, SKUs, ratings and image URLs.