Customers

Customers are the people who place orders with your bakery. This page covers the customer endpoints for managing your customer database.

The customer model

Properties

Name
id
Type
string
Description
Unique identifier for the customer.
Name
first_name
Type
string
Description
Customer's first name.
Name
last_name
Type
string
Description
Customer's last name.
Name
contact
Type
object
Description
Contact details including email, phone, and address.
Name
company
Type
string
Description
Company or business name (for B2B customers).
Name
tags
Type
array
Description
Tags for categorizing customers (e.g., "vip", "wholesale").
Name
total_orders
Type
integer
Description
Number of orders placed by this customer.
Name
total_spent
Type
number
Description
Total amount spent across all orders.
Name
is_blacklisted
Type
boolean
Description
Whether the customer is blacklisted.
Name
created_at
Type
timestamp
Description
When the customer was created.

GET/api/v1/customers

List all customers

Retrieve a paginated list of customers.

Query parameters

Name
limit
Type
integer
Description
Number of customers to return (default: 50, max: 100).
Name
cursor
Type
string
Description
Pagination cursor.
Name
search
Type
string
Description
Search by name, email, or phone.
Name
created_after
Type
string
Description
Filter by creation date (ISO 8601).
Name
sort
Type
string
Description
Sort field: createdAt, name, email. Prefix with - for descending.

Request

GET

/api/v1/customers

curl -G https://api.ibakepro.com/api/v1/customers \
  -H "Authorization: Bearer {api_key}" \
  -d search=smith \
  -d limit=20

Response

{
  "success": true,
  "data": [
    {
      "id": "cust_xyz789",
      "first_name": "John",
      "last_name": "Smith",
      "full_name": "John Smith",
      "email": "john.smith@email.com",
      "phone": "0412345678",
      "company": null,
      "total_orders": 12,
      "total_spent": 1450.00,
      "is_blacklisted": false,
      "tags": ["regular"],
      "created": "2024-06-15T09:00:00Z",
      "source": "app"
    }
  ],
  "pagination": {
    "limit": 20,
    "has_more": false
  }
}

POST/api/v1/customers

Create a customer

Create a new customer.

Required attributes

Name
first_name
Type
string
Description
Customer's first name.

Optional attributes

Name
last_name
Type
string
Description
Customer's last name.
Name
contact
Type
object
Description
Contact details with email, phone, and mobile.
Name
address
Type
object
Description
Customer's address (see address format below).
Name
company
Type
string
Description
Company or business name.
Name
tags
Type
array
Description
Array of tags for categorization.
Name
external_id
Type
string
Description
Your external reference ID.

Address format

You can provide the address as either a string or structured object. The API will geocode the address via Google to get coordinates.

As a string:

"address": "456 Oak Ave, Melbourne, VIC 3000, Australia"

As an object:

Name
address.street
Type
string
Description
Street address.
Name
address.street2
Type
string
Description
Unit, apartment, or additional line.
Name
address.city
Type
string
Description
City or suburb.
Name
address.state
Type
string
Description
State or province abbreviation.
Name
address.postcode
Type
string
Description
Postal or ZIP code.
Name
address.country
Type
string
Description
Country name or code.

Response includes (auto-populated via geocoding):

formatted_address - Google's formatted address string
latitude / longitude - Coordinates for mapping
place_id - Google Places ID
geocode_failed - Boolean indicating if geocoding failed (address still saved)

Geocoding failure handling: If geocoding fails, the address is still saved with geocode_failed: true. The response will include a warnings array with details.

Request

POST

/api/v1/customers

curl -X POST https://api.ibakepro.com/api/v1/customers \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Emma",
    "last_name": "Wilson",
    "contact": {
      "email": "emma.wilson@techcorp.com.au",
      "phone": "0398765432"
    },
    "company": "TechCorp Australia",
    "address": {
      "street": "100 Collins Street",
      "city": "Melbourne",
      "state": "VIC",
      "postcode": "3000",
      "country": "Australia"
    },
    "tags": ["corporate", "wholesale"]
  }'

Response

{
  "success": true,
  "data": {
    "id": "cust_emma01",
    "first_name": "Emma",
    "last_name": "Wilson",
    "contact": {
      "email": "emma.wilson@techcorp.com.au",
      "phone": "0398765432"
    },
    "company": "TechCorp Australia",
    "address": {
      "street": "100 Collins Street",
      "city": "Melbourne",
      "state": "VIC",
      "postcode": "3000",
      "country": "Australia",
      "formatted_address": "100 Collins Street, Melbourne VIC 3000, Australia",
      "latitude": -37.8136,
      "longitude": 144.9631,
      "place_id": "ChIJ90260rVG1moRkM2MIXVWBAQ",
      "geocode_failed": false
    },
    "tags": ["corporate", "wholesale"],
    "dates": {
      "created": "2025-01-15T14:30:00Z"
    }
  }
}

Response (geocoding failed)

{
  "success": true,
  "data": {
    "id": "cust_emma01",
    "first_name": "Emma",
    "last_name": "Wilson",
    "address": {
      "street": "100 Collins Street",
      "city": "Melbourne",
      "state": "VIC",
      "postcode": "3000",
      "country": "Australia",
      "formatted_address": "100 Collins Street, Melbourne VIC 3000, Australia",
      "latitude": null,
      "longitude": null,
      "place_id": null,
      "geocode_failed": true
    }
  },
  "warnings": [
    {
      "code": "geocode_failed",
      "message": "Address was saved but could not be geocoded. Coordinates are not available.",
      "field": "address"
    }
  ]
}

GET/api/v1/customers/:id

Retrieve a customer

Get a single customer by ID with full details.

Request

GET

/api/v1/customers/cust_xyz789

curl https://api.ibakepro.com/api/v1/customers/cust_xyz789 \
  -H "Authorization: Bearer {api_key}"

PATCH/api/v1/customers/:id

Update a customer

Update an existing customer. Only include fields you want to change.

Request

PATCH

/api/v1/customers/cust_xyz789

curl -X PATCH https://api.ibakepro.com/api/v1/customers/cust_xyz789 \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": {
      "email": "john.smith@newdomain.com"
    },
    "tags": ["vip", "regular"]
  }'

POST/api/v1/customers/:id/geocode

Geocode a customer address

Geocode or re-geocode a customer's address. Use this to manually trigger geocoding for a customer, either with their existing address or a new address string.

Optional attributes

Name
address
Type
string
Description
New address to geocode. If not provided, the existing address will be re-geocoded.

Response

Name
success
Type
boolean
Description
Whether geocoding was successful.
Name
address
Type
object
Description
The geocoded address with coordinates.

Request

POST

/api/v1/customers/cust_xyz789/geocode

curl -X POST https://api.ibakepro.com/api/v1/customers/cust_xyz789/geocode \
  -H "Authorization: Bearer {api_key}"

Response

{
  "success": true,
  "address": {
    "street": "42 George Street",
    "city": "Sydney",
    "state": "NSW",
    "postcode": "2000",
    "country": "Australia",
    "formatted_address": "42 George Street, Sydney NSW 2000, Australia",
    "latitude": -33.8688,
    "longitude": 151.2093,
    "place_id": "ChIJP3Sa8ziYEmsRUKgyFmh9AQM",
    "geocode_status": "success",
    "geocoded_at": "2025-01-15T14:30:00Z"
  }
}

Error Response (422)

{
  "success": false,
  "error": "Could not geocode address. Please check the address and try again.",
  "original_address": "Invalid Address String"
}