# Zip

> Work with Zip procurement: find and update requests, reject or cancel them, follow approvals, manage vendors, read purchase orders, invoices and contracts, and post comments.

App · 24 actions. Web page: https://docs.lodol.com/docs/integrations/zip-hq

## Actions

### Create or update vendor

Create a vendor in Zip under your own vendor ID, or update the vendor that already has it.

**Inputs**

- Your vendor ID (`external_id`, text, required): Your own id for the vendor, such as its number in your ERP. A vendor with this id is updated; otherwise a new vendor is made.
- Name (`name`, text, required): The vendor's name as people in Zip will see it.
- Legal name (`legal_name`, text): The vendor's registered company name.
- Status (`status`, text): Active, Preferred, Inactive or Draft. A new vendor starts as Draft. One of: `1` (Active), `2` (Preferred), `3` (Inactive), `5` (Draft).
- Currency (`currency`, text): The vendor's main currency, a three-letter code such as USD.
- Purchase order email (`po_email`, text): Where purchase orders for this vendor are sent.
- Remittance email (`remittance_email`, text): Where payment notices for this vendor are sent.
- Phone (`primary_phone`, text): The vendor's main phone number.
- Tax ID (`tax_id_number`, text): The vendor's tax identification number.
- Risk (`risk`, text): The vendor's risk rating. One of: `green` (Green (low)), `yellow` (Yellow (medium)), `red` (Red (high)).
- Tier (`tier`, text): The vendor's tier. One of: `tier_1` (Tier 1), `tier_2` (Tier 2), `tier_3` (Tier 3), `tier_4` (Tier 4).
- Entities (`subsidiary_ids`, list): The entities (subsidiaries) that may buy from this vendor.

**Outputs**

- `vendor` (object): The vendor

**Example output**

```json
{
  "vendor": {
    "address": {
      "country": "US",
      "lines": [
        "123 Main St"
      ],
      "locality": "San Francisco",
      "postcode": "94105",
      "region": "US-CA"
    },
    "attributes": [],
    "categories": [
      {
        "id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
        "name": "Software"
      }
    ],
    "contacts": [],
    "created_at": 1791000000,
    "currency": "USD",
    "department": {
      "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
      "name": "Engineering"
    },
    "description": "Office and design supplies.",
    "external_id": "V-10042",
    "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
    "legal_name": "Acme Supplies LLC",
    "name": "Acme Supplies",
    "po_email": "orders@example.com",
    "primary_phone": "+1 415 555 0100",
    "remittance_email": "billing@example.com",
    "risk": "green",
    "status": 1,
    "subsidiaries": [
      {
        "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
        "name": "Acme Inc."
      }
    ],
    "tier": "tier_2",
    "updated_at": 1792086400,
    "website_link": "https://example.com"
  }
}
```

### Delete comment

Delete a comment, as the Zip user who deletes it.

**Inputs**

- Comment ID (`comment_id`, text, required): The comment's id, from 'List comments' or 'Post comment'.
- Deleted by (`deleted_by_id`, text, required): The Zip user deleting it, usually whoever posted it.

**Outputs**

- `comment_id` (text): The comment deleted
- `deleted` (true/false): True once deleted

**Example output**

```json
{
  "comment_id": "0a1b2c3d-4e5f-4061-8728-394a5b6c7d8e",
  "deleted": true
}
```

### Delete vendor

Delete a vendor from Zip for good. Unlike setting it to Inactive, this cannot be undone.

**Inputs**

- Vendor (`vendor_id`, text, required): The vendor. Pick one, or give its id from an earlier step.

**Outputs**

- `deleted` (true/false): True once deleted
- `vendor_id` (text): The vendor deleted

**Example output**

```json
{
  "deleted": true,
  "vendor_id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c"
}
```

### Get invoice

Get one invoice with its lines, approvals, matched purchase orders and payments.

**Inputs**

- Invoice ID (`invoice_id`, text, required): The invoice's id (not the supplier's invoice number), from 'List invoices' or an earlier step.

**Outputs**

- `invoice` (object): The invoice

**Example output**

```json
{
  "invoice": {
    "amount": "12000.00",
    "amount_usd": "12000.00",
    "approvals": [],
    "approved_at": 0,
    "assignee": {
      "email": "jo@example.com",
      "first_name": "Jo",
      "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
      "last_name": "Bloggs"
    },
    "created_at": 1794528000,
    "currency": "USD",
    "department": {
      "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
      "name": "Engineering"
    },
    "description": "Design tool licences, year one",
    "due_date": 1797120000,
    "due_date_iso": "2026-12-31",
    "id": "9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
    "invoice_date": "2026-12-01",
    "invoice_number": "INV-7781",
    "invoice_url": "https://acme.ziphq.com/invoices/9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
    "line_items": [],
    "purchase_orders": [
      {
        "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
        "po_number": "PO-1042"
      }
    ],
    "status": "PENDING_APPROVAL",
    "subsidiary": {
      "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
      "name": "Acme Inc."
    },
    "updated_at": 1794614400,
    "vendor": {
      "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
      "name": "Acme Supplies"
    }
  }
}
```

### Get purchase order

Get one purchase order with its lines, invoices, change orders and the request it came from.

**Inputs**

- Purchase order ID (`purchase_order_id`, text, required): The purchase order's id (not its PO number), from 'List purchase orders' or an earlier step.

**Outputs**

- `purchase_order` (object): The purchase order

**Example output**

