Upload Equipment Inventory to SetSale with the Distributor API

Keep equipment availability in SetSale up to date by sending inventory from your warehouse or ERP system through the Distributor API.

This guide shows a distributor administrator how to create an API key, find warehouse location IDs, upload equipment quantities, and review every import result.

How It Works

Your system requests the SetSale IDs for your distributor locations.
It sends equipment model numbers and available quantities to the inventory import endpoint.
SetSale creates or updates one inventory record for each model and location.
SetSale reports which records were created, updated, skipped, or returned an error.

Inventory is stored separately for each location. A new quantity replaces the previous quantity for that model at that location; it is not added to it.

Before You Begin

⚠️ Heads Up: You will need:

Distributor administrator access to Settings → API & Webhooks.
A server-side integration, ERP, warehouse system, or scheduled job that can send HTTPS requests.
At least one distributor location in SetSale.
Equipment model numbers that match SetSale's equipment catalog.

👇 IMPORTANT 👇

🚨 API keys provide access to your distributor's data. Never put a key in a browser code, a spreadsheet, screenshots, tickets, email, or shared conversations. Store it in a server-side secret manager or protected environment.🚨

1. Generate a Distributor API Key

In your distributor account, go to Settings → API & Webhooks.
Under API Keys, click Generate API Key.
Enter a descriptive name, such as Warehouse inventory sync.
Click Generate API Key.
Copy the key when SetSale displays it and store it securely. You will not be able to view the full key again.

Send the key as a Bearer token:

Authorization: Bearer YOUR_SECRET_TOKEN

✨ Pro Tip: Use a separate key for each integration. If one is exposed, you can revoke only that key without interrupting your other systems.

2. Get Your Location IDs

Every inventory record needs the SetSale ID of the warehouse or branch where that quantity is available.

In the SetSale API documentation, select Distributor → List distributor locations, then call:

GET https://app.setsale.ai/customer-api/distributor/locations

Use the id returned for the correct location. Do not use distributorId or districtId as the inventory locationId.

List distributor locations and copy the location id

If a warehouse does not exist yet, create it in Locations in SetSale or use Create a distributor location in the API documentation.

3. Prepare the Inventory Records

Each record has three required fields:

modelNumber: The manufacturer's AHRI model number or model pattern.
quantity: The available quantity as a whole number of zero or more.
locationId: The SetSale location ID from Step 2.

Example:

{
  "records": [
    {
      "modelNumber": "YOUR_MODEL_NUMBER",
      "quantity": 5,
      "locationId": "YOUR_LOCATION_ID"
    }
  ]
}

You can send between 1 and 1,002 records in one request.

⚠️ Quantity overwrites the current value. If SetSale currently shows 4 and you send quantity: 3, the new available quantity is 3—not 7. Send quantity: 0 when the item is out of stock.

4. Send the Inventory Import

In the API documentation, select Distributor → Import inventory records.

Send a POST request to:

https://app.setsale.ai/customer-api/distributor/inventory/import

Include both headers:

Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json

Open the inventory import endpoint and submit the records array

Copy and paste this security-safe request template:

curl https://app.setsale.ai/customer-api/distributor/inventory/import \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
    "records": [
      {
        "modelNumber": "YOUR_MODEL_NUMBER",
        "quantity": 5,
        "locationId": "YOUR_LOCATION_ID"
      }
    ]
  }'

It contains placeholders only. Never save a real API key in the article or in a shared script.

5. Review Every Import Result

A successful HTTP 200 means SetSale processed the batch. It does not mean every record was imported.

Always check all four result fields:

created: New inventory rows created.
updated: Existing inventory quantities replaced.
skipped: Records SetSale intentionally did not import, with a reason.
errors: Records that failed during processing, with an error message.

Review created, updated, skipped, and error results

The number of submitted records should equal:

created + updated + skipped.length + errors.length

Do not discard the skipped or errors arrays. Log them and send them to a review queue.

What Happens to New Model Numbers?

If the model already exists in your distributor catalog, SetSale updates its inventory.
If the model is in SetSale's global equipment catalog, SetSale can add the matching equipment to your distributor catalog and create its inventory row.
If the model cannot be matched, SetSale returns it in skipped with Model number not found in our global equipment catalog.

Use the manufacturer's model number exactly as it appears in your source system. Supported model patterns can include wildcard characters such as **.

Recommended Sync Process

For an automated warehouse or ERP sync:

Fetch and cache your SetSale location IDs.
Export the current available quantity for each model and location.
Send batches of no more than 1,002 records.
Pause and retry with exponential backoff if SetSale returns 429 Too Many Requests.
Record the result for every submitted row.
Alert someone when skipped or errors is not empty.

The API limit is 200 requests per minute per IP address. Most integrations should use fewer, larger batches rather than one request per model.

Troubleshooting

The API returns 401 Unauthorized
Confirm the header begins with Bearer, the API key has not been revoked, and the key was created for the distributor account—not a contractor account.

A location is skipped
Confirm locationId is the location's id and that the location belongs to the distributor account associated with the API key.

A model is skipped
Compare the model number with the manufacturer's data. Remove accidental spaces and confirm the model exists in SetSale's global equipment catalog.

The quantity is lower than expected
Imports overwrite the current quantity. Send the total quantity currently available, not the change since the last sync.

The API returns 429 Too Many Requests
Pause briefly, retry with exponential backoff, and combine more records into each batch.

The response is 200, but some equipment is missing
Inspect both skipped and errors. HTTP 200 describes the batch request; individual records can still require attention.

Security Checklist

Keep API keys server-side only.
Use a separate key for each integration.
Never log the Authorization header.
Redact keys and internal location IDs from screenshots and support messages.
Revoke and replace a key immediately if it is exposed.
Send requests only to https://app.setsale.ai/customer-api.
Restrict access to import logs because they contain operational inventory data.

Need More Help?

For SetSale API or equipment-matching questions, email [email protected].

When contacting support, include the request time, HTTP status, and sanitized skipped or errors entries. Never send your API key or full Authorization header.