MCP tools

Customers

MCP tools for the customer directory, its tax details and addresses, and linking a customer to a manufacturer record.

A customer is a buyer your organization invoices, quotes and sells to: a hospital, a company or an individual. Its profile holds what those documents need in one place: the display and legal names, the tax treatment, the VAT and CR numbers, a buyer identifier for ZATCA, the national and shipping addresses, and the contact persons. The directory is separate from the manufacturer (supplier) directory, and a party that is both is linked across the two, never merged. The guide to the app side is Customers.

Warning:A profile fills a document and nothing more. Invoices, sales orders and quotations take a customer_id to link them to a profile, and each keeps its own copy of the buyer details as they were when it was written. Editing or deleting a customer never changes a document already written, and an issued invoice never changes at all. See `invoices_create`, `sales_orders_create` and `quotations_create`.

Note:Every member of the organization can read the directory, because a customer's name and address print on documents everyone sees. Owner, admin, sales and purchasing can create, change, delete and link customers. Like every MCP tool, they need the Pro or Enterprise plan.

Tool	What it does
customers_list	List customers
customers_get	Get a customer
customers_create	Create a customer
customers_update	Update a customer
customers_delete	Delete a customer
customers_link_vendor	Link a customer to a supplier record
customers_unlink_vendor	Unlink a customer from its supplier record

The customer directory

customers_list

Lists your customer directory alphabetically by display name, leaving out inactive customers unless you ask for them. Filter by status, by whether the customer has a supplier record, by type or by tax treatment, or search a word across names, VAT and CR numbers, email and phone.

Read-only · scope customers.read · all roles · Pro and Enterprise plans

Parameter	Type	Required	Description
`active`	`string`	No	Which customers to list: `active` (the default), `inactive` or `all`.
`vendor`	`string`	No	`linked` for customers that also have a supplier record, `unlinked` for those that do not, or `all` (the default).
`customer_type`	`string`	No	`business` or `individual`.
`tax_treatment`	`string`	No	Only customers with this tax treatment: `vat_registered`, `vat_not_registered`, `gcc_vat_registered`, `gcc_vat_not_registered` or `non_gcc`. Each value is explained under `customers_create`.
`manufacturer_id`	`integer`	No	The customer linked to this manufacturer record, if there is one.
`q`	`string`	No	A word or part of one, matched anywhere in the display name, legal name, VAT number, CR number, email or phone. Up to 200 characters.
`page`	`integer`	No	Page number, starting at 1.
`page_size`	`integer`	No	Results per page: 20 by default, 100 at most.

{
  "q": "hospital",
  "tax_treatment": "vat_registered",
  "vendor": "linked"
}

Example arguments

Returns: A page of customers in data, with total, page, page_size and total_pages. Each has the profile's main fields (names, type, tax treatment, VAT and CR numbers, address, currency and is_active) and manufacturers, holding the id and name of the linked supplier record or null.

The list does not carry the contact persons, website, shipping address or notes. Read those with customers_get.

customers_get

Returns one customer in full: the profile, its contact persons, the linked supplier record if there is one, and the newest invoices, sales orders and quotations that started from it, with the total count of each kind.

Read-only · scope customers.read · all roles · Pro and Enterprise plans

Parameter	Type	Required	Description
`id`	`integer`	Yes	The customer's ID, from `customers_list`.

Returns: customer (the full profile), contacts, manufacturer (id and name, or null), documents (up to the 10 newest of invoices, sales_orders and quotations) and counts (the total of each kind).

The server answers 404 when the customer is not in your organization. Each listed document carries its reference details, such as number, status and date.

customers_create

Creates a customer profile. The display name must be unique in your organization, ignoring case. A VAT-registered customer, the default, must carry a valid Saudi VAT number: choose another tax treatment for a buyer without one. Send manufacturer_id to record from the start that the customer is also one of your suppliers.

