Pennylane

https://pennylane.readme.io
Admin
Pennylane is an all-in-one financial and accounting OS for SMEs and accounting firms that automates...
Tokens:207,201
Snippets:2,071
Trust Score:9.9
Update:13 hours ago
Show doc for...
Tokens:
Raw
### Example request with filters[]

Source: https://pennylane.readme.io/docs/filter-my-customers

Example GET request to the /customers endpoint using the filters[] parameter with a start_with filter on the name field.

```curl
GET /customers?filters=[{"field":"name","operator":"start_with","value":"Tes"}]
```

--------------------------------

### Example request (cURL)

Source: https://pennylane.readme.io/docs/filter-my-supplier-invoices

Shows a GET request to /supplier_invoices with a filters[] parameter containing a single filter for supplier_id.

```cURL
GET /supplier_invoices?filters=[{"field":"supplier_id","operator":"eq","value":"sup_123"}]
```

--------------------------------

### List electronic billing addresses response example

Source: https://pennylane.readme.io/changelog/new-endpoints-create-and-update-a-customer-and-list-electronic-billing-addresses

Example response from GET api/external/v2/customers/{customer_id}/electronic_billing_addresses. The endpoint returns all addresses in one response; has_more is always false and next_cursor is always null. The list is empty for an individual customer.

```json
{
  "items": [
    { "electronic_billing_address": "123456789_12345678912345" }
  ],
  "has_more": false,
  "next_cursor": null
}
```

--------------------------------

### Response for GET /api/external/v2/me

Source: https://pennylane.readme.io/changelog/v2-new-user-profile-endpoint

Example JSON response containing user and company details, including id, name, and registration number.

```JSX
{
  "user": {
    "id": 12345,
    "first_name": "John",
    "last_name": "Doe",
    "email": "jdoe@pennylane.com",
    "locale": "fr"
  },
  "company": {
    "id": 123456,
    "name": "Pennylane",
    "reg_no": 123456789
  }
}
```

--------------------------------

### List custom header fields response example

Source: https://pennylane.readme.io/changelog/v2-customer-invoice-custom-header-fields-api

Example response from the GET /api/external/v2/billing_subscriptions endpoint, showing a paginated list of custom header fields with fields like id, title, value, rank, and timestamps.

```JSON
{
  "has_more": true,
  "next_cursor": "dXBkYXRlZF9hdDoxNjc0MTIzNDU2",
  "items": [
    {
      "id": 444,
      "title": "customer_reference",
      "value": "REF-12345",
      "rank": 1,
      "created_at": "2025-06-30T10:08:08.146343Z",
      "updated_at": "2025-06-30T10:08:08.146343Z"
    },
    {
      "id": 555,
      "title": "customer_reference",
      "value": "REF-12345",
      "rank": 2,
      "created_at": "2025-06-30T10:08:08.146343Z",
      "updated_at": "2025-06-30T10:08:08.146343Z"
    }
......................................................
  ]
}
```

--------------------------------

### Example payload for dms_file.created

Source: https://pennylane.readme.io/docs/list-of-events

JSON payload example for the dms_file.created event. Triggered when a DMS file is created. Requires OAuth scopes dms_files:readonly or dms_files:all. previous_attributes is not included because it is a create event.

```JSON
{
  "id": 987656,
  "event": "dms_file.created",
  "retry_count": 0,
  "created": 1704067200,
  "data": {
    "context": {
      "company_id": 12345,
      "firm_id": 678
    },
    "object": {
      "id": 111,
      "created_at": "2024-01-01T00:00:00Z"
    }
  }
}
```

--------------------------------

### cURL: Example Response for Import Supplier Invoice

Source: https://pennylane.readme.io/docs/supplier-invoicing

Example JSON response from the import endpoint. Shows the created invoice with id, status "imported", supplier_name, and currency_amount.

```json
{
  "id": 4431,
  "status": "imported",
  "supplier_name": "ACME Office Supplies",
  "currency_amount": "120.00"
}
```

--------------------------------

### Verify Setup with /me Endpoint

Source: https://pennylane.readme.io/docs/getting-started

Call the /me endpoint to confirm your authentication works and that your environment (sandbox or production) is accessible. Replace <YOUR_API_KEY_OR_OAUTH_TOKEN> with your token.

```Shell
curl https://app.pennylane.com/api/external/v2/me \
  -H "Authorization: Bearer <YOUR_API_KEY_OR_OAUTH_TOKEN>"
```

--------------------------------

### Verify Authentication with cURL

Source: https://pennylane.readme.io/docs/how-to-build-a-pos-integration

Use this GET request to confirm your token and environment are correctly set up before posting sales entries. Expected response is 200 OK.

```cURL
curl https://app.pennylane.com/api/external/v2/me \
-H "Authorization: Bearer <ACCESS_TOKEN>"
```

