> For the complete documentation index, see [llms.txt](https://docs.eu-pactum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eu-pactum.com/price-lists-api/overview.md).

# Overview

The Price Lists API lets your own systems create, start and track Price Lists negotiations. Use it when negotiation data already lives in your ERP or procurement software and you want to send it to Pactum without uploading files by hand.

You can use the API in two ways:

* **Fully integrated.** Your system creates the negotiation and starts it through the API.
* **Load, then review.** Your system creates the negotiation through the API. A buyer then opens it in Price Lists, checks the pricing strategy and starts it there.

Either way, buyers can follow every negotiation in Price Lists, and your system can read its status and results through the API.

## Hosts

Use the host for the region your Pactum workspace runs in. Pactum tells you which region you are in during onboarding.

| Region | API host                                   |
| ------ | ------------------------------------------ |
| US     | `https://direct-procurement.pactum.com`    |
| EU     | `https://direct-procurement.eu-pactum.com` |

All endpoints below are relative to this host. Always use HTTPS.

## Quickstart

This walk-through creates one negotiation with one supplier and one material, starts it and checks its status.

### 1. Get an access token

Create API client credentials in **Settings → API Clients** (see [Client Credentials](https://docs.eu-pactum.com/price-lists-api/authentication/client-credentials.md)), then exchange them for a token:

```bash
PACTUM_API_BASE_URL="https://direct-procurement.pactum.com"

curl --request POST "$PACTUM_API_BASE_URL/auth/v1/oauth/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET"
```

Send the `access_token` from the response as `Authorization: Bearer <token>` on every other call. If you use an RSA key pair instead, see [RSA key-pair](https://docs.eu-pactum.com/price-lists-api/authentication/rsa-key-pair.md).

### 2. Find your workspace ID

```bash
curl "$PACTUM_API_BASE_URL/price-lists/v1/workspaces" \
  --header "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{
  "data": [
    { "id": "k3Xq9", "name": "Northwind Manufacturing" }
  ]
}
```

The response lists the workspaces your API client can access. Use the `id` as `workspaceId` in every other path.

### 3. Create a negotiation

```bash
curl --request POST "$PACTUM_API_BASE_URL/price-lists/v1/workspaces/$WORKSPACE_ID/negotiations" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data @negotiation.json
```

A minimal `negotiation.json`. Replace `YYYY-MM-DD` with a date 1 to 60 days from today:

```json
{
  "negotiationId": "NW-2026-0042",
  "title": "Annual review - Acme Components",
  "trigger": "ANNUAL_REVIEW",
  "deadline": "YYYY-MM-DD",
  "buyerName": "Jordan Lee",
  "buyerEmail": "jordan.lee@northwind.example",
  "buyerOrganisationName": "Northwind Manufacturing",
  "supplier": {
    "companyName": "Acme Components",
    "representativeEmail": "sales@acme-components.example",
    "units": [
      {
        "externalId": "MAT-1001",
        "name": "Hex bolt M8 x 40",
        "currency": "EUR",
        "priceCurrent": 0.42,
        "unitOfMeasure": "PC",
        "goalPrice": 0.39,
        "acceptanceLimit": 0.41,
        "historicDemand": [{ "year": 2025, "volume": 120000 }]
      }
    ]
  }
}
```

What the API checks when you create a negotiation:

* `negotiationId` is your own ID for the negotiation. It must be unique in the workspace. You can also send an optional `referenceId` to link the negotiation to a record in your system; several negotiations can share one.
* `deadline` must be in the future: at least 1 and at most 60 days from today (`YYYY-MM-DD` or an ISO date-time). A date in the past or further out is rejected.
* `trigger` is one of `MONTHLY_REVIEW`, `QUARTERLY_REVIEW`, `ANNUAL_REVIEW`, `CONTRACT_EXPIRATION`, `CONTRACTUAL_OBLIGATION`, `PROJECT_VOLUME_DEMAND_INCREASE`, `EXPECTED_PRICE_INCREASE`, `PRICE_HARMONIZATION` or `CUSTOM`. `CUSTOM` also needs `customTrigger`.
* Each material (`units` item) needs a unique `externalId`, a 3-letter ISO 4217 `currency`, a positive `priceCurrent` and a `unitOfMeasure`.
* Each material needs at least one `historicDemand` entry (`year`, `volume`, optional `globalVolume`). Years must be unique and not in the future, volumes can't be negative, and either the total `volume` or the total `globalVolume` must be above zero. For `PROJECT_VOLUME_DEMAND_INCREASE`, send at least one `projectVolumeForecast` entry and a `startOfProductionDate` instead.
* Price rules for a material without `expectedIncreasedPrice`: `goalPrice` and `acceptanceLimit` must each be at most `priceCurrent`, and `acceptanceLimit` must be at least `goalPrice`.
* Price rules for a material with `expectedIncreasedPrice`: `priceCurrent` must be below `expectedIncreasedPrice`, `acceptanceLimit` must be below `expectedIncreasedPrice` and at least `goalPrice`. Goal price and acceptance limit may be above `priceCurrent`.
* `expectedIncreasedPrice` is optional, but you can only send it when `trigger` is `EXPECTED_PRICE_INCREASE`.
* `locale` defaults to `en-US`.

A valid request returns `201` with the negotiation, including its numeric `id`. Use that `id` as `negotiationId` in the paths below. Invalid input returns `400` with the reason.

### 4. Wait for preparation

After you create a negotiation, Pactum prepares its pricing strategy. You can't start it until preparation finishes. Poll:

```bash
curl "$PACTUM_API_BASE_URL/price-lists/v1/workspaces/$WORKSPACE_ID/negotiations/$ID/preparation" \
  --header "Authorization: Bearer $ACCESS_TOKEN"
```

It returns `404` until a completed preparation exists, then `200` with the latest completed preparation: anchor offers, strategy and arguments.

### 5. Start the negotiation

```bash
curl --request POST "$PACTUM_API_BASE_URL/price-lists/v1/workspaces/$WORKSPACE_ID/negotiations/$ID/start" \
  --header "Authorization: Bearer $ACCESS_TOKEN"
```

`200` means the negotiation started and Pactum will email the supplier.

Start checks the **latest** preparation of any status, while the preparation endpoint returns the latest **completed** one. So start can still return `400` after the preparation endpoint returned `200`, for example when a newer preparation is still running. Read the message:

* "Negotiation preparation not found" or "Negotiation preparation result is not yet ready": preparation is still running. Wait a few seconds and retry.
* "Negotiation preparation failed": retrying won't help. Contact Pactum with the negotiation `id` and the `Request-Id` of the failed call.

### 6. Track its status

```bash
curl "$PACTUM_API_BASE_URL/price-lists/v1/workspaces/$WORKSPACE_ID/negotiations/$ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN"
```

The `status` field moves through values such as `STARTED`, `LINK_SENT`, `IN_PROGRESS` and finally an outcome such as `AGREEMENT_REACHED`, `DECLINED` or `EXPIRED`. [Negotiation statuses](https://docs.eu-pactum.com/price-lists/reference/negotiation-statuses.md) describes each status you'll see, what it means and what you can do next.

## Endpoints

All paths start with `/price-lists/v1/workspaces/{workspaceId}/negotiations`. The full request and response schemas are in the API reference in this section.

| Method and path                                                             | What it does                                                                                                                                                                                                             |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST /`                                                                    | Create a negotiation.                                                                                                                                                                                                    |
| `GET /`                                                                     | List negotiations. Supports `page` (from 0), `pageSize`, `status`, `search`, `externalId`, `referenceId`, `tags`, date and spend filters, and `sort`. Returns `{ events, total }`.                                       |
| `GET /{id}`                                                                 | Get one negotiation, including its supplier.                                                                                                                                                                             |
| `PUT /{id}`                                                                 | Update buyer, supplier or negotiation details. Materials are managed with the line-item endpoints below.                                                                                                                 |
| `DELETE /{id}`                                                              | Delete a negotiation.                                                                                                                                                                                                    |
| `GET /{id}/preparation`                                                     | Get the latest completed preparation.                                                                                                                                                                                    |
| `POST /{id}/start`                                                          | Start the negotiation.                                                                                                                                                                                                   |
| `POST /{id}/withdraw`                                                       | Withdraw it. Body: `{ "commentForSupplier": "..." }`. The supplier sees your comment.                                                                                                                                    |
| `POST /{id}/restart`                                                        | Restart a negotiation with a new invitation to the supplier. Only for status `WITHDRAWN`, `SUPPLIER_DECLINED_PARTICIPATION`, `UNDELIVERED`, `INCORRECT_CONTACT_DETAILS` or `RESTARTING`; any other status returns `400`. |
| `PUT /{id}/deadline`                                                        | Extend the deadline. Body: `{ "deadlineTime": "<ISO date>" }`, which must be in the future.                                                                                                                              |
| `POST /{id}/update-supplier-contact`                                        | Replace the supplier contact and restart the negotiation. Only for status `UNDELIVERED` or `INCORRECT_CONTACT_DETAILS`, before the deadline, and the new email must differ from the current one. Returns `202`.          |
| `POST /{id}/preview`                                                        | Get a preview link of the supplier chat. Returns `{ "chatLink": "..." }`.                                                                                                                                                |
| `PUT /{id}/tags`                                                            | Replace the negotiation's tags.                                                                                                                                                                                          |
| `GET /tags`                                                                 | List the most used tags with counts.                                                                                                                                                                                     |
| `POST /{id}/attachments`                                                    | Upload one file as multipart form field `files`. Add `visibleToSupplier=true` to show it to the supplier; it is hidden by default. Returns the attachment `id`.                                                          |
| `GET /{id}/attachments/{attachmentId}`                                      | Download an attachment, including files the supplier uploaded.                                                                                                                                                           |
| `DELETE /{id}/attachments/{attachmentId}`                                   | Delete an attachment. Returns `204`.                                                                                                                                                                                     |
| `GET /{id}/download-chat-snapshot`                                          | Download the negotiation chat as a PDF.                                                                                                                                                                                  |
| `POST /export`                                                              | Download negotiations as an Excel file. Body: `{ "negotiationIds": [1, 2] }`.                                                                                                                                            |
| `GET`, `POST /{id}/suppliers/{supplierId}/line-items`                       | List or add materials.                                                                                                                                                                                                   |
| `GET`, `PUT`, `DELETE /{id}/suppliers/{supplierId}/line-items/{lineItemId}` | Read, update or remove one material.                                                                                                                                                                                     |

Attachments can be CSV, PNG, JPG, PDF, XLS, XLSX, DOCX or PPTX files of up to 10 MB.

## Request IDs

Every response carries a `Request-Id` header. Include it when you contact Pactum about a specific call.

## Errors and rate limits

* `400`: the request failed validation. The body explains why.
* `401`: the token is missing or expired. Get a new one.
* `403`: the `workspaceId` is invalid or your API client has no access to it, or the client lacks the permissions the endpoint needs.
* `404`: the negotiation, preparation or attachment doesn't exist in this workspace.
* `429` from the token endpoint: too many token requests. Wait for the number of seconds in the `Retry-After` header, and reuse each token until it expires instead of requesting a new one per call.

## Related

* [Authentication](https://docs.eu-pactum.com/price-lists-api/authentication.md)
* [Negotiation statuses](https://docs.eu-pactum.com/price-lists/reference/negotiation-statuses.md)
* [Price Lists API Demo](https://docs.eu-pactum.com/price-lists-api/price-lists-api-demo.md)
