Products API

🚀 Why Use the Products API?

Products are essential inventory items in DataDocks that you manage across warehouses. The Products API enables you to programmatically synchronize your product catalog with DataDocks, ensuring real-time accuracy and consistency between your inventory management systems and warehousing operations.

Real Problems This API Solves

Maintain inventory accuracy: Keep product data synchronized between your ERP and DataDocks
Streamline receiving operations: Ensure products are properly identified during receiving
Enhance packing list creation: Quickly add valid products to packing lists
Improve reporting: Track product movement through warehouses with consistent product data
Eliminate duplicate data entry: Update products once in your system and automatically sync to DataDocks

5-Minute Quickstart

Want to see the API in action right now? Follow these steps to get your first product created:

Get your API token from support
Find your location subdomain (e.g., your-warehouse.datadocks.com)
Create a basic product with this command:

See cURL example

curl -X POST \
  https://your-warehouse.datadocks.com/api/v1/products \
  -H 'Authorization: Token YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "product": {
      "name": "Premium Widget",
      "sku": "WIDGET-001"
    }
  }'

Voilà! You've created your first product. Check your DataDocks dashboard to see it.

API Architecture Overview

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│  Your System    │──────▶│  DataDocks API  │──────▶│  Warehouse Ops  │
│  (ERP/WMS)      │◀──────┤   (REST/JSON)   │◀──────┤  (Products)     │
└─────────────────┘       └─────────────────┘       └─────────────────┘
                                  │  ▲
                                  │  │
                                  ▼  │
                           ┌─────────────────┐
                           │  Packing Lists  │
                           │  & Appointments │
                           └─────────────────┘

Authentication

All API requests must include your API token in the Authorization header:

Authorization: Token YOUR_API_TOKEN

Listing Products

Purpose

Retrieve a paginated list of products with optional filtering by name or SKU. Use this endpoint to search your product catalog, synchronize with external systems, or populate dropdown menus in your applications.

Business Use Cases

Sync products with your ERP or WMS system
Populate product selection interfaces in your applications
Generate inventory reports
Verify product data during order processing

HTTP Request

GET https://[location_subdomain].datadocks.com/api/v1/products

Query Parameters

Parameter	Type	Required	Description	Example
`page`	Integer	No	Page number for pagination (defaults to 1)	`page=2`
`name`	String	No	Filter by product name (case-insensitive, starts with)	`name=widget`
`sku`	String	No	Filter by product SKU (case-insensitive, exact match)	`sku=ABC123`

Response Format

The response contains a paginated array of product objects, each with the following fields:

Field	Type	Description
`id`	Integer	Unique identifier for the product
`name`	String	Name of the product
`sku`	String	Stock Keeping Unit code for the product

Code Examples

cURL

See cURL example

# Basic listing
curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://YOUR_LOCATION.datadocks.com/api/v1/products

# Filtered by name
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://YOUR_LOCATION.datadocks.com/api/v1/products?name=premium"

# Filtered by SKU
curl -H "Authorization: Token YOUR_API_TOKEN" \
     "https://YOUR_LOCATION.datadocks.com/api/v1/products?sku=WIDGET-001"

JavaScript

See JavaScript example

// Using fetch API with filters
const getProducts = async (nameFilter, skuFilter) => {
  const params = new URLSearchParams();
  if (nameFilter) params.append("name", nameFilter);
  if (skuFilter) params.append("sku", skuFilter);

  const response = await fetch(
    `https://YOUR_LOCATION.datadocks.com/api/v1/products?${params.toString()}`,
    {
      method: "GET",
      headers: {
        Authorization: "Token YOUR_API_TOKEN",
        "Content-Type": "application/json",
      },
    }
  );

  // Handle potential errors
  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(`Failed to fetch products: ${JSON.stringify(errorData)}`);
  }

  return response.json();
};

Sample Response

See sample response example

