Return policies

Return policies are merchant rules for eligibility, deadlines, allowed resolutions, approval mode, refund timing, inspection, destination, completion, shipping, and restocking fees. Publishing creates an immutable revision. A Return freezes the revision and evaluated result it used so later policy changes do not rewrite history. The Return policies guide shows a policy end to end.

The policy carries identity: name, status, and current revision. Rules live on revisions. PATCH /v1/return-policies/{return_policy_id} changes identity only; changing a window, fee, or scope means publishing a new revision.

Matching#

Policies match by scope and resolve by priority. match_type is all, the catch-all where every other selector must be empty, or include, which names what it covers through product_ids, variant_ids, category_handles, location_ids, or channel_types.

Final sale is a high-priority include policy with eligibility_result: "ineligible" and an ineligibility_reason, layered over a low-priority all policy that permits returns.

An ineligible revision commits no resolution behavior: it must omit allowed_resolution_types, resolution_mode, refund_timing, and completion_mode, and is rejected if it sets any of them. Every other rule below applies only to eligible and review_required revisions.

When no policy matches, API-created requests remain possible and route to explicit merchant review, and deciding one needs no override reason. Buyer self-service is enabled only by an active policy that permits it.

Windows#

return_window is a duration_seconds plus the event it counts from.

`starts_at_event`	Counts from
`fulfilled`	The fulfillment completing
`delivered`	The carrier delivering
`picked_up`	The buyer collecting in person
`service_completed`	The work being finished

Modes#

approval_mode decides whether Flint approves the Return itself. resolution_mode decides whether it also creates and confirms the outcome. Both are automatic or manual.

Automatic resolution can construct refunds and no-monetary-action outcomes. Exchange and replacement outcomes require a manual resolution because they need explicit replacement merchandise.

resolution_selection_mode decides who picks: policy_default uses automatic_resolution_type without asking, and buyer_requested waits for the buyer to choose from allowed_resolution_types. completion_mode decides whether Flint completes the Return when the last blocker clears (automatic) or waits for a /complete call (manual).

Fees#

return_shipping.payer is merchant or buyer. It states policy rather than charging anything: Flint does not buy labels, so no amount lives here. Where a fee is charged it lands as a return_shipping_fee adjustment on the resolution.

restocking_fee is calculation_type: "flat" with flat_money, or calculation_type: "percent" with a whole-number percent (10 means 10 percent). It surfaces as a restocking_fee adjustment and appears in the Return's financial_summary as a deduction.

The Return policy object#

Every field on a return policy, as returned by retrieve and carried by the endpoints below.

Attributes

created_atstringRequired

RFC3339 timestamp.

current_return_policy_revision_idstringRequired

current_revisionobject or null

external_reference_idstring

Caller-owned identifier for this resource in an external system.

metadatamap of stringRequired

namestringRequired

return_policy_idstringRequired

statusenumRequired

active
inactive
archived

supported_actionsarray of stringRequired

updated_atstringRequired

RFC3339 timestamp.

versionintegerRequired

JSON

{
  "current_return_policy_revision_id": "rpolv_01K1VERSION0000000000",
  "name": "Standard returns",
  "return_policy_id": "rpol_01K1POLICY000000000000",
  "status": "active"
}

List return policies#

GET/v1/return-policies

Requires scope commerce.return_policies.write or commerce.return_reasons.write or commerce.returns.operations.write or commerce.returns.read or commerce.returns.resolutions.write or commerce.returns.write

List Return policies with their status and current revision.

Query parameters

external_reference_idstring

Exact-match filter on the caller-owned external reference ID.

page_sizeinteger

Page size. Defaults to 20 and is capped at 100.

page_tokenstring

Opaque cursor returned by the previous page.

querystring

Search by return policy ID, name, or external reference ID.

statusarray of enum

Filter by status.

active
inactive
archived

Response · 200

dataarray of objectRequired

metaobject

next_page_tokenstring

request_idstring

curl https://api.withflintpay.com/v1/return-policies \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create return policy#

POST/v1/return-policiesIdempotent

Requires scope commerce.return_policies.write

Create a Return policy with its first revision. The policy ID is stable across revisions, and each published revision is immutable.

Request body

external_reference_idstring

Caller-owned identifier for this resource in an external system.

metadatamap of string

namestringRequired

revisionone ofRequired

Response · 201

dataobjectRequired

metaobject

request_idstring

