Orders

Orders are at the heart of ibakepro. This page covers the order endpoints you can use to create, retrieve, and update orders programmatically.

The order model

The order model contains all the information about customer orders, including items, pricing, payment status, and delivery details.

Properties

Name
id
Type
string
Description
Unique identifier for the order.
Name
order_number
Type
integer
Description
Sequential order number.
Name
friendly_order_number
Type
string
Description
Display-friendly order number (e.g., "#1001").
Name
status
Type
string
Description
Order status: pending, confirmed, in_progress, ready, delivered, cancelled.
Name
payment_status
Type
string
Description
Payment status: pending, partial, paid, refunded.
Name
customer_id
Type
string
Description
Reference to the customer who placed the order.
Name
items
Type
array
Description
Array of order items with product details, quantities, and prices.
Name
pricing
Type
object
Description
Pricing breakdown including subtotal, tax, discount, and total.
Name
payment
Type
object
Description
Payment details including method, amount paid, and balance.
Name
dates
Type
object
Description
Important dates including event date and due date.
Name
delivery
Type
object
Description
Delivery information including type, address, date, time, and notes.
Name
notes
Type
object
Description
Public notes (visible to customer) and private notes (internal only).
Name
created_at
Type
timestamp
Description
When the order was created.
Name
updated_at
Type
timestamp
Description
When the order was last updated.

GET/api/v1/orders

List all orders

Retrieve a paginated list of orders. By default, orders are sorted by creation date (newest first).

Query parameters

Name
limit
Type
integer
Description
Number of orders to return (default: 50, max: 100).
Name
cursor
Type
string
Description
Pagination cursor for fetching the next page.
Name
status
Type
string
Description
Filter by status. Comma-separated for multiple (e.g., confirmed,in_progress).
Name
customer_id
Type
string
Description
Filter orders by customer ID.
Name
created_after
Type
string
Description
Filter orders created after this date (ISO 8601).
Name
created_before
Type
string
Description
Filter orders created before this date (ISO 8601).
Name
sort
Type
string
Description
Sort field. Prefix with - for descending. Options: createdAt, eventDate, total.

Request

GET

/api/v1/orders

curl -G https://api.ibakepro.com/api/v1/orders \
  -H "Authorization: Bearer {api_key}" \
  -d status=confirmed \
  -d limit=10

Response

{
  "success": true,
  "data": [
    {
      "id": "ord_abc123",
      "order_number": 1001,
      "friendly_order_number": "#1001",
      "status": "confirmed",
      "payment_status": "paid",
      "customer_name": "John Smith",
      "customer_id": "cust_xyz789",
      "items_count": 3,
      "total": 125.00,
      "currency": "AUD",
      "event_date": "2025-02-14",
      "delivery_type": "delivery",
      "created": "2025-01-15T10:30:00Z",
      "source": "app"
    }
  ],
  "pagination": {
    "limit": 10,
    "has_more": true,
    "next_cursor": "eyJpZCI6Im9yZF9hYmMxMjMifQ"
  }
}

POST/api/v1/orders

Create an order

Create a new order. At minimum, you need to provide items or a customer reference.

Required attributes

Name
items
Type
array
Description
Array of order items. Each item should have product_id, quantity, and unit_price.

Optional attributes

Name
customer_id
Type
string
Description
Reference to an existing customer.
Name
status
Type
string
Description
Initial order status (default: pending).
Name
pricing
Type
object
Description
Pricing details: subtotal, tax, discount, total.
Name
payment
Type
object
Description
Payment info: method, status, amount_paid.
Name
dates
Type
object
Description
Important dates: event, due.
Name
delivery
Type
object
Description
Delivery details: type (pickup or delivery), date, time, fee, notes, and address object.
Name
notes
Type
object
Description
Notes: public (customer-visible), private (internal).
Name
external_id
Type
string
Description
Your external reference ID for this order.

Delivery 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 and validate it.

As a string:

"address": "123 Main Street, Sydney, NSW 2000, Australia"

As an object:

Name
address.street
Type
string
Description
Street address (e.g., "123 Main Street").
Name
address.city
Type
string
Description
City or suburb name.
Name
address.state
Type
string
Description
State or province abbreviation (e.g., "NSW", "VIC", "CA").
Name
address.postcode
Type
string
Description
Postal or ZIP code.
Name
address.country
Type
string
Description
Country name (optional, defaults to tenant's country).

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/orders

curl -X POST https://api.ibakepro.com/api/v1/orders \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_xyz789",
    "items": [
      {
        "product_id": "prod_choc_cake_8",
        "name": "Chocolate Birthday Cake (8\")",
        "quantity": 1,
        "unit_price": 85.00
      },
      {
        "product_id": "prod_cupcake_6pk",
        "name": "Vanilla Cupcakes (6 pack)",
        "quantity": 1,
        "unit_price": 30.00
      }
    ],
    "pricing": {
      "subtotal": 115.00,
      "total": 115.00
    },
    "dates": {
      "event": "2025-02-14"
    },
    "delivery": {
      "type": "delivery",
      "date": "2025-02-14",
      "time": "10:00",
      "fee": 15.00,
      "address": {
        "street": "42 George Street",
        "city": "Sydney",
        "state": "NSW",
        "postcode": "2000"
      }
    },
    "notes": {
      "public": "Happy Birthday Sarah!"
    }
  }'