--------------------------------

### Example response for creating a customer invoice

Source: https://pennylane.readme.io/docs/create-a-customer-invoice-use-case

Shows the response structure for a draft invoice, including id, invoice_number, status, and currency amounts. Note that amounts are strings.

```json
{
  "id": 9876,
  "invoice_number": "INV-2025-001",
  "status": "draft",
  "currency_amount_before_tax": "150.00",
  "currency_tax": "30.00",
  "currency_amount": "180.00",
  "customer": { "id": 123 },
}
```

--------------------------------

### Query payment type ledger accounts (cash and providers)

Source: https://pennylane.readme.io/docs/how-to-build-a-pos-integration

Use these cURL GET requests to find payment type ledger accounts: one for cash (starting with '53') and one for payment providers (starting with '511').

```cURL
# Cash (530…)
curl --request GET \
  --url 'https://app.pennylane.com/api/external/v2/ledger_accounts?filter=[{"field":"number","operator":"start_with","value":"53"}]' \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

# Payment providers (511…)
curl --request GET \
  --url 'https://app.pennylane.com/api/external/v2/ledger_accounts?filter=[{"field":"number","operator":"start_with","value":"511"}]' \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

--------------------------------

### Opt-in using header (Phase 1)

Source: https://pennylane.readme.io/docs/2026-api-changes-guide

Use this curl command to opt in to the new 2026 API behavior by sending the X-Use-2026-API-Changes header with value true. This is recommended for production during the Preview Phase.

```bash
curl -H "X-Use-2026-API-Changes: true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.pennylane.com/api/external/v2/ledger_entries
```

--------------------------------

### GET /api/external/v2/me

Source: https://pennylane.readme.io/docs/customer-invoicing

Verifies that the access token and environment are correctly configured. Returns 200 OK if authentication is successful.

```APIDOC
## GET /api/external/v2/me

### Description
Verifies that the access token and environment are correctly configured. Returns 200 OK if authentication is successful.

### Method
GET

### Endpoint
https://app.pennylane.com/api/external/v2/me

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```
curl https://app.pennylane.com/api/external/v2/me \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

### Response
#### Success Response (200)
- Authentication successful.

```

--------------------------------

### Response from GET ledger accounts for 706000000009

Source: https://pennylane.readme.io/docs/handle-vat-rates-by-ledger-accounts

Example response from the GET ledger accounts endpoint showing multiple ledger account items for the same number, each with a different VAT rate. The item with id 1326475509 and vat_rate 'FR_200' corresponds to a 20% VAT rate.

```json
{  
       "total_pages": 1,  
       "current_page": 1,  
       "per_page": 20,  
       "total_items": 3,  
       "items": [  
           {  
               "id": 1326475509,  
               "number": "706000000009",  
               "label": "Prestations de services",  
               "vat_rate": "FR_200",  
               "country_alpha2": "any",  
               "enabled": true  
           },  
           {  
               "id": 1326475560,  
               "number": "706000000009",  
               "label": "Prestations de services",  
               "vat_rate": "any",  
               "country_alpha2": "any",  
               "enabled": true  
           },  
           {  
               "id": 1326475596,  
               "number": "706000000009",  
               "label": "Prestations de services",  
               "vat_rate": "exempt",  
               "country_alpha2": "any",  
               "enabled": true  
           }  
       ]  
   }
```

--------------------------------

### POST /api/external/v2/products

Source: https://pennylane.readme.io/reference/postproducts-1

Creates a new product. Requires the `products:all` scope. The request body must include label, price_before_tax, and vat_rate.