[
  {
    "id": 1,
    "name": "Premium Widget",
    "sku": "WIDGET-001"
  },
  {
    "id": 2,
    "name": "Standard Widget",
    "sku": "WIDGET-002"
  },
  {
    "id": 3,
    "name": "Widget Accessories",
    "sku": "WIDGET-ACC-001"
  }
]

Pagination

The response is paginated to manage data volume. For detailed information about pagination headers and navigation, please refer to the Pagination documentation.

Retrieving a Single Product

Purpose

Get detailed information about a specific product by ID. Use this endpoint when you need complete data about a particular product.

Business Use Cases

Display detailed product information in your application
Verify product details before adding to a packing list
Retrieve current product data for inventory management

HTTP Request

GET https://[location_subdomain].datadocks.com/api/v1/products/:id

Path Parameters

Parameter	Type	Required	Description
`id`	Integer	Yes	Unique ID of the product

Response

A successful request returns a 200 OK response with the full product object in the same format as the list response.

Code Examples

cURL

See cURL example

curl -H "Authorization: Token YOUR_API_TOKEN" \
     https://YOUR_LOCATION.datadocks.com/api/v1/products/123

JavaScript

See JavaScript example

const getProduct = async (productId) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/products/${productId}`,
      {
        method: "GET",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
      }
    );

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`Product #${productId} not found`);
      }

      const errorData = await response.json();
      throw new Error(
        `Failed to retrieve product: ${JSON.stringify(errorData)}`
      );
    }

    return await response.json();
  } catch (error) {
    console.error("Error fetching product:", error);
    throw error;
  }
};

Creating a Product

Purpose

Add a new product to your DataDocks catalog. This endpoint allows you to create products that can then be used in packing lists and tracking inventory.

Decision Tree: When to Create a Product via API

┌─────────────────┐
│ Need to add a   │
│    product?     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     Yes     ┌─────────────────┐
│  Adding many    │────────────▶│   Consider      │
│  products at    │             │   bulk import   │
│     once?       │             │                 │
└────────┬────────┘             └─────────────────┘
         │ No
         ▼
┌─────────────────┐     Yes     ┌─────────────────┐
│ Is this a one-  │────────────▶│   Use the web   │
│ time addition?  │             │   interface     │
└────────┬────────┘             └─────────────────┘
         │ No
         ▼
┌─────────────────┐
│   Perfect for   │
│   the API!      │
└─────────────────┘

Business Use Cases

System Integration: Create products directly from your ERP or WMS
Automated Catalog Updates: Programmatically add new products to your warehouse
Data Migration: Transfer product records from legacy systems
Supplier Integration: Allow suppliers to register new products through your systems

HTTP Request

POST https://[location_subdomain].datadocks.com/api/v1/products

Request Body

Parameter	Type	Required	Description	Constraints	Example
`name`	String	Yes	Name of the product	Must not be empty	`"Premium Widget"`
`sku`	String	Yes	SKU of the product	Must be unique within the location	`"WIDGET-001"`

Response

A successful request returns a 200 OK response with the full product object, including the generated id.

Code Examples

cURL

See cURL example

curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "product": {
         "name": "Premium Widget",
         "sku": "WIDGET-001"
       }
     }' \
     https://YOUR_LOCATION.datadocks.com/api/v1/products

JavaScript

See JavaScript example