Response

{
  "success": true,
  "data": {
    "id": "ord_def456",
    "order_number": 1002,
    "friendly_order_number": "#1002",
    "status": "pending",
    "customer_id": "cust_xyz789",
    "items": [...],
    "pricing": {
      "subtotal": 115.00,
      "discount": 0,
      "total": 115.00
    },
    "delivery": {
      "fee": 15.00
    },
    "created_at": "2025-01-15T14:00:00Z"
  }
}

GET/api/v1/orders/:id

Retrieve an order

Retrieve a single order by its ID. Returns the full order details including all items, pricing, and notes.

Request

GET

/api/v1/orders/ord_abc123

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

Response

{
  "success": true,
  "data": {
    "id": "ord_abc123",
    "order_number": 1001,
    "friendly_order_number": "#1001",
    "status": "confirmed",
    "payment_status": "paid",
    "customer": {
      "id": "cust_xyz789",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@email.com"
    },
    "items": [
      {
        "id": "item_1",
        "product_id": "prod_choc_cake_8",
        "name": "Chocolate Birthday Cake (8\")",
        "quantity": 1,
        "unit_price": 85.00,
        "total": 85.00
      },
      {
        "id": "item_2",
        "product_id": "prod_cupcake_6pk",
        "name": "Vanilla Cupcakes (6 pack)",
        "quantity": 1,
        "unit_price": 30.00,
        "total": 30.00
      },
      {
        "id": "item_3",
        "product_id": "prod_candles",
        "name": "Birthday Candles Set",
        "quantity": 1,
        "unit_price": 10.00,
        "total": 10.00
      }
    ],
    "pricing": {
      "subtotal": 125.00,
      "tax": 0,
      "discount": 0,
      "total": 125.00
    },
    "payment": {
      "method": "card",
      "status": "paid",
      "amount_paid": 125.00,
      "balance": 0
    },
    "dates": {
      "event": "2025-02-14",
      "due": "2025-02-13"
    },
    "delivery": {
      "type": "delivery",
      "date": "2025-02-14",
      "time": "10:00",
      "fee": 15.00,
      "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_failed": false
      },
      "notes": "Leave at front desk if not home"
    },
    "notes": {
      "public": "Happy Birthday Sarah!",
      "private": "Regular customer - priority delivery"
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:35:00Z"
  }
}

Response (geocoding failed)

{
  "success": true,
  "data": {
    "id": "ord_abc123",
    "delivery": {
      "type": "delivery",
      "address": {
        "street": "42 George Street",
        "city": "Sydney",
        "state": "NSW",
        "postcode": "2000",
        "formatted_address": "42 George Street, Sydney NSW 2000",
        "latitude": null,
        "longitude": null,
        "place_id": null,
        "geocode_failed": true
      }
    }
  },
  "warnings": [
    {
      "code": "geocode_failed",
      "message": "Delivery address was saved but could not be geocoded. Coordinates are not available.",
      "field": "delivery.address"
    }
  ]
}

PATCH/api/v1/orders/:id

Update an order

Update an existing order. Only include the fields you want to update.

Optional attributes

Name
status
Type
string
Description
Update the order status.
Name
items
Type
array
Description
Replace the order items.
Name
pricing
Type
object
Description
Update pricing details.
Name
payment
Type
object
Description
Update payment information.
Name
dates
Type
object
Description
Update event or due dates.
Name
delivery
Type
object
Description
Update delivery details: type, date, time, fee, notes, and address.
Name
notes
Type
object
Description
Update public or private notes.

Request

PATCH

/api/v1/orders/ord_abc123

curl -X PATCH https://api.ibakepro.com/api/v1/orders/ord_abc123 \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "notes": {
      "private": "Started baking at 2pm"
    }
  }'

Response

{
  "success": true,
  "data": {
    "id": "ord_abc123",
    "status": "in_progress",
    "notes": {
      "public": "Happy Birthday Sarah!",
      "private": "Started baking at 2pm"
    },
    "updated_at": "2025-01-15T14:00:00Z"
  }
}

POST/api/v1/orders/batch

Batch create orders

Create multiple orders in a single request. Useful for importing orders from external systems.

Request body

Name
orders
Type
array
Description
Array of order objects (same format as single order creation). Maximum 100 orders per request.

Request

POST

/api/v1/orders/batch

curl -X POST https://api.ibakepro.com/api/v1/orders/batch \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "customer_id": "cust_1",
        "items": [{"product_id": "prod_1", "quantity": 1, "unit_price": 50}],
        "pricing": {"total": 50}
      },
      {
        "customer_id": "cust_2",
        "items": [{"product_id": "prod_2", "quantity": 2, "unit_price": 30}],
        "pricing": {"total": 60}
      }
    ]
  }'

Response

{
  "success": true,
  "data": {
    "created": 2,
    "failed": 0,
    "orders": [
      { "id": "ord_new1", "order_number": 1003 },
      { "id": "ord_new2", "order_number": 1004 }
    ]
  }
}