Returns & Delivery Intelligence API Documentation

Read supplied orders, addresses, carrier events, and return rates, and calculate only the comparisons those records support. Payment is the exact USDC price on Base with x402.

POSThttps://brainiac.software/api/v1/returns-delivery/exception-classify$0.04 USDC

Classify delivery exceptions

Classify a supplied carrier code or order status only when it matches a documented token. Any other code stays unrecognized, and no tracking scan is added.

Body

Field	Required	Notes
`text`	No	string
`json`	No	string
`csv`	No	string
`file`	No	object; Object
`orders`	No	array; Array
`addresses`	No	array; Array
`events`	No	array; Array
`returns`	No	array; Array
`rates`	No	array; Array
`window`	No	object; Object
`rules`	No	array; Array

Request exampleJSON

{
  "text": "Event: E-1 | O-1 | 2026-11-02T15:00:00Z | refused | customer refused\nEvent: E-2 | O-2 | 2026-11-03T15:00:00Z | erase | note\nThe carrier lost the parcel.\n"
}

Response exampleJSON

{
  "checkedAt": "2026-11-04T12:00:00.000Z",
  "status": "classified",
  "items": [
    {
      "id": "E-1",
      "orderId": "O-1",
      "source": "event",
      "code": "refused",
      "category": "refused",
      "at": "2026-11-02T15:00:00.000Z",
      "confirmed": false,
      "interpretation": "stated"
    },
    {
      "id": "E-2",
      "orderId": "O-2",
      "source": "event",
      "code": "erase",
      "category": "unrecognized",
      "at": "2026-11-03T15:00:00.000Z",
      "confirmed": false,
      "interpretation": "none"
    }
  ],
  "carrierContacted": false,
  "returnInitiated": false,
  "refundGranted": false,
  "deliverabilityConfirmed": false,
  "eventsInvented": false,
  "findings": [
    {
      "kind": "ignored",
      "code": "unlabeled_line",
      "subject": "",
      "detail": "Lines without a recognized label were not read and their text was not copied."
    }
  ],
  "limitations": [
    "Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.",
    "No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.",
    "An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.",
    "A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.",
    "No carrier account is contacted and no return is initiated."
  ]
}

cURL

curl -i -X POST "https://brainiac.software/api/v1/returns-delivery/exception-classify" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "text": "Event: E-1 | O-1 | 2026-11-02T15:00:00Z | refused | customer refused\nEvent: E-2 | O-2 | 2026-11-03T15:00:00Z | erase | note\nThe carrier lost the parcel.\n"
}
JSON

POSThttps://brainiac.software/api/v1/returns-delivery/failed-pattern-detect$0.05 USDC

Detect failed-delivery patterns

Group supplied failed, undeliverable, refused, or returned orders by postcode, address, or carrier. A pattern needs at least three orders. One failure is not a carrier finding.

Body

Field	Required	Notes
`text`	No	string
`json`	No	string
`csv`	No	string
`file`	No	object; Object
`orders`	No	array; Array
`addresses`	No	array; Array
`events`	No	array; Array
`returns`	No	array; Array
`rates`	No	array; Array
`window`	No	object; Object
`rules`	No	array; Array

Request exampleJSON

