v1

latestOpenAPI 3.1.0Proprietary2026-08-06177398877.4 KB

Customers

Update customer

Partially update a customer. Only provided fields will be updated.

patch/customers/{id}

Path parameters

idstring required

Resource ID (UUID) or client key

Query parameters

by'id' | 'key'

Specify lookup type for faster retrieval. If omitted, defaults to looking up by ID first, then falls back to client key if not found. Use by=key when you know you're providing a client key for best performance.

Request body

namestring

Customer company name

Customer account status (includes lead stages):

NEW: New lead, not yet contacted
CONTACTED: Initial contact made with lead
QUALIFIED: Lead has been qualified as potential customer
QUOTED: Quote has been provided to lead
NURTURING: Lead being nurtured for future opportunity
PENDING: Customer prospect pending activation
ACTIVE: Active customer account
INACTIVE: Deactivated customer account
BLOCKED: Customer account blocked from operations
CLOSED: Customer account permanently closed

serviceTier'TIER_1' | 'TIER_2' | 'TIER_3'

Service tier level for the customer

websitestring nullable

Customer website URL

phoneNumberstring nullable

Primary phone number

Industry classification for the customer

Annual revenue range

Annual freight spend estimate range

spendType'CONTRACT' | 'SPOT'

Customer spend type:

CONTRACT: Customer operates under contract pricing
SPOT: Customer operates on spot market pricing

naicsstring nullable

NAICS industry code

einstring nullable

Employer Identification Number

dunsstring nullable

Dun & Bradstreet number

leadSourcestring nullable

How this customer was acquired

dbaNamestring nullable

Doing business as name

numberOfEmployees'_0_TO_1' | '_2_TO_5' | '_6_TO_9' | '_10_TO_24' | '_25_TO_99' | '_100_TO_249' | '_250_TO_499' | '_500_OR_MORE'

Number of employees in the company

externalIdstring nullable

External system identifier

currency'USD' | 'CAD' | 'MXN' | 'EUR' | 'GBP' | 'JPY' | 'CNY' | 'AUD' | 'BRL' | 'INR' | 'KRW' | 'RUB' | 'SAR' | 'TRY' | 'IDR' | 'ARS' | 'ZAR'

Preferred currency for transactions

creditLimitnumber float nullable

Maximum credit allowed

creditUsageWarningnumber float nullable

Credit usage warning threshold

freeCreditReqnumber float nullable

Free credit requirement

Transportation mode type

defaultMarginnumber float nullable

Default margin percentage (0-1, e.g., 0.15 for 15%)

minMarginnumber float nullable

Minimum margin threshold

maxMarginnumber float nullable

Maximum margin threshold

defaultInternalNotesstring nullable

Default internal notes template

defaultCarrierNotesstring nullable

Default carrier-facing notes template used when note splitting is enabled

defaultExternalNotesstring nullable

Default external notes template

defaultShowNotes'ALL' | 'SPLIT'

Controls whether external notes are shown on all documents or split from carrier-facing notes.

ALL: Use external notes on customer-facing and carrier-facing documents
SPLIT: Use external notes on customer-facing documents and carrier notes on carrier-facing documents

autoAcceptTenderboolean nullable

Auto-accept tender flag

groupIdstring uuid nullable

Customer group reference

notesstring nullable

Internal notes

deactivationReason'NOT_PAYING_INVOICE' | 'ACQUIRED' | 'DUPLICATE' | 'NOT_IN_BUSINESS' | 'OTHER'

Reason for customer deactivation:

NOT_PAYING_INVOICE: Customer is not paying invoices
ACQUIRED: Customer was acquired by another company
DUPLICATE: Duplicate customer record
NOT_IN_BUSINESS: Customer is no longer in business
OTHER: Other reason (see deactivationNotes for details)

deactivationNotesstring nullable

Additional deactivation details

deactivationDatestring date-time nullable

Deactivation date

qboCustomerIdstring nullable

QuickBooks Online customer ID

keystring nullable

Client-defined reference identifier

Example request

