ForSURE.orders_data.orders.__api__

baseURL = '{domain}/saas/orders'

Base URL for all requests

POST /saas/orders
async def add_orders()

Add orders to the system via API.

This endpoint allows you to programmatically add orders to the system using a JSON payload. The endpoint supports flexible duplicate handling strategies to control how duplicate orders are processed.

Parameters

orders OrdersAPI - OrdersAPI object containing:

  • orders: List of Order objects with the following required fields:
    • sku str - Product SKU identifier
    • title str - Product title/name
    • orderid str - Unique order identifier
    • quantity int - Number of items ordered
    • date datetime - Order date in ISO format
    • country str - Country code (e.g., "NL")
    • postal_code str - Postal/ZIP code
    • b2b bool - Whether this is a business-to-business order
    • company_name str, optional - Company name for B2B orders
    • total_weight float, optional - Total weight of the order
    • packaging_weight float, optional - Weight of packaging
  • duplicates (ErrorHandling, optional): How to handle duplicate orders:
    • SKIP ErrorHandling (Enum) - Silently ignore duplicates
    • WARN_AND_SKIP ErrorHandling (Enum) - Report duplicates but continue (default)
    • RAISE ErrorHandling (Enum) - Raise an error and stop processing

Returns

dict

Response containing:

status str - "success" if operation completed

duplicates list, optional - List of duplicate orders if WARN_AND_SKIP is used

Raises

HTTPException If duplicates=RAISE and duplicates are found, or if validation fails

Example

curl -X POST "https://api.example.com/saas/orders" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "orders": [
    {
      "sku": "481769825",
      "title": "Example Product 1",
      "orderid": "FS1234",
      "quantity": 1,
      "date": "2024-01-27T22:16:25.365Z",
      "country": "NL",
      "postal_code": "1234AB",
      "b2b": false
    }
  ],
  "duplicates": "WARN_AND_SKIP"
}'

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

{
  "status": "success",
  "duplicates": []
}

Error response If the request failed you might receive status code 400 with a response body like this:

{
  "detail": "Failed to add orders"
}

Note

Requires ORDERS_ADD permission. Orders are validated before insertion. Duplicate detection is based on the combination of (orderid, organization, sku).

POST /saas/orders/add-with-profile
async def add_orders_with_profile()

Add orders to the system via API using profile-based column mapping.

This endpoint allows you to add orders using a flexible dictionary format where column names can be any keys. The profile defines the mapping between your external column names and the internal system field names. This is useful when integrating with external systems that use different column naming conventions.

Parameters

orders OrdersWithProfileAPI - OrdersWithProfileAPI object containing:

  • orders: List of dictionaries with any keys. The keys should match the column names defined in your profile mapping. Example:

[
  {
    "Product SKU": "481769825",
    "Order ID": "FS1234",
    "Quantity": 1,
    "Purchase Date": "2024-01-27T22:16:25.365Z",
    "Country Code": "NL",
    "Postal Code": "1234AB",
    "Business Type": "B2C"
  }
]

  • profile: Profile ID (int) that defines the column mapping. The profile must be configured with mappings for required fields: sku, orderid, and amount.
  • duplicates (ErrorHandling, optional): How to handle duplicate orders:
    • SKIP ErrorHandling (Enum) - Silently ignore duplicates
    • WARN_AND_SKIP ErrorHandling (Enum) - Report duplicates but continue (default)
    • RAISE ErrorHandling (Enum) - Raise an error and stop processing

Returns

dict

Response containing:

status str - "success" if operation completed

duplicates list, optional - List of duplicate orders if WARN_AND_SKIP is used

Raises

HTTPException If profile is not found, required mappings are missing, or if duplicates=RAISE and duplicates are found

Example

curl -X POST "https://api.example.com/saas/orders/add-with-profile" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "orders": [
    {
      "Product SKU": "481769825",
      "Order ID": "FS1234",
      "Quantity": 1,
      "Purchase Date": "2024-01-27T22:16:25.365Z",
      "Country Code": "NL",
      "Postal Code": "1234AB",
      "Business Type": "B2C"
    }
  ],
  "profile": 1,
  "duplicates": "WARN_AND_SKIP"
}'

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

{
  "status": "success",
  "duplicates": []
}

Error response If the request failed you might receive status code 400 with a response body like this:

{
  "detail": "Failed to add orders with profile mapping: Profile 1 not found or not configured for this organization"
}

Note

Requires ORDERS_ADD permission. The profile must be configured with proper column mappings before using this endpoint. Any columns in your order dictionaries that are not mapped in the profile will be stored in the 'unmapped' field as JSON. Duplicate detection is based on the combination of (orderid, organization, sku).

GET /saas/orders
async def get_orders()

Retrieve orders with filtering, pagination, and search capabilities.

This endpoint returns a paginated list of orders grouped by order ID. Orders are sorted by the most recent order date first. The endpoint supports multiple filtering options to narrow down the results.