{
  "orders": [
    {
      "id": "O-1",
      "status": "failed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "O-2",
      "status": "failed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "O-3",
      "status": "failed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "O-4",
      "status": "delayed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    }
  ]
}

Response exampleJSON

{
  "checkedAt": "2026-11-04T12:00:00.000Z",
  "status": "checked",
  "level": "review",
  "signals": [
    {
      "code": "shared_postcode",
      "confirmed": false,
      "orders": [
        "O-1",
        "O-2",
        "O-3"
      ],
      "detail": "3 failed orders share postcode sw1a 1aa|gb. This is not a carrier finding."
    },
    {
      "code": "shared_carrier",
      "confirmed": false,
      "orders": [
        "O-1",
        "O-2",
        "O-3"
      ],
      "detail": "3 failed orders share carrier example carrier. This is not a carrier finding."
    }
  ],
  "carrierContacted": false,
  "returnInitiated": false,
  "refundGranted": false,
  "deliverabilityConfirmed": false,
  "eventsInvented": false,
  "findings": [],
  "limitations": [
    "Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.",
    "No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.",
    "An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.",
    "A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.",
    "No carrier account is contacted and no return is initiated."
  ]
}

cURL

curl -i -X POST "https://brainiac.software/api/v1/returns-delivery/failed-pattern-detect" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "orders": [
    {
      "id": "O-1",
      "status": "failed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "O-2",
      "status": "failed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "O-3",
      "status": "failed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "O-4",
      "status": "delayed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    }
  ]
}
JSON

POSThttps://brainiac.software/api/v1/returns-delivery/shipping-address-validate$0.04 USDC

Validate shipping-address structure

Check that the supplied lines, city, postcode, and country are present, and compare a postcode with a published shape for nine country codes. The check does not confirm that a carrier can deliver.

Body

Field	Required	Notes
`text`	No	string
`json`	No	string
`csv`	No	string
`file`	No	object; Object
`orders`	No	array; Array
`addresses`	No	array; Array
`events`	No	array; Array
`returns`	No	array; Array
`rates`	No	array; Array
`window`	No	object; Object
`rules`	No	array; Array

Request exampleJSON

{
  "addresses": [
    {
      "id": "A-2",
      "line1": "10 Example Street",
      "city": "Austin",
      "region": "TX",
      "postcode": "1234",
      "country": "US"
    },
    {
      "id": "A-1",
      "line1": "10 Example Street",
      "city": "London",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "A-3",
      "line1": "",
      "city": "",
      "postcode": "",
      "country": ""
    }
  ]
}

Response exampleJSON

{
  "checkedAt": "2026-11-04T12:00:00.000Z",
  "status": "checked",
  "addresses": [
    {
      "id": "A-2",
      "line1": "10 Example Street",
      "line2": "",
      "city": "Austin",
      "region": "TX",
      "postcode": "1234",
      "country": "US",
      "countryKnown": true,
      "format": "differs",
      "structure": "format",
      "complete": true,
      "deliverabilityConfirmed": false,
      "issues": [
        {
          "code": "postcode_format",
          "detail": "The postcode does not match the published shape for this country code. Delivery was not checked."
        }
      ],
      "interpretation": "stated"
    },
    {
      "id": "A-1",
      "line1": "10 Example Street",
      "line2": "",
      "city": "London",
      "region": "",
      "postcode": "SW1A 1AA",
      "country": "GB",
      "countryKnown": true,
      "format": "matches",
      "structure": "present",
      "complete": true,
      "deliverabilityConfirmed": false,
      "issues": [],
      "interpretation": "stated"
    },
    {
      "id": "A-3",
      "line1": "",
      "line2": "",
      "city": "",
      "region": "",
      "postcode": "",
      "country": "",
      "countryKnown": false,
      "format": "not_checked",
      "structure": "incomplete",
      "complete": false,
      "deliverabilityConfirmed": false,
      "issues": [
        {
          "code": "line1_missing",
          "detail": "The first address line was not supplied."
        },
        {
          "code": "city_missing",
          "detail": "The city was not supplied."
        },
        {
          "code": "postcode_missing",
          "detail": "The postcode was not supplied."
        },
        {
          "code": "country_missing",
          "detail": "The country was not supplied."
        }
      ],
      "interpretation": "stated"
    }
  ],
  "carrierContacted": false,
  "returnInitiated": false,
  "refundGranted": false,
  "deliverabilityConfirmed": false,
  "eventsInvented": false,
  "findings": [],
  "limitations": [
    "Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.",
    "No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.",
    "An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.",
    "A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.",
    "No carrier account is contacted and no return is initiated."
  ]
}

cURL

curl -i -X POST "https://brainiac.software/api/v1/returns-delivery/shipping-address-validate" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "addresses": [
    {
      "id": "A-2",
      "line1": "10 Example Street",
      "city": "Austin",
      "region": "TX",
      "postcode": "1234",
      "country": "US"
    },
    {
      "id": "A-1",
      "line1": "10 Example Street",
      "city": "London",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "A-3",
      "line1": "",
      "city": "",
      "postcode": "",
      "country": ""
    }
  ]
}
JSON