curl -X POST https://api.withflintpay.com/v1/return-policies \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "",
    "revision": {
      "approval_mode": "automatic",
      "eligibility_result": "eligible",
      "is_merchandise_return_required": false,
      "priority": 0,
      "scope": {
        "category_handles": [
          {}
        ],
        "channel_types": [
          {}
        ],
        "location_ids": [
          {}
        ],
        "match_type": "all",
        "product_ids": [
          {}
        ],
        "variant_ids": [
          {}
        ]
      }
    }
  }'

Get return policy#

GET/v1/return-policies/{return_policy_id}

Retrieve one Return policy. Supports expand for current_revision.

Path parameters

return_policy_idstringRequired

Flint return policy id.

Query parameters

expandarray of enum

Supported expansions: current_revision. Expanded relationships are returned only when explicitly requested and authorized. Limits: at most 10 unique expand paths per request; path depth at most 2. Repeat expand, for example expand=current_revision&expand=current_revision, or pass one comma-separated value.

current_revision

Response · 200

Same response as Create return policy.

curl https://api.withflintpay.com/v1/return-policies/{return_policy_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "current_return_policy_revision_id": "rpolv_01K1VERSION0000000000",
    "name": "Standard returns",
    "return_policy_id": "rpol_01K1POLICY000000000000",
    "status": "active"
  },
  "request_id": "req_123"
}

Update return policy#

PATCH/v1/return-policies/{return_policy_id}Idempotent

Requires scope commerce.return_policies.write

Update policy identity fields or set status to active or inactive. Rules live on revisions, so changing a window, fee, or scope means publishing a new revision.

Path parameters

return_policy_idstringRequired

Flint return policy id.

Request body

expected_versioninteger

external_reference_idstring or null

Caller-owned identifier for this resource in an external system.

metadatamap of string or null

Caller-owned metadata. Omit this field to leave metadata unchanged. Send an object to merge by key, set a key to null to remove it, or set metadata to null to clear all metadata. An empty object makes no change. Empty strings are stored. Keys starting with flint_ are reserved and cannot be written through the public API.

namestring

statusenum

active
inactive

Response · 200

Same response as Create return policy.

curl -X PATCH https://api.withflintpay.com/v1/return-policies/{return_policy_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_version": 0,
    "external_reference_id": "",
    "metadata": {},
    "name": "",
    "status": "active"
  }'

Retire return policy#

DELETE/v1/return-policies/{return_policy_id}Idempotent

Requires scope commerce.return_policies.write

Retire a Return policy so it is no longer evaluated and no longer appears as an active choice.

Path parameters

return_policy_idstringRequired

Flint return policy id.

Query parameters

expected_versioninteger

Filter by expected version.

Response · 200

Same response as Create return policy.

curl -X DELETE https://api.withflintpay.com/v1/return-policies/{return_policy_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

List return policy revisions#

GET/v1/return-policies/{return_policy_id}/revisions

List every published revision of a Return policy.

Path parameters

return_policy_idstringRequired

Flint return policy id.

Query parameters

page_sizeinteger

Page size. Defaults to 20 and is capped at 100.

page_tokenstring

Opaque cursor returned by the previous page.

Response · 200

dataarray of objectRequired

metaobject

next_page_tokenstring

request_idstring

curl https://api.withflintpay.com/v1/return-policies/{return_policy_id}/revisions \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Publish return policy revision#

POST/v1/return-policies/{return_policy_id}/revisionsIdempotent

Requires scope commerce.return_policies.write

Publish a new immutable Return policy revision while preserving the stable policy identity.

Path parameters

return_policy_idstringRequired

Flint return policy id.

Request body

expected_current_return_policy_revision_idstringRequired

expected_versioninteger

revisionone ofRequired

Response · 200

Same response as Create return policy.

curl -X POST https://api.withflintpay.com/v1/return-policies/{return_policy_id}/revisions \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_current_return_policy_revision_id": "",
    "revision": {
      "approval_mode": "automatic",
      "eligibility_result": "eligible",
      "is_merchandise_return_required": false,
      "priority": 0,
      "scope": {
        "category_handles": [
          {}
        ],
        "channel_types": [
          {}
        ],
        "location_ids": [
          {}
        ],
        "match_type": "all",
        "product_ids": [
          {}
        ],
        "variant_ids": [
          {}
        ]
      }
    }
  }'

Get return policy revision#

GET/v1/return-policies/{return_policy_id}/revisions/{return_policy_revision_id}

Retrieve one immutable policy revision, including the exact rules a Return was evaluated against.

Path parameters

return_policy_idstringRequired

Flint return policy id.

return_policy_revision_idstringRequired

Flint return policy revision id.

Response · 200

dataobjectRequired

metaobject

request_idstring

curl https://api.withflintpay.com/v1/return-policies/{return_policy_id}/revisions/{return_policy_revision_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Was this helpful?