Changes data · scope customers.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Parameter	Type	Required	Description
`display_name`	`string`	Yes	The name shown in lists and pickers, 1 to 200 characters. Unique in your organization, ignoring case.
`customer_type`	`string`	No	`business` (the default) or `individual`.
`company_name`	`string`	No	The legal name printed on documents when it differs from the display name, up to 200 characters.
`email`	`string`	No	The customer's email address.
`phone`	`string`	No	The customer's phone number, up to 50 characters.
`website`	`string`	No	The customer's website, up to 500 characters.
`currency`	`string`	No	ISO 4217 code of the customer's currency, three letters. Defaults to `SAR`.
`tax_treatment`	`string`	No	How the customer is treated for VAT, which decides what an invoice prints in its buyer block: `vat_registered` (the default) holds a Saudi VAT number, required in `vat_number`; `vat_not_registered` has none, and documents show the CR number or another identifier instead; `gcc_vat_registered` holds another GCC state's number, kept in `vat_number` and printed as a GCC identifier; `gcc_vat_not_registered` and `non_gcc` are treated as a buyer without a number.
`vat_number`	`string`	No	The VAT registration number, up to 20 characters. For a Saudi-registered buyer it is 15 digits starting and ending with 3. For `gcc_vat_registered` it holds the other state's number.
`cr_number`	`string`	No	The commercial registration number, up to 30 characters. On an invoice, a buyer with no VAT number is identified by it (as `CRN`) unless you give another identifier below.
`buyer_id_scheme`	`string`	No	The type of another identifier for a buyer without a VAT number, as ZATCA names them: `CRN` commercial registration, `MOM` MOMRA (municipalities) licence, `MLS` MHRSD (human resources) licence, `700` the 700 number, `SAG` MISA (investment) licence, `NAT` national ID, `GCC` GCC citizen ID, `IQA` iqama, `PAS` passport, `OTH` other. It goes with `buyer_id_value`.
`buyer_id_value`	`string`	No	The identifier's value, up to 50 characters, used with `buyer_id_scheme`.
`street_name`	`string`	No	National address: the street, up to 200 characters.
`building_number`	`string`	No	National address: the 4-digit building number.
`district`	`string`	No	National address: the district, up to 100 characters.
`city`	`string`	No	National address: the city, up to 100 characters.
`postal_code`	`string`	No	National address: the 5-digit postal code.
`additional_number`	`string`	No	National address: the additional number, up to 10 characters.
`country_code`	`string`	No	Two-letter ISO 3166-1 country code. Defaults to `SA`.
`shipping_address`	`string`	No	A free-text delivery address when it differs from the national address, up to 500 characters.
`notes`	`string`	No	Free-text notes on the customer, up to 2,000 characters.
`is_active`	`boolean`	No	`false` hides the profile from pickers and from the default list, and never affects a document. Defaults to `true`.
`manufacturer_id`	`integer`	No	The ID of your supplier record (manufacturer) for the same party, from `manufacturers_list`. A manufacturer can be linked to one customer only. See `customers_link_vendor`.
`contacts`	`object[]`	No	The contact persons at the customer, up to 20.
`contacts[].name`	`string`	Yes	The person's name, 1 to 200 characters.
`contacts[].email`	`string`	No	The person's email address.
`contacts[].phone`	`string`	No	The person's phone number, up to 50 characters.
`contacts[].mobile`	`string`	No	The person's mobile number, up to 50 characters.
`contacts[].designation`	`string`	No	The person's job title, up to 100 characters.
`contacts[].is_primary`	`boolean`	No	Marks the main contact. When none is flagged, the first person in the list is the main contact.

{
  "display_name": "Al Noor Hospital",
  "company_name": "Al Noor Medical Company",
  "tax_treatment": "vat_registered",
  "vat_number": "300123456700003",
  "cr_number": "1010123456",
  "street_name": "King Fahd Road",
  "building_number": "8228",
  "district": "Al Olaya",
  "city": "Riyadh",
  "postal_code": "12214",
  "additional_number": "2121",
  "email": "purchasing@alnoor.example.com",
  "contacts": [
    {
      "name": "Sara Alharbi",
      "designation": "Purchasing manager",
      "mobile": "0551234567",
      "is_primary": true
    }
  ]
}

