Skip to main content

Store Management API

The Store Management API allows you to manage store information in the Nilo platform. These endpoints help you create, update, and retrieve store data, including store details, users, credit information, and settings.

Understanding Stores​

Stores in Nilo represent the retail locations that can place orders:

  • Store Structure

    • Unique internal code (matches ERP)
    • Owner and legal information
    • Address and location data
    • User associations (via phone or email)
    • Credit and payment status
    • Settings and configurations
    • Group associations (price lists, stock, promotions)

  • Store Hierarchy

    • Independent entities with unique identifiers
    • Can have multiple associated users
    • Maintain their own credit status
    • Can belong to different groupers
    • Support batch operations for updates

Important Considerations​

  1. Unique Codes: Each store requires a unique internal code that matches your ERP system
  2. User Management: Users are associated via phone number (with country code) or email
  3. Credit System: Stores have credit limits and payment status tracking
  4. Location Data: Stores require accurate address and geolocation information
  5. Multiple Groupers: Stores can belong to multiple promotion groupers if configured
  6. Batch Operations: Support for efficiently updating multiple stores

Single Store Operations​

Create Store​

POST/store

Create a new store in the Nilo platform. This endpoint is used to register all store details including:

  • Store information (owner name, legal details)
  • Address and location data
  • Contact information
  • Group associations

Request Body Parameters​

ParameterTypeRequiredDescription
ownerNamestringYesName of the store owner
ownerIdentifierstringNoOwner identifier
internalCodestringYesStore code (matches ERP)
addressesarrayYesList of store addresses
legalNamestringYesLegal business name
legalIdstringYesLegal business identifier
latitudestringNoStore latitude
longitudestringNoStore longitude
addressFormatstringNoGoogle Maps formatted address
supportContactEmailstringNoEmail for support contact
supportContactPhonestringNoPhone for support contact
promotionGrouperCodestringNoCode for promotion group association
promotionGrouperCodesarrayNoArray of promotion grouper codes (only if multiple grouper configuration is enabled by Nilo)
stockGrouperCodestringNoCode for stock group association
deliveryConfigCodestringNoDelivery configuration code to assign. If omitted, the current assignment is unchanged
priceListCodestringNoCode for price list association
routeCodestringNoRoute code for delivery
settingsobjectNoStore settings (dropSize, etc.)

addresses array items:

ParameterTypeRequiredDescription
internalCodestringNoAddress code (same as in ERP)
addressLinestringYesFull address
apartmentNumberstringNoApartment/unit number
zipCodestringNoZIP/postal code

settings object:

ParameterTypeRequiredDescription
dropSizeobjectNoMinimum order amount (amount, currency)

Request Body Example​

{
  "ownerName": "Owner name",
  "ownerIdentifier": "Owner identifier",
  "internalCode": "1234",
  "addresses": [
    {
      "internalCode": "1234",
      "addressLine": "25 de mayo 1200, Buenos Aires, Argentina",
      "apartmentNumber": "2",
      "zipCode": "2400"
    }
  ],
  "legalName": "Legal Name S.A.",
  "legalId": "30-12345678-9",
  "latitude": "-34.545278",
  "longitude": "-58.449722",
  "addressFormat": "Av. Pres. Figueroa Alcorta 7597, C1428 Buenos Aires",
  "supportContactEmail": "support@store.com",
  "supportContactPhone": "+5491123456789",
  "promotionGrouperCode": "1234",
  "stockGrouperCode": "6789",
  "deliveryConfigCode": "DELIVERY-1",
  "priceListCode": "1222",
  "routeCode": "ROUTE1",
  "settings": {
    "dropSize": {
      "amount": 1000,
      "currency": "USD"
    }
  }
}

Response Codes​

CodeDescription
200Successful operation
404Store not found

Get All Stores​

GET/store

Retrieve a paginated list of all stores. This endpoint is useful for:

  • Browsing through the store catalog
  • Implementing cursor-based pagination
  • Filtering stores by enabled status

When a store has a delivery configuration assigned, its response includes:

{
  "deliveryConfig": {
    "name": "Weekly delivery",
    "internalCode": "DELIVERY-1"
  }
}

