Orders API

Base URL

All URLs referenced in the documentation have the following base:

https://api.meetandrock.com/v1/dev

Order Management

Endpoints for managing orders

List Orders

Retrieve orders for the project with pagination and search

curl -X GET "https://api.meetandrock.com/v1/dev/crm/orders?page=1&limit=10&search=notes&status=pending&customer_id=uuid&product_id=uuid" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters:
- page: Page number (default: 1)
- limit: Number of items per page (default: 10)
- search: Search term to filter by notes, billing_address, or shipping_address
- status: Filter by status (pending, processing, shipped, delivered, cancelled)
- customer_id: Filter by customer ID (UUID)
- product_id: Filter by product ID (UUID)

Response:
{
  "data": [
    {
      "id": "uuid",
      "customer_id": "uuid",
      "total_amount": 199.98,
      "status": "pending",
      "order_date": "2024-01-20T10:00:00.000Z",
      "shipping_address": "123 Main St, City, State 12345",
      "billing_address": "123 Main St, City, State 12345",
      "notes": "Please handle with care",
      "project_id": "uuid",
      "createdAt": "datetime",
      "updatedAt": "datetime",
      "customer": {
        "id": "uuid",
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "+1234567890",
        "company": "Acme Corp"
      },
      "orderItems": [
        {
          "id": "uuid",
          "order_id": "uuid",
          "product_id": "uuid",
          "quantity": 2,
          "unit_price": 99.99,
          "total_amount": 199.98,
          "product": {
            "id": "uuid",
            "name": "Premium Widget",
            "sku": "WID-001",
            "price": 99.99,
            "images": [
              {
                "id": "uuid",
                "url": "https://...",
                "name": "product-image.jpg"
              }
            ]
          }
        }
      ]
    }
  ],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 10
  }
}

Search: The search parameter searches across order notes, billing address, and shipping address fields.

Pagination: Use page and limit parameters to control pagination. The response includes pagination metadata.

Order Items: Each order can contain multiple items. The orderItems array contains all products in the order, each with its own quantity, unit_price, and total_amount.

Create Order

Create a new order. The total amount is automatically calculated based on product prices and quantities.

curl -X POST "https://api.meetandrock.com/v1/dev/crm/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "uuid",
    "items": [
      {
        "product_id": "uuid",
        "quantity": 2
      },
      {
        "product_id": "uuid",
        "quantity": 1
      }
    ],
    "status": "pending",
    "order_date": "2024-01-20T10:00:00.000Z",
    "shipping_address": "123 Main St, City, State 12345",
    "billing_address": "123 Main St, City, State 12345",
    "notes": "Please handle with care"
  }'

Response:
{
  "data": {
    "id": "uuid",
    "customer_id": "uuid",
    "total_amount": 299.97,
    "status": "pending",
    "order_date": "2024-01-20T10:00:00.000Z",
    "shipping_address": "123 Main St, City, State 12345",
    "billing_address": "123 Main St, City, State 12345",
    "notes": "Please handle with care",
    "project_id": "uuid",
    "createdAt": "datetime",
    "updatedAt": "datetime",
    "customer": {
      "id": "uuid",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "company": "Acme Corp"
    },
    "orderItems": [
      {
        "id": "uuid",
        "order_id": "uuid",
        "product_id": "uuid",
        "quantity": 2,
        "unit_price": 99.99,
        "total_amount": 199.98,
        "product": {
          "id": "uuid",
          "name": "Premium Widget",
          "sku": "WID-001",
          "price": 99.99,
          "images": [...]
        }
      },
      {
        "id": "uuid",
        "order_id": "uuid",
        "product_id": "uuid",
        "quantity": 1,
        "unit_price": 99.99,
        "total_amount": 99.99,
        "product": {
          "id": "uuid",
          "name": "Basic Widget",
          "sku": "WID-002",
          "price": 99.99,
          "images": [...]
        }
      }
    ]
  }
}

Required fields: customer_id, items (array with at least one item)

Items array: Each item must have product_id (UUID) and quantity (integer, min 1). You can include multiple products in a single order.

Optional fields: status, order_date, shipping_address, billing_address, notes

Status values: pending, processing, shipped, delivered, cancelled

Note: The unit_price and total_amount for each item are automatically calculated from the product price and quantity. The order's total_amount is the sum of all item totals. If order_date is not provided, it defaults to the current date.

Get Order

Retrieve a specific order by ID