Example arguments

Returns: The new profile in customer and its contact persons in contacts.

The server answers 400 vat_number_required when a VAT-registered customer has no VAT number, and 400 vat_number_invalid when the number is not 15 digits starting and ending with 3.
It answers 409 display_name_taken when another customer has the name, 404 manufacturer_not_found when the manufacturer is not your organization's, and 409 vendor_already_linked when another customer is already linked to it.

customers_update

Changes a customer profile. Fields you leave out stay as they are, null clears a field that can be empty, and contacts, when sent, replaces the whole list of contact persons. The VAT rule is applied to the profile as it will be after the change, so switching to vat_registered needs a VAT number on file or in the same call. Documents already written keep their own copy of the buyer details.

Changes data · scope customers.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Parameter	Type	Required	Description
`id`	`integer`	Yes	The customer's ID, from `customers_list`.
`display_name`	`string`	No	A new display name, 1 to 200 characters, unique in your organization ignoring case.
`customer_type`	`string`	No	`business` (the default) or `individual`.
`company_name`	`string`	No	The legal name printed on documents when it differs from the display name, up to 200 characters. Send `null` to clear the value.
`email`	`string`	No	The customer's email address. Send `null` to clear the value.
`phone`	`string`	No	The customer's phone number, up to 50 characters. Send `null` to clear the value.
`website`	`string`	No	The customer's website, up to 500 characters. Send `null` to clear the value.
`currency`	`string`	No	ISO 4217 code of the customer's currency, three letters. Defaults to `SAR`.
`tax_treatment`	`string`	No	How the customer is treated for VAT, which decides what an invoice prints in its buyer block: `vat_registered` (the default) holds a Saudi VAT number, required in `vat_number`; `vat_not_registered` has none, and documents show the CR number or another identifier instead; `gcc_vat_registered` holds another GCC state's number, kept in `vat_number` and printed as a GCC identifier; `gcc_vat_not_registered` and `non_gcc` are treated as a buyer without a number.
`vat_number`	`string`	No	The VAT registration number, up to 20 characters. For a Saudi-registered buyer it is 15 digits starting and ending with 3. For `gcc_vat_registered` it holds the other state's number. Send `null` to clear the value.
`cr_number`	`string`	No	The commercial registration number, up to 30 characters. On an invoice, a buyer with no VAT number is identified by it (as `CRN`) unless you give another identifier below. Send `null` to clear the value.
`buyer_id_scheme`	`string`	No	The type of another identifier for a buyer without a VAT number, as ZATCA names them: `CRN` commercial registration, `MOM` MOMRA (municipalities) licence, `MLS` MHRSD (human resources) licence, `700` the 700 number, `SAG` MISA (investment) licence, `NAT` national ID, `GCC` GCC citizen ID, `IQA` iqama, `PAS` passport, `OTH` other. It goes with `buyer_id_value`. Send `null` to clear the value.
`buyer_id_value`	`string`	No	The identifier's value, up to 50 characters, used with `buyer_id_scheme`. Send `null` to clear the value.
`street_name`	`string`	No	National address: the street, up to 200 characters. Send `null` to clear the value.
`building_number`	`string`	No	National address: the 4-digit building number. Send `null` to clear the value.
`district`	`string`	No	National address: the district, up to 100 characters. Send `null` to clear the value.
`city`	`string`	No	National address: the city, up to 100 characters. Send `null` to clear the value.
`postal_code`	`string`	No	National address: the 5-digit postal code. Send `null` to clear the value.
`additional_number`	`string`	No	National address: the additional number, up to 10 characters. Send `null` to clear the value.
`country_code`	`string`	No	Two-letter ISO 3166-1 country code. Defaults to `SA`.
`shipping_address`	`string`	No	A free-text delivery address when it differs from the national address, up to 500 characters. Send `null` to clear the value.
`notes`	`string`	No	Free-text notes on the customer, up to 2,000 characters. Send `null` to clear the value.
`is_active`	`boolean`	No	`false` hides the profile from pickers and from the default list, and never affects a document. Defaults to `true`.
`manufacturer_id`	`integer`	No	The ID of your supplier record (manufacturer) for the same party, from `manufacturers_list`. A manufacturer can be linked to one customer only. Send `null` to unlink; see `customers_link_vendor`.
`contacts`	`object[]`	No	The contact persons at the customer, up to 20. Sending the list replaces the current one entirely; leave it out to keep the contacts as they are.
`contacts[].name`	`string`	Yes	The person's name, 1 to 200 characters.
`contacts[].email`	`string`	No	The person's email address. Send `null` to clear the value.
`contacts[].phone`	`string`	No	The person's phone number, up to 50 characters. Send `null` to clear the value.
`contacts[].mobile`	`string`	No	The person's mobile number, up to 50 characters. Send `null` to clear the value.
`contacts[].designation`	`string`	No	The person's job title, up to 100 characters. Send `null` to clear the value.
`contacts[].is_primary`	`boolean`	No	Marks the main contact. When none is flagged, the first person in the list is the main contact.