{
  "name": "Acme Manufacturing Corp",
  "website": "https://acme-manufacturing.com",
  "phoneNumber": "+1-555-123-4567",
  "naics": "336411",
  "ein": "12-3456789",
  "duns": "123456789",
  "leadSource": "Referral",
  "dbaName": "Acme Corp DBA",
  "externalId": "EXT-12345",
  "creditLimit": 50000,
  "creditUsageWarning": 40000,
  "freeCreditReq": 5000,
  "defaultMargin": 0.15,
  "minMargin": 0.1,
  "maxMargin": 0.25,
  "defaultInternalNotes": "Contact via email only",
  "defaultCarrierNotes": "Call pickup contact before arrival",
  "defaultExternalNotes": "Please call 1 hour before delivery",
  "notes": "Prefers email communication",
  "corporateAddress": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isSmartyValidated": true,
    "obeysDst": true
  },
  "billingAddress": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isSmartyValidated": true,
    "obeysDst": true
  },
  "key": "ERP-CUSTOMER-12345"
}

Response

Customer updated successfully

object'CUSTOMER'

Object type identifier

idstring uuid required

Unique customer identifier

namestring required

Customer company name

friendlyIdstring required

Human-readable customer identifier, starts with "A"

Customer account status (includes lead stages):

NEW: New lead, not yet contacted
CONTACTED: Initial contact made with lead
QUALIFIED: Lead has been qualified as potential customer
QUOTED: Quote has been provided to lead
NURTURING: Lead being nurtured for future opportunity
PENDING: Customer prospect pending activation
ACTIVE: Active customer account
INACTIVE: Deactivated customer account
BLOCKED: Customer account blocked from operations
CLOSED: Customer account permanently closed

serviceTier'TIER_1' | 'TIER_2' | 'TIER_3'

Service tier level for the customer

websitestring nullable

Customer website URL

phoneNumberstring nullable

Primary phone number

Industry classification for the customer

Annual revenue range

Annual freight spend estimate range

spendType'CONTRACT' | 'SPOT'

Customer spend type:

CONTRACT: Customer operates under contract pricing
SPOT: Customer operates on spot market pricing

naicsstring nullable

NAICS industry code

einstring nullable

Employer Identification Number

dunsstring nullable

Dun & Bradstreet number

leadSourcestring nullable

How this customer was acquired

dbaNamestring nullable

Doing business as name

numberOfEmployees'_0_TO_1' | '_2_TO_5' | '_6_TO_9' | '_10_TO_24' | '_25_TO_99' | '_100_TO_249' | '_250_TO_499' | '_500_OR_MORE'

Number of employees in the company

externalIdstring nullable

External system identifier

currency'USD' | 'CAD' | 'MXN' | 'EUR' | 'GBP' | 'JPY' | 'CNY' | 'AUD' | 'BRL' | 'INR' | 'KRW' | 'RUB' | 'SAR' | 'TRY' | 'IDR' | 'ARS' | 'ZAR'

Preferred currency for transactions

creditLimitnumber float nullable

Maximum credit allowed

creditUsageWarningnumber float nullable

Credit usage warning threshold

freeCreditReqnumber float nullable

Free credit requirement

Transportation mode type

defaultMarginnumber float nullable

Default margin percentage (0-1, e.g., 0.15 for 15%)

minMarginnumber float nullable

Minimum margin threshold

maxMarginnumber float nullable

Maximum margin threshold

defaultInternalNotesstring nullable

Default internal notes template

defaultCarrierNotesstring nullable

Default carrier-facing notes template used when note splitting is enabled

defaultExternalNotesstring nullable

Default external notes template

defaultShowNotes'ALL' | 'SPLIT'

Controls whether external notes are shown on all documents or split from carrier-facing notes.

ALL: Use external notes on customer-facing and carrier-facing documents
SPLIT: Use external notes on customer-facing documents and carrier notes on carrier-facing documents

autoAcceptTenderboolean nullable

Auto-accept tender flag

notesstring nullable

Internal notes about this customer

deactivationReason'NOT_PAYING_INVOICE' | 'ACQUIRED' | 'DUPLICATE' | 'NOT_IN_BUSINESS' | 'OTHER'

