Wallet & disputes | Logistics API Docs

Shipments are prepaid from your 7feastr wallet. Each environment has its own wallet: sandbox starts with ₦500,000 of test credit, and production is funded by card or bank transfer from the merchant dashboard. Funding is a dashboard action and is not part of the API.

Get your wallet balance

GET/wallet

Auth: API key. Returns the balance of the wallet for the key's environment.

cURL

curl "https://api.7feastr.com/api/v1/logistics/v1/wallet" \
  -H "Authorization: Bearer $SEVENFEASTR_API_KEY"

200 OK

JSON

{
  "success": true,
  "message": "OK",
  "sandbox": true,
  "data": { "balance": 491507.5, "currency": "NGN", "environment": "sandbox" }
}

Field	Type	Description
`balance`	number	Available balance in NGN
`currency`	string	Always `NGN`
`environment`	string	`sandbox` or `production`

Errors: 401 authentication_error.

List wallet transactions

GET/wallet/transactions

Auth: API key. Returns the wallet ledger, newest first.

Query parameter	Type	Required	Description
`page`	integer	No	Page number, from 1. Default `1`
`limit`	integer	No	Results per page, 1 to 100. Default `20`

cURL

curl "https://api.7feastr.com/api/v1/logistics/v1/wallet/transactions?page=1&limit=20" \
  -H "Authorization: Bearer $SEVENFEASTR_API_KEY"

200 OK

JSON