```APIDOC
## POST /api/external/v2/products

### Description
Creates a new product in Pennylane. Requires the `products:all` scope.

### Method
POST

### Endpoint
https://app.pennylane.com/api/external/v2/products

### Parameters
#### Headers
- **X-Company-Id** (string) - Optional - Company identifier.

#### Request Body
- **label** (string) - Required - Product label.
- **description** (string) - Optional - Product description. Maximum 5,000 characters.
- **external_reference** (string) - Optional - Unique external reference. If not provided, Pennylane will pick one.
- **price_before_tax** (string) - Required - Product price without taxes. Must match pattern `^-?\d+(\.\d+)?$`.
- **vat_rate** (string) - Required - Product VAT rate. Example: FR_200 for 20% VAT in France. See enum values.
- **unit** (string) - Optional - Product unit.
- **currency** (string) - Optional - Defaults to EUR. See enum values.
- **reference** (string) - Optional - Product reference.
- **ledger_account_id** (int64) - Optional - Ledger account identifier.
- **substance** (string) - Optional - Resolves the product's ledger account to goods or services account. Allowed values: `goods`, `services`. When provided with `ledger_account_id`, both must refer to the same account, otherwise returns 422.
- **custom_fields** (array of objects) - Optional - Custom fields.

### Request Example
```json
{
  "label": "Product label",
  "price_before_tax": "100.00",
  "vat_rate": "FR_200"
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created product.
- **label** (string) - The product label.
- **price_before_tax** (string) - The product price before tax.
- **vat_rate** (string) - The VAT rate.
- **currency** (string) - The currency.
- **unit** (string) - The unit.
- **reference** (string) - The product reference.
- **external_reference** (string) - The external reference.
- **description** (string) - The product description.
- **ledger_account_id** (int64) - The ledger account ID.
- **substance** (string) - The substance (goods/services).
- **custom_fields** (array) - Custom fields.

#### Response Example
```json
{
  "id": "12345",
  "label": "Product label",
  "price_before_tax": "100.00",
  "vat_rate": "FR_200",
  "currency": "EUR",
  "unit": "piece",
  "reference": "REF-001",
  "external_reference": "ext-123",
  "description": "A sample product",
  "ledger_account_id": 123,
  "substance": "goods",
  "custom_fields": []
}
```

### Error Handling
- **422** - If `substance` and `ledger_account_id` refer to different accounts.

```

--------------------------------

### Example request to filter draft invoices

Source: https://pennylane.readme.io/docs/filter-my-draft-invoices

This cURL request demonstrates how to use the filters parameter to retrieve draft invoices from the GET /customer_invoices endpoint.

```cURL
GET /customer_invoices?filters=[{"field":"status","operator":"eq","value":"draft"}]
```

--------------------------------

### Opt-in using query parameter (Phase 1)

Source: https://pennylane.readme.io/docs/2026-api-changes-guide

Use this curl command to opt in to the new 2026 API behavior by adding the use_2026_api_changes=true query parameter. This is easier for testing during the Preview Phase.

```bash
curl "https://api.pennylane.com/api/external/v2/ledger_entries?use_2026_api_changes=true" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

--------------------------------

### GET /api/external/v2/fiscal_years

Source: https://pennylane.readme.io/reference/company-fiscal-years

Retrieves a list of fiscal years of the company. Supports pagination with cursor and limit, and sorting by id or start attributes. Requires the fiscal_years:readonly scope.

```APIDOC
## GET /api/external/v2/fiscal_years

### Description
This endpoint returns a list of fiscal years of the company. By default, returns fiscal years ordered by descending IDs. A `sort` query parameter is available allowing to sort by `id` or `start` attributes.

### Method
GET

### Endpoint
https://app.pennylane.com/api/external/v2/fiscal_years

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - Cursor for pagination. Use this to fetch the next set of results. The cursor is an opaque string returned in the previous response's metadata. Leave empty for the first request.
- **limit** (integer) - Optional - Number of items to return per request. Defaults to 20 if not specified. Must be between 1 and 100.
- **sort** (string) - Optional - You can choose to sort items on specific attributes. Sort field may be prefixed with `-` for descending order. Example: `id` will sort by ascending order, `-id` will sort by descending order. Available fields: `id`, `start`.

#### Headers
- **X-Company-Id** (string) - Optional - 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.

### Response
#### Success Response (200)
Returns the list of fiscal years of the company.

#### Error Responses
- **400** - Bad request
- **401** - Access token is missing or invalid
- **403** - Access to this resource forbidden
- **404** - The resource was not found

### Authentication
This endpoint requires the following scope: `fiscal_years:readonly`

```

--------------------------------

### Expected JSON Response from /me

Source: https://pennylane.readme.io/docs/getting-started

Example JSON response returned by the /me endpoint, showing the user's id, email, and role.

```JSON
{
  "id": "12345",
  "email": "[email protected]",
  "role": "customer"
}
```

--------------------------------

### Successful validation response

Source: https://pennylane.readme.io/docs/supplier-invoicing

Example JSON response from the validation GET request, showing an imported invoice with id 4431, amount 120.00, and supplier name 'ACME Office Supplies'.

```JSON
{
  "id": 4431,
  "status": "imported",
  "currency_amount": "120.00",
  "supplier_name": "ACME Office Supplies"
}
```

--------------------------------

### Create a webhook subscription

Source: https://pennylane.readme.io/docs/quickstart

Use this curl command to create a webhook subscription with a callback URL and the `dms_file.created` event. The response includes a `secret` that is returned only once, so store it securely.

```bash
curl -X POST https://app.pennylane.com/api/external/v2/webhook_subscriptions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://example.com/webhooks",
    "events": ["dms_file.created"]
  }'
```

--------------------------------

### Query VAT ledger accounts (start_with 4457)

Source: https://pennylane.readme.io/docs/how-to-build-a-pos-integration

Use this cURL GET request to find VAT ledger accounts whose number starts with '4457'. These accounts usually exist already, so avoid duplicates.

```cURL
curl --request GET \
  --url 'https://app.pennylane.com/api/external/v2/ledger_accounts?filter=[{"field":"number","operator":"start_with","value":"4457"}]' \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

--------------------------------

### Query revenue ledger accounts (start_with 706)

Source: https://pennylane.readme.io/docs/how-to-build-a-pos-integration

Use this cURL GET request to find revenue ledger accounts whose number starts with '706'. The response is not shown, but you would use the returned ledger_account_id for mapping.

```cURL
curl --request GET \
  --url 'https://app.pennylane.com/api/external/v2/ledger_accounts?filter=[{"field":"number","operator":"start_with","value":"706"}]' \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

--------------------------------

### Example response for customer invoice import

Source: https://pennylane.readme.io/docs/customer-invoicing

Shows the JSON response returned after a successful import request. It includes the invoice id, status, currency_amount, and customer_name.

```json
{
  "id": 5678,
  "status": "imported",
  "currency_amount": "120.00",
  "customer_name": "ABC Consulting"
}
```

--------------------------------

### GET ledger accounts filtered by number prefix

Source: https://pennylane.readme.io/docs/create-a-ledger-entry

Use this cURL command to retrieve ledger accounts whose number starts with a given prefix (e.g., 512 for bank accounts). The response includes account IDs, numbers, labels, and enabled status. Always use account IDs (ledger_account_id) rather than numbers, and note that the same account number can exist under multiple IDs with different VAT rates.

```cURL
curl --request GET \
  --url 'https://app.pennylane.com/api/external/v2/ledger_accounts?filter=[{"field":"number","operator":"start_with","value":"512"}]' \
  -H 'Authorization: Bearer <ACCESS_TOKEN
```

```cURL
{
  "items": [
    {
      "id": 98765,
      "number": "512000",
      "label": "Banque",
      "enabled": true
    }
  ]
}
```

--------------------------------

### Example Response for File Upload

Source: https://pennylane.readme.io/docs/supplier-invoicing

Example JSON response from the file upload endpoint. The id field is the file_attachment_id to use in the next step.

```json
{
  "id": 13245,
  "filename": "invoice-october.pdf",
  "status": "uploaded"
}
```

--------------------------------

### Example request with filters[] parameter

Source: https://pennylane.readme.io/docs/filter-my-customer-invoices

Example cURL request showing how to pass the filters[] parameter to the /customer_invoices endpoint. The filter array must be URL-encoded.

```curl
GET /customer_invoices?filters=[{"field":"customer_id","operator":"eq","value":"cust_123"}]
```

--------------------------------

### POST /api/external/v2/customer_invoices

Source: https://pennylane.readme.io/docs/create-a-customer-invoice-use-case

Creates a customer invoice in Pennylane. The minimal example creates a finalized invoice with one line item, while the product/template example can create a draft invoice.

```APIDOC
## POST /api/external/v2/customer_invoices

### Description
Creates a customer invoice in Pennylane. The minimal example creates a finalized invoice with one line item, while the product/template example can create a draft invoice.

### Method
POST

### Endpoint
https://app.pennylane.com/api/external/v2/customer_invoices

### Parameters
#### Request Body
- **customer_id** (integer) - Required - The ID of the customer.
- **date** (string) - Required - The invoice date in YYYY-MM-DD format.
- **deadline** (string) - Required - The payment deadline in YYYY-MM-DD format.
- **invoice_lines** (array) - Required - Array of invoice line items.
  - **label** (string) - Optional - Description of the line item (used in minimal example).
  - **product_id** (integer) - Optional - ID of the product to use (used in product/template example).
  - **quantity** (number) - Required - Quantity of the item.
  - **unit** (string) - Required - Unit of measure (e.g., "hour", "piece").
  - **raw_currency_unit_price** (string) - Required - Unit price as a string (e.g., "100.00").
  - **vat_rate** (string) - Required - VAT rate code (e.g., "FR_200").
- **external_reference** (string) - Optional - External reference for the invoice (e.g., "INV-ACME-2025-001").
- **customer_invoice_template_id** (integer) - Optional - ID of the invoice template to use.
- **draft** (boolean) - Optional - Set to true to create a draft invoice; omit or set false to finalize immediately.

### Request Example
{
  "customer_id": 123,
  "date": "2025-10-01",
  "deadline": "2025-10-31",
  "invoice_lines": [
    {
      "label": "Consulting services",
      "quantity": 2,
      "unit": "hour",
      "raw_currency_unit_price": "100.00",
      "vat_rate": "FR_200"
    }
  ],
  "external_reference": "INV-ACME-2025-001"
}

### Response
#### Response Example
{
  "id": 9876,
  "invoice_number": "INV-2025-001",
  "status": "draft",
  "currency_amount_before_tax": "150.00",
  "currency_tax": "30.00",
  "currency_amount": "180.00",
  "customer": { "id": 123 }
}
```
Tokens:
Raw