{
  "id": 214,
  "city": "Jeddah",
  "postal_code": "21442",
  "contacts": [
    {
      "name": "Sara Alharbi",
      "mobile": "0551234567",
      "is_primary": true
    },
    {
      "name": "Omar Alqahtani",
      "designation": "Accountant"
    }
  ]
}

Example arguments

Returns: The profile after the change in customer and its contact persons in contacts.

The server answers 404 not_found when the customer is not in your organization, and the same 400 and 409 errors as customers_create apply to the profile as it will be after the change.
Changing the profile never edits a document already written; only new documents pick up the new details.

customers_delete

Deletes a customer profile and its contact persons. Invoices, sales orders and quotations that started from it keep their buyer details and are only unlinked from the profile. A linked supplier record stays. This cannot be undone.

Deletes or overwrites data · scope customers.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Parameter	Type	Required	Description
`id`	`integer`	Yes	The customer's ID, from `customers_list`.

Returns: A confirmation: ok is true.

The server answers 404 not_found when the customer is not in your organization. To hide a customer from pickers without deleting it, update it with is_active set to false.

A customer that is also a supplier

A company you both sell to and buy from needs both records: the customer profile for what you issue to it, and the manufacturer record for what you buy from it. The link between them is what says they are one party.

customers_link_vendor

Marks a customer as also one of your suppliers by giving it a supplier record. Send manufacturer_id to link an existing manufacturer, or leave it out and the server creates a manufacturer from the profile (name, primary contact, address and country) and links it. The two stay separate records, and the link alone says they are one party.

Changes data · scope customers.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Parameter	Type	Required	Description
`id`	`integer`	Yes	The customer's ID, from `customers_list`.
`manufacturer_id`	`integer`	No	The existing manufacturer to link to the customer, from `manufacturers_list`. Leave it out to create one from the profile.

Returns: The customer after the link in customer, and the linked supplier record in manufacturer (id and name).

When linking an existing manufacturer, the server answers 404 manufacturer_not_found if it is not your organization's, and 409 vendor_already_linked if another customer is already linked to it. If the customer already had a supplier record, the link moves to the new one.
When creating from the profile, it answers 409 already_linked if the customer already has a supplier record, and 409 manufacturer_exists when a manufacturer with the same name exists (the legal name if set, else the display name): link that one instead of creating a second.
Creating the supplier record copies the profile's details once, and later edits to either record are not copied to the other.

customers_unlink_vendor

Removes the link between a customer and its supplier record (manufacturer). Both records stay as they are; only the link goes.

Changes data · scope customers.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Parameter	Type	Required	Description
`id`	`integer`	Yes	The customer's ID, from `customers_list`.

Returns: The customer after the unlink in customer, with manufacturer set to null.

The server answers 404 not_found when the customer is not in your organization. Calling it on a customer with no link changes nothing.