Parameters

limit int, default 50 - Maximum number of order groups to return (1-200).

offset int, default 0 - Number of order groups to skip for pagination.

start_date date, optional - Filter orders from this date (inclusive). Format: YYYY-MM-DD.

end_date date, optional - Filter orders until this date (inclusive). Format: YYYY-MM-DD.

search str, optional - Free text search across all string columns (case-insensitive partial match).

source str, optional - Filter by specific source/file name.

Returns

OrdersPage

Paginated response containing:

  • items list - List of order groups (each group contains all items for an order ID)
  • source_names list - List of unique source names in the result set
  • total int - Total number of order groups matching the filters
  • limit int - Current page size
  • offset int - Current offset
  • next_offset int - Offset for next page (None if no next page)
  • prev_offset int - Offset for previous page (None if no previous page)

Example

curl -X GET "https://api.example.com/saas/orders?limit=50&offset=0&start_date=2024-01-01&end_date=2024-01-31&search=FS1234" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

{
  "items": [
    {
      "orderid": "FS1234",
      "sku": "481769825",
      "title": "Example Product 1",
      "quantity": 1,
      "date": "2024-01-27T22:16:25.365Z",
      "country": "NL",
      "postal_code": "1234AB",
      "b2b": false
    }
  ],
  "source_names": ["orders_upload_2024_01"],
  "total": 150,
  "limit": 50,
  "offset": 0,
  "next_offset": 50,
  "prev_offset": null
}

Error response If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to get orders"
}

Note

Requires ORDERS_VIEW permission. Results are grouped by order ID, so a single order with multiple SKUs will appear as one group with multiple items.

POST /saas/orders/upload
async def upload_orders()

Upload orders from CSV or Excel files.

This endpoint allows bulk upload of orders from CSV or Excel files. Files are processed in the background to handle large uploads efficiently. Each file must be associated with a profile that defines the column mapping, and a resolution that maps external column names to internal field names.

Parameters

file_lists list[UploadFile] - List of uploaded files (CSV or Excel format).

profiles list[str] - List of profile IDs, one per file. Profiles define column mappings.

fileId list[str] - List of file identifiers to track the source of each order.

resolutions list[str] - List of JSON strings containing column name mappings (external -> internal).

Returns

dict

Response containing:

status_code int - HTTP status code: 200: Success (files are being processed in background), 400: Error (contains list of file errors)

Raises

HTTPException If file validation fails or processing errors occur.

Example

curl -X POST "https://api.example.com/saas/orders/upload" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file_lists=@orders1.csv" \
-F "file_lists=@orders2.xlsx" \
-F "profiles=1" \
-F "profiles=2" \
-F "fileId=source1" \
-F "fileId=source2" \
-F 'resolutions={"Order ID": "orderid", "SKU": "sku"}' \
-F 'resolutions={"OrderID": "orderid"}'

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

{
  "status_code": 200
}

Error response If the request failed you might receive status code 400 with a response body like this:

{
  "status_code": 400,
  "data": [
    {
      "file_id": "source1",
      "error": "File validation failed: missing required column 'orderid'"
    }
  ]
}

Note

  • Requires ORDERS_ADD permission
  • Files are validated synchronously, then processed asynchronously
  • Large files may take time to process - check status separately
  • Order volumes are automatically refreshed after successful upload
  • Each file must have a corresponding profile and fileId
  • Column mappings must be defined correctly in the profile before upload
POST /saas/orders/check
async def check_orders()

Validate an orders file before upload.

This endpoint performs validation on an orders file without actually uploading the data. It checks for required columns, data format, and provides feedback on any issues found. Use this endpoint before uploading to ensure your file is correctly formatted.

Parameters

file_list UploadFile - The orders file to validate (CSV or Excel format)

profile int - Profile ID that defines the expected column mapping.

file_id str, optional - Identifier for tracking this file.

Returns

dict

Validation result containing:

  • success bool - True if file is valid, False otherwise
  • total_orders int - Total number of orders found in the file
  • missing_orders int - Number of orders with missing required fields
  • details dict - Detailed information about validation issues
  • description str - Human-readable description of validation results

Example

curl -X POST "https://api.example.com/saas/orders/check" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file_list=@orders.csv" \
-F "profile=1" \
-F "file_id=test_upload"

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

{
  "success": true,
  "total_orders": 150,
  "missing_orders": 0,
  "details": {},
  "description": "File validation successful"
}

Error response If the request failed you might receive status code 200 with validation errors in a response body like this:

{
  "success": false,
  "total_orders": 150,
  "missing_orders": 5,
  "details": {
    "missing_orderid": 3,
    "missing_sku": 2
  },
  "description": "File validation failed: 5 orders have missing required fields"
}

Note

  • Requires ORDERS_ADD permission
  • This endpoint does not save any data - it only validates
  • Use this before /upload to catch errors early
  • Profile must be configured with correct column mappings