POSThttps://brainiac.software/api/v1/returns-delivery/return-shipping-cost-calculate$0.04 USDC

Calculate return shipping cost

Apply one matching caller-supplied rate to a return. A missing rate is not estimated, currencies are not converted, and the result is not a refund.

Body

Field	Required	Notes
`text`	No	string
`json`	No	string
`csv`	No	string
`file`	No	object; Object
`orders`	No	array; Array
`addresses`	No	array; Array
`events`	No	array; Array
`returns`	No	array; Array
`rates`	No	array; Array
`window`	No	object; Object
`rules`	No	array; Array

Request exampleJSON

{
  "orders": [
    {
      "id": "O-1",
      "carrier": "Example Carrier",
      "country": "GB"
    },
    {
      "id": "O-2",
      "carrier": "Example Carrier",
      "country": "FR"
    }
  ],
  "rates": [
    {
      "carrier": "Example Carrier",
      "country": "GB",
      "amount": 4.5,
      "currency": "USD",
      "basis": "flat"
    }
  ],
  "returns": [
    {
      "id": "R-1",
      "orderId": "O-1",
      "reason": "size"
    },
    {
      "id": "R-2",
      "orderId": "O-2",
      "reason": "size"
    }
  ]
}

Response exampleJSON

{
  "checkedAt": "2026-11-04T12:00:00.000Z",
  "status": "calculated",
  "costs": [
    {
      "returnId": "R-1",
      "orderId": "O-1",
      "currency": "USD",
      "stated": 0,
      "statedSupplied": false,
      "calculated": 4.5,
      "calculatedSupplied": true,
      "basis": "flat",
      "refundGranted": false,
      "interpretation": "stated"
    },
    {
      "returnId": "R-2",
      "orderId": "O-2",
      "currency": "",
      "stated": 0,
      "statedSupplied": false,
      "calculated": 0,
      "calculatedSupplied": false,
      "basis": "",
      "refundGranted": false,
      "interpretation": "stated"
    }
  ],
  "carrierContacted": false,
  "returnInitiated": false,
  "refundGranted": false,
  "deliverabilityConfirmed": false,
  "eventsInvented": false,
  "findings": [],
  "limitations": [
    "Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.",
    "No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.",
    "An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.",
    "A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.",
    "No carrier account is contacted and no return is initiated."
  ]
}

cURL

curl -i -X POST "https://brainiac.software/api/v1/returns-delivery/return-shipping-cost-calculate" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "orders": [
    {
      "id": "O-1",
      "carrier": "Example Carrier",
      "country": "GB"
    },
    {
      "id": "O-2",
      "carrier": "Example Carrier",
      "country": "FR"
    }
  ],
  "rates": [
    {
      "carrier": "Example Carrier",
      "country": "GB",
      "amount": 4.5,
      "currency": "USD",
      "basis": "flat"
    }
  ],
  "returns": [
    {
      "id": "R-1",
      "orderId": "O-1",
      "reason": "size"
    },
    {
      "id": "R-2",
      "orderId": "O-2",
      "reason": "size"
    }
  ]
}
JSON

POSThttps://brainiac.software/api/v1/returns-delivery/return-reason-analyze$0.04 USDC

Analyze return reasons

Count supplied return reasons exactly as written. A reason is a pattern only at three or more returns. The reason text is not rewritten and no refund is granted.

Body

Field	Required	Notes
`text`	No	string
`json`	No	string
`csv`	No	string
`file`	No	object; Object
`orders`	No	array; Array
`addresses`	No	array; Array
`events`	No	array; Array
`returns`	No	array; Array
`rates`	No	array; Array
`window`	No	object; Object
`rules`	No	array; Array

Request exampleJSON

{
  "returns": [
    {
      "id": "R-1",
      "reason": "size"
    },
    {
      "id": "R-2",
      "reason": "size"
    },
    {
      "id": "R-3",
      "reason": "size"
    },
    {
      "id": "R-4",
      "reason": "color"
    },
    {
      "id": "R-5",
      "reason": "erase"
    }
  ]
}

Response exampleJSON

