> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleo-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/payables — Create a New Payable

> POST /v1/payables creates a new payable (invoice). Provide contact info, total amount in cents, and optional line items, dates, and memo.

The Create Payable endpoint lets you programmatically generate a new payable (invoice) in Cleo Pay. You supply at minimum a contact and a total amount; optionally, you can attach structured line items, set issue and due dates, provide your own reference number, and add a free-text description. Newly created payables start in `draft` status and must proceed through your configured approval workflow before payment can be initiated.

## Request

**`POST https://api.cleo-pay.com/v1/payables`**

Include your bearer token and set the content type on every request:

```
Authorization: Bearer <token>
Content-Type: application/json
```

### Request Body Parameters

<ParamField body="contact" type="object" required>
  The counterparty for this payable. Cleo Pay will match against existing contacts by email, or create a new contact record if no match is found.

  <Expandable title="contact fields">
    <ParamField body="name" type="string" required>
      Full display name of the contact (e.g. `"Acme Corporation"`).
    </ParamField>

    <ParamField body="email" type="string">
      Email address of the contact. Used to match or create a contact record. Optional, but recommended for deduplication.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="totalAmountCents" type="number" required>
  Total invoice amount expressed in cents. Must be `1` or greater (e.g. pass `10000` for \$100.00). If you also supply `items`, ensure this value equals the sum of all `items[].totalCents` to avoid reconciliation discrepancies.
</ParamField>

<ParamField body="dueDate" type="string">
  Payment due date in `YYYY-MM-DD` format (e.g. `"2024-08-15"`). Optional. When omitted, the payable is created without a due date.
</ParamField>

<ParamField body="issueDate" type="string">
  Invoice issue date in `YYYY-MM-DD` format (e.g. `"2024-07-15"`). Optional. Defaults to the creation date when omitted.
</ParamField>

<ParamField body="customNumber" type="string">
  Your own invoice or purchase-order reference number (e.g. `"INV-1042"`). Optional. This value is stored as-is and surfaced in the dashboard alongside the system-generated `publicId`.
</ParamField>

<ParamField body="description" type="string">
  Free-text memo or description for this payable (e.g. `"Q3 software licensing fees"`). Optional.
</ParamField>

<ParamField body="items" type="array">
  Structured line items that make up the invoice. Optional. Each element represents one line on the invoice.

  <Expandable title="item fields">
    <ParamField body="name" type="string">
      Short label for the line item (e.g. `"Professional Services"`). Optional.
    </ParamField>

    <ParamField body="description" type="string">
      Longer description of the line item. Optional.
    </ParamField>

    <ParamField body="quantity" type="number" required>
      Number of units for this line item. Must be a positive number.
    </ParamField>

    <ParamField body="unitAmountCents" type="number" required>
      Price per unit in cents. Must be a positive number (e.g. `5000` = \$50.00 per unit).
    </ParamField>
  </Expandable>
</ParamField>

### Example Request

```bash theme={null}
curl --request POST \
  --url "https://api.cleo-pay.com/v1/payables" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "contact": {
      "name": "Acme Corporation",
      "email": "ap@acme.example.com"
    },
    "totalAmountCents": 250000,
    "dueDate": "2024-08-15",
    "issueDate": "2024-07-15",
    "customNumber": "INV-1042",
    "description": "Q3 software licensing fees",
    "items": [
      {
        "name": "Enterprise License",
        "description": "Annual seat license — 10 users",
        "quantity": 10,
        "unitAmountCents": 20000
      },
      {
        "name": "Implementation Support",
        "description": "Onboarding and configuration services",
        "quantity": 5,
        "unitAmountCents": 10000
      }
    ]
  }'
```

## Response

A successful request returns HTTP `201 Created` with the full `PayableDetail` object, including all line items as stored.

<ResponseField name="id" type="string">
  Internal opaque identifier for the new payable. Use this when calling other endpoints that reference a specific payable.
</ResponseField>

<ResponseField name="publicId" type="string">
  Stable public identifier shown in the Cleo Pay dashboard.
</ResponseField>

<ResponseField name="status" type="string">
  Initial lifecycle status of the payable. Newly created payables always start as `draft`.
</ResponseField>

<ResponseField name="paymentStatus" type="string">
  Initial payment status. Always `none` for newly created payables.
</ResponseField>

<ResponseField name="totalAmountCents" type="number">
  Total invoice amount in cents, as provided in the request.
</ResponseField>

<ResponseField name="amountPaidCents" type="number">
  Amount paid so far, in cents. Always `0` for newly created payables.
</ResponseField>

<ResponseField name="remainingAmountCents" type="number">
  Outstanding balance in cents. Equal to `totalAmountCents` for newly created payables.
</ResponseField>

<ResponseField name="dueDate" type="string | null">
  Payment due date in `YYYY-MM-DD` format, or `null` if not provided.
</ResponseField>

<ResponseField name="issueDate" type="string | null">
  Invoice issue date in `YYYY-MM-DD` format, or `null` if not provided.
</ResponseField>

<ResponseField name="customNumber" type="string | null">
  Your custom reference number as stored, or `null` if not provided.
</ResponseField>

<ResponseField name="description" type="string | null">
  Memo or description as stored, or `null` if not provided.
</ResponseField>

<ResponseField name="contact" type="object">
  Resolved contact record associated with this payable.

  <Expandable title="contact fields">
    <ResponseField name="id" type="string | null">
      Internal identifier of the matched or created contact record.
    </ResponseField>

    <ResponseField name="displayName" type="string | null">
      Display name of the contact as stored.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="items" type="array">
  Line items attached to this payable, as stored.

  <Expandable title="item fields">
    <ResponseField name="name" type="string | null">
      Line item label, or `null` if not provided.
    </ResponseField>

    <ResponseField name="description" type="string | null">
      Line item description, or `null` if not provided.
    </ResponseField>

    <ResponseField name="quantity" type="number">
      Number of units for this line item.
    </ResponseField>

    <ResponseField name="unitAmountCents" type="number">
      Price per unit in cents.
    </ResponseField>

    <ResponseField name="totalCents" type="number">
      Computed total for this line item in cents (`quantity × unitAmountCents`).
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "id": "pay_01hx9k2mq3fvb8n7cptd6ewrja",
  "publicId": "PAY-2024-00042",
  "status": "draft",
  "paymentStatus": "none",
  "totalAmountCents": 250000,
  "amountPaidCents": 0,
  "remainingAmountCents": 250000,
  "dueDate": "2024-08-15",
  "issueDate": "2024-07-15",
  "customNumber": "INV-1042",
  "description": "Q3 software licensing fees",
  "contact": {
    "id": "con_01hx8a1bc2def3gh4ijk5lm6no",
    "displayName": "Acme Corporation"
  },
  "items": [
    {
      "name": "Enterprise License",
      "description": "Annual seat license — 10 users",
      "quantity": 10,
      "unitAmountCents": 20000,
      "totalCents": 200000
    },
    {
      "name": "Implementation Support",
      "description": "Onboarding and configuration services",
      "quantity": 5,
      "unitAmountCents": 10000,
      "totalCents": 50000
    }
  ]
}
```