```json
{
  "purchase_order": {
    "amount_billed": "0.00",
    "created_at": 1792090000,
    "currency": "USD",
    "department": {
      "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
      "name": "Engineering"
    },
    "description": "Design tool licences",
    "end_date": "2027-11-30",
    "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
    "invoices": [],
    "last_activity_at": 1792090000,
    "line_items": [],
    "original_request": {
      "id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
      "name": "Design tool licences",
      "request_number": 1042
    },
    "payment_frequency": "ANNUAL",
    "payment_method": "PURCHASE_ORDER",
    "po_number": "PO-1042",
    "requester": {
      "email": "jo@example.com",
      "first_name": "Jo",
      "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
      "last_name": "Bloggs"
    },
    "start_date": "2026-12-01",
    "status": 0,
    "subsidiary": {
      "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
      "name": "Acme Inc."
    },
    "total_amount": "12000.00",
    "total_amount_usd": "12000.00",
    "updated_at": 1792090000,
    "vendor": {
      "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
      "name": "Acme Supplies"
    }
  }
}
```

### Get request

Get one request with its amount, line items, vendor, requester, custom fields, purchase order and attachments.

**Inputs**

- Request ID (`request_id`, text, required): The request's id (not its number), from 'List requests' or an earlier step.

**Outputs**

- `request` (object): The request

**Example output**

```json
{
  "request": {
    "amount_usd": "12000.00",
    "attachments": [
      {
        "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e",
        "name": "quote.pdf",
        "url": "https://acme.ziphq.com/files/quote.pdf"
      }
    ],
    "attributes": [
      {
        "config_id": "63d42e86-147b-4fd7-baa3-d52d7e27494d",
        "data": [
          "CC-100"
        ],
        "name": "Cost center"
      }
    ],
    "category": {
      "id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
      "name": "Software"
    },
    "completed_at": 0,
    "created_at": 1792000000,
    "department": {
      "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
      "name": "Engineering"
    },
    "description": "Ten seats for the design team.",
    "id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
    "name": "Design tool licences",
    "owner": {
      "email": "jo@example.com",
      "first_name": "Jo",
      "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
      "last_name": "Bloggs"
    },
    "payment_method": "PURCHASE_ORDER",
    "price_detail": {
      "currency": "USD",
      "id": "3c4d5e6f-7081-4923-ab4c-5d6e7f809102",
      "line_items": [],
      "total": "12000.00",
      "total_usd": "12000.00"
    },
    "priority": 1,
    "purchase_order": {
      "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "po_number": "PO-1042"
    },
    "request_link": "https://acme.ziphq.com/request/1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
    "request_number": 1042,
    "request_type": "PURCHASE_REQUEST",
    "requester": {
      "email": "jo@example.com",
      "first_name": "Jo",
      "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
      "last_name": "Bloggs"
    },
    "status": 1,
    "subsidiary": {
      "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
      "name": "Acme Inc."
    },
    "updated_at": 1792086400,
    "vendor": {
      "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
      "name": "Acme Supplies"
    },
    "workflow": {
      "id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
      "name": "Software"
    }
  }
}
```

### Get request questionnaires

Get the questionnaires on a request, such as a security review, with each answer given.

**Inputs**

- Request ID (`request_id`, text, required): The request's id (not its number), from 'List requests' or an earlier step.

**Outputs**

- `count` (number): How many
- `questionnaires` (list): The questionnaires
- `total` (number): How many in all

**Example output**

```json
{
  "count": 1,
  "questionnaires": [
    {
      "id": "1b2c3d4e-5f60-4172-8839-4a5b6c7d8e9f",
      "name": "Security questionnaire",
      "question_responses": [
        {
          "question_prompt": "Do you hold SOC 2?",
          "text": "Yes"
        }
      ],
      "status": "COMPLETED",
      "vendor": {
        "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
        "name": "Acme Supplies"
      }
    }
  ],
  "total": 1
}
```

### Get user

Get one Zip user with their department, entity, manager, roles and permission groups.

**Inputs**

- User (`zip_user_id`, text, required): The Zip user. Pick one, or give their id from an earlier step.

**Outputs**

- `user` (object): The user

**Example output**

```json
{
  "user": {
    "department": {
      "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
      "name": "Engineering"
    },
    "email": "jo@example.com",
    "first_name": "Jo",
    "groups": [
      {
        "id": "9b4a5f6e-7d8c-4b92-8ca3-c4d5e6f7a8b0",
        "name": "Default"
      }
    ],
    "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
    "is_active": true,
    "last_name": "Bloggs",
    "manager": {
      "email": "sam@example.com",
      "first_name": "Sam",
      "id": "7f2e3d4c-5b6a-4f70-9a81-a2b3c4d5e6f8",
      "last_name": "Lee"
    },
    "roles": [
      {
        "id": "8a3f4e5d-6c7b-4a81-9b92-b3c4d5e6f7a9",
        "name": "Manager"
      }
    ],
    "subsidiary": {
      "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
      "name": "Acme Inc."
    }
  }
}
```

### Get vendor

Get one vendor with its status, contacts, entities, categories and custom fields.

**Inputs**

- Vendor (`vendor_id`, text, required): The vendor. Pick one, or give its id from an earlier step.

**Outputs**

- `vendor` (object): The vendor

**Example output**

