---
title: "Create template"
description: "Create a template from one of the app's designs (see GET /templates/designs): the design sets the document type and the starting layout. Optionally name it and make it the default for regular orders. Returns the new temp"
url: https://docs.invoicefalcon.com/v3-reference/templates/create-template/
api: "API v3 reference"
method: POST
path: "/templates"
---

# Create template

`POST https://app.invoicefalcon.com/api/v3/external/templates`

Create a template from one of the app's designs (see [`GET /templates/designs`](https://docs.invoicefalcon.com/v3-reference/templates/list-designs/)): the design sets the document type and the starting layout. Optionally name it and make it the default for regular orders. Returns the new template in full; edit it with [`PATCH /templates/:id`](https://docs.invoicefalcon.com/v3-reference/templates/update-template/).

**Note:** The new template is not used for any order until it is a default or chosen when printing.

## Request body

- `design` (string, required): Design key from GET /templates/designs, e.g. default, classic, modern.
- `name` (string): Template name; defaults to the design name, made unique.
- `set_as_default` (boolean): true to make it the default template for regular orders.

## Returns

The [template object](https://docs.invoicefalcon.com/v3-reference/templates/).

Rate limit: this call costs 2 points ([rate limits](https://docs.invoicefalcon.com/v3/docs/api-v3/rate-limits/)).

## Examples

### Create from a design

```sh
curl -X POST "https://app.invoicefalcon.com/api/v3/external/templates" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "design": "modern"
  }'
```

### Create, name it and make it the default

```sh
curl -X POST "https://app.invoicefalcon.com/api/v3/external/templates" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "design": "classic",
    "name": "Wholesale invoice",
    "set_as_default": true
  }'
```

## 200

The resource, when it already existed.

```json
{
  "id": 156,
  "name": "Main invoice (1)",
  "document_type": "invoice",
  "design": {
    "key": "modern",
    "name": "Modern"
  },
  "default_for": {
    "orders": true,
    "draft_orders": false,
    "pos_orders": false,
    "credit_notes": false
  },
  "logo": {
    "enabled": true,
    "url": null,
    "width": 150,
    "lock_aspect_ratio": true
  },
  "created_at": "2026-11-10T09:07:43Z",
  "updated_at": "2026-11-10T09:07:43Z",
  "style": {
    "accent_color": "#000000",
    "font_family": "Arial",
    "font_size": 12,
    "date_format": "MMM DD, YYYY"
  },
  "numbering": {
    "prefix": "INV",
    "next_number": null,
    "use_order_number": true,
    "credit_notes_use_order_number": false,
    "sequential_numbering_available": true
  },
  "sections": {
    "order_information": {
      "show_invoice_number": true,
      "show_custom_invoice_number": false,
      "show_order_number": true,
      "show_po_number": false,
      "show_delivery_note_number": false,
      "show_order_date": true,
      "show_issue_date": false,
      "show_due_date": false,
      "show_fulfillment_date": false,
      "show_payment_terms": false,
      "show_order_amount": true,
      "show_order_tags": false,
      "show_barcode": false,
      "show_order_barcode": false
    },
    "payment_information": {
      "show_payment_address": true,
      "show_payment_method": true,
      "show_payment_breakdown": false,
      "show_credit_card": true,
      "show_financial_status": false,
      "show_discount_code": false,
      "show_tax_date": false,
      "show_tracking_company": false,
      "show_tracking_numbers": false,
      "show_paid_by_customer": true
    },
    "shipping_information": {
      "show_shipping_address": true
    },
    "customer_information": {
      "show_customer_email": true,
      "show_customer_phone": true,
      "show_customer_note": true,
      "show_localized_tax_id": false,
      "localized_tax_id_string": "Tax ID"
    },
    "items": {
      "show_product_images": true,
      "show_sku": true,
      "show_hs_code": false,
      "show_product_weight": false,
      "show_total_product_weight": false,
      "show_country_of_origin": false,
      "show_product_type": false,
      "show_product_description": false,
      "show_note_attributes": false,
      "show_variants": true,
      "show_selling_plan": false,
      "show_item_discount": false,
      "show_discount_reason": false,
      "show_compare_at_price": false,
      "show_original_price": false,
      "show_properties": true,
      "show_item_barcode": false,
      "show_total_qty": false,
      "show_item_tax": true,
      "show_item_tax_amount": true,
      "group_amount_digits": false
    },
    "order_total": {
      "show_subtotal": true,
      "show_order_discount": true,
      "show_order_discount_reason": false,
      "show_discount_breakdown": false,
      "show_tax": true,
      "show_tax_inclusion_label": false,
      "show_tax_breakdown": true,
      "show_shipping": true,
      "show_discounts": true,
      "show_shipping_rate_name": true,
      "show_amount_in_words": false,
      "show_total_weight": false,
      "show_refund_amount": true,
      "show_refund_reason": false,
      "show_payment_link": false,
      "show_balance": true
    },
    "extra": {
      "show_order_notes": true,
      "show_footer_notes": false,
      "footer_message": null,
      "show_store_domain": false,
      "store_domain_text": null,
      "show_paid_unpaid_watermark": false
    },
    "social": {
      "show_social_page": false,
      "facebook_url": null,
      "instagram_url": null,
      "twitter_url": null
    }
  },
  "label_overrides": {},
  "content_translations": {},
  "liquid_code": "    <!DOCTYPE html>\n    <html>\n    <head>\n      <meta charset=\"utf-8\">\n      <link href=\"https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Open+Sans:wght@400;600;700&family=No…"
}
```

## 201

Created: the new resource.

```json
{
  "id": 156,
  "name": "Main invoice (1)",
  "document_type": "invoice",
  "design": {
    "key": "modern",
    "name": "Modern"
  },
  "default_for": {
    "orders": true,
    "draft_orders": false,
    "pos_orders": false,
    "credit_notes": false
  },
  "logo": {
    "enabled": true,
    "url": null,
    "width": 150,
    "lock_aspect_ratio": true
  },
  "created_at": "2026-11-10T09:07:43Z",
  "updated_at": "2026-11-10T09:07:43Z",
  "style": {
    "accent_color": "#000000",
    "font_family": "Arial",
    "font_size": 12,
    "date_format": "MMM DD, YYYY"
  },
  "numbering": {
    "prefix": "INV",
    "next_number": null,
    "use_order_number": true,
    "credit_notes_use_order_number": false,
    "sequential_numbering_available": true
  },
  "sections": {
    "order_information": {
      "show_invoice_number": true,
      "show_custom_invoice_number": false,
      "show_order_number": true,
      "show_po_number": false,
      "show_delivery_note_number": false,
      "show_order_date": true,
      "show_issue_date": false,
      "show_due_date": false,
      "show_fulfillment_date": false,
      "show_payment_terms": false,
      "show_order_amount": true,
      "show_order_tags": false,
      "show_barcode": false,
      "show_order_barcode": false
    },
    "payment_information": {
      "show_payment_address": true,
      "show_payment_method": true,
      "show_payment_breakdown": false,
      "show_credit_card": true,
      "show_financial_status": false,
      "show_discount_code": false,
      "show_tax_date": false,
      "show_tracking_company": false,
      "show_tracking_numbers": false,
      "show_paid_by_customer": true
    },
    "shipping_information": {
      "show_shipping_address": true
    },
    "customer_information": {
      "show_customer_email": true,
      "show_customer_phone": true,
      "show_customer_note": true,
      "show_localized_tax_id": false,
      "localized_tax_id_string": "Tax ID"
    },
    "items": {
      "show_product_images": true,
      "show_sku": true,
      "show_hs_code": false,
      "show_product_weight": false,
      "show_total_product_weight": false,
      "show_country_of_origin": false,
      "show_product_type": false,
      "show_product_description": false,
      "show_note_attributes": false,
      "show_variants": true,
      "show_selling_plan": false,
      "show_item_discount": false,
      "show_discount_reason": false,
      "show_compare_at_price": false,
      "show_original_price": false,
      "show_properties": true,
      "show_item_barcode": false,
      "show_total_qty": false,
      "show_item_tax": true,
      "show_item_tax_amount": true,
      "group_amount_digits": false
    },
    "order_total": {
      "show_subtotal": true,
      "show_order_discount": true,
      "show_order_discount_reason": false,
      "show_discount_breakdown": false,
      "show_tax": true,
      "show_tax_inclusion_label": false,
      "show_tax_breakdown": true,
      "show_shipping": true,
      "show_discounts": true,
      "show_shipping_rate_name": true,
      "show_amount_in_words": false,
      "show_total_weight": false,
      "show_refund_amount": true,
      "show_refund_reason": false,
      "show_payment_link": false,
      "show_balance": true
    },
    "extra": {
      "show_order_notes": true,
      "show_footer_notes": false,
      "footer_message": null,
      "show_store_domain": false,
      "store_domain_text": null,
      "show_paid_unpaid_watermark": false
    },
    "social": {
      "show_social_page": false,
      "facebook_url": null,
      "instagram_url": null,
      "twitter_url": null
    }
  },
  "label_overrides": {},
  "content_translations": {},
  "liquid_code": "    <!DOCTYPE html>\n    <html>\n    <head>\n      <meta charset=\"utf-8\">\n      <link href=\"https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Open+Sans:wght@400;600;700&family=No…"
}
```

## 401

Missing or unknown `X-Auth-Token`, or the shop uninstalled the app.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "unauthorized"
}
```

## 403

`v3_required`: the shop still runs the previous dashboard. `paid_plan_required`: API access needs a paid plan.

```json
{
  "errors": [
    "API access requires a paid plan"
  ],
  "code": "paid_plan_required"
}
```

## 422

The request failed validation. Nothing was saved.

```json
{
  "errors": [
    "id is missing"
  ]
}
```

## 429

Rate limited: cost-weighted per key (reads cost less than writes). Wait `Retry-After` seconds; see `X-RateLimit-*` headers.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited"
}
```