curl -X GET "https://api.meetandrock.com/v1/dev/crm/orders/:orderId" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:
{
  "data": {
    "id": "uuid",
    "customer_id": "uuid",
    "total_amount": 199.98,
    "status": "pending",
    "order_date": "2024-01-20T10:00:00.000Z",
    "shipping_address": "123 Main St, City, State 12345",
    "billing_address": "123 Main St, City, State 12345",
    "notes": "Please handle with care",
    "project_id": "uuid",
    "createdAt": "datetime",
    "updatedAt": "datetime",
    "customer": {
      "id": "uuid",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "company": "Acme Corp"
    },
    "orderItems": [
      {
        "id": "uuid",
        "order_id": "uuid",
        "product_id": "uuid",
        "quantity": 2,
        "unit_price": 99.99,
        "total_amount": 199.98,
        "product": {
          "id": "uuid",
          "name": "Premium Widget",
          "sku": "WID-001",
          "price": 99.99,
          "images": [...]
        }
      }
    ]
  }
}

Update Order

Update an existing order. If items are provided, all existing order items will be replaced with the new items and the total amount will be recalculated.

curl -X PUT "https://api.meetandrock.com/v1/dev/crm/orders/:orderId" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "product_id": "uuid",
        "quantity": 3
      }
    ],
    "status": "processing",
    "shipping_address": "456 Oak Ave, City, State 67890",
    "notes": "Updated notes"
  }'

Response:
{
  "data": {
    "id": "uuid",
    "customer_id": "uuid",
    "total_amount": 299.97,
    "status": "processing",
    "order_date": "2024-01-20T10:00:00.000Z",
    "shipping_address": "456 Oak Ave, City, State 67890",
    "billing_address": "123 Main St, City, State 12345",
    "notes": "Updated notes",
    "project_id": "uuid",
    "createdAt": "datetime",
    "updatedAt": "datetime",
    "customer": {
      "id": "uuid",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "company": "Acme Corp"
    },
    "orderItems": [
      {
        "id": "uuid",
        "order_id": "uuid",
        "product_id": "uuid",
        "quantity": 3,
        "unit_price": 99.99,
        "total_amount": 299.97,
        "product": {
          "id": "uuid",
          "name": "Premium Widget",
          "sku": "WID-001",
          "price": 99.99,
          "images": [...]
        }
      }
    ]
  }
}

Note: If items array is provided, all existing order items will be deleted and replaced with the new items. The unit_price and total_amount for each item are automatically recalculated based on the product's current price. The order's total_amount is updated to reflect the sum of all item totals. You can update other fields (status, shipping_address, etc.) without providing items.

Delete Order

Delete an order

curl -X DELETE "https://api.meetandrock.com/v1/dev/crm/orders/:orderId" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response: 204 No Content

Pagination & Search

Query parameters for filtering and paginating orders

Query Parameters

page (optional)

Page number for pagination. Default: 1

?page=2

limit (optional)

Number of items per page. Default: 10

?limit=20

search (optional)

Search term that filters orders by notes, billing_address, or shipping_address (case-insensitive partial match)

?search=main street

status (optional)

Filter by order status. Values: pending, processing, shipped, delivered, cancelled

?status=pending

customer_id (optional)

Filter by customer ID (UUID)

?customer_id=550e8400-e29b-41d4-a716-446655440000

product_id (optional)

Filter by product ID (UUID). Returns orders that contain this product in their orderItems.

?product_id=550e8400-e29b-41d4-a716-446655440000

Example Requests

Get first page with default limit:

GET /crm/orders?page=1&limit=10

Search for orders:

GET /crm/orders?search=main street&page=1&limit=10

Filter by status:

GET /crm/orders?status=pending&page=1&limit=10

Filter by customer:

GET /crm/orders?customer_id=550e8400-e29b-41d4-a716-446655440000&page=1&limit=10

Combine search with filters:

GET /crm/orders?search=notes&status=processing&page=1&limit=20

Pagination Response

The response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "total": 150,
    "page": 1,
    "limit": 10
  }
}

total: Total number of orders matching the query
page: Current page number
limit: Number of items per page

Error Responses

400 Bad Request
{
  "message": "Invalid request parameters"
}

400 Bad Request (Validation Error)
{
  "message": "customer_id is required"
}

400 Bad Request (Validation Error)
{
  "message": "items must contain at least 1 item"
}

401 Unauthorized
{
  "message": "Invalid or missing API key"
}

404 Not Found
{
  "message": "Order not found"
}

404 Not Found
{
  "message": "Product with id {uuid} not found"
}

404 Not Found
{
  "message": "Customer not found"
}

500 Internal Server Error
{
  "message": "Something went wrong"
}