Pipedrive settings

Every setting on the Pipedrive order Configuration, covering how deals are placed, linked and filled, and how they follow the order through to won or lost.

With Pipedrive, Supply Lens writes to the CRM: each order (or quote) from your back office, typically Unleashed, becomes a Pipedrive deal. The settings below are on the Pipedrive Order Configuration. Where a setting is marked "also on the quote settings", the same setting exists on the Configuration that creates deals from quotes.

Placing the deal

Setting	What it does	Values / default	When to change it
Pipeline by tag `tagToPipelineIdMap`	Chooses the Pipedrive pipeline from the order's tags. Entries are checked in order and the first matching tag wins, with a default for orders that match none.	Tag map to pipeline ID.	Route different kinds of order (trade, online) to different pipelines.
Stage by tag `tagToStageIdMap`	Chooses the stage within the pipeline from the order's tags, in the same way.	Tag map to stage ID.	Start some deals at a different stage.

Linking the customer

Setting	What it does	Values / default	When to change it
Customer field identifiers `customerFieldIdentifiers`	Maps customer identifier types to Pipedrive person or organisation field names, so the deal is linked to the right customer.	Dictionary of identifier type to field name.	Set it to the field that holds your customer code or account number in Pipedrive.
Use newest matching organisation `useNewestMatchingOrganisation`	When more than one organisation matches the `customerFieldIdentifiers`, uses the newest (highest ID) instead of failing, and logs a warning listing every match. Also on the quote settings.	`true` or `false`. Default `false`: the deal fails, because the matches are duplicates.	Turn on while you clean up duplicate organisations, then merge them in Pipedrive.
Delivery contact person `deliveryContactPerson`	Finds or creates the order's delivery contact as a Pipedrive person and links them to the deal. Orders only: Unleashed's API doesn't expose a quote's delivery contact. See Delivery contact person.	Object. `enabled` is off by default.	Turn on when sales need the delivery contact on the deal.

Delivery contact person

deliveryContactPerson has three fields:

Field	What it does
`enabled`	Turns the feature on. Off by default.
`contactIdField`	Optional. The key of a person custom field holding the source system's contact ID. When set, people are matched on it first, and it's written to every person created or updated.
`contactIdTag`	The Document tag holding the contact ID. Defaults to `unleashed:delivery_contact_guid`, which the Unleashed order import adds.

A person is matched on the contact ID, then on email, then on name within the deal's organisation. The first step that finds exactly one person wins. A contact found nowhere is created. A matched person gets the contact's name, and the contact's email and phone as their primary ones; their other emails and phones, and every other field, are left alone.

Duplicates link nobody

A step that finds more than one person links nobody. The duplicates are logged so you can merge them in Pipedrive. If finding or creating the person fails, that's logged too, and the deal is created without a person.

Filling the deal

Setting	What it does	Values / default	When to change it
Include products on deal `includeProductsOnDeal`	Adds the order's product lines to the deal, so sales can see what was ordered.	`true` or `false`. Not set means only the deal is created.	Turn on if sales need line detail in Pipedrive.
Custom field mapping `customFieldMapping`	Maps Supply Lens Document fields (each identified by a `CustomFieldType`) to Pipedrive deal custom field API keys.	Dictionary of field type to Pipedrive field key.	Use it to write extra order data into deal custom fields.
Custom field date format `customFieldDateFormat`	The format for dates written to custom fields, in .NET format string syntax.	Text, for example `"yyyy-MM-dd"`.	Match the format your Pipedrive fields expect.
Profit margin decimal places `profitMarginDecimalPlaces`	The number of decimal places when writing the profit margin to a custom field.	Number.	Set the precision you want shown.
Record link format `recordUrlFormat`	A link to the record in the source system, where `{0}` is the record's number.	Text.	Set it, with `recordUrlField`, to give sales a link back to the order.
Record link field `recordUrlField`	The key of the deal custom field the link is written to.	A Pipedrive field key.	Set it with `recordUrlFormat`.

Unleashed links take the record's number, not its ID, and start with the account's region, for example https://au.unleashedsoftware.com/v2/SalesOrder/Update/{0} on the order settings, and https://au.unleashedsoftware.com/v2/SalesQuote/Update/{0} on the quote settings.

Following the order: won, completed and lost

Setting	What it does	Values / default	When to change it
Mark quote as won `markQuoteAsWon`	Marks the quote's deal Won when the quote is converted to an order. With `deliveryContactPerson` enabled, the quote's deal is also given the order's delivery contact as its person, replacing any person it had; if no person is found, the deal is only marked Won.	`true` or `false`.	Turn on when you create deals from quotes as well as orders.
Completed order pipeline `completedOrderPipelineId`	The pipeline a deal moves to when its order is completed.	A pipeline ID.	Move fulfilled deals to an after-sales pipeline.
Completed order stage `completedOrderStageId`	The stage set on the deal when its order is completed.	A stage ID.	Move fulfilled deals to a "Delivered" stage, for example.
Completed order status `completedOrderStatus`	The deal status set when its order is completed.	For example `"won"` or `"lost"`.	Close deals automatically on completion.
Mark cancelled as lost `markCancelledAsLost`	Sets the deal to lost when its order is cancelled or deleted in the source system (the order's fulfilment status becomes `Cancelled`). Only the order's own deal is lost; the quote's deal keeps its won status. An order with no deal is logged and skipped. Also on the quote settings.	`true` or `false`.	Turn on so cancelled orders don't sit as open deals.
Lost reason by tag `lostReasonTagMap`	The lost reason set on the deal, from the first matching Document tag, else the default. Also on the quote settings.	Tag map to lost reason text.	Give cancelled and deleted records different reasons.

When at least one of completedOrderPipelineId, completedOrderStageId or completedOrderStatus is set, deals are updated automatically as their orders complete.

The Unleashed import tags a cancelled record unleashed:status:<status>, so a deleted record can be given a different lost reason from a cancelled one:

{
  "default": "Unleashed Sales Quote / Sales Order cancelled",
  "items": [
    { "source": "unleashed", "key": "status", "value": "Deleted", "data": "Unleashed record deleted" }
  ]
}

Fixed lost-reason lists

If the Pipedrive account keeps a fixed list of lost reasons, every reason you send must be one of them. Otherwise Pipedrive refuses the update and the send fails.