/sales/items

Path: /sales/items
Namespace: sales
Resource: items

Overview

The Item resource in the sales namespace provides access to products and inventory items for sales operations. Items can be added to invoices and tracked for sales purposes.

Key Difference from Admin: Sales namespace provides sales-focused access to items for use in sales invoices.

Relationships

See Admin Items for complete relationship documentation. Sales items use the same Item model with sales-focused access.

Key Features

• Sales-Focused Access: Access to items for sales operations
• Product Catalog: Browse and manage products for sales
• Inventory Tracking: Track inventory for sales purposes
• Same Item Model: Uses the same unified Item model as admin namespace

Available Operations

List Items (GET)

Endpoint: GET /sales/items.json

Query Parameters:

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

Request Examples:

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

curl -X GET "https://your-company.erpax.com/sales/items.json?scope=in_stock" \
  -H "Accept: application/json"

JavaScript Example:

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

Response (200 OK):

{
  "items": [
    {
      "id": 1,
      "code": "PROD-001",
      "name": "Widget A",
      "price_cents": 10000,
      "inventory_quantity": 100,
      "created_at": "2024-01-10T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 5,
    "total_count": 123
  }
}

Show Item (GET /:id)

Endpoint: GET /sales/items/:id.json

Request Example:

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

Response (200 OK):

{
  "item": {
    "id": 1,
    "code": "PROD-001",
    "name": "Widget A",
    "description": "High-quality widget",
    "price_cents": 10000,
    "inventory_quantity": 100,
    "currency_code": "USD"
  }
}

Create Item (POST)

Endpoint: POST /sales/items.json

Request Example:

curl -X POST "https://your-company.erpax.com/sales/items.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "item": {
      "code": "PROD-002",
      "name": "Widget B",
      "price_cents": 20000,
      "inventory_quantity": 50,
      "currency_code": "USD"
    }
  }'

Response (201 Created):

{
  "item": {
    "id": 2,
    "code": "PROD-002",
    "name": "Widget B",
    "created_at": "2024-01-15T14:30:00Z"
  }
}

Update Item (PATCH /:id)

Endpoint: PATCH /sales/items/:id.json

Request Example:

curl -X PATCH "https://your-company.erpax.com/sales/items/1.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie" \
  -d '{
    "item": {
      "price_cents": 12000
    }
  }'

JavaScript Example:

const response = await fetch('/sales/items/1.json', {
  method: 'PATCH',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    item: {
      price_cents: 12000
    }
  })
});
const data = await response.json();

Response (200 OK):

{
  "item": {
    "id": 1,
    "price_cents": 12000,
    "updated_at": "2024-01-15T15:00:00Z"
  }
}

Delete Item (DELETE /:id)

Endpoint: DELETE /sales/items/:id.json

Request Example:

curl -X DELETE "https://your-company.erpax.com/sales/items/1.json" \
  -H "Accept: application/json" \
  -H "Cookie: session_cookie"

JavaScript Example:

const response = await fetch('/sales/items/1.json', {
  method: 'DELETE',
  credentials: 'include',
  headers: { 'Accept': 'application/json' }
});

Response (204 No Content):

(empty response)

Scopes

See Admin Items for complete scope documentation. Sales namespace supports the same scopes as admin namespace.

Filters

See Admin Items for complete filter documentation. Sales namespace supports the same filters as admin namespace.

Business Rules

• Sales-Focused Access: Access is limited to sales-related operations
• Product Catalog: Items are used in sales invoices
• Same Business Rules: Follows the same business rules as admin namespace items

Related Resources

• Admin Items - Complete item documentation with all features
• Sales Invoices - Add items to sales invoices
• Sales Addresses - Address management in sales namespace