```json
{
  "vendor": {
    "address": {
      "country": "US",
      "lines": [
        "123 Main St"
      ],
      "locality": "San Francisco",
      "postcode": "94105",
      "region": "US-CA"
    },
    "attributes": [],
    "categories": [
      {
        "id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
        "name": "Software"
      }
    ],
    "contacts": [],
    "created_at": 1791000000,
    "currency": "USD",
    "department": {
      "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
      "name": "Engineering"
    },
    "description": "Office and design supplies.",
    "external_id": "V-10042",
    "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
    "legal_name": "Acme Supplies LLC",
    "name": "Acme Supplies",
    "po_email": "orders@example.com",
    "primary_phone": "+1 415 555 0100",
    "remittance_email": "billing@example.com",
    "risk": "green",
    "status": 1,
    "subsidiaries": [
      {
        "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
        "name": "Acme Inc."
      }
    ],
    "tier": "tier_2",
    "updated_at": 1792086400,
    "website_link": "https://example.com"
  }
}
```

### List approvals

Find approval steps on requests by request, status, type or date, with who each waits on and when it is due.

**Inputs**

- Request number (`request_number`, number): Only the approvals on this request, by the number Zip shows. At least 1.
- Status (`status`, text): Only approvals in this status. One of: `0` (Upcoming), `1` (Ready to start (waiting on the approver)), `2` (Rejected), `3` (Approved), `4` (Approved automatically), `5` (Canceled), `6` (Custom status, timer on), `7` (Custom status, timer off).
- Request types (`request_types`, list): Only approvals on requests of these types. One or more of: `PURCHASE_REQUEST` (Purchase request), `SOURCING_PROJECT` (Sourcing project), `SOURCING_INSTANCE` (Sourcing event), `SOURCING_REQUEST` (Sourcing request), `BILL`, `PAYOUT_GROUP` (Payout group), `INVOICE_ASSIGNMENT` (Invoice assignment), `PO_CHANGE_ORDER` (PO change order), `CHANGE_ORDER` (Change order), `SECURITY_REVIEW` (Security review), and 7 more.
- Started after (`started_after`, date and time): Only approvals that started after this time.
- Completed after (`completed_after`, date and time): Only approvals completed after this time.
- Due after (`due_after`, date and time): Only approvals due after this time.
- Due before (`due_before`, date and time): Only approvals due before this time, such as now for overdue ones.
- Sort by (`sort_by`, text): What to sort by. Leave empty for Zip's order. One of: `start_time` (When started), `complete_time` (When completed), `due_date` (Due date), `request_create_time` (When the request was created), `request_number` (Request number).
- Order (`sort_order`, text): Sort direction, when sorting. Defaults to newest or highest first. One of: `desc` (Newest or highest first (default)), `asc` (Oldest or lowest first).
- Page size (`page_size`, number): How many to return, 1 to 100. From 1 to 100.
- Next page token (`page_token`, text): The 'next_page_token' from an earlier page, to get the page after it.

**Outputs**

- `approvals` (list): The approval steps
- `count` (number): How many on this page
- `next_page_token` (text): Pass as 'Next page token' for the next page; empty on the last
- `total` (number): How many match in all

**Example output**

```json
{
  "approvals": [
    {
      "assignee": {
        "email": "jo@example.com",
        "first_name": "Jo",
        "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
        "last_name": "Bloggs"
      },
      "complete_time": 0,
      "config_type": "APPROVAL",
      "created_at": 1792000000,
      "display_status": "Ready to start",
      "due_date": 1792259800,
      "id": "4d5e6f70-8192-4a3b-bc4d-5e6f708192a3",
      "name": "Finance approval",
      "node_type": "NODE",
      "queue": {
        "id": "5e6f7081-92a3-4b4c-8d5e-6f708192a3b4",
        "name": "Finance"
      },
      "request": {
        "id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
        "name": "Design tool licences",
        "request_number": 1042,
        "request_type": "PURCHASE_REQUEST",
        "status": "AWAITING_APPROVAL"
      },
      "sla_hours": 72,
      "start_time": 1792000600,
      "status": 1,
      "updated_at": 1792000600
    }
  ],
  "count": 1,
  "next_page_token": "",
  "total": 1
}
```

### List comments

List the comments on a request, with who wrote each and when.

**Inputs**

- Request ID (`request_id`, text, required): The request's id (not its number), from 'List requests' or an earlier step.

**Outputs**

- `comments` (list): The comments
- `count` (number): How many
- `total` (number): How many in all

**Example output**

```json
{
  "comments": [
    {
      "commenter": {
        "email": "jo@example.com",
        "first_name": "Jo",
        "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
        "last_name": "Bloggs"
      },
      "created_at": 1792090000,
      "deleted": false,
      "external_display_name": "Lodol",
      "external_url": "",
      "id": "0a1b2c3d-4e5f-4061-8728-394a5b6c7d8e",
      "text": "Quote attached; please review.",
      "text_html": "<p>Quote attached; please review.</p>",
      "type": "COMMENT",
      "updated_at": 1792090000
    }
  ],
  "count": 1,
  "total": 1
}
```

### List contracts

