FlintflintDocs

Return policies

Return policies are versioned merchant rules for eligibility, deadlines, allowed resolutions, approval mode, refund timing, inspection, destination, completion, shipping, and restocking fees. Publishing creates an immutable version. A Return freezes the version 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 version. Rules live on versions. PATCH /v1/return-policies/{return_policy_id} changes identity only; changing a window, fee, or scope means publishing a new version.

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, categories, 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 version 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 version rule below applies only to eligible and review_required versions.

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_eventCounts from
fulfilledThe fulfillment completing
deliveredThe carrier delivering
picked_upThe buyer collecting in person
service_completedThe 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.

Endpoints

List return policies#

GET/v1/return-policiesRequires scope: commerce.return_policies.write or commerce.return_reasons.write or commerce.returns.decisions.write or commerce.returns.operations.write or commerce.returns.process.write or commerce.returns.read or commerce.returns.resolutions.write or commerce.returns.write

List Return policies with their status and current version.

Query parameters
page_sizeinteger

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

page_tokenstring

Opaque cursor returned by the previous page.

statusarray of enum

Filter by status.

activeinactivearchived
Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDED
Bash
curl https://api.withflintpay.com/v1/return-policies \
  -H "Authorization: Bearer YOUR_API_KEY"

Create return policy#

POST/v1/return-policiesIdempotentRequires scope: commerce.return_policies.write

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

Request body
external_reference_idstring
metadatamap of string
namestringrequired
versionone ofrequired
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/return-policies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "",
    "version": {
      "approval_mode": "automatic",
      "eligibility_result": "eligible",
      "is_merchandise_return_required": false,
      "priority": 0,
      "scope": {
        "match_type": "all"
      }
    }
  }'

Get return policy#

GET/v1/return-policies/{return_policy_id}Requires scope: commerce.return_policies.write or commerce.return_reasons.write or commerce.returns.decisions.write or commerce.returns.operations.write or commerce.returns.process.write or commerce.returns.read or commerce.returns.resolutions.write or commerce.returns.write

Retrieve one Return policy. Supports expand for current_version.

Path parameters
return_policy_idstringrequired

Flint return policy id.

Query parameters
expandarray of enum

Supported expansions: current_version. Expanded relationships are returned only when explicitly requested and authorized. Limits: at most 10 unique expand paths per request; path depth at most 2. Send repeated expand parameters as the canonical form, for example expand=current_version&expand=current_version. Comma-separated values, expand[]=current_version, and numeric expand[0]=current_version are accepted for common client compatibility.

current_version
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/return-policies/{return_policy_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Update return policy#

PATCH/v1/return-policies/{return_policy_id}IdempotentRequires scope: commerce.return_policies.write

Update policy identity fields. Rules live on versions, so changing a window, fee, or scope means publishing a new version.

Path parameters
return_policy_idstringrequired

Flint return policy id.

Request body
expected_return_policy_revisionintegerrequired
external_reference_idstring
metadatamap of string
namestring
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X PATCH https://api.withflintpay.com/v1/return-policies/{return_policy_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_policy_revision": 0
  }'

Activate return policy#

POST/v1/return-policies/{return_policy_id}/activateIdempotentRequires scope: commerce.return_policies.write

Activate a policy so it is evaluated for new Returns. Returns that already froze a version keep that version.

Path parameters
return_policy_idstringrequired

Flint return policy id.

Request body
expected_return_policy_revisionintegerrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/return-policies/{return_policy_id}/activate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_policy_revision": 0
  }'

Archive return policy#

POST/v1/return-policies/{return_policy_id}/archiveIdempotentRequires scope: commerce.return_policies.write

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

Path parameters
return_policy_idstringrequired

Flint return policy id.

Request body
expected_return_policy_revisionintegerrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/return-policies/{return_policy_id}/archive \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_policy_revision": 0
  }'

Deactivate return policy#

POST/v1/return-policies/{return_policy_id}/deactivateIdempotentRequires scope: commerce.return_policies.write

Stop evaluating a policy for new Returns without archiving it.

Path parameters
return_policy_idstringrequired

Flint return policy id.

Request body
expected_return_policy_revisionintegerrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/return-policies/{return_policy_id}/deactivate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_return_policy_revision": 0
  }'

List return policy versions#

GET/v1/return-policies/{return_policy_id}/versionsRequires scope: commerce.return_policies.write or commerce.return_reasons.write or commerce.returns.decisions.write or commerce.returns.operations.write or commerce.returns.process.write or commerce.returns.read or commerce.returns.resolutions.write or commerce.returns.write

List every published version 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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/return-policies/{return_policy_id}/versions \
  -H "Authorization: Bearer YOUR_API_KEY"

Publish return policy version#

POST/v1/return-policies/{return_policy_id}/versionsIdempotentRequires scope: commerce.return_policies.write

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

Path parameters
return_policy_idstringrequired

Flint return policy id.

Request body
expected_current_return_policy_version_idstringrequired
expected_return_policy_revisionintegerrequired
versionone ofrequired
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl -X POST https://api.withflintpay.com/v1/return-policies/{return_policy_id}/versions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_current_return_policy_version_id": "",
    "expected_return_policy_revision": 0,
    "version": {
      "approval_mode": "automatic",
      "eligibility_result": "eligible",
      "is_merchandise_return_required": false,
      "priority": 0,
      "scope": {
        "match_type": "all"
      }
    }
  }'

Get return policy version#

GET/v1/return-policies/{return_policy_id}/versions/{return_policy_version_id}Requires scope: commerce.return_policies.write or commerce.return_reasons.write or commerce.returns.decisions.write or commerce.returns.operations.write or commerce.returns.process.write or commerce.returns.read or commerce.returns.resolutions.write or commerce.returns.write

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

Path parameters
return_policy_idstringrequired

Flint return policy id.

return_policy_version_idstringrequired

Flint return policy version id.

Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
Bash
curl https://api.withflintpay.com/v1/return-policies/{return_policy_id}/versions/{return_policy_version_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
Rate this doc