Customers

Update customer

Changed on

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

patch/customers/{id}

Request

  • Base URL: https://api.mvmnt.io/v1
  • URL: https://api.mvmnt.io/v1/customers/{id}
  • Auth: HTTP bearer

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

status'NEW' | 'CONTACTED' | 'QUALIFIED' | 'QUOTED' | 'NURTURING' | 'PENDING' | 'ACTIVE' | 'INACTIVE' | 'BLOCKED' | 'CLOSED'

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'AGRICULTURE_FORESTRY' | 'CONSTRUCTION' | 'CONSUMER_GOODS' | 'EDUCATIONAL_SERVICES' | 'ENTERTAINMENT' | 'FOOD_SERVICES' | 'HEALTHCARE' | 'INDUSTRIAL_MACHINERY' | 'MANUFACTURING' | 'MINING' | 'RETAIL_TRADE' | 'TRANSPORTATION_WAREHOUSING' | 'UTILITIES' | 'WHOLESALE_TRADE'

Industry classification for the customer

annualRevenue'_0_TO_500K' | '_500K_TO_3M' | '_3M_TO_10M' | '_10M_TO_25M' | '_25M_TO_50M' | '_50M_TO_100M' | '_100M_TO_500M' | '_500M_PLUS'

Annual revenue range

annualSpend'_0_TO_25K' | '_25_TO_150K' | '_150K_TO_300K' | '_300K_TO_1M' | '_1_TO_5M' | '_5M_TO_25M' | '_25M_TO_75M' | '_75M_PLUS'

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

defaultMode'FTL' | 'LTL' | 'AIR' | 'OCEAN' | 'RAIL' | 'INTERMODAL' | 'DRAYAGE' | 'EXPEDITED_GROUND' | 'EXPEDITED_AIR' | 'AUTO' | 'PTL' | 'RLTL' | 'BULK'

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",
    "state": "IL",
    "zipCode": "60601",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isSmartyValidated": true,
    "obeysDst": true
  },
  "billingAddress": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "state": "IL",
    "zipCode": "60601",
    "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"

status'NEW' | 'CONTACTED' | 'QUALIFIED' | 'QUOTED' | 'NURTURING' | 'PENDING' | 'ACTIVE' | 'INACTIVE' | 'BLOCKED' | 'CLOSED' required

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'AGRICULTURE_FORESTRY' | 'CONSTRUCTION' | 'CONSUMER_GOODS' | 'EDUCATIONAL_SERVICES' | 'ENTERTAINMENT' | 'FOOD_SERVICES' | 'HEALTHCARE' | 'INDUSTRIAL_MACHINERY' | 'MANUFACTURING' | 'MINING' | 'RETAIL_TRADE' | 'TRANSPORTATION_WAREHOUSING' | 'UTILITIES' | 'WHOLESALE_TRADE'

Industry classification for the customer

annualRevenue'_0_TO_500K' | '_500K_TO_3M' | '_3M_TO_10M' | '_10M_TO_25M' | '_25M_TO_50M' | '_50M_TO_100M' | '_100M_TO_500M' | '_500M_PLUS'

Annual revenue range

annualSpend'_0_TO_25K' | '_25_TO_150K' | '_150K_TO_300K' | '_300K_TO_1M' | '_1_TO_5M' | '_5M_TO_25M' | '_25M_TO_75M' | '_75M_PLUS'

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

defaultMode'FTL' | 'LTL' | 'AIR' | 'OCEAN' | 'RAIL' | 'INTERMODAL' | 'DRAYAGE' | 'EXPEDITED_GROUND' | 'EXPEDITED_AIR' | 'AUTO' | 'PTL' | 'RLTL' | 'BULK'

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": 5,
    "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",
    "state": "IL",
    "zipCode": "60601",
    "country": "USA",
    "market": "CHI",
    "latitude": "41.8781",
    "longitude": "-87.6298",
    "isSmartyValidated": true,
    "obeysDst": true
  },
  "billingAddress": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "Chicago",
    "state": "IL",
    "zipCode": "60601",
    "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"
  }
}

Changes

  • 2cd6ecfbeb82Revision changes
    • breaking

      the response's body type changed from object to no type for status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • warning

      the optional response header X-RateLimit-Reset removed for the status 429

    • info

      added subschema #2 to the response body allOf list for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • db5522486028Revision changes
    • warning

      added the new BULK enum value to the //// response property for the response status

    • info

      added the new BULK enum value to the request property ////