Find contracts (Zip's agreements) by vendor, department or entity, with their dates, amounts and renewal status.

**Inputs**

- Vendor (`vendor_id`, text): Only contracts with this vendor.
- Department (`department_id`, text): Only contracts of this department.
- Entity (`subsidiary_id`, text): Only contracts of this entity.
- Sort by (`sort_by`, text): What to sort by. Leave empty for Zip's order. One of: `created_at` (When created (default)), `updated_at` (When last updated).
- Order (`sort_order`, text): Sort direction, when sorting. Defaults to newest or highest first. One of: `desc` (Newest or highest first (default)), `asc` (Oldest or lowest first).
- Page size (`page_size`, number): How many to return, 1 to 100. From 1 to 100.
- Next page token (`page_token`, text): The 'next_page_token' from an earlier page, to get the page after it.

**Outputs**

- `contracts` (list): The contracts
- `count` (number): How many on this page
- `next_page_token` (text): Pass as 'Next page token' for the next page; empty on the last
- `total` (number): How many match in all

**Example output**

```json
{
  "contracts": [
    {
      "agreement_number": 311,
      "agreement_owner": {
        "email": "jo@example.com",
        "first_name": "Jo",
        "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
        "last_name": "Bloggs"
      },
      "agreement_status": "ACTIVE",
      "agreement_type": "MSA",
      "amount": "12000.00",
      "auto_renews": true,
      "currency": "USD",
      "department": {
        "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
        "name": "Engineering"
      },
      "end_date": "2027-11-30",
      "name": "Acme Supplies master agreement",
      "original_request": {
        "id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
        "name": "Design tool licences",
        "request_number": 1042
      },
      "renewal_date": "2027-11-30",
      "renewal_status": "NOT_SCHEDULED",
      "start_date": "2026-12-01",
      "status": "ACTIVE",
      "vendor": {
        "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
        "name": "Acme Supplies"
      }
    }
  ],
  "count": 1,
  "next_page_token": "",
  "total": 1
}
```

### List departments

List the departments set up in Zip.

**Inputs**

- Name (`name`, text): Only the department with this name.
- Active (`active`, true/false): On for active departments only, off for inactive ones only. Leave empty for both.
- Page size (`page_size`, number): How many to return, 1 to 100. From 1 to 100.
- Next page token (`page_token`, text): The 'next_page_token' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `departments` (list): The departments
- `next_page_token` (text): Pass as 'Next page token' for the next page; empty on the last
- `total` (number): How many match in all

**Example output**

```json
{
  "count": 1,
  "departments": [
    {
      "created_at": 1780000000,
      "display_name": "Engineering",
      "hide_in_zip": false,
      "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
      "is_active": true,
      "name": "Engineering",
      "updated_at": 1780000000
    }
  ],
  "next_page_token": "",
  "total": 1
}
```

### List invoices

Find supplier invoices (bills) by number, status, vendor, date or amount.

**Inputs**

- Invoice number (`invoice_number`, text): Only invoices with this number, as the supplier wrote it.
- Statuses (`statuses`, list): Only invoices in any of these statuses. One or more of: `INITIAL` (New (not yet sent for approval)), `PENDING_APPROVAL` (Pending approval), `APPROVED`, `REJECTED`, `ARCHIVED`, `PENDING_PAYOUT_APPROVAL` (Pending payment approval), `PAYOUT_SCHEDULED` (Payment scheduled), `PAYOUT_INITIATED` (Payment started), `PAID`, `PAYOUT_FAILED` (Payment failed), `PAYOUT_CANCELED` (Payment canceled), `RECEIPT_HOLD` (On hold for receipt).
- Vendor (`vendor_id`, text): Only invoices from this vendor.
- Created after (`created_after`, date and time): Only invoices created after this time.
- Updated after (`updated_after`, date and time): Only invoices changed after this time.
- Approved after (`approved_after`, date and time): Only invoices approved after this time.
- Smallest amount (`amount_min`, number): Only invoices of at least this amount. At least 0.
- Largest amount (`amount_max`, number): Only invoices of at most this amount. At least 0.
- Sort by (`sort_by`, text): What to sort by. Leave empty for Zip's order. One of: `created_at` (When created (default)), `updated_at` (When last updated).
- Order (`sort_order`, text): Sort direction, when sorting. Defaults to newest or highest first. One of: `desc` (Newest or highest first (default)), `asc` (Oldest or lowest first).
- Page size (`page_size`, number): How many to return, 1 to 50. From 1 to 50.
- Next page token (`page_token`, text): The 'next_page_token' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `invoices` (list): The invoices
- `next_page_token` (text): Pass as 'Next page token' for the next page; empty on the last
- `total` (number): How many match in all

**Example output**

```json
{
  "count": 1,
  "invoices": [
    {
      "amount": "12000.00",
      "amount_usd": "12000.00",
      "approvals": [],
      "approved_at": 0,
      "assignee": {
        "email": "jo@example.com",
        "first_name": "Jo",
        "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
        "last_name": "Bloggs"
      },
      "created_at": 1794528000,
      "currency": "USD",
      "department": {
        "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
        "name": "Engineering"
      },
      "description": "Design tool licences, year one",
      "due_date": 1797120000,
      "due_date_iso": "2026-12-31",
      "id": "9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
      "invoice_date": "2026-12-01",
      "invoice_number": "INV-7781",
      "invoice_url": "https://acme.ziphq.com/invoices/9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
      "line_items": [],
      "purchase_orders": [
        {
          "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
          "po_number": "PO-1042"
        }
      ],
      "status": "PENDING_APPROVAL",
      "subsidiary": {
        "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
        "name": "Acme Inc."
      },
      "updated_at": 1794614400,
      "vendor": {
        "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
        "name": "Acme Supplies"
      }
    }
  ],
  "next_page_token": "",
  "total": 1
}
```

### List purchase orders

Find purchase orders by vendor, date or amount still open, with what has been billed against each.

**Inputs**

- Vendor (`vendor_id`, text): Only purchase orders with this vendor.
- PO number (`po_number`, text): Only the purchase order with this number. Works only if Zip has turned on extra purchase order search for your company.
- Created after (`created_after`, date and time): Only purchase orders created after this time.
- Created before (`created_before`, date and time): Only purchase orders created before this time.
- Updated after (`updated_after`, date and time): Only purchase orders with activity after this time.
- Open amount over (`open_amount_greater_than`, number): Only purchase orders with more than this amount not yet billed. At least 0.
- Include custom fields (`include_custom_fields`, true/false): Also return each record's custom fields. Zip answers more slowly.
- Sort by (`sort_by`, text): What to sort by. Leave empty for Zip's order. One of: `created_at` (When created (default)), `updated_at` (When last updated).
- Order (`sort_order`, text): Sort direction, when sorting. Defaults to newest or highest first. One of: `desc` (Newest or highest first (default)), `asc` (Oldest or lowest first).
- Page size (`page_size`, number): How many to return, 1 to 50. From 1 to 50.
- Next page token (`page_token`, text): The 'next_page_token' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `next_page_token` (text): Pass as 'Next page token' for the next page; empty on the last
- `purchase_orders` (list): The purchase orders
- `total` (number): How many match in all

**Example output**

```json
{
  "count": 1,
  "next_page_token": "",
  "purchase_orders": [
    {
      "amount_billed": "0.00",
      "created_at": 1792090000,
      "currency": "USD",
      "department": {
        "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
        "name": "Engineering"
      },
      "description": "Design tool licences",
      "end_date": "2027-11-30",
      "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "invoices": [],
      "last_activity_at": 1792090000,
      "line_items": [],
      "original_request": {
        "id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
        "name": "Design tool licences",
        "request_number": 1042
      },
      "payment_frequency": "ANNUAL",
      "payment_method": "PURCHASE_ORDER",
      "po_number": "PO-1042",
      "requester": {
        "email": "jo@example.com",
        "first_name": "Jo",
        "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
        "last_name": "Bloggs"
      },
      "start_date": "2026-12-01",
      "status": 0,
      "subsidiary": {
        "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
        "name": "Acme Inc."
      },
      "total_amount": "12000.00",
      "total_amount_usd": "12000.00",
      "updated_at": 1792090000,
      "vendor": {
        "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
        "name": "Acme Supplies"
      }
    }
  ],
  "total": 1
}
```

### List requests

Find purchase and other requests by number, status, type, requester, department, vendor or date, newest first.

**Inputs**

- Request number (`request_number`, number): The request number Zip shows, such as 1042. At least 1.
- Status (`status`, text): Only requests in this status. One of: `1` (Awaiting approval), `2` (Rejected), `3` (Approved), `4` (Canceled), `5` (Closed), `6` (Paused).
- Priority (`priority`, text): Only urgent or only normal requests. One of: `0` (Urgent), `1` (Normal).
- Request type (`request_type`, text): Only requests of this type. One of: `PURCHASE_REQUEST` (Purchase request), `SOURCING_PROJECT` (Sourcing project), `SOURCING_INSTANCE` (Sourcing event), `SOURCING_REQUEST` (Sourcing request), `BILL`, `PAYOUT_GROUP` (Payout group), `INVOICE_ASSIGNMENT` (Invoice assignment), `PO_CHANGE_ORDER` (PO change order), `CHANGE_ORDER` (Change order), `SECURITY_REVIEW` (Security review), and 7 more.
- Requester (`requester_id`, text): Only requests made by this person.
- Departments (`department_ids`, list): Only requests for any of these departments.
- Vendor (`vendor_id`, text): Only requests for this vendor.
- Created after (`created_after`, date and time): Only requests created after this time.
- Created before (`created_before`, date and time): Only requests created before this time.
- Updated after (`updated_after`, date and time): Only requests changed after this time.
- Completed after (`completed_after`, date and time): Only requests completed after this time.
- Include custom fields (`include_custom_fields`, true/false): Also return each record's custom fields. Zip answers more slowly.
- Sort by (`sort_by`, text): What to sort by. Leave empty for Zip's order. One of: `create_time` (When created), `last_updated_time` (When last updated), `complete_time` (When completed), `request_number` (Request number), `status`.
- Order (`sort_order`, text): Sort direction, when sorting. Defaults to newest or highest first. One of: `desc` (Newest or highest first (default)), `asc` (Oldest or lowest first).
- Page size (`page_size`, number): How many to return, 1 to 30. From 1 to 30.
- Next page token (`page_token`, text): The 'next_page_token' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `next_page_token` (text): Pass as 'Next page token' for the next page; empty on the last
- `requests` (list): The requests
- `total` (number): How many match in all

**Example output**

```json
{
  "count": 1,
  "next_page_token": "",
  "requests": [
    {
      "amount_usd": "12000.00",
      "attachments": [
        {
          "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e",
          "name": "quote.pdf",
          "url": "https://acme.ziphq.com/files/quote.pdf"
        }
      ],
      "attributes": [
        {
          "config_id": "63d42e86-147b-4fd7-baa3-d52d7e27494d",
          "data": [
            "CC-100"
          ],
          "name": "Cost center"
        }
      ],
      "category": {
        "id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
        "name": "Software"
      },
      "completed_at": 0,
      "created_at": 1792000000,
      "department": {
        "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
        "name": "Engineering"
      },
      "description": "Ten seats for the design team.",
      "id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
      "name": "Design tool licences",
      "owner": {
        "email": "jo@example.com",
        "first_name": "Jo",
        "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
        "last_name": "Bloggs"
      },
      "payment_method": "PURCHASE_ORDER",
      "price_detail": {
        "currency": "USD",
        "id": "3c4d5e6f-7081-4923-ab4c-5d6e7f809102",
        "line_items": [],
        "total": "12000.00",
        "total_usd": "12000.00"
      },
      "priority": 1,
      "purchase_order": {
        "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
        "po_number": "PO-1042"
      },
      "request_link": "https://acme.ziphq.com/request/1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
      "request_number": 1042,
      "request_type": "PURCHASE_REQUEST",
      "requester": {
        "email": "jo@example.com",
        "first_name": "Jo",
        "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
        "last_name": "Bloggs"
      },
      "status": 1,
      "subsidiary": {
        "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
        "name": "Acme Inc."
      },
      "updated_at": 1792086400,
      "vendor": {
        "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
        "name": "Acme Supplies"
      },
      "workflow": {
        "id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
        "name": "Software"
      }
    }
  ],
  "total": 1
}
```

### List users

Find Zip users by email, with their department, manager, roles and permission groups.

**Inputs**

- Email (`email`, text): Only the user with this email address.
- Deactivated (`deactivated`, true/false): On for deactivated users only, off for active users only.
- Sort by (`sort_by`, text): What to sort by. Leave empty for Zip's order. One of: `created_at` (When created (default)), `updated_at` (When last updated), `email`.
- Order (`sort_order`, text): Sort direction, when sorting. Defaults to newest or highest first. One of: `desc` (Newest or highest first (default)), `asc` (Oldest or lowest first).
- Page size (`page_size`, number): How many to return, 1 to 100. From 1 to 100.
- Next page token (`page_token`, text): The 'next_page_token' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `next_page_token` (text): Pass as 'Next page token' for the next page; empty on the last
- `total` (number): How many match in all
- `users` (list): The users

**Example output**

```json
{
  "count": 1,
  "next_page_token": "",
  "total": 1,
  "users": [
    {
      "department": {
        "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
        "name": "Engineering"
      },
      "email": "jo@example.com",
      "first_name": "Jo",
      "groups": [
        {
          "id": "9b4a5f6e-7d8c-4b92-8ca3-c4d5e6f7a8b0",
          "name": "Default"
        }
      ],
      "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
      "is_active": true,
      "last_name": "Bloggs",
      "manager": {
        "email": "sam@example.com",
        "first_name": "Sam",
        "id": "7f2e3d4c-5b6a-4f70-9a81-a2b3c4d5e6f8",
        "last_name": "Lee"
      },
      "roles": [
        {
          "id": "8a3f4e5d-6c7b-4a81-9b92-b3c4d5e6f7a9",
          "name": "Manager"
        }
      ],
      "subsidiary": {
        "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
        "name": "Acme Inc."
      }
    }
  ]
}
```

### List vendors

Find vendors by name, status, entity, department or when they last changed.

**Inputs**

- Name (`name`, text): Only vendors whose name contains this.
- Statuses (`statuses`, list): Only vendors in any of these statuses. One or more of: `ACTIVE`, `PREFERRED`, `INACTIVE`, `BANNED`, `DRAFT`.
- Entity (`subsidiary_id`, text): Only vendors of this entity.
- Department (`department_id`, text): Only vendors of this department.
- Updated after (`updated_after`, date and time): Only vendors changed after this time.
- Include custom fields (`include_custom_fields`, true/false): Also return each record's custom fields. Zip answers more slowly.
- Sort by (`sort_by`, text): What to sort by. Leave empty for Zip's order. One of: `name`, `created_at` (When created), `updated_at` (When last updated).
- Order (`sort_order`, text): Sort direction, when sorting. Defaults to newest or highest first. One of: `desc` (Newest or highest first (default)), `asc` (Oldest or lowest first).
- Page size (`page_size`, number): How many to return, 1 to 100. From 1 to 100.
- Next page token (`page_token`, text): The 'next_page_token' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many on this page
- `next_page_token` (text): Pass as 'Next page token' for the next page; empty on the last
- `total` (number): How many match in all
- `vendors` (list): The vendors

**Example output**

```json
{
  "count": 1,
  "next_page_token": "",
  "total": 1,
  "vendors": [
    {
      "address": {
        "country": "US",
        "lines": [
          "123 Main St"
        ],
        "locality": "San Francisco",
        "postcode": "94105",
        "region": "US-CA"
      },
      "attributes": [],
      "categories": [
        {
          "id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
          "name": "Software"
        }
      ],
      "contacts": [],
      "created_at": 1791000000,
      "currency": "USD",
      "department": {
        "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
        "name": "Engineering"
      },
      "description": "Office and design supplies.",
      "external_id": "V-10042",
      "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
      "legal_name": "Acme Supplies LLC",
      "name": "Acme Supplies",
      "po_email": "orders@example.com",
      "primary_phone": "+1 415 555 0100",
      "remittance_email": "billing@example.com",
      "risk": "green",
      "status": 1,
      "subsidiaries": [
        {
          "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
          "name": "Acme Inc."
        }
      ],
      "tier": "tier_2",
      "updated_at": 1792086400,
      "website_link": "https://example.com"
    }
  ]
}
```

### Mark invoice paid

Record that an invoice was paid outside Zip, such as by your ERP or bank, with the day and currency.

**Inputs**

- Invoice ID (`invoice_id`, text, required): The invoice's id (not the supplier's invoice number), from 'List invoices' or an earlier step.
- Paid on (`paid_on`, date, required): The day the invoice was paid.
- Currency (`currency`, text, required): The currency it was paid in, a three-letter code such as USD.
- Amount paid (`amount`, text): How much was paid, such as 1250.00. Leave empty for the invoice's amount.
- Payment reference (`reference`, text): Your reference for the payment, such as a check or transfer number.