The deliveryConfig property is omitted when the store has no delivery configuration assigned.

Query Parameters​

ParameterTypeRequiredDescription
takenumberNoNumber of items per page (default: 50, max: 50)
pagestringNoPage number (default: 1)
cursorstringNoCursor for pagination. First call should pass 0, subsequent calls should use the cursor from the last item of the previous response
enabledbooleanNoFilter by enabled status

Response Example​

{
  "data": [
    {
      "ownerName": "Jane Doe",
      "internalCode": "STORE-1234",
      "ownerIdentifier": "OWNER-42",
      "legalName": "Jane Doe Market LLC",
      "legalId": "TAX-123456",
      "addressFormat": "123 Main Street, Springfield",
      "addresses": [
        {
          "internalCode": "ADDRESS-1",
          "addressLine": "123 Main Street",
          "apartmentNumber": "Suite 2",
          "zipCode": "10001"
        }
      ],
      "latitude": "40.7128",
      "longitude": "-74.0060",
      "enabled": true,
      "deleted": false,
      "users": [
        {
          "username": "jane@example.com",
          "name": "Jane Doe",
          "phone": "5551234567",
          "countryCode": "+1",
          "lastLoginAt": "2026-07-31T20:46:14.325Z"
        }
      ],
      "credit": { "amount": 5000, "currency": "USD" },
      "priceList": { "name": "Retail", "internalCode": "PRICE-1" },
      "promotionGroup": {
        "name": "Default promotions",
        "internalCode": "PROMO-GROUP-1"
      },
      "stockGroup": {
        "name": "Main stock",
        "internalCode": "STOCK-GROUP-1"
      },
      "deliveryConfig": {
        "name": "Weekly delivery",
        "internalCode": "DELIVERY-1"
      },
      "settings": {
        "supportContactEmail": "support@example.com",
        "supportContactPhone": "+15551234567",
        "dropSize": { "value": 1000, "text": "USD 1,000.00" }
      },
      "commertialRoute": {
        "name": "North route",
        "internalCode": "ROUTE-1"
      }
    }
  ],
  "page": {
    "cursorBased": {
      "firstCursor": "1234",
      "lastCursor": "1234",
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  }
}

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store?take=50&cursor=0&enabled=true",
  {
    method: "GET",
    headers: headers,
  },
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Upsert Store​

PUT/store

Create a new store or update an existing one based on the internal code. This is useful for:

  • Syncing store data from your ERP
  • Creating stores if they don't exist, updating if they do
  • Simplifying store management logic

Request Body Parameters​

Same as Create Store, with enabled being required:

ParameterTypeRequiredDescription
internalCodestringYesStore code (matches ERP) - used to find existing store
ownerNamestringYesName of the store owner
addressesarrayYesList of store addresses
legalNamestringYesLegal business name
legalIdstringYesLegal business identifier
enabledbooleanYesWhether the store is enabled
ownerIdentifierstringNoOwner identifier
latitudestringNoStore latitude
longitudestringNoStore longitude
addressFormatstringNoGoogle Maps formatted address
supportContactEmailstringNoEmail for support contact
supportContactPhonestringNoPhone for support contact
promotionGrouperCodestringNoCode for promotion group association
promotionGrouperCodesarrayNoArray of promotion grouper codes (only if multiple grouper configuration is enabled)
stockGrouperCodestringNoCode for stock group association
deliveryConfigCodestringNoDelivery configuration code to assign. If omitted, the current assignment is unchanged
priceListCodestringNoCode for price list association
routeCodestringNoRoute code for delivery
latePayerbooleanNoWhether the store is a late payer
settingsobjectNoStore settings (dropSize, etc.)

Request Body Example​

{
  "internalCode": "1234",
  "ownerName": "Owner name",
  "addresses": [
    {
      "addressLine": "25 de mayo 1200, Buenos Aires, Argentina",
      "zipCode": "2400"
    }
  ],
  "legalName": "Legal Name S.A.",
  "legalId": "30-12345678-9",
  "enabled": true,
  "stockGrouperCode": "6789",
  "deliveryConfigCode": "DELIVERY-1",
  "priceListCode": "1222"
}

Response Codes​

CodeDescription
200Successful operation
404Store not found

Get Store Details​

GET/store/{code}

Retrieve detailed information about a specific store. This endpoint returns:

  • Store metadata
  • Address information
  • User associations
  • Credit status
  • Group associations
  • The assigned delivery configuration, when present

The optional deliveryConfig response property has the same shape in this endpoint and in GET /store: { "name": string, "internalCode": string }. It is omitted when no delivery configuration is assigned.

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Response Example​

{
  "ownerName": "Jane Doe",
  "internalCode": "STORE-1234",
  "ownerIdentifier": "OWNER-42",
  "legalName": "Jane Doe Market LLC",
  "legalId": "TAX-123456",
  "addressFormat": "123 Main Street, Springfield",
  "addresses": [
    {
      "internalCode": "ADDRESS-1",
      "addressLine": "123 Main Street",
      "apartmentNumber": "Suite 2",
      "zipCode": "10001"
    }
  ],
  "latitude": "40.7128",
  "longitude": "-74.0060",
  "enabled": true,
  "deleted": false,
  "users": [
    {
      "username": "jane@example.com",
      "name": "Jane Doe",
      "phone": "5551234567",
      "countryCode": "+1",
      "lastLoginAt": "2026-07-31T20:46:14.325Z"
    }
  ],
  "credit": { "amount": 5000, "currency": "USD" },
  "priceList": { "name": "Retail", "internalCode": "PRICE-1" },
  "promotionGroup": {
    "name": "Default promotions",
    "internalCode": "PROMO-GROUP-1"
  },
  "stockGroup": {
    "name": "Main stock",
    "internalCode": "STOCK-GROUP-1"
  },
  "deliveryConfig": {
    "name": "Weekly delivery",
    "internalCode": "DELIVERY-1"
  },
  "settings": {
    "supportContactEmail": "support@example.com",
    "supportContactPhone": "+15551234567",
    "dropSize": { "value": 1000, "text": "USD 1,000.00" }
  },
  "commertialRoute": {
    "name": "North route",
    "internalCode": "ROUTE-1"
  }
}

Response Codes​

CodeDescription
200Successful operation
404Store not found

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store/1234", {
  method: "GET",
  headers: headers,
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Update Store​

PUT/store/{code}

Update an existing store's information. This endpoint allows you to:

  • Modify store details
  • Update address information
  • Change group associations
  • Adjust settings

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Request Body Parameters​

ParameterTypeRequiredDescription
ownerNamestringYesName of the store owner
addressesarrayYesList of store addresses
legalNamestringYesLegal business name
legalIdstringYesLegal business identifier
enabledbooleanYesWhether the store is enabled
ownerIdentifierstringNoOwner identifier
latitudestringNoStore latitude
longitudestringNoStore longitude
addressFormatstringNoGoogle Maps formatted address
supportContactEmailstringNoEmail for support contact
supportContactPhonestringNoPhone for support contact
promotionGrouperCodestringNoCode for promotion group association
promotionGrouperCodesarrayNoArray of promotion grouper codes (only if multiple grouper configuration is enabled)
stockGrouperCodestringNoCode for stock group association
deliveryConfigCodestringNoDelivery configuration code to assign. If omitted, the current assignment is unchanged
priceListCodestringNoCode for price list association
routeCodestringNoRoute code for delivery
latePayerbooleanNoWhether the store is a late payer
settingsobjectNoStore settings (dropSize, etc.)

Request Body Example​

{
  "ownerName": "Owner name",
  "ownerIdentifier": "Owner identifier",
  "addresses": [
    {
      "internalCode": "1234",
      "addressLine": "25 de mayo 1200, Buenos Aires, Argentina",
      "apartmentNumber": "2",
      "zipCode": "2400"
    }
  ],
  "latitude": "-34.545278",
  "longitude": "-58.449722",
  "addressFormat": "Av. Pres. Figueroa Alcorta 7597, C1428 Buenos Aires",
  "legalName": "Legal Name S.A.",
  "legalId": "30-12345678-9",
  "enabled": true,
  "supportContactEmail": "support@store.com",
  "supportContactPhone": "+5491123456789",
  "promotionGrouperCode": "1234",
  "stockGrouperCode": "6789",
  "deliveryConfigCode": "DELIVERY-1",
  "priceListCode": "1222",
  "routeCode": "1234",
  "latePayer": false,
  "settings": {
    "dropSize": {
      "amount": 1000,
      "currency": "USD"
    }
  }
}

Response Codes​

CodeDescription
200Successful operation
404Store not found

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  ownerName: "Updated Owner Name",
  addresses: [
    {
      addressLine: "New Address Line",
      apartmentNumber: "3",
      zipCode: "2401",
    },
  ],
  legalName: "Updated Legal Name",
  promotionGrouperCode: "5678",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store/1234", {
  method: "PUT",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Change Store Status​

PUT/store/{code}/status

Enable or disable a store. This endpoint allows you to:

  • Control store visibility
  • Manage store access
  • Update operational status

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Request Body Parameters​

ParameterTypeRequiredDescription
enabledbooleanYesWhether the store should be enabled

Request Body Example​

{
  "enabled": true
}

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  enabled: true,
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store/1234/status",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  },
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Manage Store Users​

Add User by Phone​

PUT/store/{code}/add/user

Add a user to a store using their phone number. This endpoint allows:

  • Associating new users with the store via phone
  • Setting up user access
  • Managing store personnel

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Request Body Parameters​

ParameterTypeRequiredDescription
countryCodestringYesCountry code with + prefix (e.g., "+54")
phonestringYesPhone number without country code
namestringNoUser's name

Request Body Example​

{
  "countryCode": "+54",
  "phone": "1123456789",
  "name": "John Doe"
}

Response Codes​

CodeDescription
200Successful operation
404Store not found

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  countryCode: "+54",
  phone: "1123456789",
  name: "John Doe",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store/1234/add/user",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  },
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Add User by Email​

PUT/store/{code}/add/user-email

Add a user to a store using their email address. This endpoint allows:

  • Associating new users with the store via email
  • Setting up user access for email-based authentication
  • Managing store personnel

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Request Body Parameters​

ParameterTypeRequiredDescription
emailstringYesUser's email
namestringNoUser's name

Request Body Example​

{
  "email": "user@example.com",
  "name": "John Doe"
}

Response Codes​

CodeDescription
200Successful operation
404Store not found

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  email: "user@example.com",
  name: "John Doe",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store/1234/add/user-email",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  },
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Remove Users​

PUT/store/{code}/remove/user

Remove users from a store. This endpoint enables:

  • Removing user associations
  • Managing access control
  • Updating store personnel

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Request Body Parameters​

ParameterTypeRequiredDescription
usersarrayYesArray of users to remove

users array items:

ParameterTypeRequiredDescription
countryCodestringYesCountry code with + prefix (e.g., "+54")
phonestringYesPhone number without country code

Request Body Example​

{
  "users": [
    {
      "countryCode": "+54",
      "phone": "1123456789"
    },
    {
      "countryCode": "+54",
      "phone": "1198765432"
    }
  ]
}

Response Codes​

CodeDescription
200Successful operation
404Store not found

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  users: [
    { countryCode: "+54", phone: "1123456789" },
    { countryCode: "+54", phone: "1198765432" },
  ],
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store/1234/remove/user",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  },
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Manage Store Credit​

POST/store/{code}/credit

Update store credit information. This endpoint allows:

  • Setting credit limits
  • Managing credit availability
  • Updating payment terms

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Request Body Parameters​

ParameterTypeRequiredDescription
creditLimitnumberYesNew credit limit for the store

Request Body Example​

{
  "creditLimit": 5000
}

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  creditLimit: 5000,
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store/1234/credit",
  {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
  },
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Payment Status Management​

Set as Defaulter​

POST/store/{code}/debtor

Mark a store as a defaulter. When a store is marked as a defaulter:

  • New orders are blocked
  • Credit access is restricted
  • Payment status is updated

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store/1234/debtor",
  {
    method: "POST",
    headers: headers,
  },
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Set as Late Payer​

POST/store/{code}/latepayer

Mark a store as a late payer. This status means:

  • Store can place new orders
  • Credit access is restricted
  • Payment status is monitored

Path Parameters​

ParameterTypeRequiredDescription
codestringYesStore internal code (matches ERP)

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/store/1234/latepayer",
  {
    method: "POST",
    headers: headers,
  },
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Batch Operations​

Assign Stores to Delivery Configurations​

POST/batch/delivery-config/stores

Adds or removes stores from delivery configurations asynchronously. Each operation identifies the delivery configuration with groupInternalCode and the store with storeInternalCode.

{
  "add": {
    "stores": [
      {
        "groupInternalCode": "2345",
        "storeInternalCode": "124f"
      }
    ]
  },
  "remove": {
    "stores": []
  }
}

At least one item must be present across add.stores and remove.stores. Empty arrays are accepted for the side that has no work. The endpoint returns 202 Accepted with separate batch IDs:

{
  "code": 202,
  "batchIds": {
    "add": ["550e8400-e29b-41d4-a716-446655440000"],
    "remove": []
  },
  "message": "Operation in processing"
}

For POST /store, PUT /store/{code}, and PUT /store, deliveryConfigCode is optional:

  • If omitted, Nilo leaves the current delivery configuration assignment unchanged.
  • If a valid code is provided, Nilo assigns or reassigns the store after validating that the configuration belongs to the authenticated supplier.
  • Explicit null is invalid and does not remove an assignment.
  • Use this batch endpoint's remove operation to unassign a store.

Required permission: supplier/grouper.bulkwrite.

Change Store Status in Batch​

POST/batch/store/status

Enables or disables multiple stores asynchronously. Each item requires code and enabled. The response returns 202 Accepted with batchIds, which can be followed through the Batch Operations API.

{
  "items": [
    { "code": "STORE-001", "enabled": true },
    { "code": "STORE-002", "enabled": false }
  ]
}

Required permission: supplier/store.bulkwrite.

Update Store Settings​

POST/batch/store/setting

Update settings for multiple stores simultaneously. This endpoint is useful for:

  • Bulk configuration updates
  • Standardizing store settings
  • Efficient store management

Request Body Parameters​

ParameterTypeRequiredDescription
storesarrayYesArray of store settings to update

Request Body Example for Batch Store Settings​

{
  "stores": [
    {
      "storeCode": "1234",
      "settings": {
        "credit": 5000,
        "debtor": false,
        "latePayer": false,
        "allowPartialDelivery": true,
        "minimumOrderAmount": 1000
      }
    },
    {
      "storeCode": "5678",
      "settings": {
        "credit": 10000,
        "debtor": true,
        "latePayer": true,
        "allowPartialDelivery": false,
        "minimumOrderAmount": 2000
      }
    }
  ]
}

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  stores: [
    {
      storeCode: "1234",
      settings: {
        credit: 5000,
        debtor: false,
        latePayer: false,
        allowPartialDelivery: true,
        minimumOrderAmount: 1000,
      },
    },
    {
      storeCode: "5678",
      settings: {
        credit: 10000,
        debtor: true,
        latePayer: true,
        allowPartialDelivery: false,
        minimumOrderAmount: 2000,
      },
    },
  ],
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/store/setting",
  {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
  },
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Batch Store Updates​

POST/batch/store

Perform updates on multiple stores simultaneously. This endpoint supports:

  • Creating multiple stores
  • Updating existing stores
  • Upserting store data

Request Body Parameters​

ParameterTypeRequiredDescription
createarrayNoArray of stores to create
updatearrayNoArray of stores to update
upsertarrayNoArray of stores to upsert
removearrayNoArray of store codes to remove

Request Body Example for Batch Store​

{
  "create": [
    {
      "ownerName": "Owner name",
      "ownerIdentifier": "Owner identifier",
      "internalCode": "1234",
      "addresses": [
        {
          "internalCode": "1234",
          "addressLine": "25 de mayo 1200, Buenos aires, Argentina",
          "apartmentNumber": "2",
          "zipCode": "2400"
        }
      ],
      "latitude": "-34.545278°",
      "longitude": "-58.449722",
      "addressFormat": "Av. Pres. Figueroa Alcorta 7597, C1428 Buenos Aires",
      "legalName": "legal name",
      "legalId": "legal id",
      "supportContactEmail": "string",
      "supportContactPhone": "string",
      "promotionGrouperCode": "1234",
      "stockGrouperCode": "6789",
      "pricelistCode": "1222",
      "routeCode": "1234",
      "settings": {
        "dropSize": {
          "amount": 1000,
          "currency": "USD"
        }
      }
    }
  ],
  "update": [
    {
      "ownerName": "Owner name updated",
      "ownerIdentifier": "Owner identifier updated",
      "internalCode": "5678",
      "addresses": [
        {
          "internalCode": "5678",
          "addressLine": "New address",
          "apartmentNumber": "3",
          "zipCode": "2401"
        }
      ],
      "latitude": "-34.545278°",
      "longitude": "-58.449722",
      "addressFormat": "New complete address",
      "legalName": "new legal name",
      "legalId": "new legal id",
      "enabled": true,
      "supportContactEmail": "new@email.com",
      "supportContactPhone": "1234567890",
      "promotionGrouperCode": "PROMO2",
      "stockGrouperCode": "STOCK2",
      "pricelistCode": "PRICE2",
      "routeCode": "ROUTE2",
      "latePayer": true,
      "settings": {
        "dropSize": {
          "amount": 2000,
          "currency": "USD"
        }
      }
    }
  ],
  "upsert": [
    {
      "internalCode": "9012",
      "ownerName": "Owner name upsert",
      "ownerIdentifier": "Owner identifier upsert",
      "addresses": [
        {
          "internalCode": "9012",
          "addressLine": "Upsert address",
          "apartmentNumber": "4",
          "zipCode": "2402"
        }
      ],
      "latitude": "-34.545278°",
      "longitude": "-58.449722",
      "addressFormat": "Upsert complete address",
      "legalName": "upsert legal name",
      "legalId": "upsert legal id",
      "enabled": true,
      "supportContactEmail": "upsert@email.com",
      "supportContactPhone": "0987654321",
      "promotionGrouperCode": "PROMO3",
      "stockGrouperCode": "STOCK3",
      "pricelistCode": "PRICE3",
      "routeCode": "ROUTE3",
      "latePayer": false,
      "settings": {
        "dropSize": {
          "amount": 3000,
          "currency": "USD"
        }
      }
    }
  ],
  "remove": ["9012"]
}

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  create: [
    {
      ownerName: "Owner 1",
      internalCode: "1234",
      addresses: [
        {
          addressLine: "Address 1",
          zipCode: "2400",
        },
      ],
      legalName: "Legal Name 1",
    },
    {
      ownerName: "Owner 2",
      internalCode: "5678",
      addresses: [
        {
          addressLine: "Address 2",
          zipCode: "2401",
        },
      ],
      legalName: "Legal Name 2",
    },
  ],
  update: [
    {
      ownerName: "Updated Owner Name",
      ownerIdentifier: "Updated Owner Identifier",
      internalCode: "5678",
      addresses: [
        {
          internalCode: "5678",
          addressLine: "New Address",
          apartmentNumber: "3",
          zipCode: "2401",
        },
      ],
      latitude: "-34.545278°",
      longitude: "-58.449722",
      addressFormat: "New Complete Address",
      legalName: "Updated Legal Name",
      enabled: true,
      supportContactEmail: "updated@email.com",
      supportContactPhone: "1234567890",
      promotionGrouperCode: "PROMO2",
      stockGrouperCode: "STOCK2",
      pricelistCode: "PRICE2",
      routeCode: "ROUTE2",
      latePayer: true,
      settings: {
        dropSize: {
          amount: 2000,
          currency: "USD",
        },
      },
    },
  ],
  upsert: [
    {
      internalCode: "9012",
      ownerName: "Upsert Owner Name",
      ownerIdentifier: "Upsert Owner Identifier",
      addresses: [
        {
          internalCode: "9012",
          addressLine: "Upsert Address",
          apartmentNumber: "4",
          zipCode: "2402",
        },
      ],
      latitude: "-34.545278°",
      longitude: "-58.449722",
      addressFormat: "Upsert Complete Address",
      legalName: "Upsert Legal Name",
      legalId: "Upsert Legal ID",
      enabled: true,
      supportContactEmail: "upsert@email.com",
      supportContactPhone: "0987654321",
      promotionGrouperCode: "PROMO3",
      stockGrouperCode: "STOCK3",
      pricelistCode: "PRICE3",
      routeCode: "ROUTE3",
      latePayer: false,
      settings: {
        dropSize: {
          amount: 3000,
          currency: "USD",
        },
      },
    },
  ],
  remove: ["9012"],
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/store",
  {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
  },
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Response Types​

Success Response​

{
  "code": 200,
  "message": "Operation successful",
  "data": {
    "ownerName": "Owner name",
    "internalCode": "1234",
    "addresses": [
      {
        "addressLine": "25 de mayo 1200, Buenos aires, Argentina",
        "apartmentNumber": "2",
        "zipCode": "2400"
      }
    ],
    "enabled": true
  }
}

Error Response Examples​

Store Not Found​

{
  "code": 404,
  "message": "Store not found"
}

Validation Error​

{
  "code": 400,
  "message": "Invalid store data",
  "errors": [
    {
      "field": "internalCode",
      "message": "Internal code is required"
    }
  ]
}

Best Practices​

  1. Store Management

    • Use consistent naming conventions
    • Maintain accurate address information
    • Implement proper status management
    • Keep store information up to date

  2. User Management

    • Validate user information
    • Maintain user access records
    • Document user changes
    • Implement user removal procedures

  3. Credit Management

    • Monitor credit limits
    • Track payment history
    • Document status changes
    • Implement credit checks

  4. Performance Optimization

    • Use batch operations for multiple updates
    • Implement caching strategies
    • Monitor API usage
    • Optimize data synchronization

Common Use Cases​

  1. Initial Store Setup

    • Create store profile
    • Configure user access
    • Set up credit limits
    • Configure group associations

  2. Store Maintenance

    • Update store information
    • Manage user access
    • Monitor credit status
    • Adjust store settings

  3. Bulk Operations

    • Import multiple stores
    • Update store settings
    • Modify group associations
    • Sync store data

  4. Credit Management

    • Monitor payment status
    • Update credit limits
    • Handle defaulters
    • Process credit changes

Implementation Guidelines​

  1. Store Creation

    • Validate required fields
    • Check for duplicate codes
    • Process address data
    • Set up initial configurations

  2. User Management

    • Validate user credentials
    • Handle user permissions
    • Manage user associations
    • Track user activities

  3. Credit Handling

    • Implement credit checks
    • Process payment status
    • Handle credit updates
    • Monitor credit usage

  4. Batch Processing

    • Validate batch data
    • Handle partial failures
    • Implement rollback
    • Report batch results

Security​

All API endpoints require two types of authentication:

  1. API Key in header: x-api-key
  2. Authorization token in header: Authorization

Required Permissions​

For store management endpoints, the following permissions are required:

  • For read operations: supplier/store.read
  • For write operations: supplier/store.write
  • For batch operations: supplier/store.bulkwrite
  • For credit operations: supplier/credit.write

Error Codes​

When an operation fails, the API returns a structured error response:

{
  "code": 404,
  "message": "STORE_NOT_FOUND",
  "object": {
    "statusCode": 404,
    "code": "STORE_NOT_FOUND",
    "message": "Store not found",
    "entity": "store",
    "entityCode": "STORE-001",
    "timestamp": "2026-05-18T15:16:47.000Z"
  }
}

The object field provides additional context about the error:

FieldDescription
statusCodeHTTP status code
codeError code (same as top-level message)
messageHuman-readable error description
entityEntity type that caused the error
entityCodeThe internalCode of the entity involved
timestampWhen the error occurred (ISO 8601)

404 — Not Found​

Error CodeDescription
STORE_NOT_FOUNDThe store does not exist for the given supplier
STORE_INTERNAL_CODE_NOT_EXISTThe provided internal code does not match any existing store
ROUTE_CODE_NOT_EXISTThe specified commercial route code does not exist
STORE_CURRENCY_NOT_EXISTThe specified currency is not configured for this store
ADDRESS_NOT_EXISTThe specified address does not exist for this store
USER_NOT_FOUNDThe user (email or phone) was not found in the system
SUPPLIER_RELATION_NOT_FOUNDNo relationship exists between the supplier and this store
CHANNEL_NOT_FOUNDThe specified channel does not exist

409 — Conflict​

Error CodeDescription
STORE_ALREADY_EXISTA store with the same name already exists
STORE_INTERNAL_CODE_ALREADY_EXISTA store with the same internal code already exists
ADDRESS_ALREADY_EXISTThe specified address already exists for this store
USER_ALREADY_EXISTThe username is already taken by another user
USER_ALREADY_EXIST_IN_SFAThe user is already associated to a sales representative

400 — Bad Request​

Error CodeDescription
ADDRESSES_REQUIREDAt least one address is required when creating a store
INVALID_PAGEThe page parameter is invalid
INVALID_PAGE_SIZEThe page size parameter is invalid
INVALID_COUNTRY_CODEThe provided country code format is invalid

422 — Business Rule Violation​

Error CodeDescription
STORE_NOT_TRANSACTIONALThe store is not enabled for transactions
STORE_NOT_BELONGS_TO_USERThe store does not belong to the specified user
MAX_STORES_PER_USER_EXCEEDEDThe user has exceeded the maximum number of stores allowed

Error Handling​

  1. Input Validation

    • Validate store codes
    • Verify address data
    • Check user information
    • Validate credit data

  2. Error Responses

    • Use appropriate HTTP codes
    • Provide clear messages
    • Include field-level errors
    • Add error tracking

  3. Recovery Procedures

    • Handle network failures
    • Implement retries
    • Maintain data consistency
    • Log error details

  4. Monitoring

    • Track error rates
    • Monitor API performance
    • Alert on critical errors
    • Analyze error patterns

Batch Add Users to Stores​

POST/batch/store/add/user

This endpoint allows you to add users to multiple stores at once. Each item must provide either an email, or a country code and phone number to identify the user.

Use this endpoint when you need to:

  • Onboard multiple store users simultaneously
  • Assign users to stores in bulk from your CRM
  • Synchronize store-user relationships from your ERP system

Request Body Parameters​

ParameterTypeRequiredDescription
addarrayYesArray of user-store assignment objects
add[].storeInternalCodestringYesStore internal code where the user will be added
add[].emailstringNoUser email (required if countryCode/phone not provided)
add[].countryCodestringNoCountry code (required if email not provided)
add[].phonestringNoPhone number (required if email not provided)
add[].namestringNoUser display name
User Identification

Each item must include either email OR countryCode + phone. If the user doesn't exist in the system, they will be invited automatically.

Request Body Example​

{
  "add": [
    {
      "storeInternalCode": "STORE-001",
      "email": "owner@store1.com",
      "name": "Store Owner 1"
    },
    {
      "storeInternalCode": "STORE-002",
      "countryCode": "+54",
      "phone": "1155667788",
      "name": "Store Owner 2"
    },
    {
      "storeInternalCode": "STORE-003",
      "email": "manager@store3.com"
    }
  ]
}

Response Codes​

CodeDescription
202Request accepted, processing initiated
404Store not found

Response Example​

{
  "code": 202,
  "batchIds": {},
  "message": "Operation in processing"
}

Example Usage​

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  add: [
    {
      storeInternalCode: "STORE-001",
      email: "owner@store1.com",
      name: "Store Owner 1",
    },
    {
      storeInternalCode: "STORE-002",
      countryCode: "+54",
      phone: "1155667788",
      name: "Store Owner 2",
    },
  ],
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/store/add/user",
  {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
  },
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));
  • Copyright © 2026 Nilo Labs
    Nilo
Tana

Tana

Ask me anything about Nilo's API — endpoints, authentication, integration guides, or code examples.

Best practice: validate against the official documentation for the most up-to-date details.