Customers

The companies you sell to, with their shipping addresses.

sales:readsales:writehttps://public-api.nutrasoft.ca/v1

Links toCustomer typescustomer_type_id Price listsprice_list_id Salespersonssalesperson_id Shipping methodsshipping_method_id Tax ratestax_rate_id Territoriesterritory_id

Linked fromSales orderscustomer_id Invoicescustomer_id

The Customer object

idinteger
activeboolean
addressobject
ShowHide 5 fields of address
- citystringnullable
- line1stringnullable
- line2stringnullable
- postal_codestringnullable
- statestringnullable
companystringnullable
contactstringnullable
created_atstringnullable
- UTC timestamp
customer_codestringnullable
customer_type_idintegernullable
emailstringnullable
phonestringnullable

Show 7 more attributes

price_list_idintegernullable
salesperson_idintegernullable
shipping_method_idintegernullable
tax_rate_idintegernullable
territory_idintegernullable
updated_atstringnullable
- UTC timestamp
websitestringnullable

The Shipping address object

idinteger
addressobject
ShowHide 5 fields of address
- citystringnullable
- line1stringnullable
- line2stringnullable
- postal_codestringnullable
- statestringnullable
contactstringnullable
customer_idintegernullable
is_defaultboolean
phonestringnullable

Operations

List customers

get/customerssales:read

Query parameters

customer_codestringnullable
Partial match.
companystringnullable
Partial match.
emailstringnullable
Partial match.
price_list_idintegernullable
- > 0
searchstringnullable
Free-text match.
sortstringnullable
Comma-separated field:direction pairs, e.g. id:desc. Sortable: company, created_at, customer_code, id, updated_at. id is always added last, so paging is stable.
limitinteger
Rows to return. Maximum 200.
- >= 1
- <= 200
- default 50
offsetinteger
Rows to skip. Maximum 10000: to read further, narrow the filters or page with updated_since.
- >= 0
- <= 10000
- default 0
updated_sincestringnullable
Only rows changed after this instant, as an ISO 8601 timestamp; without an offset it is read as UTC. Tracks the record itself, not its child rows, and deletions are not reported, so reconcile by re-listing from time to time.
- UTC timestamp

Returns

200 A page of Customer objects in data, with pagination.

Errors

400 401 403 429 500 503

GET /customers

curl "https://public-api.nutrasoft.ca/v1/customers?limit=50" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": [
    {
      "id": 123,
      "active": true,
      "address": {
        "city": "Montreal",
        "line1": "123 Example Street",
        "line2": "Suite 200",
        "postal_code": "H4S 2C1",
        "state": "QC"
      },
      "company": "Example Foods Inc.",
      "contact": "Alex Martin",
      "created_at": "2026-09-10T14:30:00Z",
      "customer_code": "SAMPLE-01",
      "customer_type_id": 123,
      "email": "orders@example.com",
      "phone": "+1-514-555-0100",
      "price_list_id": 123,
      "salesperson_id": 123,
      "shipping_method_id": 123,
      "tax_rate_id": 123,
      "territory_id": 123,
      "updated_at": "2026-09-10T14:30:00Z",
      "website": "https://example.com"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "has_more": false
  },
  "order": "id:asc"
}

Retrieve a customer

get/customers/{customer_id}sales:read

Path parameters

customer_idintegerrequired
The customer's id.
- > 0

Returns

200 One Customer object in data.

Errors

400 401 403 404 429 500 503

GET /customers/{customer_id}

curl "https://public-api.nutrasoft.ca/v1/customers/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": {
    "id": 123,
    "active": true,
    "address": {
      "city": "Montreal",
      "line1": "123 Example Street",
      "line2": "Suite 200",
      "postal_code": "H4S 2C1",
      "state": "QC"
    },
    "company": "Example Foods Inc.",
    "contact": "Alex Martin",
    "created_at": "2026-09-10T14:30:00Z",
    "customer_code": "SAMPLE-01",
    "customer_type_id": 123,
    "email": "orders@example.com",
    "phone": "+1-514-555-0100",
    "price_list_id": 123,
    "salesperson_id": 123,
    "shipping_method_id": 123,
    "tax_rate_id": 123,
    "territory_id": 123,
    "updated_at": "2026-09-10T14:30:00Z",
    "website": "https://example.com"
  }
}

