# Suppliers and dropshipping

Add your products to a merchant's store, keep their price and stock fresh, and ship what customers order.

## What your app needs

| You want to | Scope | Where |
|---|---|---|
| Add products and update their content | `products:write` | [`POST /products`](/api/products-create), [`PATCH /products/{id}/content`](/api/products-content) |
| Set prices | `products.prices:write` | [`PATCH /products/{id}/prices`](/api/products-prices) |
| Update images | `products.media:write` | [`PATCH /products/{id}/media`](/api/products-media-update) |
| Publish or hide products | `products.publish:write` | [`PATCH /products/{id}/status`](/api/products-status-update) |
| Delete products | `products.delete:write` | [`DELETE /products/{id}`](/api/products-delete) |
| Change stock | `inventory:write` | [`POST /products/{id}/inventory-adjustments`](/api/inventory-adjust) |
| Add codes to digital products | `inventory.codes:write` | [`POST /products/{id}/codes`](/api/products-codes-create) |
| See orders of your products | `orders:read` | [`order.paid`](/events/order-paid) |
| Get the recipient's name, phone and address | `customers:read` | Inside the order |
| Report the shipment | `orders.shipment:write` | [`PATCH /orders/{id}/shipment`](/api/orders-shipment-update) |

## Add a product

A new product starts hidden. Send its choices and stock with it:

```bash
curl -X POST "https://larm.sa/stores/$STORE_ID/v1/products" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cotton T-shirt",
    "description": "A soft cotton T-shirt.",
    "product_kind": "physical",
    "price": "79.00",
    "physical": { "sku": "TS-100", "weight_grams": 250, "length_cm": 30, "width_cm": 25, "height_cm": 3 },
    "options": [{ "name": "Size", "values": ["S", "M"] }],
    "variants": [
      { "options": { "Size": "S" }, "sku": "TS-100-S", "quantity": 8 },
      { "options": { "Size": "M" }, "sku": "TS-100-M", "quantity": 6 }
    ]
  }'
```

Then publish it with [`PATCH /products/{id}/status`](/api/products-status-update). A product with no price cannot be published. Sending `price` also needs `products.prices:write`, and sending stock also needs `inventory:write`.

Store the `id` of each product. To match your catalog later, use `GET /products?sku=TS-100`.

## Keep price and stock fresh

- **Price.** Read the product, then send its `ETag` in `If-Match` with the new price. A change above 90% is refused with `PRICE_CHANGE_TOO_LARGE`, to protect the merchant from a wrong feed.
- **Stock.** Send the difference with [`POST /products/{id}/inventory-adjustments`](/api/inventory-adjust). The store takes stock off by itself on each sale, and [`inventory.physical.updated`](/events/inventory-physical-updated) tells you when it does.
- **The merchant can edit too.** Listen for [`product.updated`](/events/product-updated) so your copy stays right.

## Ship an order

An order can hold products from several suppliers. On [`order.paid`](/events/order-paid), keep the items whose `product_id` or `sku` is yours, ship them, and report it with [`PATCH /orders/{id}/shipment`](/api/orders-shipment-update). An order has one shipment. When you share an order with others, agree with the merchant who reports it.

## Money

The customer pays the merchant, and the amount stays with the merchant in their settlement. Larm does not split a payment between a merchant and a supplier. Bill the merchant under your own agreement.