php

customer

/customer

Retrieve customers

Permissions:
  • customer_read

Produces: application/json
get
/customer/customers

Retrieves customers from the account. If no parameters are specified, all customers will be returned. You will need to make multiple API calls in order to retrieve the entire result set since this API performs result set pagination.

Parameters
Parameter Description Location Data Type Required
email Email query string optional
qb_class Quickbooks class query string optional
quickbooks_code Quickbooks code query string optional
last_modified_dts_start Last modified date start query string optional
last_modified_dts_end Last modified date end query string optional
signup_dts_start Signup date start query string optional
signup_dts_end Signup date end query string optional
billing_first_name Billing first name query string optional
billing_last_name Billing last name query string optional
billing_company Billing company query string optional
billing_city Billing city query string optional
billing_state Billing state query string optional
billing_postal_code Billing postal code query string optional
billing_country_code Billing country code query string optional
billing_day_phone Billing day phone query string optional
billing_evening_phone Billing evening phone query string optional
shipping_first_name Shipping first name query string optional
shipping_last_name Shipping last name query string optional
shipping_company Shipping company query string optional
shipping_city Shipping city query string optional
shipping_state Shipping state query string optional
shipping_postal_code Shipping postal code query string optional
shipping_country_code Shipping country code query string optional
shipping_day_phone Shipping day phone query string optional
shipping_evening_phone Shipping evening phone query string optional
pricing_tier_oid Pricing tier oid query integer (int32) optional
pricing_tier_name Pricing tier name query string optional
_limit The maximum number of records to return on this one API call. (Max 200)
Default: 100
query integer optional
_offset Pagination of the record set. Offset is a zero based index.
Default: 0
query integer optional
_since Fetch customers that have been created/modified since this date/time. query dateTime optional
_sort The sort order of the customers. See Sorting documentation for examples of using multiple values and sorting by ascending and descending.
Allowed Values
  • customer_profile_id
  • billing.first_name
  • billing.last_name
  • billing.city
  • billing.state_region
  • billing.postal_code
  • billing.country_code
  • billing.day_phone
  • email
  • billing.evening_phone
  • last_modified_dts
  • last_modified_by
query string optional
_expand The object expansion to perform on the result. See documentation for examples query string optional
Responses
Status Code Reason Response Model
200
Successful response CustomersResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Insert a customer

Permissions:
  • customer_write

Consumes: application/json
Produces: application/json
post
/customer/customers

Insert a customer on the UltraCart account.

Parameters
Parameter Description Location Data Type Required
customer Customer to insert body Customer required
Responses
Status Code Reason Response Model
200
Successful response CustomerResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Delete a customer

Permissions:
  • customer_write

Consumes: application/json
Produces: application/json
delete
/customer/customers/{customer_profile_oid}

Delete a customer on the UltraCart account.

Parameters
Parameter Description Location Data Type Required
customer_profile_oid The customer_profile_oid to delete. path integer (int32) required
Responses
Status Code Reason Response Model
200
Successful response CustomerResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Retrieve a customer

Permissions:
  • customer_read

Produces: application/json
get
/customer/customers/{customer_profile_oid}

Retrieves a single customer using the specified customer profile oid.

Parameters
Parameter Description Location Data Type Required
customer_profile_oid The customer oid to retrieve. path integer (int32) required
_expand The object expansion to perform on the result. See documentation for examples query string optional
Responses
Status Code Reason Response Model
200
Successful response CustomerResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Update a customer

Permissions:
  • customer_write

Consumes: application/json
Produces: application/json
put
/customer/customers/{customer_profile_oid}

Update a customer on the UltraCart account.

Parameters
Parameter Description Location Data Type Required
customer Customer to update body Customer required
customer_profile_oid The customer_profile_oid to update. path integer (int32) required
Responses
Status Code Reason Response Model
200
Successful response CustomerResponse
400
Bad Request 400
401
Unauthorized 401
410
Authorized Application Disabled 410
429
Too Many Requests 429
500
Server Side 500

Webhooks

The following webhook events are generated for this resource.

Event Description Response Expansion
customer_create Trigger when a customer is created Customer Yes
customer_delete Trigger when a customer is deleted Customer Yes
customer_update Trigger when a customer is updated Customer Yes

Customer

