# Create invoice API

Create an invoice with a hosted payment page. The same invoices appear in the Moolre dashboard. The API does not send the email, PDF or SMS that the dashboard sends: give the customer the payment_link.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/invoice/create

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-KEY | string | Yes | Your wallet private API key. A public key is refused. |
| Idempotency-Key | string | No | Optional. 1 to 128 printable characters. Repeating a request with the same key and the same body returns the stored response with meta.replayed true for 24 hours; the same key with a different body returns IDEM01. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| accountnumber | string | Yes | Your Moolre wallet account number. |
| currency | string | Yes | GHS or NGN. Must equal the wallet currency. |
| service_id | string | No | Required only when the wallet has several collection services. Otherwise the single service is used. |
| invoice_name | string | Yes | Title of the invoice, at most 100 characters. |
| customer | object | Yes | name (required, at most 100 characters), phone (9 to 15 digits, optional leading +) and email (optional). A customer with the same phone on the service is reused. |
| amount | string | No | A single line for this amount. Send either amount or items. |
| items | array | No | Send either amount or items: 1 to 50 lines of { description (at most 200 characters), quantity (whole number 1 to 100000, default 1), amount (unit price) }. |
| tax | number | No | Percent, 0 to 100. Default 0. Total = subtotal x (1 + tax / 100), rounded to the cent. |
| due_date | string | Yes | YYYY-MM-DD (end of that day) or YYYY-MM-DD HH:MM:SS, UTC. Not in the past and within 2 years. |
| narration | string | No | At most 500 characters. Defaults to invoice_name. |
| reference | string | No | Your reference, at most 128 characters, unique per wallet. The same reference with the same body returns the original invoice (INV02); a different body is INV07. |
| metadata | object | No | Up to 2000 bytes of your own data, returned as given. |

## Response (200 Success)
The invoice object. INV02 with data.replayed true is returned when the same reference and body are sent again.

```json
{
  "status": 1,
  "code": "INV01",
  "message": "Invoice created.",
  "data": {
    "invoiceid": "5-1",
    "status": "pending",
    "reference": "INV-1001",
    "invoice_name": "Term 1 fees",
    "currency": "GHS",
    "total": "100.00",
    "amount_paid": "0.00",
    "tax": "0",
    "items": [
      {
        "amount": "50.00",
        "quantity": "2",
        "description": "Tuition"
      }
    ],
    "customer": {
      "name": "Ama Mensah",
      "phone": "0240000001",
      "email": ""
    },
    "narration": "Term 1 fees",
    "due_date": "2026-12-31T23:59:59Z",
    "payment_link": "https://invoice.moolre.com/5-1",
    "payment_code": "*203*0621#",
    "metadata": null,
    "created": "2026-11-15T09:00:00Z"
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

## Response (200 (HTTP 409 in strict mode) Reference reused)
The reference was already used on this wallet for a different invoice.

```json
{
  "status": 0,
  "code": "INV07",
  "message": "reference was already used on this wallet for a different invoice.",
  "data": "reference",
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

## Invoice status

| status | Meaning |
| --- | --- |
| pending | Created, unpaid |
| partially_paid | A payment smaller than the total has arrived |
| overdue | The due date has passed and the invoice is unpaid or part paid. It can still be paid |
| paid | Fully paid |
| cancelled | Cancelled: the hosted link no longer works |

When the invoice becomes fully paid Moolre sends one invoice.paid webhook (code INV20) to your callback URL. Part payments send no event: poll Invoice status for partially_paid. invoice.expired is not sent yet.

## Fields every response can carry

These fields are additive: existing fields keep their names, order and types.

| Field | Meaning |
| :--- | :--- |
| error | On a failure: { code, message, fields: [{ field, code, message }] } listing every failing field. |
| meta | Always present, last in the object. meta.replayed is true only when the response is the stored answer to a repeated Idempotency-Key (absent otherwise). meta.requestid is the unique id of the request (also the X-Request-Id response header): quote it when you contact support. meta.notices is always an array, empty when there is nothing to report; each notice is { code, message, docs? }, for example that a deprecated way of sending credentials was used. See [Deprecations](https://docs.moolre.com/guides/deprecations). |

There is no outcome field. Decide the result from status, code and, on payment and transfer endpoints, data.txstatus (0 pending, 1 succeeded, 2 failed). These codes mean the result is unknown and may still succeed, so treat them as pending and check the status: PY01, PY02, TR01, TR02, TP11, TP18, APY10, APY16, ASL06, SYS500. Status 1 with TR08, OBGH01, OTGH01, OBNG01, GHQ03 or OM03 is final success; any other status 1 is an accepted, unfinished request.

Send X-Moolre-Http-Status: strict to receive real HTTP status codes (400, 401, 403, 404, 409, 422, 429, 5xx) instead of HTTP 200. See [Responses and request IDs](https://docs.moolre.com/guides/responses).