{
  "checkedAt": "2026-11-04T12:00:00.000Z",
  "status": "analyzed",
  "reasons": [
    {
      "reason": "size",
      "count": 3,
      "pattern": true,
      "refundGranted": false,
      "interpretation": "stated"
    },
    {
      "reason": "color",
      "count": 1,
      "pattern": false,
      "refundGranted": false,
      "interpretation": "stated"
    },
    {
      "reason": "erase",
      "count": 1,
      "pattern": false,
      "refundGranted": false,
      "interpretation": "stated"
    }
  ],
  "carrierContacted": false,
  "returnInitiated": false,
  "refundGranted": false,
  "deliverabilityConfirmed": false,
  "eventsInvented": false,
  "findings": [],
  "limitations": [
    "Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.",
    "No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.",
    "An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.",
    "A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.",
    "No carrier account is contacted and no return is initiated."
  ]
}

cURL

curl -i -X POST "https://brainiac.software/api/v1/returns-delivery/return-reason-analyze" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "returns": [
    {
      "id": "R-1",
      "reason": "size"
    },
    {
      "id": "R-2",
      "reason": "size"
    },
    {
      "id": "R-3",
      "reason": "size"
    },
    {
      "id": "R-4",
      "reason": "color"
    },
    {
      "id": "R-5",
      "reason": "erase"
    }
  ]
}
JSON

POSThttps://brainiac.software/api/v1/returns-delivery/promise-variance$0.04 USDC

Calculate delivery-promise variance

Subtract the supplied promise timestamp from the supplied delivery timestamp. A missing timestamp is not filled in, and the comparison is not a carrier guarantee.

Body

Field	Required	Notes
`text`	No	string
`json`	No	string
`csv`	No	string
`file`	No	object; Object
`orders`	No	array; Array
`addresses`	No	array; Array
`events`	No	array; Array
`returns`	No	array; Array
`rates`	No	array; Array
`window`	No	object; Object
`rules`	No	array; Array

Request exampleJSON

{
  "orders": [
    {
      "id": "O-1",
      "promised": "2026-11-01",
      "delivered": "2026-11-03"
    },
    {
      "id": "O-2",
      "promised": "2026-11-05",
      "delivered": "2026-11-04"
    },
    {
      "id": "O-3",
      "promised": "2026-11-01"
    }
  ]
}

Response exampleJSON

{
  "checkedAt": "2026-11-04T12:00:00.000Z",
  "status": "calculated",
  "orders": [
    {
      "id": "O-1",
      "promised": "2026-11-01",
      "delivered": "2026-11-03",
      "varianceDays": 2,
      "daysSupplied": true,
      "varianceHours": 0,
      "hoursSupplied": false,
      "withinPromise": false,
      "promiseChecked": true,
      "guaranteeConfirmed": false
    },
    {
      "id": "O-2",
      "promised": "2026-11-05",
      "delivered": "2026-11-04",
      "varianceDays": -1,
      "daysSupplied": true,
      "varianceHours": 0,
      "hoursSupplied": false,
      "withinPromise": true,
      "promiseChecked": true,
      "guaranteeConfirmed": false
    },
    {
      "id": "O-3",
      "promised": "2026-11-01",
      "delivered": "",
      "varianceDays": 0,
      "daysSupplied": false,
      "varianceHours": 0,
      "hoursSupplied": false,
      "withinPromise": false,
      "promiseChecked": false,
      "guaranteeConfirmed": false
    }
  ],
  "carrierContacted": false,
  "returnInitiated": false,
  "refundGranted": false,
  "deliverabilityConfirmed": false,
  "eventsInvented": false,
  "findings": [],
  "limitations": [
    "Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.",
    "No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.",
    "An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.",
    "A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.",
    "No carrier account is contacted and no return is initiated."
  ]
}

cURL

curl -i -X POST "https://brainiac.software/api/v1/returns-delivery/promise-variance" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "orders": [
    {
      "id": "O-1",
      "promised": "2026-11-01",
      "delivered": "2026-11-03"
    },
    {
      "id": "O-2",
      "promised": "2026-11-05",
      "delivered": "2026-11-04"
    },
    {
      "id": "O-3",
      "promised": "2026-11-01"
    }
  ]
}
JSON

