/client/orders

Path: /client/orders
Namespace: client
Resource: orders

Overview

The Order resource in the client namespace provides customer self-service access to purchase orders and invoices. Customers can view their orders, track status, and manage their purchases.

Note: Orders are invoices in ERPax. The client namespace provides a customer-facing interface to the unified Invoice model.

Key Difference from Admin: In the client namespace, the user address is automatically used as buyer, and the seller must be from host addresses.

Relationships

See Admin Invoices for complete relationship documentation. Client orders use the same Invoice model with namespace-specific behavior.

Namespace-Specific Relationship Behavior

Buyer Assignment (Automatic)

• Type: Automatic assignment
• Description: In the client namespace, the user's address is automatically set as buyer_id when creating orders. This ensures customers only create orders for themselves.
• API Access:
  • Direct: buyer_id is automatically set to user.address_id
  • Filter: GET /client/orders.json?q[buyer_id_eq]=user_address_id (only returns user's own orders)
• Example: Create order with automatic buyer assignment:

  const order = await fetch('/client/orders.json', {
    method: 'POST',
    credentials: 'include',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    body: JSON.stringify({
      order: {
        invoice_type: 'cart',
        seller_id: 5, // Must be from host addresses
        // buyer_id omitted - user.address_id used automatically
        date: '2024-01-15'
      }
    })
  }).then(r => r.json());
  // order.buyer_id is automatically set to user.address_id

Seller Restriction

• Type: Access restriction
• Description: In the client namespace, sellers must be from host addresses. Customers can only purchase from approved host addresses.
• API Access: Seller ID must belong to host addresses
• Validation: Server validates seller_id belongs to host addresses
• Related Documentation: Admin Invoices - Address Relationships

Order Access Scope

• Type: Access restriction
• Description: In the client namespace, customers can only access their own orders (where buyer_id equals their address ID).
• API Access:
  • List: GET /client/orders.json - Only returns user's own orders
  • Show: GET /client/orders/:id.json - Only accessible if order belongs to user
• Example: Get user's orders (automatically filtered):

  const orders = await fetch('/client/orders.json', {
    credentials: 'include',
    headers: { 'Accept': 'application/json' }
  }).then(r => r.json());
  // Only returns orders where buyer_id equals user.address_id

Key Features

• Automatic Buyer Assignment: User address is automatically used as buyer
• Customer Self-Service: Customers can view and manage their own orders
• Limited Access: Access is restricted to customer's own orders
• Same Invoice Model: Uses the same unified Invoice model as admin namespace

Available Operations

List Orders (GET)

Endpoint: GET /client/orders.json

Query Parameters:

• q[field_predicate]=value - Ransack query filters for advanced filtering
• scope=name - Apply named scope (e.g., unpaid, due, confirmed)
• page=N - Page number for pagination
• per_page=N - Items per page (default: 25)

Request Examples:

curl -X GET "https://your-company.erpax.com/client/orders.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

curl -X GET "https://your-company.erpax.com/client/orders.json?scope=unpaid" \
  -H "Accept: application/json"

JavaScript Example:

const response = await fetch('/client/orders.json', {
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
});
const data = await response.json();

Response (200 OK):

{
  "orders": [
    {
      "id": 1,
      "invoice_type": "cart",
      "number": null,
      "date": "2024-01-15",
      "seller_id": 5,
      "buyer_id": 2,
      "total_amount_cents": 100000,
      "confirmed": false
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 2,
    "total_count": 45
  }
}

Show Order (GET /:id)

Endpoint: GET /client/orders/:id.json

Request Example:

curl -X GET "https://your-company.erpax.com/client/orders/123.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

Response (200 OK):

{
  "order": {
    "id": 123,
    "invoice_type": "cart",
    "number": null,
    "date": "2024-01-15",
    "seller_id": 5,
    "buyer_id": 2,
    "total_amount_cents": 100000,
    "confirmed": false,
    "invoice_lines": [...]
  }
}

Create Order (POST)

Endpoint: POST /client/orders.json

Request Example:

curl -X POST "https://your-company.erpax.com/client/orders.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "order": {
      "invoice_type": "cart",
      "seller_id": 5,
      "date": "2024-01-15",
      "currency_code": "USD",
      "invoice_lines_attributes": [
        {
          "item_id": 1,
          "quantity": 2,
          "unit_price_cents": 10000
        }
      ]
    }
  }'

Note: In the client namespace, buyer_id is automatically set to the user address, so it should be omitted from the request. The seller_id must be from host addresses.

JavaScript Example:

const response = await fetch('/client/orders.json', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    order: {
      invoice_type: 'cart',
      seller_id: 5,
      date: '2024-01-15',
      currency_code: 'USD',
      invoice_lines_attributes: [
        {
          item_id: 1,
          quantity: 2,
          unit_price_cents: 10000
        }
      ]
    }
  })
});
const order = await response.json();

Response (201 Created):

{
  "order": {
    "id": 123,
    "invoice_type": "cart",
    "seller_id": 5,
    "buyer_id": 2,
    "date": "2024-01-15",
    "currency_code": "USD",
    "total_amount_cents": 20000,
    "confirmed": false,
    "created_at": "2024-01-15T14:30:00Z"
  }
}

Update Order (PATCH /:id)

Endpoint: PATCH /client/orders/:id.json

Request Example:

curl -X PATCH "https://your-company.erpax.com/client/orders/123.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "order": {
      "invoice_lines_attributes": [
        {
          "id": 1,
          "quantity": 3
        }
      ]
    }
  }'

Response (200 OK):

{
  "order": {
    "id": 123,
    "total_amount_cents": 30000,
    "updated_at": "2024-01-15T15:00:00Z"
  }
}

Delete Order (DELETE /:id)

Endpoint: DELETE /client/orders/:id.json

Request Example:

curl -X DELETE "https://your-company.erpax.com/client/orders/123.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

Response (204 No Content):

(empty response)

Member Actions

Custom actions available on individual orders via API:

Print Order

Endpoint: GET /client/orders/:id/print

Description: Generate and return a printable version of the order.

Request Example:

curl -X GET "https://your-company.erpax.com/client/orders/123/print" \
  -H "Accept: application/pdf" \
  -H "Cookie: session_cookie"

Response: Returns PDF or HTML printable version of the order.

Scopes

See Admin Invoices for complete scope documentation. Client namespace supports the same scopes as admin namespace, but filtered to the current user's orders.

Filters

See Admin Invoices for complete filter documentation. Client namespace supports the same filters as admin namespace, but filtered to the current user's orders.

Business Rules

• Automatic Buyer Assignment: User address is automatically used as buyer when creating orders
• Seller Restriction: Seller must be from host addresses
• Customer Access: Customers can only access their own orders
• Same Business Rules: Follows the same business rules as admin namespace invoices

Related Resources

• Admin Invoices - Complete invoice documentation (orders are invoices)
• Client Dashboard - Client namespace overview
• Client Addresses - Address management in client namespace
• Client Items - Item management in client namespace