Products

Browse synced products and update variant shipping details (weight, dimensions, customs info).

List Products

GET /api/v1/products

Returns a paginated list of products with their variants and thumbnail image.

Query Parameters

Example

curl "https://shipwave.app/api/v1/products?search=widget&limit=10" \
  -H "Authorization: Bearer sw_live_abc123..."

const res = await fetch(
  "https://shipwave.app/api/v1/products?search=widget&limit=10",
  { headers: { Authorization: "Bearer sw_live_abc123..." } }
);
const { data, meta } = await res.json();

Response

{
  "data": [
    {
      "id": "clx3prod1",
      "storeId": "clw9store1",
      "title": "Blue Widget",
      "handle": "blue-widget",
      "vendor": "Acme Co",
      "productType": "Accessories",
      "tags": ["bestseller", "widget"],
      "variants": [
        {
          "id": "clx3var1",
          "title": "Small",
          "sku": "WIDGET-001-SM",
          "price": "29.99",
          "weight": "8.00",
          "weightUnit": "oz"
        },
        {
          "id": "clx3var2",
          "title": "Large",
          "sku": "WIDGET-001-LG",
          "price": "49.99",
          "weight": "16.00",
          "weightUnit": "oz"
        }
      ],
      "images": [
        {
          "src": "https://cdn.shopify.com/s/files/1/widget-blue.jpg",
          "alt": "Blue Widget"
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 3,
    "totalPages": 1
  }
}

---

Get Product

GET /api/v1/products/:id

Returns a single product with all variants and all images.

Example

curl https://shipwave.app/api/v1/products/clx3prod1 \
  -H "Authorization: Bearer sw_live_abc123..."

Response

Same shape as the list item, but with complete variant details and all images.

Errors

---

Update Variant Shipping Details

PUT /api/v1/products/:id/variants/:variantId

Updates shipping-related fields on a product variant. This is useful for setting weight, dimensions, and customs information for accurate rate calculation.

Updatable Fields

Example

curl -X PUT https://shipwave.app/api/v1/products/clx3prod1/variants/clx3var1 \
  -H "Authorization: Bearer sw_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "weight": 8.5,
    "weightUnit": "oz",
    "length": 6,
    "width": 4,
    "height": 3,
    "dimensionUnit": "in",
    "hsCode": "8507.60",
    "countryOfOrigin": "CN"
  }'

const res = await fetch(
  "https://shipwave.app/api/v1/products/clx3prod1/variants/clx3var1",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer sw_live_abc123...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      weight: 8.5,
      weightUnit: "oz",
      length: 6,
      width: 4,
      height: 3,
      dimensionUnit: "in",
      hsCode: "8507.60",
      countryOfOrigin: "CN",
    }),
  }
);
const { data } = await res.json();

Response

{
  "data": {
    "id": "clx3var1",
    "productId": "clx3prod1",
    "title": "Small",
    "sku": "WIDGET-001-SM",
    "barcode": null,
    "price": "29.99",
    "compareAtPrice": null,
    "weight": "8.50",
    "weightUnit": "oz",
    "length": "6.00",
    "width": "4.00",
    "height": "3.00",
    "dimensionUnit": "in",
    "hsCode": "8507.60",
    "countryOfOrigin": "CN",
    "customsDescription": null,
    "customsValue": null
  }
}

Errors