Every action below is available as a verb in Cerebral OS — callable from a Cerebral, a Map, or the Runtime API. All executions are governed, audited, and dry-run safe.
Add Or Update Address
fulfil:add_or_update_address
WORKFLOW FOR CREATE: 1. Build address data with all provided fields 2. Create address on customer using party.party API 3. Fetch customer to get new address ID 4. Return new address_id WORKFLOW FOR UPDATE: 1. Get current address to preserve existing fields 2. Merge: keep existing values, only update provided fields 3. Update address directly via party.address API 4. Return updated address_id WHEN TO USE: - Creating first address for new customer - Adding additional addresses (home, work, etc.) - Updating existing address (fix typo, add apartment, change phone) CRITICAL: - When updating, only provide fields that need to change - All unprovided fields preserve their existing values - Country and subdivision must be Fulfil IDs, not codes
Write
Low risk
Create Customer
fulfil:create_customer
Create a new customer in Fulfil with optional address. IMPORTANT: Check with find_customer first to avoid duplicates. Country and subdivision must be valid Fulfil record IDs. Returns the new customer ID.
Write
Low risk
Find Customer
fulfil:find_customer
WORKFLOW: 1. Search party.contact_mechanism table for email (email is stored separately from party record) 2. Extract party ID from contact_mechanism result 3. Get full party/customer details using that ID 4. Return customer_id, name, and email for use in subsequent actions WHY TWO STEPS: - Fulfil stores email in party.contact_mechanism table, not directly on party.party - The email field on party.party does not support search operations - Must search contact_mechanism first to get party ID, then fetch party details RETURNS: - found: boolean (true if customer exists) - customer_id: number (use this for fulfil:get_customer_orders) - name: string (customer's full name) - email: string (confirmed email address)
Read
Low risk
Find Order
fulfil:find_order
WORKFLOW: 1. Search sale.sale by order number field 2. Return order details including IDs needed for updates 3. Order number search is exact match (case-sensitive) RETURNS: - found: boolean (true if order exists) - order.id: numeric order ID (use for fulfil:update_order_address) - order.number: order number string (e.g., "SO2522140") - order.customer_id: party ID for the customer - order.state: order status (processing, confirmed, done, etc.) - order.shipment_address_id: current shipping address ID
Read
Low risk
Get Customer
fulfil:get_customer
Get full details for a Fulfil customer by ID. Returns complete customer record including all addresses. Use this after creating/updating to get the full current state.
Read
Low risk
Get Customer Orders
fulfil:get_customer_orders
WORKFLOW: MATCHING SHOPIFY ORDERS TO FULFIL ORDERS PROBLEM: - Shopify order number (PH29169745219) does NOT match Fulfil order number (SO2522140) - Cannot search Fulfil by Shopify reference directly SOLUTION: Match by creation date and customer STEP-BY-STEP MATCHING: 1. Get Shopify order → Extract created_at date (e.g., "2025-11-26") 2. Get customer email from Shopify order 3. Call fulfil:find_customer with email → Get customer_id 4. Call THIS ACTION with customer_id and state="processing" 5. Compare dates: Find Fulfil order where create_date matches Shopify created_at 6. Use matched order's ID (not number!) for fulfil:update_order_address WHAT THIS RETURNS: - id: Fulfil's internal order ID (USE THIS for updates!) - number: Fulfil order number like "SO2522140" (for reference only) - created_at: Order creation date (MATCH THIS to Shopify created_at) - sale_date: Sale date (alternative matching field) - state: Order status (processing, confirmed, done, etc.) - shipment_address_id: Current shipping address ID MATCHING LOGIC: - Compare Shopify order created_at to Fulfil order create_date - Match on same date (year-month-day) - If multiple matches, use the one in "processing" state - If still multiple, use the one with closest time CRITICAL: Always use order.id (numeric) for updates, NEVER order.number (string)!
Read
Low risk
Get Order
fulfil:get_order
WORKFLOW: 1. Get order details by order_id 2. Extract shipment_address_id and invoice_address_id 3. Fetch full address details for both addresses 4. Return order with complete address objects WHAT THIS RETURNS: - Order details: id, number, state, amounts, dates - shipment_address: COMPLETE address object with all fields (street, street2, city, subdivision, zip, country, name, phone) - invoice_address: COMPLETE address object with all fields - Customer: customer_id for reference - Arrays: line_ids, shipment_ids, invoice_ids USE CASES: - After updating address: get order to confirm address change worked - Before responding to customer: get actual current address to show them - Debugging: see complete order state including full addresses CRITICAL: This returns ACTUAL current address data from Fulfil, not just IDs Use the returned address fields in confirmation messages to show customer what's on file
Read
Low risk
get shipment
fulfil:get_shipment
WORKFLOW: 1. Get shipment by ID from stock.shipment.out model 2. Return hold status (on_hold, hold_reason), state, delivery_address ID, tracking 3. Use this to determine if address update is allowed: - on_hold: true → Can update address (shipment not sent to 3PL yet) - on_hold: false && state: "assigned" → Check 3PL, might be too late - state: "done" → Already shipped, cannot change CRITICAL USAGE: - Always check hold status BEFORE attempting address update - Hold status indicates if shipment has been sent to 3PL - If not on hold, address change may require 3PL coordination or be impossible
Read
Low risk
Update Customer
fulfil:update_customer
Update top-level fields on an existing Fulfil customer. Only provide fields you want to change - others remain unchanged. Use add_or_update_address to modify customer addresses. Returns success indicator.
Write
Low risk
Update Order Address
fulfil:update_order_address
WORKFLOW: 1. Get current order using order_id to find shipment_address_id 2. Get current address details to preserve existing fields 3. Merge: Keep all existing fields, only update fields provided in props 4. Update the address with merged data 5. Get order again to confirm update and return actual address CRITICAL RULES: - Input MUST be order_id (numeric) from fulfil:get_customer_orders, NOT order_number or Shopify reference - Only provide fields that need to change - empty/undefined fields preserve existing values - All existing address fields are preserved unless explicitly overridden - Returns actual address from Fulfil after update for customer confirmation COMMON USE CASES: 1. Add apartment number only: { order_id: 3066051, street2: "Apt 4B" } → Preserves street, city, state, zip, keeps everything except adds apartment 2. Change entire address: { order_id: 3066051, street: "123 New St", city: "Austin", subdivision: 3807, zip: "78701" } → Updates provided fields, preserves country, name, phone from existing address 3. Fix ZIP code only: { order_id: 3066051, zip: "45230-2438" } → Only updates ZIP, preserves all other fields RETURNS: - order_id: Fulfil order ID that was updated - shipment_address: Complete address object with ALL fields after update - This includes: street, streetbis (apt/unit), city, subdivision, zip, country, name, phone - Use this for customer confirmation: "Your order will ship to [address details]"
Write
Low risk
update shipment address
fulfil:update_shipment_address
WORKFLOW: 1. Create new party.address record with updated address fields 2. Update stock.shipment.out.delivery_address to point to new address 3. Return confirmation with new address details CRITICAL REQUIREMENTS: - Shipment MUST be on_hold: true (check with fulfil:get_shipment first) - If shipment already sent to 3PL, this will fail or cause issues - street2 maps to "streetbis" in Fulfil API - subdivision and country are NUMERIC IDs, not codes - This creates NEW address, doesn't modify existing (safe for other orders) FIELD MAPPING: - street2 (input) → streetbis (Fulfil) - subdivision (input) → subdivision (Fulfil) - must be numeric ID - country (input) → country (Fulfil) - must be numeric ID IMPORTANT: - After updating Fulfil, you MUST also update Shopify separately - Changes in Fulfil do NOT sync to Shopify automatically - Use shopify:update_order for the Shopify side
Write
Low risk