01.software Docs

returnRefund

Use the SDK for application integration. This read-only reference covers Commerce, Customer Auth, Membership and Events.

All HTTP operations
POST
/api/returns/return-refund

Public integration credentials: sk01_ with write scope under the admin-sk-only policy; PAT and Customer JWT are not supported. Omit pgPaymentId only for an original full-credit Order whose frozen provider_payable is zero. Ordinary and mixed Orders require the original capture identity, including a mixed Order remainder with zero provider refund amount. Explicit blank IDs are invalid; either pgPaymentId or paymentKey on an original full-credit Order conflicts. Managed refund authority, durable uncertainty/recovery and same-key replay remain provider/domain-owned. Success is the bounded terminal return/transaction receipt with optional notification warning; non-2xx retains legacy extra fields.

Authorization

serverSecretKey
headerAuthorizationBearer <token>

Public integration credential: opaque sk01_ secret API key only; PAT and Customer JWT are not supported by this scheme. Requires tenant binding and the read or write scope named by the operation.

Header Parameters

X-Idempotency-Key?string

Optional retry identity. Preserve exact body and identity for the same operation; absence does not imply safe automatic retry.

Length1 <= length

Request Body

application/json
  1. body
orderNumber*string

Order number (required)

Length1 <= length
reason?string

Return reason (optional)

Value in"change_of_mind""defective""wrong_delivery""damaged""size_too_large""size_too_small""color""style""not_as_described""wrong_item""unknown""other"
reasonDetail?string

Detailed reason text (optional)

Length1 <= length
returnItems*array<>

Array of products to return (required)

Items1 <= items <= 100
refundAmount*integer

Refund amount (required, min 1)

Range0 < value <= 9007199254740991
returnShippingFee?integer

Return shipping fee charged to the customer (ADR 0005 §Gap 1)

Range0 <= value <= 9007199254740991
initialShippingRefundAmount?integer

Initial order shipping amount refunded to the customer

Range0 <= value <= 9007199254740991
initialShippingRefundOverrideNote?string

Operator audit note required when overriding policy suggestion

Length1 <= length
pgPaymentId?string

PG payment ID. Omit only when the original Order frozen provider_payable is zero (full-credit Order). Mixed Orders require the original capture identity even when this refund restores credit only. Explicit blank values are invalid.

Length1 <= length
paymentKey?string

Provider payment key for verified refund

Length1 <= length
refundReceiptUrl?string

Refund receipt URL (optional)

Length1 <= length

Response Body

Actual shaped success body

application/json
  1. response
return*
transaction*
refundSeq*integer
Range1 <= value <= 9007199254740991
notificationWarning?string

Examples may be generated from schemas; they are illustrative, not recorded successful API calls. Example snippets may omit required authentication headers.

Example Request
curl -X POST 'https://api.01.software/api/returns/return-refund' \  -H 'Content-Type: application/json' \  -d '{  "orderNumber": "string",  "returnItems": [    {      "orderItem": "string",      "quantity": 1    }  ],  "refundAmount": 1}'
Example Response
{  "return": {    "id": "string",    "status": "completed",    "refundAmount": 0,    "returnShippingFee": 0,    "initialShippingRefundAmount": 0,    "completedAt": "stringstringstringstring"  },  "transaction": {    "id": "string",    "type": "refund",    "kind": "refund",    "status": "refunded",    "amount": 0,    "providerEventId": "string"  },  "refundSeq": 1,  "notificationWarning": "string"}