API Documentation: Products Import API

Table of Contents

1. Base URL
2. Authentication
3. Endpoints
   • Import Products
   • Check Import Status
4. Request and Response Formats
   • Import Products Request
   • Import Products Response
   • Import Status Response
5. Error Handling
6. Rate Limiting
7. Example Usage
   • Import Products Example
   • Check Import Status Example
8. Product Attributes
9. HTTP Status Codes
10. Changelog

Base URL

https://app.quotiza.com/api/v1

Authentication

All API requests require authentication using an API token associated with your account. The token must be included in the Authorization header of each request.

Authentication Header

Authorization: Bearer YOUR_API_TOKEN

• Replace YOUR_API_TOKEN with the API token provided for your account.

How to Obtain an API Token

• Log in to your account dashboard.
• Navigate to the API settings section.
• Generate a new API token or retrieve your existing token.

Important: Keep your API token secure. Do not share it publicly or expose it in client-side code.

Endpoints

1. Import Products

Import multiple products into your account asynchronously.

• URL: /products/import
• Method: POST
• Authentication: Required
• Content-Type: application/json

Parameters

• account_id (string, required): The ID of your account.
• products (array of objects, required): An array of product objects containing the product data to import.

2. Check Import Status

Retrieve the status and progress of an import job.

• URL: /products/import_status
• Method: GET
• Authentication: Required
• Content-Type: application/json

Parameters

• account_id (string, required): The ID of your account.
• job_id (string, required): The ID of the import job returned from the import request.

Request and Response Formats

Import Products Request

Endpoint: /products/import

Method: POST

Request Headers

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Request Body

{
  "account_id": "1",
  "products": [
    {
      "sku": "ABC123",
      "name": "Product Name",
      "description": "Product Description",
      "cost": 9.99,
      "upc": "123456789012",
      "brand": "Brand Name",
      "msrp": 19.99,
      "base_price": 14.99,
      "category": "Category Name",
      "active": true,
      "custom1_name": "Size",
      "custom1_value": "Medium",
      "custom2_name": "Color",
      "custom2_value": "Blue",
      "custom3_name": "Material",
      "custom3_value": "Cotton",
      "image_url": "https://example.com/image.jpg",
      "sales_unit": "Piece",
      "base_unit_of_measure": "Unit",
      "base_units_per_sales_unit": 1
    }, 
    // ... Add up to 1000 products
  ]
}

Notes:

• The products array can contain up to 1000 products per request.
• Each product object can include the attributes listed in the Product Attributes section.

Import Products Response

Success Response

• Status Code: 202 Accepted
• Content-Type: application/json

{
  "job_id": "123456"
}

Fields:

• job_id (string): The ID of the import job. Use this ID to check the status of your import.

Error Responses

• See Error Handling for details on possible error responses.

Import Status Response

Endpoint: /products/import_status

Method: GET

Request Headers

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Request Parameters

• Include account_id and job_id as query parameters or in the request body.

Example URL with Query Parameters:

https://app.quotiza.com.com/api/v1/products/import_status?account_id=1&job_id=123456

Success Response

• Status Code: 200 OK
• Content-Type: application/json

{
  "job_id": "123456",
  "status": "completed",
  "total": 100,
  "processed": 100,
  "successes": 95,
  "failures": 5,
  "errors": [
    {
      "line": 10,
      "sku": "DEF456",
      "message": "Validation failed: Name can't be blank"
    }
    // ... other errors
  ]
}

Fields:

• job_id (string): The ID of the import job.
• status (string): The current status of the job (pending, processing, completed, failed).
• total (integer): Total number of products in the import job.
• processed (integer): Number of products processed so far.
• successes (integer): Number of products successfully imported.
• failures (integer): Number of products that failed to import.
• errors (array of objects): Details of any errors that occurred during the import.

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of an API request. In addition to the status code, error responses include a JSON body with details about the error.

Error Response Format

{
  "error": {
    "code": "error_code",
    "message": "Error message",
    "status": http_status_code
  }
}

Common Error Codes and Messages

HTTP Status Code	Error Code	Message
400 Bad Request	invalid_products_data	Invalid products data
400 Bad Request	missing_account_id	account_id is required
401 Unauthorized	unauthorized	Authentication token is missing or invalid
404 Not Found	account_not_found	Account not found
404 Not Found	job_not_found	Job not found
413 Payload Too Large	too_many_products	Too many products. Maximum allowed is 1000.
429 Too Many Requests	throttle_limit_reached	Rate limit exceeded. Try again later.