Create a customer

post/customerssales:write

customer_code is unique within your account; a duplicate is a 409. The price list, customer type, salesperson, territory, shipping method and tax rate must be your account's or shared. Add shipping addresses afterwards.

Request body

companystringrequired
The customer name.
- min 1 chars
- max 100 chars
customer_codestringrequired
Your reference for this customer, unique within your account. Stored trimmed and upper-cased.
- min 1 chars
- max 40 chars
activeboolean
- default true
addressobjectnullable
ShowHide 5 fields of address
- citystringnullable
  - max 100 chars
- line1stringnullable
  - max 100 chars
- line2stringnullable
  - max 100 chars
- postal_codestringnullable
  Postal or ZIP code.
  - max 20 chars
- statestringnullable
  Province or state. Free text.
  - max 100 chars
contactstringnullable
- max 100 chars
customer_type_idintegernullable
- > 0
emailstringnullable
- max 100 chars
phonestringnullable
- max 50 chars
price_list_idintegernullable
- > 0
salesperson_idintegernullable
- > 0
shipping_method_idintegernullable
- > 0
tag_idsarray of integernullable
The customer's complete set of tags, each a tag of your account. Replaces the current set; [] removes every tag.
- at most 100 items
tax_rate_idintegernullable
- > 0
territory_idintegernullable
- > 0
websitestringnullable
- max 100 chars

Returns

201 One Customer object in data.

Errors

400 401 403 409 429 500 503

POST /customers

curl -X POST "https://public-api.nutrasoft.ca/v1/customers" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company": "Example Foods Inc.",
  "customer_code": "SAMPLE-01"
}'

Response201

{
  "data": {
    "id": 123,
    "active": true,
    "address": {
      "city": "Montreal",
      "line1": "123 Example Street",
      "line2": "Suite 200",
      "postal_code": "H4S 2C1",
      "state": "QC"
    },
    "company": "Example Foods Inc.",
    "contact": "Alex Martin",
    "created_at": "2026-09-10T14:30:00Z",
    "customer_code": "SAMPLE-01",
    "customer_type_id": 123,
    "email": "orders@example.com",
    "phone": "+1-514-555-0100",
    "price_list_id": 123,
    "salesperson_id": 123,
    "shipping_method_id": 123,
    "tax_rate_id": 123,
    "territory_id": 123,
    "updated_at": "2026-09-10T14:30:00Z",
    "website": "https://example.com"
  }
}

Update a customer

patch/customers/{customer_id}sales:write

Omitted fields are left unchanged. address and tag_ids are replaced as a whole. Existing orders and invoices keep the address they were raised with.

Path parameters

customer_idintegerrequired
The customer's id.
- > 0

Request body

activebooleannullable
addressobjectnullable
ShowHide 5 fields of address
- citystringnullable
  - max 100 chars
- line1stringnullable
  - max 100 chars
- line2stringnullable
  - max 100 chars
- postal_codestringnullable
  Postal or ZIP code.
  - max 20 chars
- statestringnullable
  Province or state. Free text.
  - max 100 chars
companystringnullable
- min 1 chars
- max 100 chars
contactstringnullable
- max 100 chars
customer_codestringnullable
- min 1 chars
- max 40 chars
customer_type_idintegernullable
- > 0
emailstringnullable
- max 100 chars
phonestringnullable
- max 50 chars
price_list_idintegernullable
- > 0
salesperson_idintegernullable
- > 0
shipping_method_idintegernullable
- > 0
tag_idsarray of integernullable
Replaces the current set of tags; [] removes every tag.
- at most 100 items
tax_rate_idintegernullable
- > 0
territory_idintegernullable
- > 0
websitestringnullable
- max 100 chars