**Outputs**

- `invoice` (object): The invoice

**Example output**

```json
{
  "invoice": {
    "amount": "12000.00",
    "amount_usd": "12000.00",
    "approvals": [],
    "approved_at": 0,
    "assignee": {
      "email": "jo@example.com",
      "first_name": "Jo",
      "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
      "last_name": "Bloggs"
    },
    "created_at": 1794528000,
    "currency": "USD",
    "department": {
      "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
      "name": "Engineering"
    },
    "description": "Design tool licences, year one",
    "due_date": 1797120000,
    "due_date_iso": "2026-12-31",
    "id": "9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
    "invoice_date": "2026-12-01",
    "invoice_number": "INV-7781",
    "invoice_url": "https://acme.ziphq.com/invoices/9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
    "line_items": [],
    "purchase_orders": [
      {
        "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
        "po_number": "PO-1042"
      }
    ],
    "status": "PAID",
    "subsidiary": {
      "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
      "name": "Acme Inc."
    },
    "updated_at": 1794614400,
    "vendor": {
      "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
      "name": "Acme Supplies"
    }
  }
}
```

### Post comment

Post a comment on a request or an invoice as a Zip user. People mentioned by email are notified by Zip.

**Inputs**

- Post as (`author_id`, text, required): The Zip user the comment is posted as. Pick one, or give their id.
- Comment (`text`, text, required): What to say. Mention someone with their Zip email, such as @jo@example.com.
- Request ID (`request_id`, text): The request to comment on. Give this or an invoice ID.
- Invoice ID (`invoice_id`, text): The invoice to comment on. Give this or a request ID.
- Posted from (`display_name`, text): The app name Zip shows on the comment. Defaults to Lodol.
- Link (`link`, text): A web address Zip links the comment to, such as the record it came from.

