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

# Create Invoice

> Create a new payment invoice

# Create Invoice

Creates a new payment invoice. The invoice represents a payment request for a specified fiat amount. After creation, the customer selects a token and chain on the checkout page, which triggers address generation on-demand.

## Request

<ParamField body="amount" type="string" required>
  Invoice amount as a decimal string. Must be greater than 0.

  **Example:** `"99.99"`
</ParamField>

<ParamField body="currency" type="string" required>
  The fiat currency of the invoice. Supported: `USD`, `EUR`, `GBP`, etc.

  **Example:** `"USD"`
</ParamField>

<ParamField body="description" type="string">
  Optional human-readable description of the invoice.

  **Example:** `"Order #1234 — 2x T-shirts"`
</ParamField>

<ParamField body="expiresInMinutes" type="number">
  Time in minutes until the invoice expires. If omitted, defaults to 15 minutes. Must be between `1` and `525600` (1 year).

  **Example:** `15`
</ParamField>

<ParamField body="webhookUrl" type="string">
  URL to receive webhook event notifications for this invoice. Must be a valid HTTPS URL. Overrides the default webhook URL set in merchant settings.

  **Example:** `"https://yoursite.com/webhooks/settlx"`
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs to store with the invoice. Useful for correlating with your internal order IDs.

  **Example:** `{ "orderId": "order_abc123", "userId": "user_456" }`
</ParamField>

## Response

<ResponseField name="data" type="object">
  <Expandable title="Invoice object">
    <ResponseField name="id" type="string">UUID of the invoice</ResponseField>
    <ResponseField name="merchantId" type="string">UUID of your merchant account</ResponseField>
    <ResponseField name="amount" type="string">Invoice amount</ResponseField>
    <ResponseField name="currency" type="string">Invoice currency</ResponseField>
    <ResponseField name="status" type="string">Invoice status — always `pending` on creation</ResponseField>
    <ResponseField name="description" type="string | null">Invoice description</ResponseField>
    <ResponseField name="expiresAt" type="string">ISO 8601 expiry timestamp. Always set — defaults to the platform rate window if not specified.</ResponseField>
    <ResponseField name="webhookUrl" type="string | null">Webhook URL for this invoice</ResponseField>
    <ResponseField name="paymentUrl" type="string">Hosted checkout URL. Only needed if you are using our hosted checkout — redirect your customer here. If you are building your own checkout UI, ignore this field.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 creation timestamp</ResponseField>
    <ResponseField name="updatedAt" type="string">ISO 8601 last-updated timestamp</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.settlx.io/api/v1/invoices \
    -H "Authorization: Bearer pk_live_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": "99.99",
      "currency": "USD",
      "description": "Order #1234",
      "expiresInMinutes": 15,
      "webhookUrl": "https://yoursite.com/webhooks/settlx",
      "metadata": {
        "orderId": "order_abc123"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.settlx.io/api/v1/invoices', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer pk_live_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: '99.99',
      currency: 'USD',
      description: 'Order #1234',
      expiresInMinutes: 30,
      webhookUrl: 'https://yoursite.com/webhooks/settlx',
      metadata: { orderId: 'order_abc123' }
    })
  });

  const { data } = await response.json();
  console.log(data.paymentUrl); // Redirect customer here
  ```

  ```python Python theme={null}
  import httpx

  client = httpx.Client(headers={"Authorization": "Bearer pk_live_your_api_key"})

  response = client.post("https://api.settlx.io/api/v1/invoices", json={
      "amount": "99.99",
      "currency": "USD",
      "description": "Order #1234",
      "expiresInMinutes": 15,
      "webhookUrl": "https://yoursite.com/webhooks/settlx",
      "metadata": {"orderId": "order_abc123"}
  })

  invoice = response.json()["data"]
  print(invoice["paymentUrl"])  # Redirect customer here
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "merchantId": "f9e8d7c6-b5a4-3210-9876-543210fedcba",
      "amount": "99.99",
      "currency": "USD",
      "status": "pending",
      "description": "Order #1234",
      "expiresAt": "2024-01-15T10:30:00.000Z",
      "webhookUrl": "https://yoursite.com/webhooks/settlx",
      "paymentUrl": "https://api.settlx.io/checkout/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Bad Request",
    "message": "Amount must be greater than 0"
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "Forbidden",
    "message": "Merchant account is not active"
  }
  ```
</ResponseExample>