const createProduct = async (productData) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/products`,
      {
        method: "POST",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ product: productData }),
      }
    );

    if (!response.ok) {
      const errorData = await response.json();
      const errorMessages = Object.entries(errorData.errors || {})
        .map(([field, messages]) => `${field}: ${messages.join(", ")}`)
        .join("\n");

      throw new Error(`Failed to create product:\n${errorMessages}`);
    }

    return await response.json();
  } catch (error) {
    console.error("API Error:", error);
    throw error;
  }
};

// Example usage
const newProduct = {
  name: "Premium Widget",
  sku: "WIDGET-001",
};

createProduct(newProduct)
  .then((product) => console.log("Product created:", product))
  .catch((error) => console.error("Failed to create product:", error));

Updating a Product

Purpose

Update the details of an existing product. This endpoint allows you to modify any attribute of a product's information.

Business Use Cases

Keep Data Current: Update product names or SKUs when they change in your systems
Correct Errors: Fix typos or incorrect information in product data
Standardize Product Data: Update product information to match new naming conventions
Synchronize Systems: Keep DataDocks in sync with your inventory management system

HTTP Request

PUT https://[location_subdomain].datadocks.com/api/v1/products/:id

Path Parameters

Parameter	Type	Required	Description
`id`	Integer	Yes	Unique ID of the product

Request Body

The request body accepts the same parameters as the create endpoint. Only the fields you want to change need to be included.

Common Update Scenarios

Updating Product Name

{
  "product": {
    "name": "Premium Widget XL"
  }
}

Updating All Fields

{
  "product": {
    "name": "Premium Widget XL",
    "sku": "WIDGET-XL-001"
  }
}

Code Examples

cURL

See cURL example

curl -H "Authorization: Token YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -X PUT \
     -d '{
       "product": {
         "name": "Premium Widget XL"
       }
     }' \
     https://YOUR_LOCATION.datadocks.com/api/v1/products/123

JavaScript

See JavaScript example

const updateProduct = async (productId, updateData) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/products/${productId}`,
      {
        method: "PUT",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ product: updateData }),
      }
    );

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Failed to update product: ${JSON.stringify(errorData)}`);
    }

    return await response.json();
  } catch (error) {
    console.error("Error updating product:", error);
    throw error;
  }
};

// Example usage - updating just the name
const updateProductName = async (productId, newName) => {
  try {
    const updatedProduct = await updateProduct(productId, {
      name: newName,
    });

    console.log(`Successfully updated product #${updatedProduct.id} name`);
    return updatedProduct;
  } catch (error) {
    console.error(`Failed to update product #${productId}:`, error);
    throw error;
  }
};

Error Handling

Error Code	Description	Possible Cause
400	Bad Request	Invalid values or format
404	Not Found	Product ID doesn't exist
422	Unprocessable Entity	Validation failed (e.g., duplicate SKU)
401	Unauthorized	Invalid or missing API token
403	Forbidden	Insufficient permissions to update

Deleting a Product

Purpose

Remove a product from the system. This endpoint allows you to delete products that are no longer needed.

Important Considerations

Before deleting a product, consider the following:

The product must not be referenced by any active packing lists or appointments
Deletion is permanent and cannot be undone
In many cases, it's better to archive or deactivate a product rather than delete it

Business Use Cases

Clean Up Test Data: Remove test or dummy products
Remove Obsolete Products: Delete products that are no longer in your catalog
Remove Duplicate Records: Clean up after data de-duplication
System Maintenance: Remove old, unused product records

HTTP Request

DELETE https://[location_subdomain].datadocks.com/api/v1/products/:id

Path Parameters

Parameter	Type	Required	Description
`id`	Integer	Yes	Unique ID of the product

Response

A successful request returns a 204 No Content response, indicating that the product was deleted successfully.

Code Examples

cURL

See cURL example

curl -H "Authorization: Token YOUR_API_TOKEN" \
     -X DELETE \
     https://YOUR_LOCATION.datadocks.com/api/v1/products/123

JavaScript

See JavaScript example

const deleteProduct = async (productId) => {
  try {
    const response = await fetch(
      `https://YOUR_LOCATION.datadocks.com/api/v1/products/${productId}`,
      {
        method: "DELETE",
        headers: {
          Authorization: "Token YOUR_API_TOKEN",
        },
      }
    );

    if (!response.ok) {
      if (response.status === 404) {
        throw new Error(`Product #${productId} not found`);
      }

      const errorData = await response.json();
      throw new Error(`Failed to delete product: ${JSON.stringify(errorData)}`);
    }

    return true; // Successfully deleted
  } catch (error) {
    console.error("Error deleting product:", error);
    throw error;
  }
};

Error Handling

