Commercial Documents

Create a commercial document

Changed on Nov 3, 2026

This endpoint allows you to create a commercial document (proforma, shipping order or purchasing order).

The document number is assigned by Pennylane, based on the numbering configured for this type of document. GET /api/external/v2/numberings lists whether proforma, shipping_order, or purchasing_order is configured.

ℹ️ This endpoint requires the following scope: commercial_documents:all

post/api/external/v2/commercial_documents

Request

Base URL
https://app.pennylane.com
URL
https://app.pennylane.com/api/external/v2/commercial_documents
Auth
OAuth 2
Authorization code: https://app.pennylane.com/oauth/authorize
Token URL: https://app.pennylane.com/oauth/oauth/token scopes: commercial_documents:all

Headers

X-Company-Idstring

Example:12345

Numeric ID of the company to act on. Required when authenticating with a firm token. Ignored when the token is already bound to a company.

Request body

document_type'proforma' | 'shipping_order' | 'purchasing_order' required

datestring date required

Document issue date (ISO 8601)

deadlinestring date required

Document validity deadline (ISO 8601)

customer_idinteger required

Customer identifier

commercial_document_template_idinteger

The commercial document template ID

pdf_invoice_free_textstring nullable

For example, the contact details of the person to contact

pdf_invoice_subjectstring nullable

Document title

pdf_descriptionstring nullable

Document description

currency'EUR' | 'USD' | 'GBP' | 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BYR' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'FJD' | 'FKP' | 'GEL' | 'GGP' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'IMP' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JEP' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SLE' | 'SOS' | 'SRD' | 'STD' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'UYU' | 'UZS' | 'VEF' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XDR' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMK' | 'ZMW' | 'ZWL'

special_mentionstring nullable

Additional details. Maximum 2,000 characters.

language'fr_FR' | 'en_GB' | 'de_DE' | 'es_ES'

The local default is based on the thirdparty (customer / supplier ) billing_language . In case the customer is not present, we will default to the company locale.

external_referencestring

A unique external reference you can provide to track this document. If not provided, Pennylane will generate an identifier for you.

Example request

{
  "date": "2023-08-30",
  "deadline": "2023-09-02",
  "customer_id": 42,
  "commercial_document_template_id": 42,
  "pdf_invoice_free_text": "Additional free field",
  "pdf_invoice_subject": "Document subject",
  "pdf_description": "Document description",
  "special_mention": "Additional details",
  "discount": {
    "value": "25"
  },
  "invoice_line_sections": [
    {
      "title": "Consulting Services",
      "description": "Consulting for August",
      "rank": 1
    }
  ],
  "external_reference": "FR123",
  "invoice_lines": [
    {
      "product_id": 42,
      "quantity": 2,
      "label": "Consulting fees",
      "raw_currency_unit_price": "33.333334",
      "unit": "piece",
      "vat_rate": "FR_200",
      "description": "Consulting services for August",
      "section_rank": 1,
      "discount": {
        "value": "10"
      }
    }
  ]
}

Response

Renders the created commercial document

idinteger required

Commercial document identifier

labelstring nullable required

document_numberstring required

document_type'proforma' | 'shipping_order' | 'purchasing_order' required

amountstring required

Document amount (total value of the document in euros. If the currency is euro, currency_amount and amount are identical)

currency_amountstring required

Document currency amount (total value of the document in the currency of the document)

currency_amount_before_taxstring required

Document currency amount before tax (total value before tax of the document in the currency of the document)

exchange_ratestring required

Document exchange rate (used to convert the document to euros. If the document currency is euro it will be 1.0)

datestring date nullable required

Document issue date (ISO 8601)

deadlinestring date nullable required

Document deadline (ISO 8601)

currency_taxstring required

Document taxable amount (in document currency)

taxstring required

Document taxable amount (in document currency)

language'fr_FR' | 'en_GB' | 'de_DE' | 'es_ES' required

The local default is based on the thirdparty (customer / supplier ) billing_language . In case the customer is not present, we will default to the company locale.

public_file_urlstring nullable required

Public URL of the document file. The URL will expire after 30 minutes.

filenamestring nullable required

Name of the file attached to the document

special_mentionstring nullable required

Additional details

pdf_invoice_free_textstring required

pdf_invoice_subjectstring required

pdf_descriptionstring nullable required

external_referencestring required

The unique external reference that was assigned during creation either by you or Pennylane. (Same attribute as external_id in the API v1)

archived_atstring date-time nullable required

The time the document has been archived

created_atstring date-time required

The time the document has been created

updated_atstring date-time required

The last time the document has been updated

Example response

{
  "id": 42,
  "label": "Commercial document label",
  "document_number": "PLERYGTXYOIMZZ",
  "amount": "230.32",
  "currency_amount": "230.32",
  "currency_amount_before_tax": "196.32",
  "exchange_rate": "1.0",
  "date": "2020-01-01",
  "deadline": "2020-12-31",
  "currency_tax": "34.0",
  "tax": "34.0",
  "discount": {
    "value": "25"
  },
  "public_file_url": "https://app.pennylane.com/.../file.pdf",
  "filename": "my_file.pdf",
  "special_mention": "Additional details",
  "customer": {
    "id": 42,
    "url": "https://app.pennylane.com/api/external/v2/customers/42"
  },
  "invoice_line_sections": {
    "url": "https://app.pennylane.com/api/external/v2/commercial_documents/42/invoice_line_sections"
  },
  "invoice_lines": {
    "url": "https://app.pennylane.com/api/external/v2/commercial_documents/42/invoice_lines"
  },
  "quote": {
    "id": 201,
    "url": "https://app.pennylane.com/api/external/v2/quotes/201"
  },
  "pdf_invoice_free_text": "Document details",
  "pdf_invoice_subject": "Document subject",
  "pdf_description": "Document description",
  "appendices": {
    "url": "https://app.pennylane.com/api/external/v2/commercial_documents/42/appendices"
  },
  "external_reference": "FR123",
  "archived_at": "2023-08-30T10:08:08.146343Z",
  "created_at": "2023-08-30T10:08:08.146343Z",
  "updated_at": "2023-08-30T10:08:08.146343Z"
}

Changes

Nov 3, 2026871f863307e5 Revision changes
- info
  endpoint added

Operation history