---
title: "Create invoice"
method: POST
path: "/invoices"
tags: ["Invoices"]
---

# Create invoice

`POST /invoices`

## Request

- Base URL: `https://api.palomma.com/v1`
- URL: `https://api.palomma.com/v1/invoices`
- Auth: HTTP bearer

Creates a new invoice for the authenticated merchant.

## Request body

- CreateInvoiceRequest
  - `reference` string, required: Unique invoice reference for your records (e.g. `"INV-2026-0001"`).
  - `amount` integer, required: Invoice amount in COP. Must be between 3,000 and 550,000,000.
  - `description` string, required: Invoice description shown to the customer.
  - `redirectUrl` string, uri, required: URL where the customer is redirected after completing the payment flow.
  - `customerDocumentNumber` string, required: Customer's document or identification number.
  - `documentType` 'cc' | 'ce' | 'nit' | 'ti' | 'ps' | 'cif' | 'ne' | 'rc' | 'ppt': Customer's document type. One of: `cc` (cedula), `ce` (cedula de extranjeria), `nit` (NIT), `ti` (tarjeta de identidad), `ps` (pasaporte), `cif` (codigo de identificacion fiscal), `ne` (NIT extranjero), `rc` (registro civil), `ppt` (permiso de permanencia temporal).
  - `customerName` string: Customer's display name (optional).
  - `contract` string: Contract identifier. Defaults to `"00000"` if not provided.

## Response `200`

Created invoice

- Invoice
  - `id` string, required: Unique invoice identifier.
  - `reference` string: Merchant-provided invoice reference.
  - `status` 'ready' | 'paid' | 'cancelled' | 'chargeback', required: Invoice status: `ready` (payment link active), `paid`, `cancelled`, or `chargeback`.
  - `amount` number, required: Invoice amount in COP.
  - `description` string, required: Invoice description.
  - `contract` string, required: Contract identifier.
  - `expirationDate` string: Payment link expiration datetime (ISO 8601). Invoices expire 5 minutes after creation, so redirect the customer immediately. Once a transaction is in progress, it no longer expires until the transaction completes.
  - `customerDocumentNumber` string, required: Customer's document number.
  - `customerName` string: Customer's display name.
  - `createdAt` string, required: Invoice creation datetime (ISO 8601).
  - `paymentDate` string, date-time: When the invoice was paid. Present on paid and chargeback invoices.
  - `paymentMethod` 'pse' | 'nequiButton' | 'bancolombiaButton' | 'breb' | 'card': Payment method used. Present on paid and chargeback invoices.
  - `paymentSource` 'whatsapp' | 'portal' | 'link': Channel through which payment was made. Present on paid and chargeback invoices.
  - `paymentAmount` number: Amount actually paid in COP. Present on paid and chargeback invoices.
  - `settlementDate` string: Expected settlement date (`YYYY-MM-DD`). Present on paid and chargeback invoices.
  - `settlementTime` string: Expected settlement cycle. Present on paid and chargeback invoices.
  - `paymentId` string: Payment identifier. Present on paid and chargeback invoices.
  - `paymentUrl` string, uri, required: Palomma hosted payment page URL for this invoice.

## Other responses

- `400`: Invalid request input
- `401`: Invalid or missing bearer token
- `500`: Unexpected server error

---

[API](https://skmtc.dev/palomma/apis/palomma-rentals-api.md) - [All operations](https://skmtc.dev/palomma/apis/palomma-rentals-api/llms.txt) - [OpenAPI document](https://skmtc.dev/palomma/apis/palomma-rentals-api/revisions/1ccb5e11c48d?raw)