Attributes
Name Data Type Description
affiliate_oid integer (int32) Affiliate oid
allow_3rd_party_billing boolean Allow 3rd party billing
allow_cod boolean Allow COD
allow_purchase_order boolean Allow purchase orders by this customer
allow_quote_request boolean Allow quote request
allow_selection_of_address_type boolean Allow selection of residential or business address type
auto_approve_cod boolean Auto approve COD
auto_approve_purchase_order boolean Auto approve purchase orders by this customer
automatic_merchant_notes string Automatic merchant notes are added to every order placed
billing array of CustomerBilling Billing addresses for this customer
business_notes string(2000) Business notes (internally visible only)
cards array of CustomerCard Credit Cards for this customer
customer_profile_oid (read only) integer (int32) Customer profile object identifier
dhl_account_number string(20) DHL account number
email string Email address of this customer profile
exempt_shipping_handling_charge boolean Exempt shipping handling charge
fedex_account_number string(20) FedEx account number
free_shipping boolean This customer always receives free shipping
free_shipping_minimum number If free_shipping is true, this is the minimum subtotal required for free shipping
last_modified_by (read only) string(100) Last modified by
last_modified_dts (read only) string(25) Last modified date
maximum_item_count integer (int32) Maximum item count
minimum_item_count integer (int32) Minimum item count
minimum_subtotal number Minimum subtotal
no_coupons boolean No coupons
no_free_shipping boolean No free shipping regardless of coupons or item level settings
no_realtime_charge boolean No realtime charge
password string(30) Password (may only be set, never read)
pricing_tiers array of CustomerPricingTier Pricing tiers for this customer
qb_class string QuickBooks class to import this customer as
qb_code string QuickBooks name to import this customer as
referral_source string(50) Referral Source
sales_rep_code string(10) Sales rep code
send_signup_notification boolean Send signup notification, if true during customer creation, will send a notification.
shipping array of CustomerShipping Shipping addresses for this customer
signup_dts (read only) string Signup date
suppress_buysafe boolean Suppress buySAFE
tax_exempt boolean True if the customer is tax exempt
tax_id string(15) Tax ID
terms string Terms for this customer
track_separately boolean True if the customer should be tracked separately in QuickBooks
unapproved boolean Unapproved
ups_account_number string(20) UPS account number
website_url string(100) Website url

CustomerBilling

Attributes
Name Data Type Description
address1 string(50) Address line 1
address2 string(50) Address line 2
city string(32) City
company string(50) Company
country_code string(2) ISO-3166 two letter country code
customer_billing_oid (read only) integer (int32) Customer profile billing object identifier
customer_profile_oid (read only) integer (int32) Customer profile object identifier
day_phone string(25) Day phone
default_billing boolean Default billing
evening_phone string(25) Evening phone
first_name string(30) First name
last_name string(30) Last name
last_used_dts string(25) Last used date
postal_code string(20) Postal code
state_region string(32) State for United States otherwise region or province for other countries
tax_county string(32) Tax County
title string(50) Title

CustomerCard

Attributes
Name Data Type Description
card_expiration_month integer (int32) Card expiration month (1-12)
card_expiration_year integer (int32) Card expiration year (four digit year)
card_number string Card number (masked to the last 4)
card_number_token string Hosted field token for the card number
card_type string Card type
customer_profile_credit_card_id integer (int32) ID of the stored credit card to use
customer_profile_oid (read only) integer (int32) Customer profile object identifier

CustomerPricingTier

Attributes
Name Data Type Description
name string(50) Name
pricing_tier_oid integer (int32) Pricing Tier Oid

CustomerResponse

Attributes
Name Data Type Description
customer Customer Customer
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful

CustomerShipping

Attributes
Name Data Type Description
address1 string(50) Address line 1
address2 string(50) Address line 2
city string(32) City
company string(50) Company
country_code string(2) ISO-3166 two letter country code
customer_profile_oid (read only) integer (int32) Customer profile object identifier
customer_shipping_oid (read only) integer (int32) Customer profile shipping object identifier
day_phone string(25) Day phone
default_shipping boolean Default shipping
evening_phone string(25) Evening phone
first_name string(30) First name
last_name string(30) Last name
last_used_dts string(25) Last used date
postal_code string(20) Postal code
state_region string(32) State for United States otherwise region or province for other countries
tax_county string(32) Tax County
title string(50) Title

CustomersResponse

Attributes
Name Data Type Description
customers array of Customer
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful

Error

Attributes
Name Data Type Description
developer_message string A technical message meant to be read by a developer
error_code string HTTP status code
more_info string Additional information often a link to additional documentation
user_message string An end-user friendly message suitable for display to the customer

ErrorResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful

ResponseMetadata

Attributes
Name Data Type Description
payload_name string Payload name
result_set ResultSet Result set

ResultSet

Attributes
Name Data Type Description
count integer (int32) Number of results in this set
limit integer (int32) Maximum number of results that can be returned in a set
more boolean True if there are more results to query
next_offset integer (int32) The next offset that you should query to retrieve more results
offset integer (int32) Offset of this result set (zero based)
total_records integer (int32) The total number of records in the result set. May be null if the number is not known and the client should continue iterating as long as more is true.

400
Status Code 400: bad request input such as invalid json

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

401
Status Code 401: invalid credentials supplied

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

410
Status Code 410: Your authorized application has been disabled by UltraCart

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

429
Status Code 429: you have exceeded the allowed API call rate limit for your application.

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

500
Status Code 500: any server side error. the body will contain a generic server error message

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse