***

title: Customize an invoice
subtitle: >-
Configure payment terms, collection methods, metadata, and custom fields on
invoices.
---------

# Collection method

Control how payment is collected on an invoice:

| Method                 | Behavior                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| `charge_automatically` | PaymentKit charges the customer's payment method on file when the invoice is finalized.    |
| `send_invoice`         | The invoice is sent to the customer and they pay manually through the hosted invoice page. |

```bash
curl -X POST https://api.paymentkit.com/api/{account_id}/invoices \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "customer_id": "cus_abc123",
  "currency": "USD",
  "issued_at": "2026-02-01T00:00:00Z",
  "collection_method": "send_invoice",
  "items": [
    {"description": "Consulting - January", "quantity": 1, "amount": 2000.00}
  ]
}'
```

# Payment terms

Set `due_date` to specify when payment is due. For subscription invoices, the `net_d` field on the subscription controls due dates automatically.

```bash
curl -X POST https://api.paymentkit.com/api/{account_id}/invoices \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "customer_id": "cus_abc123",
  "currency": "USD",
  "issued_at": "2026-02-01T00:00:00Z",
  "due_date": "2026-03-01T00:00:00Z",
  "collection_method": "send_invoice",
  "items": [
    {"description": "Consulting - January", "quantity": 1, "amount": 2000.00}
  ]
}'
```

# Custom fields

Attach structured custom data to invoices. Custom field keys must match field definitions configured for the invoice entity type in your account.

## Set custom fields at creation

```bash
curl -X POST https://api.paymentkit.com/api/{account_id}/invoices \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "customer_id": "cus_abc123",
  "currency": "USD",
  "issued_at": "2026-02-01T00:00:00Z",
  "custom_fields": {
    "purchase_order": "PO-2026-0042",
    "department": "Engineering"
  },
  "items": [
    {"description": "Monthly platform fee", "quantity": 1, "amount": 999.00}
  ]
}'
```

## Retrieve custom fields

Include `expand=custom_fields` when fetching an invoice:

```bash
curl -X GET "https://api.paymentkit.com/api/{account_id}/invoices/{invoice_id}?expand=custom_fields" \
-H "Authorization: Bearer sk_live_..."
```

## Delete a custom field value

Set a field key to `null` to remove it:

```json
{
  "custom_fields": {
    "department": null
  }
}
```

# Metadata

Attach free-form key-value data to an invoice using the `metadata` field. Unlike custom fields, metadata does not require predefined field definitions.

```bash
curl -X POST https://api.paymentkit.com/api/{account_id}/invoices \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
  "customer_id": "cus_abc123",
  "currency": "USD",
  "issued_at": "2026-02-01T00:00:00Z",
  "metadata": {
    "internal_ref": "INV-2026-Q1-042",
    "sales_rep": "jsmith"
  },
  "items": [
    {"description": "Quarterly license", "quantity": 1, "amount": 4500.00}
  ]
}'
```

# Invoice documents

PaymentKit automatically generates PDF documents for finalized invoices.

| Document        | Generated when                       |
| --------------- | ------------------------------------ |
| **Invoice PDF** | Invoice is finalized (Draft to Open) |
| **Receipt PDF** | Invoice is fully paid                |

PDF URLs are available on the invoice object via `invoice_pdf_url` and `receipt_pdf_url`.

# Hosted invoice page

Every invoice has a public hosted URL that customers can access without authentication. The hosted invoice URL is included automatically in customer-facing emails sent by PaymentKit.

<Tip>
  PaymentKit automatically includes the hosted invoice URL in customer-facing emails to provide a self-service payment experience.
</Tip>