Create a supplier item

POST /2024-09/supplier-items

Default

Create a new supplier item for a merchant.

application/json

Body Required

merchant_id string(uuid) Required

The UUID of the merchant that owns this supplier item
supplier_id string(uuid) Required

The UUID of the supplier for this supplier item
sku string | null Required

Stock Keeping Unit - unique identifier for the product

Maximum length is 255.
description string | null

Description of the supplier item
product_id string | null

The UUID of the associated product
costs array[object] Required

Cost tiers for different minimum order quantities
Hide costs attributes Show costs attributes object
- minimum_order_quantity integer Required
  
  Minimum order quantity for this cost tier
  
  Minimum value is 1.
- cost object Required
  
  The cost of the item with currency
  
  Additional properties are NOT allowed.
  Hide cost attributes Show cost attributes object
  
  value number Required
  
  The numeric value of the cost
  
  Minimum value is 0.
  
  currency string Required
  
  The currency code (e.g., USD, EUR)

Responses

201 application/json

A successful response returning the created supplier item
Hide response attribute Show response attribute object
- data object
  
  Representation of a supplier item
  
  Additional properties are NOT allowed.
  
  Hide data attributes Show data attributes object
  
  id string(uuid)
  
  The UUID of the resource.
  
  merchant_id string(uuid)
  
  The UUID of the merchant that owns this supplier item
  
  supplier_id string(uuid)
  
  The UUID of the supplier for this supplier item
  
  sku string | null
  
  Stock Keeping Unit - unique identifier for the product
  
  Maximum length is 255.
  
  description string | null
  
  Description of the supplier item
  
  identifiers array[object]
  
  Array of supplier item identifiers
  
  Representation of a supplier item identifier
  
  Hide identifiers attributes Show identifiers attributes object
  
  id string(uuid)
  
  The UUID of the resource.
  
  supplier_item_id string(uuid)
  
  The UUID of the supplier item this identifier belongs to
  
  type string
  
  The type of identifier
  
  Values are UPC, EAN, GTIN, or ISBN.
  
  value string
  
  The identifier value
  
  created_at string(date-time)
  
  The date and time the resource was created.
  
  updated_at string(date-time)
  
  The date and time the resource was last updated.
  
  product_id string | null
  
  The UUID of the associated product
  
  costs array[object]
  
  Cost tiers for different minimum order quantities
  
  Hide costs attributes Show costs attributes object
  
  minimum_order_quantity integer Required
  
  Minimum order quantity for this cost tier
  
  Minimum value is 1.
  
  cost object Required
  
  The cost of the item with currency
  
  Additional properties are NOT allowed.
  
  Hide cost attributes Show cost attributes object
  
  value number Required
  
  The numeric value of the cost
  
  Minimum value is 0.
  
  currency string Required
  
  The currency code (e.g., USD, EUR)
  
  created_at string(date-time)
  
  The date and time the resource was created.
  
  updated_at string(date-time)
  
  The date and time the resource was last updated.
401 application/json

The request requires user authentication or the user is not authorized to access this resource.
Hide response attribute Show response attribute object
- message string
403 application/json

Forbidden - The user does not have permission to access this resource.
Hide response attribute Show response attribute object
- message string Required
404 application/json

The specified resource was not found
Hide response attribute Show response attribute object
- message string

POST /2024-09/supplier-items

curl \
 --request POST 'https://app.merchanthq.com/api/2024-09/supplier-items' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"merchant_id":"1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4","supplier_id":"2e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4","sku":"PROD-001","description":"Blue widget with advanced features","product_id":"3e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4","costs":[{"minimum_order_quantity":1,"cost":{"value":42.0,"currency":"string"}}]}'

Request examples

{
  "merchant_id": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
  "supplier_id": "2e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
  "sku": "PROD-001",
  "description": "Blue widget with advanced features",
  "product_id": "3e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
  "costs": [
    {
      "minimum_order_quantity": 1,
      "cost": {
        "value": 42.0,
        "currency": "string"
      }
    }
  ]
}

Response examples (201)

{
  "data": {
    "id": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
    "merchant_id": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
    "supplier_id": "2e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
    "sku": "PROD-001",
    "description": "Blue widget with advanced features",
    "identifiers": [
      {
        "id": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
        "supplier_item_id": "string",
        "type": "UPC",
        "value": "string",
        "created_at": "2025-01-10T10:37:11Z",
        "updated_at": "2025-01-10T10:37:11Z"
      }
    ],
    "product_id": "3e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
    "costs": [
      {
        "minimum_order_quantity": 1,
        "cost": {
          "value": 42.0,
          "currency": "string"
        }
      }
    ],
    "created_at": "2025-01-10T10:37:11Z",
    "updated_at": "2025-01-10T10:37:11Z"
  }
}

Response examples (401)

{
  "message": "Unauthorized"
}

Response examples (403)

{
  "message": "This action is unauthorized."
}

Response examples (404)

{
  "message": "Not found"
}