PrepBusiness LogoAPI Documentation

Products

GET/products

List products

Get a paginated list of products for the current merchant. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Returns product details only — use the stock endpoints for quantities. Deleted products are excluded. Products and inventory items refer to the same underlying records and share the same UUID. Product responses expose uuid, without the integer inventory id. Inbound shipment add-item accepts the product UUID directly in product_uuid as an alternative to item_id. Inbound shipment update-item still requires the integer inventory id; resolve it through GET /inventory?product_uuids[]={uuid} or GET /inventory?merchant_skus[]={sku}.

Optional attributes

  • Name
    q
    Type
    string
    Description
    Search language filter. Supported fields: `uuid` (uuid), `merchant_sku` (string), `title` (string). Substring matches require at least 3 characters. Clauses can be combined with `AND` / `OR`. Example: `title~"widget" AND merchant_sku:"WIDGET-001"`
  • Name
    sorts
    Type
    array<Sort>
    Description
    Sort the results. Sorting by stock quantities is not supported here — products and stock are separate resources. Example: `sorts[0][field]=title&sorts[0][order]=1`
  • Name
    expand
    Type
    array<string>
    Description
    Relations to include in each product. Omitted relations are absent from the response rather than null. Any other value is rejected with a 422. Example: `expand[]=identifiers&expand[]=tags`
  • Name
    page
    Type
    integer
    Description
    The page number to retrieve (1-indexed) 1
  • Name
    per_page
    Type
    integer
    Description
    The number of products per page 25

Request

GET/products
curl -G https://YOUR_DOMAIN/api/products \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Loading response...
POST/products

Create a product

Create a product for the current merchant. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. `merchant_sku` must be unique among the merchant's products that have not been deleted, so a SKU freed up by deleting a product can be reused.

Required attributes

  • Name
    merchant_sku
    Type
    string
    Description
    The merchant's own Stock Keeping Unit identifier. Must be unique among the merchant's products. WIDGET-001
  • Name
    title
    Type
    string
    Description
    The title or name of the product Blue Widget

Optional attributes

  • Name
    dimensions
    Type
    object
    Description
    The measurements of the product, written as a single field. All three measurements and the unit must be sent together; sending `null` clears all three. Each measurement must convert to between 1 and 500000 millimetres, and is rounded to the nearest millimetre when stored.
  • Name
    weight
    Type
    object
    Description
    The weight of the product, written as a single field. The value and the unit must be sent together; sending `null` clears the weight. The value must convert to between 1 and 500000 grams, and is rounded to the nearest gram when stored.

Request

POST/products
curl -X POST https://YOUR_DOMAIN/api/products \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_sku": "WIDGET-001",
    "title": "Blue Widget",
    "dimensions": {
        "length": 150,
        "width": 100,
        "height": 50,
        "unit": "mm"
    },
    "weight": {
        "value": 500,
        "unit": "g"
    }
}'
Loading response...
GET/products/{product_uuid}

Get a product

Get a single product by its UUID, including its images, identifiers and tags. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Returns product details only — use the stock endpoints for quantities. Deleted products are returned with `is_deleted` set to true.

Required attributes

  • Name
    product_uuid
    Type
    string
    Description
    The UUID of the product

Request

GET/products/{product_uuid}
curl -G https://YOUR_DOMAIN/api/products/{product-uuid} \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
Loading response...
PUT/products/{product_uuid}

Update a product

Update a product's details. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. Only the properties present in the request body are changed; omitted properties are left as they are. A property sent as `null` is cleared. `dimensions` and `weight` are each written as a whole: their measurements and the unit must be sent together, and sending one as `null` clears it. When the product has `are_dimensions_locked` set, sending `dimensions` or `weight` returns a 422. Deleted products cannot be updated and return a 404.

Required attributes

  • Name
    product_uuid
    Type
    string
    Description
    The UUID of the product

Optional attributes

  • Name
    title
    Type
    string
    Description
    The title or name of the product Blue Widget
  • Name
    dimensions
    Type
    object
    Description
    The measurements of the product, written as a single field. All three measurements and the unit must be sent together; sending `null` clears all three. Each measurement must convert to between 1 and 500000 millimetres, and is rounded to the nearest millimetre when stored.
  • Name
    weight
    Type
    object
    Description
    The weight of the product, written as a single field. The value and the unit must be sent together; sending `null` clears the weight. The value must convert to between 1 and 500000 grams, and is rounded to the nearest gram when stored.

Request

PUT/products/{product_uuid}
curl -X PUT https://YOUR_DOMAIN/api/products/{product-uuid} \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Blue Widget",
    "dimensions": {
        "length": 150,
        "width": 100,
        "height": 50,
        "unit": "mm"
    },
    "weight": {
        "value": 500,
        "unit": "g"
    }
}'
Loading response...
DELETE/products/{product_uuid}

Delete a product

Delete a product. Requires a merchant scope; a service provider scope is optional, and a request without a merchant scope returns a 422. The product is soft deleted: it disappears from the list endpoint, is still readable on the detail endpoint with `is_deleted` set to true, and frees its `merchant_sku` for reuse. Deleting a product that already has stock history requires the `products:delete_with_history` privilege and otherwise returns a 403. Deleting an already deleted product returns a 404.

Required attributes

  • Name
    product_uuid
    Type
    string
    Description
    The UUID of the product

Request

DELETE/products/{product_uuid}
curl -X DELETE https://YOUR_DOMAIN/api/products/{product-uuid} \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"