> For the complete documentation index, see [llms.txt](https://docs.cekat.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cekat.ai/api-documentation/orders/create-an-order.md).

# Create an order

Creates an order and its invoice. Identify the customer with `conversation_id`, `contact_id` or `phone_number`; if no contact matches, a new one is created from `phone_number` and `display_name`.

For each product, send a `product_id` from your catalog (its catalog name and price are used) or a `product_name` and `price` for a custom item. The grand total (subtotal − discount + shipping fee + VAT) must be between 1 and 9,999,999,999.

```json
{"openapi":"3.0.3","info":{"title":"Cekat Open API","version":"1.0.0"},"tags":[{"name":"Orders","description":"Create and manage orders and their invoices. Each order belongs to a contact; Cekat creates the contact if it doesn't exist yet.\n\n| Payment method | Invoice |\n| --- | --- |\n| `manual` | A PDF invoice with your bank account details. Requires `bank_account_number` of a payment bank account set up in Cekat. |\n| `xendit` | A Xendit payment link and PDF invoice. Requires Xendit to be connected. |\n| `custom` | Your own invoice, given as `custom_invoice_url`. |\n\nOrder statuses are `pending`, `processing`, `shipping`, `cancelled` and `completed`. Payment statuses are `PENDING`, `PAID`, `EXPIRED` and `SETTLED`.\n"}],"servers":[{"url":"https://api.cekat.ai","description":"Production"}],"security":[{"CekatApiKey":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"CekatApiKey":{"type":"apiKey","in":"header","name":"api_key","description":"Your business's Cekat API key, from **Settings → Developers & API** in the Cekat dashboard (https://chat.cekat.ai/developers?section=apikeys). Available on the Business and Enterprise plans."},"BearerAuth":{"type":"http","scheme":"bearer","description":"The same Cekat API key, sent as `Authorization: Bearer YOUR_API_KEY`. Accepted only by endpoints under `/api/...`."}},"schemas":{"Order":{"type":"object","description":"An order with its contact, products and invoices. Additional fields may be present.","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"order_number":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"order_status":{"type":"string","enum":["pending","processing","shipping","cancelled","completed"]},"payment_method":{"type":"string","enum":["manual","xendit","custom"]},"subtotal":{"type":"number"},"discount":{"type":"number"},"shipping_fee":{"type":"number"},"vat":{"type":"number"},"grand_total":{"type":"number"},"currency":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"contact_id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","format":"uuid","nullable":true},"contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"display_name":{"type":"string"},"phone_number":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"cekat_orders_products":{"type":"array","items":{"$ref":"#/components/schemas/OrderProduct"}},"invoices":{"type":"array","description":"The order's invoices, newest first.","items":{"$ref":"#/components/schemas/Invoice"}}}},"OrderProduct":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid","nullable":true},"product_name":{"type":"string"},"quantity":{"type":"integer"},"price":{"type":"number"}}},"Invoice":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","SETTLED"]},"amount":{"type":"number"},"payment_link":{"type":"string","nullable":true,"description":"Xendit payment link, for `xendit` orders."},"pdf_link":{"type":"string","nullable":true,"description":"Invoice PDF, or your own invoice URL for `custom` orders."},"is_sent":{"type":"boolean","nullable":true},"expiry_date":{"type":"string","nullable":true},"paid_at":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"ApiError":{"type":"object","description":"Error body returned by the `/api/...` endpoints.","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"statusCode":{"type":"integer"},"error":{"type":"object","properties":{"message":{"type":"string"}}},"correlationId":{"type":"string","description":"Request ID. Include it when contacting Cekat support."}}},"RateLimitError":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"ApiUnauthorized":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"TooManyRequests":{"description":"Rate limit exceeded. Wait and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}},"paths":{"/api/orders":{"post":{"tags":["Orders"],"operationId":"CreateOrder","summary":"Create an order","description":"Creates an order and its invoice. Identify the customer with `conversation_id`, `contact_id` or `phone_number`; if no contact matches, a new one is created from `phone_number` and `display_name`.\n\nFor each product, send a `product_id` from your catalog (its catalog name and price are used) or a `product_name` and `price` for a custom item. The grand total (subtotal − discount + shipping fee + VAT) must be between 1 and 9,999,999,999.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payment_method","orders_products"],"properties":{"payment_method":{"type":"string","enum":["manual","xendit","custom"]},"orders_products":{"type":"array","minItems":1,"items":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","description":"A catalog product. Leave out for a custom item."},"product_name":{"type":"string","description":"Name of a custom item."},"price":{"type":"number","description":"Price of a custom item."},"quantity":{"type":"integer","default":1}}}},"conversation_id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid"},"phone_number":{"type":"string"},"display_name":{"type":"string","description":"Required with `phone_number` when the contact is new."},"email":{"type":"string","format":"email"},"bank_account_number":{"type":"string","description":"Required for `manual`. A payment bank account set up in Cekat."},"custom_invoice_url":{"type":"string","format":"uri","description":"Required for `custom`."},"discount":{"type":"number","minimum":0,"default":0},"shipping_fee":{"type":"number","minimum":0,"default":0},"vat":{"type":"number","minimum":0,"default":0},"address":{"type":"string"},"notes":{"type":"string"},"id":{"type":"string","format":"uuid","description":"Optional order ID (UUID v4) to use instead of a generated one."},"created_at":{"type":"string","format":"date-time","description":"Optional order date, for importing past orders."}}}}}},"responses":{"201":{"description":"Order and invoice created.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"description":"A required field is missing, or a value is out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/ApiUnauthorized"},"404":{"description":"The bank account was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```