{
  "success": true,
  "message": "OK",
  "sandbox": true,
  "data": [
    {
      "_id": "6716a3f3c9e77b0012a4d5f0",
      "type": "shipment_debit",
      "amount": 8492.5,
      "balanceAfter": 491507.5,
      "reference": "shipment_debit_6716a3f2c9e77b0012a4d5e1",
      "shipmentId": "6716a3f2c9e77b0012a4d5e1",
      "description": "Charge for shipment 7F-20261021-4F91A2C8",
      "environment": "sandbox",
      "createdAt": "2026-10-21T09:32:10.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

Field	Type	Description
`type`	string	`funding`, `shipment_debit`, `refund` or `adjustment`
`amount`	number	Amount in NGN
`balanceAfter`	number	Wallet balance after this transaction
`reference`	string	Unique reference for the transaction
`shipmentId`	string	The related shipment, for debits and refunds
`description`	string	A readable summary

Errors: 401 authentication_error.

Refunds

When you cancel a shipment before a rider is assigned, the full price is returned to the same wallet automatically as a refund transaction, and the shipment.refunded webhook is sent. See Cancel a shipment.

Low balance alerts

When a shipment charge takes your balance to or below the low-balance threshold set in your dashboard, we send the wallet.low_balance webhook so you can top up before shipments start failing with 402 insufficient_funds.

Disputes

If a shipment is damaged, lost or badly delayed, open a dispute against it. Our support team reviews it and replies in the dispute's message thread.

Open a dispute

POST/disputes

Auth: API key. Returns 201 Created.

Field	Type	Required	Description
`shipmentId`	string	Yes	The shipment `_id`
`reason`	string	Yes	What went wrong, in your own words

cURL

curl -X POST "https://api.7feastr.com/api/v1/logistics/v1/disputes" \
  -H "Authorization: Bearer $SEVENFEASTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipmentId": "6716a3f2c9e77b0012a4d5e1",
    "reason": "Package arrived damaged and the recipient refused it."
  }'

201 Created

JSON

{
  "success": true,
  "message": "OK",
  "sandbox": true,
  "data": {
    "_id": "6717f0a1b2c3d4e5f6a7b8c9",
    "shipmentId": "6716a3f2c9e77b0012a4d5e1",
    "environment": "sandbox",
    "reason": "Package arrived damaged and the recipient refused it.",
    "status": "open",
    "messages": [
      {
        "senderType": "merchant",
        "message": "Package arrived damaged and the recipient refused it.",
        "at": "2026-10-22T11:04:51.000Z"
      }
    ],
    "createdAt": "2026-10-22T11:04:51.000Z",
    "updatedAt": "2026-10-22T11:04:51.000Z"
  }
}

HTTP	`error.code`	When
400	`invalid_request`	`shipmentId` or `reason` is missing, or a dispute is already open on this shipment
404	`not_found`	Unknown shipment
401	`authentication_error`	Missing, invalid or revoked API key

Only one open dispute is allowed per shipment at a time.

List and view disputes

GET/disputes

GET/disputes/:id

Auth: API key. GET /disputes accepts page and limit (1 to 100, default 20) and returns your disputes newest first, with meta: { page, limit, total }. GET /disputes/:id returns one dispute.

cURL

curl "https://api.7feastr.com/api/v1/logistics/v1/disputes/6717f0a1b2c3d4e5f6a7b8c9" \
  -H "Authorization: Bearer $SEVENFEASTR_API_KEY"

Field	Type	Description
`status`	string	`open`, `in_review`, `resolved` or `closed`
`messages`	array	The conversation: `{ senderType, message, at }`, where `senderType` is `merchant` or `admin`
`resolution`	string	How the dispute was resolved, once it is resolved

Errors: 404 not_found for an unknown dispute, 401 authentication_error.

Check GET /disputes/:id or the dashboard for replies from our support team.

Get your wallet balance

GET/wallet

Auth: API key. Returns the balance of the wallet for the key's environment.

cURL

curl "https://api.7feastr.com/api/v1/logistics/v1/wallet" \
  -H "Authorization: Bearer $SEVENFEASTR_API_KEY"

200 OK

JSON

{
  "success": true,
  "message": "OK",
  "sandbox": true,
  "data": { "balance": 491507.5, "currency": "NGN", "environment": "sandbox" }
}

Field	Type	Description
`balance`	number	Available balance in NGN
`currency`	string	Always `NGN`
`environment`	string	`sandbox` or `production`

Errors: 401 authentication_error.

List wallet transactions

GET/wallet/transactions

Auth: API key. Returns the wallet ledger, newest first.

Query parameter	Type	Required	Description
`page`	integer	No	Page number, from 1. Default `1`
`limit`	integer	No	Results per page, 1 to 100. Default `20`

cURL

curl "https://api.7feastr.com/api/v1/logistics/v1/wallet/transactions?page=1&limit=20" \
  -H "Authorization: Bearer $SEVENFEASTR_API_KEY"

200 OK

JSON

{
  "success": true,
  "message": "OK",
  "sandbox": true,
  "data": [
    {
      "_id": "6716a3f3c9e77b0012a4d5f0",
      "type": "shipment_debit",
      "amount": 8492.5,
      "balanceAfter": 491507.5,
      "reference": "shipment_debit_6716a3f2c9e77b0012a4d5e1",
      "shipmentId": "6716a3f2c9e77b0012a4d5e1",
      "description": "Charge for shipment 7F-20261021-4F91A2C8",
      "environment": "sandbox",
      "createdAt": "2026-10-21T09:32:10.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

Field	Type	Description
`type`	string	`funding`, `shipment_debit`, `refund` or `adjustment`
`amount`	number	Amount in NGN
`balanceAfter`	number	Wallet balance after this transaction
`reference`	string	Unique reference for the transaction
`shipmentId`	string	The related shipment, for debits and refunds
`description`	string	A readable summary

Errors: 401 authentication_error.

Refunds

Low balance alerts

Disputes

If a shipment is damaged, lost or badly delayed, open a dispute against it. Our support team reviews it and replies in the dispute's message thread.

Open a dispute

POST/disputes

Auth: API key. Returns 201 Created.

Field	Type	Required	Description
`shipmentId`	string	Yes	The shipment `_id`
`reason`	string	Yes	What went wrong, in your own words

cURL

curl -X POST "https://api.7feastr.com/api/v1/logistics/v1/disputes" \
  -H "Authorization: Bearer $SEVENFEASTR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipmentId": "6716a3f2c9e77b0012a4d5e1",
    "reason": "Package arrived damaged and the recipient refused it."
  }'

201 Created

JSON

{
  "success": true,
  "message": "OK",
  "sandbox": true,
  "data": {
    "_id": "6717f0a1b2c3d4e5f6a7b8c9",
    "shipmentId": "6716a3f2c9e77b0012a4d5e1",
    "environment": "sandbox",
    "reason": "Package arrived damaged and the recipient refused it.",
    "status": "open",
    "messages": [
      {
        "senderType": "merchant",
        "message": "Package arrived damaged and the recipient refused it.",
        "at": "2026-10-22T11:04:51.000Z"
      }
    ],
    "createdAt": "2026-10-22T11:04:51.000Z",
    "updatedAt": "2026-10-22T11:04:51.000Z"
  }
}

HTTP	`error.code`	When
400	`invalid_request`	`shipmentId` or `reason` is missing, or a dispute is already open on this shipment
404	`not_found`	Unknown shipment
401	`authentication_error`	Missing, invalid or revoked API key

Only one open dispute is allowed per shipment at a time.

List and view disputes

GET/disputes

GET/disputes/:id

cURL

curl "https://api.7feastr.com/api/v1/logistics/v1/disputes/6717f0a1b2c3d4e5f6a7b8c9" \
  -H "Authorization: Bearer $SEVENFEASTR_API_KEY"

Field	Type	Description
`status`	string	`open`, `in_review`, `resolved` or `closed`
`messages`	array	The conversation: `{ senderType, message, at }`, where `senderType` is `merchant` or `admin`
`resolution`	string	How the dispute was resolved, once it is resolved

Errors: 404 not_found for an unknown dispute, 401 authentication_error.

Check GET /disputes/:id or the dashboard for replies from our support team.