Common API recipes

These ready-to-run curl examples cover the most common REST API tasks. Replace YOUR_API_KEY with your own key and the uppercase IDs with values from your account.

List inventory items

curl "https://fiddle.io/rest/api/v2/inventory-items?size=50&page=1" \
  -H "X-API-Key: YOUR_API_KEY"

The response lists items under inventoryItems, with paging details in meta. Add query=lavender to search, or archived=true to include archived items.

Find an item by SKU

curl https://fiddle.io/rest/api/v2/inventory-items/sku/SOAP-LAV-4OZ \
  -H "X-API-Key: YOUR_API_KEY"

This matches the SKU or part number exactly and returns { "inventoryItem": { … } }. Look up an item by its ID with GET /inventory-items/ITEM_ID instead.

Check stock by lot and location

curl https://fiddle.io/rest/api/v2/inventory-items/ITEM_ID/lots \
  -H "X-API-Key: YOUR_API_KEY"

Each lot under inventoryLots lists its locations, with the inventoryLocationId and amount at each one. The item’s totalAvailable field gives the overall available quantity.

Adjust stock

Set a lot’s quantity at one location to the amount you counted:

curl -X POST https://fiddle.io/rest/api/v2/inventory-lots/adjust \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inventoryLotId": "LOT_ID",
    "inventoryLocationId": "LOCATION_ID",
    "measurementUnitId": "UNIT_ID",
    "amount": 118,
    "additionalInfo": "Cycle count"
  }'

amount is the new quantity at that location, not the change. To record five damaged units in a location holding 120, send 115.

Use the lot’s unit for measurementUnitId, which is normally the item’s base unit. Send an array to adjust several lots in one request. To move stock between locations, use POST /inventory-lots/transfer with fromInventoryLocationId, toInventoryLocationId, and amount.

Create a sales order

curl -X POST https://fiddle.io/rest/api/v2/sales-orders \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "salesOrderNumber": "WEB-1001",
    "integrationSourceId": "WEB-1001",
    "customerId": "CUSTOMER_ID",
    "customerPurchaseOrderNumber": "PO-7781",
    "dueOn": "2026-11-30",
    "items": [
      { "inventoryItemId": "INVENTORY_ITEM_ID", "quantity": 12, "price": 4.5 },
      { "sku": "PRETZEL-4OZ", "quantity": 24, "price": 3.25 }
    ]
  }'

The order is created before the response comes back, as { "salesOrder": { … } } with its id, customer and lines. Send an array of up to 10 orders to get { "salesOrders": [ … ] }.

If anything is wrong, no order is created and the response is a 400 that names each problem:

{
  "errors": {
    "salesOrderNumber": "Already in use",
    "items[1].quantity": "Must be a number greater than 0"
  }
}

• salesOrderNumber is required, and the order keeps it exactly as you send it. A number another sales order in your account already uses is rejected.
• Name the customer with customerId. Without an ID, send a customer such as "customer": { "name": "Acme Corp", "email": "ap@acme.com" }. Fiddle matches it by accountRef, email, then exact name, and creates the customer when none matches.
• Each line needs an inventoryItemId, sku, upc, internalCode, or name. A line that matches no existing item creates a new draft item, which needs a name of at least 3 characters.

Always send integrationSourceId, your own ID for the order. If a request times out, send it again unchanged: when the order was created, you get that order back, not a duplicate. If the first request is still running, you get a 400 asking you to try again in a few seconds.

Confirm a purchase order

Move a draft purchase order to open:

curl -X POST https://fiddle.io/rest/api/v2/purchase-orders/PO_ID/confirm \
  -H "X-API-Key: YOUR_API_KEY"

The same endpoint accepts close, cancel, hold, unhold, and reopen, and returns { "purchaseOrder": { … } }.

Paginated responses include meta.page and meta.lastPage. Request pages in a loop until page equals lastPage, and keep an eye on the rate limit on large jobs.

Field names and the full set of endpoints are documented in Swagger UI at https://fiddle.io/rest/api/v2/docs/swagger, where you can try each call live.

Next steps

Fiddle doesn’t send webhooks yet. See webhooks for how to keep an external system in sync by polling.