**Outputs**

- `comment` (object): The comment

**Example output**

```json
{
  "comment": {
    "commenter": {
      "email": "jo@example.com",
      "first_name": "Jo",
      "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
      "last_name": "Bloggs"
    },
    "created_at": 1792090000,
    "deleted": false,
    "external_display_name": "Lodol",
    "external_url": "",
    "id": "0a1b2c3d-4e5f-4061-8728-394a5b6c7d8e",
    "text": "Quote attached; please review.",
    "text_html": "<p>Quote attached; please review.</p>",
    "type": "COMMENT",
    "updated_at": 1792090000
  }
}
```

### Reject or cancel request

Reject or cancel a request, with the reason Zip shows on it and keeps in its audit trail. This ends the request.

**Inputs**

- Request ID (`request_id`, text, required): The request's id (not its number), from 'List requests' or an earlier step.
- Reject or cancel (`outcome`, text, required): Reject the request, or cancel it. Either ends it for good. One of: `REJECTED` (Reject), `CANCELED` (Cancel).
- Reason (`reason`, text, required): Why. Zip shows it on the request and records it in the audit trail. One of: `PURCHASE_NO_LONGER_NEEDED` (Purchase no longer needed), `NOT_ENOUGH_BUDGET` (Not enough budget), `DUPLICATE_VENDOR` (Duplicate vendor), `DUPLICATE_REQUEST` (Duplicate request), `WRONG_WORKFLOW` (Wrong workflow), `CHANGE_IN_REQUIREMENTS` (Change in requirements), `OTHER` (Other (say why)).
- Other reason (`other_reason`, text): The reason in your words, when the reason is Other (up to 500 characters).
- Explanation (`explanation`, text): More detail for the audit trail (up to 2,000 characters).