Error Code	Description	Possible Cause
404	Not Found	Product ID doesn't exist
401	Unauthorized	Invalid or missing API token
403	Forbidden	Insufficient permissions to delete
422	Unprocessable Entity	Cannot delete (e.g., has associated packing lists)

Field Validation Rules

When creating or updating products, the following validation rules apply:

Field	Validation Rules
`name`	Required, must not be empty
`sku`	Required, must be unique within the location

Best Practices

Data Management

Use Consistent SKUs: Maintain consistent SKU formats across systems
Validate Data Client-Side: Ensure data meets validation requirements before sending
Be Careful with Deletion: Consider SKU changes instead of deletion when possible
Batch Your Operations: When updating many products, consider bulk import options

Performance Optimization

Batch Your Updates: Group related product updates together
Use Pagination: Request only the products you need using pagination
Filter Efficiently: Use the available filters to minimize data transfer
Cache Common Lookups: Store frequently accessed product information locally

Common Gotchas and Troubleshooting

SKU Uniqueness: Product SKUs must be unique within a location. Ensure unique SKUs when creating products.
Product References: Products cannot be deleted if they are referenced by active packing lists or appointments.
Case Sensitivity: When searching products by name, the API performs a case-insensitive "starts with" match.
SKU Search: When searching products by SKU, the API performs a case-insensitive exact match.

Help and Support

If you're experiencing issues not covered in this documentation:

Check the error response: Most API errors include specific information about what went wrong
Verify permissions: Ensure your API token has sufficient permissions
Test in smaller steps: Break down complex operations to identify the specific issue

🚀 Why Use the Products API?​

Real Problems This API Solves​

5-Minute Quickstart​

API Architecture Overview​

Authentication​

Listing Products​

Purpose​

Business Use Cases​

HTTP Request​

Query Parameters​

Response Format​

Code Examples​

cURL​

JavaScript​

Sample Response​

Pagination​

Retrieving a Single Product​

Purpose​

Business Use Cases​

HTTP Request​

Path Parameters​

Response​

Code Examples​

cURL​

JavaScript​

Creating a Product​

Purpose​

Decision Tree: When to Create a Product via API​

Business Use Cases​

HTTP Request​

Request Body​

Response​

Code Examples​

cURL​

JavaScript​

Updating a Product​

Purpose​

Business Use Cases​

HTTP Request​

Path Parameters​

Request Body​

Common Update Scenarios​

Updating Product Name​

Updating All Fields​

Code Examples​

cURL​

JavaScript​

Error Handling​

Deleting a Product​

Purpose​

Important Considerations​

Business Use Cases​

HTTP Request​

Path Parameters​

Response​

Code Examples​

cURL​

JavaScript​

Error Handling​

Field Validation Rules​

Best Practices​

Data Management​

Performance Optimization​

Common Gotchas and Troubleshooting​

Help and Support​

🚀 Why Use the Products API?

Real Problems This API Solves

5-Minute Quickstart

API Architecture Overview

Authentication

Listing Products

Purpose

Business Use Cases

HTTP Request

Query Parameters

Response Format

Code Examples

cURL

JavaScript

Sample Response

Pagination

Retrieving a Single Product

Purpose

Business Use Cases

HTTP Request

Path Parameters

Response

Code Examples

cURL

JavaScript

Creating a Product

Purpose

Decision Tree: When to Create a Product via API

Business Use Cases

HTTP Request

Request Body

Response

Code Examples

cURL

JavaScript

Updating a Product

Purpose

Business Use Cases

HTTP Request

Path Parameters

Request Body

Common Update Scenarios

Updating Product Name

Updating All Fields

Code Examples

cURL

JavaScript

Error Handling

Deleting a Product

Purpose

Important Considerations

Business Use Cases

HTTP Request

Path Parameters

Response

Code Examples

cURL

JavaScript

Error Handling

Field Validation Rules

Best Practices

Data Management

Performance Optimization

Common Gotchas and Troubleshooting

Help and Support