POSThttps://brainiac.software/api/v1/returns-delivery/return-window-calculate$0.04 USDC

Calculate a return window

Add the supplied day count to the supplied delivered or ordered date and compare a return request with that end date. No day count is assumed, and an inside date is not a refund entitlement.

Body

Field	Required	Notes
`text`	No	string
`json`	No	string
`csv`	No	string
`file`	No	object; Object
`orders`	No	array; Array
`addresses`	No	array; Array
`events`	No	array; Array
`returns`	No	array; Array
`rates`	No	array; Array
`window`	No	object; Object
`rules`	No	array; Array

Request exampleJSON

{
  "window": {
    "days": 14,
    "from": "delivered"
  },
  "orders": [
    {
      "id": "O-1",
      "delivered": "2026-11-01"
    }
  ],
  "returns": [
    {
      "id": "R-1",
      "orderId": "O-1",
      "requested": "2026-11-20"
    },
    {
      "id": "R-2",
      "orderId": "O-1",
      "requested": "2026-11-15"
    }
  ]
}

Response exampleJSON

{
  "checkedAt": "2026-11-04T12:00:00.000Z",
  "status": "calculated",
  "days": 14,
  "daysSupplied": true,
  "from": "delivered",
  "returns": [
    {
      "id": "R-1",
      "orderId": "O-1",
      "start": "2026-11-01",
      "end": "2026-11-15",
      "requested": "2026-11-20",
      "state": "outside",
      "refundGranted": false
    },
    {
      "id": "R-2",
      "orderId": "O-1",
      "start": "2026-11-01",
      "end": "2026-11-15",
      "requested": "2026-11-15",
      "state": "inside",
      "refundGranted": false
    }
  ],
  "carrierContacted": false,
  "returnInitiated": false,
  "refundGranted": false,
  "deliverabilityConfirmed": false,
  "eventsInvented": false,
  "findings": [],
  "limitations": [
    "Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.",
    "No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.",
    "An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.",
    "A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.",
    "No carrier account is contacted and no return is initiated."
  ]
}

cURL

curl -i -X POST "https://brainiac.software/api/v1/returns-delivery/return-window-calculate" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "window": {
    "days": 14,
    "from": "delivered"
  },
  "orders": [
    {
      "id": "O-1",
      "delivered": "2026-11-01"
    }
  ],
  "returns": [
    {
      "id": "R-1",
      "orderId": "O-1",
      "requested": "2026-11-20"
    },
    {
      "id": "R-2",
      "orderId": "O-1",
      "requested": "2026-11-15"
    }
  ]
}
JSON

POSThttps://brainiac.software/api/v1/returns-delivery/logistics-report$0.12 USDC

Report returns and delivery logistics

Combine supplied exceptions, failed-order groups, address structure, return rates, promise variance, and the return window. The report does not contact a carrier or grant a refund.

Body

Field	Required	Notes
`text`	No	string
`json`	No	string
`csv`	No	string
`file`	No	object; Object
`orders`	No	array; Array
`addresses`	No	array; Array
`events`	No	array; Array
`returns`	No	array; Array
`rates`	No	array; Array
`window`	No	object; Object
`rules`	No	array; Array

Request exampleJSON