**Outputs**

- `request` (object): The request's new status

**Example output**

```json
{
  "request": {
    "canceled_at": 0,
    "completed_at": 1792090000,
    "id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
    "status": "REJECTED",
    "type": "request",
    "updated_at": 1792090000
  }
}
```

### Send invoice for approval

Check that a draft bill is complete and send it into its approval workflow in Zip.

**Inputs**

- Invoice ID (`invoice_id`, text, required): The invoice's id (not the supplier's invoice number), from 'List invoices' or an earlier step.

**Outputs**

- `invoice` (object): The invoice

**Example output**

```json
{
  "invoice": {
    "amount": "12000.00",
    "amount_usd": "12000.00",
    "approvals": [],
    "approved_at": 0,
    "assignee": {
      "email": "jo@example.com",
      "first_name": "Jo",
      "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
      "last_name": "Bloggs"
    },
    "created_at": 1794528000,
    "currency": "USD",
    "department": {
      "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
      "name": "Engineering"
    },
    "description": "Design tool licences, year one",
    "due_date": 1797120000,
    "due_date_iso": "2026-12-31",
    "id": "9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
    "invoice_date": "2026-12-01",
    "invoice_number": "INV-7781",
    "invoice_url": "https://acme.ziphq.com/invoices/9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
    "line_items": [],
    "purchase_orders": [
      {
        "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
        "po_number": "PO-1042"
      }
    ],
    "status": "PENDING_APPROVAL",
    "subsidiary": {
      "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
      "name": "Acme Inc."
    },
    "updated_at": 1794614400,
    "vendor": {
      "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
      "name": "Acme Supplies"
    }
  }
}
```