Example Error Response

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication token is missing or invalid",
    "status": 401
  }
}

Rate Limiting

To ensure fair usage and protect the system from abuse, the API enforces rate limits on incoming requests.

Rate Limits

• Import Products Endpoint (/products/import):
  • Limit: 5 requests per minute per IP address.
  • Limit: 5 requests per minute per account ID.
• All API Endpoints:
  • Limit: 10 requests per minute per IP address.

Response When Rate Limit is Exceeded

• Status Code: 429 Too Many Requests
• Headers:
  • Retry-After: Number of seconds to wait before retrying.

Example Error Response:

{
  "error": {
    "code": "throttle_limit_reached",
    "message": "Rate limit exceeded. Try again in 30 seconds.",
    "status": 429
  }
}

Note: The Retry-After header provides the time in seconds after which you can retry the request.

Example Usage

Import Products Example

Request

POST /api/v1/products/import HTTP/1.1
Host: app.quotiza.com
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "account_id": "1",
  "products": [
    {
      "sku": "ABC123",
      "name": "Premium T-Shirt",
      "description": "High-quality cotton t-shirt",
      "cost": 9.99,
      "brand": "FashionBrand",
      "category": "Apparel",
      "active": true,
      "image_url": "https://example.com/images/abc123.jpg"
    },
    {
      "sku": "DEF456",
      "name": "Stylish Jeans",
      "description": "Comfortable denim jeans",
      "cost": 29.99,
      "brand": "DenimCo",
      "category": "Apparel",
      "active": true,
      "image_url": "https://example.com/images/def456.jpg"
    }
    // ... up to 1000 products
  ]
}

Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "job_id": "789012"
}

Check Import Status Example

Request

GET /api/v1/products/import_status?account_id=1&job_id=789012 HTTP/1.1
Host: app.quotiza.com
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "job_id": "789012",
  "status": "processing",
  "total": 2,
  "processed": 1,
  "successes": 1,
  "failures": 0,
  "errors": []
}

Product Attributes

Below are the permitted attributes for each product in the products array.

Attribute	Type	Required	Description
sku	string	Yes	Stock Keeping Unit (unique identifier for the product).
name	string	Yes	Name of the product.
description	string	No	Detailed description of the product.
cost	number	No	Cost price of the product.
upc	string	No	Universal Product Code.
brand	string	Yes	Brand name of the product.
msrp	number	No	Manufacturer's Suggested Retail Price.
base_price	number	No	Base selling price of the product.
category	string	No	Category to which the product belongs.
active	boolean	No	Indicates if the product is active (true) or inactive (false). Defaults to true.
custom1_name	string	No	Name of the first custom attribute.
custom1_value	string	No	Value of the first custom attribute.
custom2_name	string	No	Name of the second custom attribute.
custom2_value	string	No	Value of the second custom attribute.
custom3_name	string	No	Name of the third custom attribute.
custom3_value	string	No	Value of the third custom attribute.
image_url	string	No	URL of the product image.
sales_unit	string	No	Unit of measurement for sales (e.g., "Piece", "Box").
base_unit_of_measure	string	No	Base unit of measure for inventory (e.g., "Unit").
base_units_per_sales_unit	integer	No	Number of base units per sales unit. Defaults to 1.

Note: Attributes marked as Deprecated should be avoided in favor of the recommended alternatives.

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of an API request.

• 200 OK: The request was successful.
• 202 Accepted: The request has been accepted for processing but is not yet complete.
• 400 Bad Request: The request is invalid or cannot be processed.
• 401 Unauthorized: Authentication failed or was not provided.
• 404 Not Found: The requested resource does not exist.
• 413 Payload Too Large: The request payload is too large.
• 429 Too Many Requests: The client has sent too many requests in a given amount of time.
• 500 Internal Server Error: An unexpected error occurred on the server.

Changelog

• v1.0
  • Initial release of the Products Import API.
  • Supports bulk product import and import status checking.
  • Implements rate limiting to ensure fair usage.
  • Provides detailed error responses for better client-side handling.

Contact Support: If you have any questions or need assistance, please contact our support team at contact@quotiza.com.

Important Notes

• Data Validation: Ensure that all required fields are provided and that data types are correct. Invalid data may cause the import job to fail for specific products.
• Asynchronous Processing: The import process is asynchronous. Always check the import status using the job_id provided in the response.
• Idempotency: The import process is idempotent based on the sku. Importing a product with an existing sku will update the existing product.

Thank You

Thank you for using our Products Import API. We continuously strive to improve our services. Your feedback is valuable to us.