Skip to main content

Invoices and credit limits

Platform accounts pay by monthly invoice instead of from a prepaid wallet. Bookings go on the month's invoice, up to a credit limit.

A business becomes a platform by applying in the dashboard, and Reeds approves it with an agreement that sets the credit limit. Your account's billing_mode in GET /wallet says which one you are on.

Credit limit​

A booking is refused when what you owe, plus the new delivery, would go over your limit. What you owe is:

  • the unbilled deliveries for the current month, plus
  • issued invoices that are not yet paid.

GET /wallet shows the sum in a credit block, so you can check your room before a busy period:

GET /wallet on an invoice account
{
  "status": "success",
  "data": {
    "livemode": true,
    "balance": 0,
    "currency": "NGN",
    "billing_mode": "invoice",
    "low_balance_threshold": null,
    "credit": {
      "limit": 50000000,
      "unbilled": 12000000,
      "unpaid_invoices": 8000000,
      "available": 30000000
    }
  }
}

available is the limit less unbilled and unpaid_invoices, the same sum the credit-limit check uses. All amounts are in kobo.

When the limit is reached​

Response 402
{
  "status": "failed",
  "error": {
    "code": "CREDIT_LIMIT_REACHED",
    "message": "This delivery would take the account over its credit limit",
    "doc_url": "https://developer.getreeds.co/errors/CREDIT_LIMIT_REACHED"
  }
}

Pay an issued invoice, or ask Reeds to raise the limit, then retry with the same Idempotency-Key. For a draft with auto_book: true, the draft gets a PAY_INVOICE action and Reeds books it automatically once there is room.

Invoice cycle​

  • Reeds issues an invoice on the 1st of each month for the previous month. The invoice.issued webhook fires.
  • Pay it before it becomes overdue.
  • If an invoice becomes overdue, the account goes on hold. New bookings return 403 ACCOUNT_ON_HOLD. Deliveries already moving carry on.
  • Pay the invoice to lift the hold.

Read invoices​

GET /invoices lists invoices, newest first. Filter with status: issued, paid, overdue or void. A void invoice was cancelled by Reeds and owes nothing.

curl "https://api.getreeds.co/shipping/v1/invoices?status=overdue" \
  -H "Authorization: Bearer $REEDS_ACCESS_TOKEN"

GET /invoices/{id} returns one invoice.

curl https://api.getreeds.co/shipping/v1/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $REEDS_ACCESS_TOKEN"
GET /invoices/{id}
{
  "status": "success",
  "data": {
    "id": "inv_6Gc4Yt8N",
    "number": "RDS-2026-000123",
    "livemode": true,
    "status": "issued",
    "period": "2026-09",
    "delivery_count": 412,
    "delivery_fees": 98400000,
    "vat": 7380000,
    "service_charges": 2420000,
    "discounts": 0,
    "adjustments": 0,
    "total": 108200000,
    "amount_paid": 0,
    "amount_credited": 0,
    "amount_due": 108200000,
    "currency": "NGN",
    "issued_at": "2026-10-01T06:00:00+01:00",
    "due_at": "2026-10-15T23:59:59+01:00",
    "paid_at": null,
    "voided_at": null
  }
}
FieldDescription
numberRDS-<year>-<6 digits> (TEST-... in Test mode), numbered per mode and year with no gaps
periodThe month invoiced, YYYY-MM
delivery_fees, vat, service_charges, discounts, adjustmentsThe parts of the total, in kobo. delivery_fees + vat + service_charges - discounts + adjustments = total. VAT is on the delivery fees only.
amount_paid, amount_credited, amount_dueWhat has been paid, what refunds and credit notes took off, and what is still owed, in kobo
issued_at, due_at, paid_at, voided_atWhen it was issued, when it is due, and when it was paid or voided

GET /invoices/{id}/pdf returns the invoice as an A4 PDF, with every line. It answers 304 to a matching If-None-Match.

curl -o invoice.pdf https://api.getreeds.co/shipping/v1/invoices/$INVOICE_ID/pdf \
  -H "Authorization: Bearer $REEDS_ACCESS_TOKEN"

Invoice accounts also see their unbilled total, credit limit and invoices in the dashboard's Wallet page.

Credit limits are set by agreement. Contact support@getreeds.co to discuss yours.

Next steps​