Returns

200 One Customer object in data.

Errors

400 401 403 404 409 429 500 503

PATCH /customers/{customer_id}

curl -X PATCH "https://public-api.nutrasoft.ca/v1/customers/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "active": true
}'

Response200

{
  "data": {
    "id": 123,
    "active": true,
    "address": {
      "city": "Montreal",
      "line1": "123 Example Street",
      "line2": "Suite 200",
      "postal_code": "H4S 2C1",
      "state": "QC"
    },
    "company": "Example Foods Inc.",
    "contact": "Alex Martin",
    "created_at": "2026-09-10T14:30:00Z",
    "customer_code": "SAMPLE-01",
    "customer_type_id": 123,
    "email": "orders@example.com",
    "phone": "+1-514-555-0100",
    "price_list_id": 123,
    "salesperson_id": 123,
    "shipping_method_id": 123,
    "tax_rate_id": 123,
    "territory_id": 123,
    "updated_at": "2026-09-10T14:30:00Z",
    "website": "https://example.com"
  }
}

Delete a customer

delete/customers/{customer_id}sales:write

Deletes the customer and its attached documents. Refused with 409 while an order, an invoice or another record uses the customer: deactivate it instead with PATCH and active: false.

Path parameters

customer_idintegerrequired
The customer's id.
- > 0

Returns

200 One Customer object in data.

Errors

400 401 403 404 409 429 500 503

DELETE /customers/{customer_id}

curl -X DELETE "https://public-api.nutrasoft.ca/v1/customers/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": {
    "id": 123,
    "active": true,
    "address": {
      "city": "Montreal",
      "line1": "123 Example Street",
      "line2": "Suite 200",
      "postal_code": "H4S 2C1",
      "state": "QC"
    },
    "company": "Example Foods Inc.",
    "contact": "Alex Martin",
    "created_at": "2026-09-10T14:30:00Z",
    "customer_code": "SAMPLE-01",
    "customer_type_id": 123,
    "email": "orders@example.com",
    "phone": "+1-514-555-0100",
    "price_list_id": 123,
    "salesperson_id": 123,
    "shipping_method_id": 123,
    "tax_rate_id": 123,
    "territory_id": 123,
    "updated_at": "2026-09-10T14:30:00Z",
    "website": "https://example.com"
  }
}

List a customer's shipping addresses

get/customers/{customer_id}/shipping-addressessales:read

Not paginated: every address of the customer is returned.

Path parameters

customer_idintegerrequired
The customer's id.
- > 0

Returns

200 A page of ShippingAddress objects in data, with pagination.

Errors

400 401 403 404 429 500 503

GET /customers/{customer_id}/shipping-addresses

curl "https://public-api.nutrasoft.ca/v1/customers/123/shipping-addresses" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": [
    {
      "id": 123,
      "address": {
        "city": "Montreal",
        "line1": "123 Example Street",
        "line2": "Suite 200",
        "postal_code": "H4S 2C1",
        "state": "QC"
      },
      "contact": "Alex Martin",
      "customer_id": 123,
      "is_default": false,
      "phone": "+1-514-555-0100"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "has_more": false
  },
  "order": "id:asc"
}

Retrieve a customer shipping address

get/customers/{customer_id}/shipping-addresses/{shipping_address_id}sales:read

Path parameters

customer_idintegerrequired
The customer's id.
- > 0
shipping_address_idintegerrequired
The address's id.
- > 0

Returns

200 One ShippingAddress object in data.

Errors

400 401 403 404 429 500 503

GET /customers/{customer_id}/shipping-addresses/{shipping_address_id}

curl "https://public-api.nutrasoft.ca/v1/customers/123/shipping-addresses/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": {
    "id": 123,
    "address": {
      "city": "Montreal",
      "line1": "123 Example Street",
      "line2": "Suite 200",
      "postal_code": "H4S 2C1",
      "state": "QC"
    },
    "contact": "Alex Martin",
    "customer_id": 123,
    "is_default": false,
    "phone": "+1-514-555-0100"
  }
}