### Update request

Change a request's name, description, department, entity, vendor or start and end dates. Empty fields are left as they are.

**Inputs**

- Request ID (`request_id`, text, required): The request's id (not its number), from 'List requests' or an earlier step.
- Name (`name`, text): A new name for the request. Leave empty to keep it.
- Description (`description`, text): A new description. Leave empty to keep it.
- Department (`department_id`, text): Move the request to this department. Leave empty to keep it.
- Entity (`subsidiary_id`, text): Move the request to this entity. Leave empty to keep it.
- Vendor (`vendor_id`, text): Change the request's vendor. Leave empty to keep it.
- Start date (`start_date`, date): When the purchase starts, such as a subscription's first day.
- End date (`end_date`, date): When the purchase ends.

**Outputs**

- `request` (object): The request

**Example output**

```json
{
  "request": {
    "amount_usd": "12000.00",
    "attachments": [
      {
        "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e",
        "name": "quote.pdf",
        "url": "https://acme.ziphq.com/files/quote.pdf"
      }
    ],
    "attributes": [
      {
        "config_id": "63d42e86-147b-4fd7-baa3-d52d7e27494d",
        "data": [
          "CC-100"
        ],
        "name": "Cost center"
      }
    ],
    "category": {
      "id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
      "name": "Software"
    },
    "completed_at": 0,
    "created_at": 1792000000,
    "department": {
      "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
      "name": "Engineering"
    },
    "description": "Ten seats for the design team.",
    "id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
    "name": "Design tool licences",
    "owner": {
      "email": "jo@example.com",
      "first_name": "Jo",
      "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
      "last_name": "Bloggs"
    },
    "payment_method": "PURCHASE_ORDER",
    "price_detail": {
      "currency": "USD",
      "id": "3c4d5e6f-7081-4923-ab4c-5d6e7f809102",
      "line_items": [],
      "total": "12000.00",
      "total_usd": "12000.00"
    },
    "priority": 1,
    "purchase_order": {
      "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "po_number": "PO-1042"
    },
    "request_link": "https://acme.ziphq.com/request/1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
    "request_number": 1042,
    "request_type": "PURCHASE_REQUEST",
    "requester": {
      "email": "jo@example.com",
      "first_name": "Jo",
      "id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
      "last_name": "Bloggs"
    },
    "status": 1,
    "subsidiary": {
      "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
      "name": "Acme Inc."
    },
    "updated_at": 1792086400,
    "vendor": {
      "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
      "name": "Acme Supplies"
    },
    "workflow": {
      "id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
      "name": "Software"
    }
  }
}
```

### Update vendor

Change a vendor's name, status, contact emails, risk, tier or entities. Empty fields are left as they are.

**Inputs**

- Vendor (`vendor_id`, text, required): The vendor. Pick one, or give its id from an earlier step.
- Name (`name`, text): A new name for the vendor. Leave empty to keep it.
- Legal name (`legal_name`, text): The vendor's registered company name. Leave empty to keep it.
- Status (`status`, text): Active, Preferred, Inactive or Draft. Leave empty to keep it. One of: `1` (Active), `2` (Preferred), `3` (Inactive), `5` (Draft).
- Currency (`currency`, text): The vendor's main currency, a three-letter code such as USD. Leave empty to keep it.
- Purchase order email (`po_email`, text): Where purchase orders for this vendor are sent. Leave empty to keep it.
- Remittance email (`remittance_email`, text): Where payment notices for this vendor are sent. Leave empty to keep it.
- Phone (`primary_phone`, text): The vendor's main phone number. Leave empty to keep it.
- Tax ID (`tax_id_number`, text): The vendor's tax identification number. Leave empty to keep it.
- Risk (`risk`, text): The vendor's risk rating. Leave empty to keep it. One of: `green` (Green (low)), `yellow` (Yellow (medium)), `red` (Red (high)).
- Tier (`tier`, text): The vendor's tier. Leave empty to keep it. One of: `tier_1` (Tier 1), `tier_2` (Tier 2), `tier_3` (Tier 3), `tier_4` (Tier 4).
- Entities (`subsidiary_ids`, list): The entities (subsidiaries) that may buy from this vendor. On an update, these replace the vendor's current ones.

**Outputs**

- `vendor` (object): The vendor

**Example output**

```json
{
  "vendor": {
    "address": {
      "country": "US",
      "lines": [
        "123 Main St"
      ],
      "locality": "San Francisco",
      "postcode": "94105",
      "region": "US-CA"
    },
    "attributes": [],
    "categories": [
      {
        "id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
        "name": "Software"
      }
    ],
    "contacts": [],
    "created_at": 1791000000,
    "currency": "USD",
    "department": {
      "id": "0667b662-49a0-7dfb-8000-96ab361b9856",
      "name": "Engineering"
    },
    "description": "Office and design supplies.",
    "external_id": "V-10042",
    "id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
    "legal_name": "Acme Supplies LLC",
    "name": "Acme Supplies",
    "po_email": "orders@example.com",
    "primary_phone": "+1 415 555 0100",
    "remittance_email": "billing@example.com",
    "risk": "green",
    "status": 1,
    "subsidiaries": [
      {
        "id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
        "name": "Acme Inc."
      }
    ],
    "tier": "tier_2",
    "updated_at": 1792086400,
    "website_link": "https://example.com"
  }
}
```