Reason for customer deactivation:

NOT_PAYING_INVOICE: Customer is not paying invoices
ACQUIRED: Customer was acquired by another company
DUPLICATE: Duplicate customer record
NOT_IN_BUSINESS: Customer is no longer in business
OTHER: Other reason (see deactivationNotes for details)

deactivationNotesstring nullable

Additional details about deactivation

deactivationDatestring date-time nullable

When the customer was deactivated

closedAtstring date-time nullable

When the customer account was closed

closedNotesstring nullable

Notes about account closure

qboCustomerIdstring nullable

QuickBooks Online customer ID

keystring nullable

Client-defined reference identifier for this customer

createdAtstring date-time required

Timestamp when customer was created

updatedAtstring date-time required

Timestamp when customer was last updated

deletedAtstring date-time nullable

Timestamp when customer was soft-deleted (null if active)

Example response

{
  "object": "CUSTOMER",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Manufacturing Corp",
  "friendlyId": "A123456",
  "website": "https://acme-manufacturing.com",
  "phoneNumber": "+1-555-123-4567",
  "naics": "336411",
  "ein": "12-3456789",
  "duns": "123456789",
  "leadSource": "Referral",
  "dbaName": "Acme Corp DBA",
  "externalId": "EXT-12345",
  "creditLimit": 50000,
  "creditUsageWarning": 40000,
  "freeCreditReq": 5000,
  "defaultMargin": 0.15,
  "minMargin": 0.1,
  "maxMargin": 0.25,
  "defaultInternalNotes": "Contact via email only",
  "defaultCarrierNotes": "Call pickup contact before arrival",
  "defaultExternalNotes": "Please call 1 hour before delivery",
  "group": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345"
  },
  "paymentTerm": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-PAYTERM-NET30",
    "name": "Net 30",
    "description": "Payment due 30 days from invoice date",
    "days": 30,
    "quickPayFee": 0.05,
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z"
  },
  "notes": "Prefers email communication",
  "closedBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone": "+1-555-123-4567",
    "phoneExt": "123",
    "status": "ACTIVE",
    "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z"
  },
  "corporateAddress": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isSmartyValidated": true,
    "obeysDst": true
  },
  "billingAddress": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isSmartyValidated": true,
    "obeysDst": true
  },
  "key": "ERP-CUSTOMER-12345",
  "contacts": [
    {
      "object": "CUSTOMER_CONTACT",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "key": "ERP-CONTACT-JOHN-001",
      "name": "John Smith",
      "contactInfo": {
        "name": "John Smith",
        "email": "john.smith@example.com",
        "phoneNumber": "+1-555-0100",
        "title": "Operations Manager"
      },
      "phoneExtension": "1234",
      "isPrimary": true,
      "contactTypes": [
        "BILLING",
        "ACCOUNT_MANAGER"
      ],
      "notifications": [
        "SHIPMENT_PICKED_UP",
        "SHIPMENT_DELIVERED"
      ],
      "invitedUser": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "key": "ERP-USER-12345",
        "email": "john.doe@example.com",
        "name": "John Doe",
        "phone": "+1-555-123-4567",
        "phoneExt": "123",
        "status": "ACTIVE",
        "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "createdAt": "2025-01-15T10:00:00Z",
        "updatedAt": "2025-01-15T14:30:00Z"
      },
      "deletedBy": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "key": "ERP-USER-12345",
        "email": "john.doe@example.com",
        "name": "John Doe",
        "phone": "+1-555-123-4567",
        "phoneExt": "123",
        "status": "ACTIVE",
        "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "createdAt": "2025-01-15T10:00:00Z",
        "updatedAt": "2025-01-15T14:30:00Z"
      },
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ],
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T14:30:00Z",
  "deletedBy": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key": "ERP-USER-12345",
    "email": "john.doe@example.com",
    "name": "John Doe",
    "phone": "+1-555-123-4567",
    "phoneExt": "123",
    "status": "ACTIVE",
    "avatarId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T14:30:00Z"
  }
}