Add a customer shipping address

post/customers/{customer_id}/shipping-addressessales:write

A customer has at most one default address, so is_default: true is a 409 while another address holds it.

Path parameters

customer_idintegerrequired
The customer's id.
- > 0

Request body

addressobjectrequired
ShowHide 5 fields of address
- citystringnullable
  - max 100 chars
- line1stringnullable
  - max 100 chars
- line2stringnullable
  - max 100 chars
- postal_codestringnullable
  Postal or ZIP code.
  - max 20 chars
- statestringnullable
  Province or state. Free text.
  - max 100 chars
contactstringnullable
- max 100 chars
is_defaultboolean
Whether this is the customer's default ship-to. Refused with 409 while another address is the default.
- default false
phonestringnullable
- max 30 chars

Returns

201 One ShippingAddress object in data.

Errors

400 401 403 404 409 429 500 503

POST /customers/{customer_id}/shipping-addresses

curl -X POST "https://public-api.nutrasoft.ca/v1/customers/123/shipping-addresses" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "address": {
    "city": "Montreal"
  }
}'

Response201

{
  "data": {
    "id": 123,
    "address": {
      "city": "Montreal",
      "line1": "123 Example Street",
      "line2": "Suite 200",
      "postal_code": "H4S 2C1",
      "state": "QC"
    },
    "contact": "Alex Martin",
    "customer_id": 123,
    "is_default": false,
    "phone": "+1-514-555-0100"
  }
}

Update a customer shipping address

patch/customers/{customer_id}/shipping-addresses/{shipping_address_id}sales:write

Omitted fields are left unchanged. address is replaced as a whole.

Path parameters

customer_idintegerrequired
The customer's id.
- > 0
shipping_address_idintegerrequired
The address's id.
- > 0

Request body

addressobjectnullable
ShowHide 5 fields of address
- citystringnullable
  - max 100 chars
- line1stringnullable
  - max 100 chars
- line2stringnullable
  - max 100 chars
- postal_codestringnullable
  Postal or ZIP code.
  - max 20 chars
- statestringnullable
  Province or state. Free text.
  - max 100 chars
contactstringnullable
- max 100 chars
is_defaultbooleannullable
phonestringnullable
- max 30 chars

Returns

200 One ShippingAddress object in data.

Errors

400 401 403 404 409 429 500 503

PATCH /customers/{customer_id}/shipping-addresses/{shipping_address_id}

curl -X PATCH "https://public-api.nutrasoft.ca/v1/customers/123/shipping-addresses/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "contact": "Alex Martin"
}'

Response200

{
  "data": {
    "id": 123,
    "address": {
      "city": "Montreal",
      "line1": "123 Example Street",
      "line2": "Suite 200",
      "postal_code": "H4S 2C1",
      "state": "QC"
    },
    "contact": "Alex Martin",
    "customer_id": 123,
    "is_default": false,
    "phone": "+1-514-555-0100"
  }
}

Delete a customer shipping address

delete/customers/{customer_id}/shipping-addresses/{shipping_address_id}sales:write

Orders already raised keep the address they were stamped with.

Path parameters

customer_idintegerrequired
The customer's id.
- > 0
shipping_address_idintegerrequired
The address's id.
- > 0

Returns

200 One ShippingAddress object in data.

Errors

400 401 403 404 409 429 500 503

DELETE /customers/{customer_id}/shipping-addresses/{shipping_address_id}

curl -X DELETE "https://public-api.nutrasoft.ca/v1/customers/123/shipping-addresses/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": {
    "id": 123,
    "address": {
      "city": "Montreal",
      "line1": "123 Example Street",
      "line2": "Suite 200",
      "postal_code": "H4S 2C1",
      "state": "QC"
    },
    "contact": "Alex Martin",
    "customer_id": 123,
    "is_default": false,
    "phone": "+1-514-555-0100"
  }
}