{
  "orders": [
    {
      "id": "O-1",
      "promised": "2026-11-01",
      "delivered": "2026-11-03",
      "status": "failed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "O-2",
      "promised": "2026-11-01",
      "delivered": "2026-11-03",
      "status": "failed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "O-3",
      "promised": "2026-11-01",
      "delivered": "2026-11-03",
      "status": "failed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    }
  ],
  "addresses": [
    {
      "id": "A-1",
      "line1": "10 Example Street",
      "city": "London",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "A-2",
      "line1": "10 Example Street",
      "city": "Austin",
      "postcode": "1234",
      "country": "US"
    }
  ],
  "returns": [
    {
      "id": "R-1",
      "orderId": "O-1",
      "reason": "size",
      "requested": "2026-11-20"
    },
    {
      "id": "R-2",
      "orderId": "O-1",
      "reason": "size",
      "requested": "2026-11-10"
    },
    {
      "id": "R-3",
      "orderId": "O-2",
      "reason": "size",
      "requested": "2026-11-10"
    }
  ],
  "rates": [
    {
      "carrier": "Example Carrier",
      "country": "GB",
      "amount": 4.5,
      "currency": "USD",
      "basis": "flat"
    }
  ],
  "window": {
    "days": 14,
    "from": "delivered"
  }
}

Response exampleJSON

{
  "checkedAt": "2026-11-04T12:00:00.000Z",
  "status": "reported",
  "orderCount": 3,
  "failedCount": 3,
  "patternCount": 2,
  "addressIssueCount": 1,
  "calculatedCount": 3,
  "lateCount": 3,
  "outsideCount": 1,
  "level": "review",
  "totals": [
    {
      "currency": "USD",
      "amount": 13.5,
      "count": 3
    }
  ],
  "items": [
    {
      "id": "O-1",
      "orderId": "O-1",
      "source": "status",
      "code": "failed",
      "category": "failed",
      "at": "2026-11-03",
      "confirmed": false,
      "interpretation": "stated"
    },
    {
      "id": "O-2",
      "orderId": "O-2",
      "source": "status",
      "code": "failed",
      "category": "failed",
      "at": "2026-11-03",
      "confirmed": false,
      "interpretation": "stated"
    },
    {
      "id": "O-3",
      "orderId": "O-3",
      "source": "status",
      "code": "failed",
      "category": "failed",
      "at": "2026-11-03",
      "confirmed": false,
      "interpretation": "stated"
    }
  ],
  "signals": [
    {
      "code": "shared_postcode",
      "confirmed": false,
      "orders": [
        "O-1",
        "O-2",
        "O-3"
      ],
      "detail": "3 failed orders share postcode sw1a 1aa|gb. This is not a carrier finding."
    },
    {
      "code": "shared_carrier",
      "confirmed": false,
      "orders": [
        "O-1",
        "O-2",
        "O-3"
      ],
      "detail": "3 failed orders share carrier example carrier. This is not a carrier finding."
    }
  ],
  "addresses": [
    {
      "id": "A-1",
      "line1": "10 Example Street",
      "line2": "",
      "city": "London",
      "region": "",
      "postcode": "SW1A 1AA",
      "country": "GB",
      "countryKnown": true,
      "format": "matches",
      "structure": "present",
      "complete": true,
      "deliverabilityConfirmed": false,
      "issues": [],
      "interpretation": "stated"
    },
    {
      "id": "A-2",
      "line1": "10 Example Street",
      "line2": "",
      "city": "Austin",
      "region": "",
      "postcode": "1234",
      "country": "US",
      "countryKnown": true,
      "format": "differs",
      "structure": "format",
      "complete": true,
      "deliverabilityConfirmed": false,
      "issues": [
        {
          "code": "postcode_format",
          "detail": "The postcode does not match the published shape for this country code. Delivery was not checked."
        }
      ],
      "interpretation": "stated"
    }
  ],
  "costs": [
    {
      "returnId": "R-1",
      "orderId": "O-1",
      "currency": "USD",
      "stated": 0,
      "statedSupplied": false,
      "calculated": 4.5,
      "calculatedSupplied": true,
      "basis": "flat",
      "refundGranted": false,
      "interpretation": "stated"
    },
    {
      "returnId": "R-2",
      "orderId": "O-1",
      "currency": "USD",
      "stated": 0,
      "statedSupplied": false,
      "calculated": 4.5,
      "calculatedSupplied": true,
      "basis": "flat",
      "refundGranted": false,
      "interpretation": "stated"
    },
    {
      "returnId": "R-3",
      "orderId": "O-2",
      "currency": "USD",
      "stated": 0,
      "statedSupplied": false,
      "calculated": 4.5,
      "calculatedSupplied": true,
      "basis": "flat",
      "refundGranted": false,
      "interpretation": "stated"
    }
  ],
  "reasons": [
    {
      "reason": "size",
      "count": 3,
      "pattern": true,
      "refundGranted": false,
      "interpretation": "stated"
    }
  ],
  "orders": [
    {
      "id": "O-1",
      "promised": "2026-11-01",
      "delivered": "2026-11-03",
      "varianceDays": 2,
      "daysSupplied": true,
      "varianceHours": 0,
      "hoursSupplied": false,
      "withinPromise": false,
      "promiseChecked": true,
      "guaranteeConfirmed": false
    },
    {
      "id": "O-2",
      "promised": "2026-11-01",
      "delivered": "2026-11-03",
      "varianceDays": 2,
      "daysSupplied": true,
      "varianceHours": 0,
      "hoursSupplied": false,
      "withinPromise": false,
      "promiseChecked": true,
      "guaranteeConfirmed": false
    },
    {
      "id": "O-3",
      "promised": "2026-11-01",
      "delivered": "2026-11-03",
      "varianceDays": 2,
      "daysSupplied": true,
      "varianceHours": 0,
      "hoursSupplied": false,
      "withinPromise": false,
      "promiseChecked": true,
      "guaranteeConfirmed": false
    }
  ],
  "returns": [
    {
      "id": "R-1",
      "orderId": "O-1",
      "start": "2026-11-03",
      "end": "2026-11-17",
      "requested": "2026-11-20",
      "state": "outside",
      "refundGranted": false
    },
    {
      "id": "R-2",
      "orderId": "O-1",
      "start": "2026-11-03",
      "end": "2026-11-17",
      "requested": "2026-11-10",
      "state": "inside",
      "refundGranted": false
    },
    {
      "id": "R-3",
      "orderId": "O-2",
      "start": "2026-11-03",
      "end": "2026-11-17",
      "requested": "2026-11-10",
      "state": "inside",
      "refundGranted": false
    }
  ],
  "carrierContacted": false,
  "returnInitiated": false,
  "refundGranted": false,
  "deliverabilityConfirmed": false,
  "eventsInvented": false,
  "findings": [],
  "limitations": [
    "Orders, addresses, events, returns, and rates are copied only from labeled fields supplied by the caller.",
    "No carrier tracking event is added. A code is classified only when it is failed, delivery_failed, not_delivered, undeliverable, refused, damaged, delayed, late, held, hold, address, address_issue, bad_address, returned, returned_to_sender, rts, or exception.",
    "An address check is structural. Postcode shape is checked only for AU, CA, DE, ES, FR, GB, IT, NL, and US. Delivery is not confirmed.",
    "A return cost uses only a supplied rate, and a window uses only a supplied day count. No refund is granted.",
    "No carrier account is contacted and no return is initiated."
  ]
}

cURL

curl -i -X POST "https://brainiac.software/api/v1/returns-delivery/logistics-report" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "orders": [
    {
      "id": "O-1",
      "promised": "2026-11-01",
      "delivered": "2026-11-03",
      "status": "failed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "O-2",
      "promised": "2026-11-01",
      "delivered": "2026-11-03",
      "status": "failed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "O-3",
      "promised": "2026-11-01",
      "delivered": "2026-11-03",
      "status": "failed",
      "carrier": "Example Carrier",
      "postcode": "SW1A 1AA",
      "country": "GB"
    }
  ],
  "addresses": [
    {
      "id": "A-1",
      "line1": "10 Example Street",
      "city": "London",
      "postcode": "SW1A 1AA",
      "country": "GB"
    },
    {
      "id": "A-2",
      "line1": "10 Example Street",
      "city": "Austin",
      "postcode": "1234",
      "country": "US"
    }
  ],
  "returns": [
    {
      "id": "R-1",
      "orderId": "O-1",
      "reason": "size",
      "requested": "2026-11-20"
    },
    {
      "id": "R-2",
      "orderId": "O-1",
      "reason": "size",
      "requested": "2026-11-10"
    },
    {
      "id": "R-3",
      "orderId": "O-2",
      "reason": "size",
      "requested": "2026-11-10"
    }
  ],
  "rates": [
    {
      "carrier": "Example Carrier",
      "country": "GB",
      "amount": 4.5,
      "currency": "USD",
      "basis": "flat"
    }
  ],
  "window": {
    "days": 14,
    "from": "delivered"
  }
}
JSON