DOCSEARCHbyAlgolia
Submit Docs

Nilo Integration API

website·Indexed 31 days ago

https://developers.nilo-labs.com

API for the Nilo B2B e-commerce platform, enabling suppliers to manage product catalogs, brands, and store connections.

Tokens
2.4K
Snippets
19
Records
19
Agent score
0%

What's inside Nilo

  1. Handle Nilo Webhooks

    Nilo sends events to your configured webhook URL. You must implement endpoints to handle these payloads.
    // Order Created (POST)
{ "id": 10, "buyer": { "storeCode": "ST001" }, "products": [...], "status": "PENDING" }

// Order Cancelled (PUT)
{ "id": 10, "status": "CANCELLED", "reason": "...", "code": "NEW_ORDER" }

// Store User Created/Deleted (POST)
{ "subject": "user-created", "store": { "internalCode": "ST001" }, "user": { "username": "..." } }

// Support Ticket Created (POST)
{ "ticket_id": "1122", "client_internal_code": "ST001", "description": "..." }

  2. Authenticate with the Nilo Integration API

    To interact with the Nilo API, you must first obtain an access token using your client credentials. All subsequent requests must include the Bearer token, your API key, and the JSON content type for write operations.
    # Request access token
curl -X POST /login \
  -H "Content-Type: application/json" \
  -d '{"clientId": "your-client-id", "clientSecret": "your-client-secret"}'

# Example of a subsequent request
curl -X GET /brand \
  -H "Authorization: Bearer {access_token}" \
  -H "x-api-key: {your-api-key}"

  3. Recommended Integration Setup Sequence

    To ensure data integrity and correct relationships, configure the Nilo platform in the following order:
    1. Stock Groupers (POST /grouper/stock)
2. Promotion Groupers (POST /grouper/promotion)
3. Brands (POST /batch/brand)
4. Categories and Subcategories
5. Products (POST /batch/product)
6. Stock/Availability (POST /batch/stock/grouper)
7. Price Lists (POST /batch/pricelist)
8. Stores (POST /batch/store)
9. Promotions (POST /batch/promotion)
10. Webhooks (for receiving orders)

  4. Implement a Full Catalog Sync

    For catalogs with fewer than 10,000 products, the recommended synchronization pattern is to use the batch product upsert endpoint, which is idempotent.
    # 1. Authenticate
POST /login

# 2. Send all products via batch upsert
POST /batch/product
Body: { "action": "upsert", "products": [...] }

# 3. Track progress
GET /batch/{uuid}/status

  5. Manage Product Categories and Subcategories

    Nilo supports a hierarchical catalog structure using Categories and Subcategories. Subcategories must reference a parentCategoryInternalCode.
    // POST /category
{ "name": "Category 1", "internalCode": "CAT01", "weight": 1, "image": "/cat/img.png" }

// POST /subcategory
{ "name": "Sub 1", "internalCode": "SUB01", "parentCategoryInternalCode": "CAT01", "weight": 1 }

  6. Update Product Stock and Availability

    Stock is managed per 'grouper' (e.g., a specific warehouse). You can update stock for a single product or use the batch endpoint for multiple products within a grouper.
    // POST /product/{code}/stock
{ "grouperCode": "WH001", "available": true, "units": 1 }

// POST /batch/stock/grouper
{
  "availability": [
    { "productCode": "SKU001", "grouperCode": "WH001", "available": true }
  ]
}

  7. Manage Brands in Nilo

    Suppliers can create, list, update, and batch-upsert brands. Brands are identified by an internalCode.
    // POST /brand or PUT /brand (Upsert)
{
  "name": "Brand 1",
  "internalCode": "B001",
  "weight": 1,
  "image": "/brand/img.png",
  "enabled": true
}

// POST /batch/brand (Async batch upsert)
{
  "upsert": [
    { "name": "Brand", "internalCode": "B001", "enabled": true }
  ]
}

  8. Manage Support Tickets

    Suppliers can list, retrieve, and interact with support tickets, including closing tickets or requesting more information from the store.
    # List tickets
GET /support/ticket?status=PENDING

# Close a ticket
PUT /support/ticket/close
Body: { "message": "Issue resolved.", "ticketId": 1234 }

# Request additional info
POST /support/ticket/additional-info
Body: { "message": "Please provide order number.", "ticketId": 1234 }

  9. Perform batch order operations

    Nilo provides endpoints for asynchronous batch status changes and historical order imports.
    # Batch order status changes (async)
POST /batch/order
Body: { "status": { "confirm": [{ "id": 10, "deliveryDate": "2025-12-03" }], "deliver": [{ "id": 5, "complete": true }], "cancel": [{ "id": 7, "code": "OUT_OF_STOCK" }] } }

# Import historical orders
POST /order/bulk-import
Body: { "orders": [{ "id": 10, "source": "ERP", "buyer": { "storeCode": "ST001", "routeCode": "R001" }, "address": { "addressLine": "Street", "zipCode": "2400" }, "status": "DELIVERED", "createdAt": "2025-12-03", "products": [{ "productCode": "SKU001.1", "units": 1, "quantity": 5 }] }] }

  10. Configure Stock and Promotion Groupers

    Groupers (warehouses for stock or groups for promotions) allow suppliers to manage availability and offers across multiple stores.
    # Create stock grouper (warehouse)
POST /grouper/stock
Body: { "name": "Warehouse North", "internalCode": "WH001" }

# Batch add/remove stores from stock groupers
POST /batch/grouper/stock
Body: { "add": { "stores": [{ "groupInternalCode": "WH001", "storeInternalCode": "ST001" }] }, "remove": { "stores": [...] } }

# Create promotion grouper
POST /grouper/promotion
Body: { "name": "Promo Group 1", "internalCode": "PG001" }

  11. Manage Loyalty Challenges

    Create and manage loyalty challenges to reward stores. Challenges can be upserted, listed with pagination, or toggled via status endpoints.
    # List challenges (paginated)
GET /loyaltychallenge?take=50&page=1

# Upsert loyalty challenge
PUT /loyaltychallenge
Body: { "title": "Summer Points", "internalCode": "CH001", "pointsGiven": 100, "requiredAmount": 500, "start": "2025-06-01", "end": "2025-08-31", "enabled": true, "products": [{ "internalCode": "SKU001" }], "description": "Earn points", "image": "https://img.jpg" }

# Enable/disable challenge
PUT /loyaltychallenge/{code}/status
Body: { "enabled": true }

  12. Manage Products and Catalog Data

    Products are managed via individual endpoints or asynchronous batch endpoints. Products include displayProducts which define the specific units/SKUs available for sale.
    // POST /product or PUT /product (Upsert)
{
  "name": "Product 1",
  "internalCode": "SKU001",
  "description": "Desc",
  "brandInternalCode": "B001",
  "categoryInternalCode": "CAT01",
  "enabled": true,
  "displayProducts": [
    { "default": true, "units": 1, "internalCode": "SKU001.1" }
  ],
  "mainImage": "https://img.jpg",
  "images": ["https://img2.jpg"]
}