Developers

Guides

Markdown

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 toScopeWhere
Add products and update their contentproducts:writePOST /products, PATCH /products/{id}/content
Set pricesproducts.prices:writePATCH /products/{id}/prices
Update imagesproducts.media:writePATCH /products/{id}/media
Publish or hide productsproducts.publish:writePATCH /products/{id}/status
Delete productsproducts.delete:writeDELETE /products/{id}
Change stockinventory:writePOST /products/{id}/inventory-adjustments
Add codes to digital productsinventory.codes:writePOST /products/{id}/codes
See orders of your productsorders:readorder.paid
Get the recipient's name, phone and addresscustomers:readInside the order
Report the shipmentorders.shipment:writePATCH /orders/{id}/shipment

Add a product

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

cURL
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. 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. The store takes stock off by itself on each sale, and inventory.physical.updated tells you when it does.
  • The merchant can edit too. Listen for product.updated so your copy stays right.

Ship an order

An order can hold products from several suppliers. On order.paid, keep the items whose product_id or sku is yours, ship them, and report it with PATCH /orders/{id}/shipment. 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.

    ↑↓ moveEnter openEsc close