Company profiles

Create and update bounded customer and supplier profiles without exposing private finance, tax, ledger, or workflow fields.

Supported writes

POST requests require a stable idempotency key. PATCH requests require the latest updatedAt value as If-Match and preserve omitted fields. Add dryRun=true to the same endpoint when your workflow needs a non-mutating readiness check before execution.

Customer profiles

Customer profile writes are limited to public identity and the initial API-managed primary location/address bundle. Use the locations and addresses endpoints for additional customer locations or addresses after the customer exists.

curl "$SHELFCYCLE_API_BASE_URL/customers" \
  -X POST \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm:lead-1842:create-customer" \
  -d '{
    "name": "Northstar Chemical",
    "externalId": "NS-1842",
    "pipelineStatus": "PROSPECT",
    "primaryLocation": {
      "name": "Northstar Chemical HQ",
      "email": "ops@northstar.example",
      "phone": "555-0100",
      "address": {
        "name": "Northstar Chemical HQ",
        "street1": "100 Market Street",
        "city": "Chicago",
        "state": "IL",
        "zip": "60601",
        "country": "US"
      }
    }
  }'

The public API does not manage customer credit, payment terms, sales reps, tax data, ledger settings, or private workflow defaults.

Supplier profiles

Supplier profile writes are limited to public identity fields and an optional API-managed ship-from address. Use the supplier ship-from endpoints for additional ship-from locations after the supplier exists.

curl "$SHELFCYCLE_API_BASE_URL/suppliers/supplier-id" \
  -X PATCH \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: 2026-06-04T13:20:21.656Z" \
  -d '{
    "name": "Acme Supply",
    "email": "orders@acme.example",
    "primaryShipFromAddress": {
      "name": "Acme Supply Warehouse",
      "street1": "20 Industrial Way",
      "city": "Houston",
      "state": "TX",
      "zip": "77002",
      "country": "US",
      "defaultSupplierShippingInstructions": "Call before pickup."
    }
  }'

The public API does not manage supplier tax ids, ACH, banking, payment terms, credit, ledger data, representative defaults, root supplier address mutation, or general location lifecycle outside the ship-from endpoints.

Read before update

Use GET /customers/{id} or GET /suppliers/{id} before a PATCH. The response includes updatedAt; send that exact value as If-Match so ShelfCycle can reject stale overwrites with 409 stale_record.