Customers
List Customers
Returns a paginated list of customers.
Show Customer
Returns a single customer.
Customer Lookup (Quick Search)
Lightweight customer quick-search used by the POS register to attach a customer at checkout. Returns a compact card per customer including the live store-credit wallet balance (summed in one join, N+1-safe), the assigned pricing tier, and tax-exemption status. Archived customers are excluded.
List Duplicate Customer Pairs
List the candidate duplicate pairs produced by a completed detection run, hydrated with each customer's identifying details for side-by-side comparison. Pairs are ordered by match score (highest first) and paginated; pairs that have since been marked 'not a duplicate' are excluded from the results.
Export Customers
Download all customers matching the current filters as a spreadsheet file (CSV by default, XLSX when format=xlsx). The file contains the columns: Sr No., id, name, company, email, sales_channel_origin_name, integration_instance_name, created_at, updated_at, phone, then the default shipping address (shipping_name, shipping_company, shipping_address1, shipping_address2, shipping_address3, shipping_city, shipping_province, shipping_zip, shipping_country, shipping_phone) and the default billing address (billing_name, billing_company, billing_address1, billing_address2, billing_address3, billing_city, billing_province, billing_zip, billing_country, billing_phone). then the customer's default settings (default_warehouse, default_warehouse_id, default_pricing_tier, default_sales_rep, default_store, default_shipping_method_domestic, default_shipping_method_international — names, except the warehouse id; blank when not set). Address columns are blank when the customer has no default address of that type. Rows are ordered by customer ID ascending and the export is not paginated - every matching customer is included.
Mark Customer Pair as Not Duplicate
Record a decision that two customers are not duplicates of each other, so the pair stops appearing in duplicate detection results. The decision is order-independent (the pair is stored with the lower ID first) and idempotent - repeating the call for the same pair returns the existing decision.
Start Customer Duplicate Detection Run
Start an asynchronous duplicate-detection run over customer records. The work is dispatched to a background job and the endpoint returns immediately with a tracked_job_log_id. Once the run completes, fetch the scored candidate pairs from the List Duplicate Customer Pairs endpoint using that ID.
Merge Customers
Merge the secondary customer into the primary customer. This is a destructive operation performed in a single transaction:
Undo Customer Merge
Reverse a previous customer merge: un-archives the secondary customer and moves the records that were reassigned during the merge back to it.
Preview Customer Merge
Preview the effect of merging one customer (secondary) into another (primary) without changing any data. Returns, per related record type, the number of records currently attached to the secondary customer that would be reassigned to the primary: sales orders (sales_orders), sales credits (sales_credits), customer SKU mappings (customer_sku_mappings), order document extractions (sales_order_ocr_extractions), and linked QuickBooks customer records (qbo_customers).
Create Customer
Create a new customer. Automatically creates a default shipping address from the root address fields. Optionally provide a separate billing address.
Bulk Delete Customers
Bulk delete customers by IDs or by applying to all filtered results.
Get Customer
Get a single customer with all related data including addresses, billing/shipping addresses, default settings, and lifetime value.
Update Customer
Update an existing customer. All fields are optional. Default settings (pricing tier, store, shipping methods, warehouse) can only be set on update.
Delete Customer
Delete a customer. Returns 400 if the customer is linked to sales orders or other records.
Get Customer Addresses
Retrieve all addresses associated with a customer including default shipping, billing, and other addresses.
Add Customer Address
Add a new address to a customer. Address deduplication is applied.
Set Default Shipping Address
Set a specific address as the customer's default shipping address.
Set Default Billing Address
Set a specific address as the customer's default billing address.
Delete Customer Address
Remove an address from a customer's address book. If the removed address was the customer's default shipping or billing address, the most recently added remaining address is automatically promoted as the new default (or the default is cleared when no other address exists). The underlying address record is permanently deleted only when no other records (other customers, sales orders, etc.) still reference it; otherwise only the customer's link to it is removed.
Bulk Archive Customers
Bulk archive customers by IDs or by applying to all filtered results.
Bulk Unarchive Customers
Bulk unarchive customers by IDs or by applying to all filtered results.
Check Deletable Customers
Check which customers can be deleted. Returns deletability status for each customer.
Archive Customer
Archive a single customer.
Unarchive Customer
Unarchive a previously archived customer.
Preview Customers Import
Preview a customer import from a CSV file before committing.
Import Customers
Import customers from a CSV file.
Find Customer Match
Find customer matches based on name, ZIP code, and address. Uses approximate matching (90% match on address1).
Get Open Sales Credits
Get the customer's open sales credits that can still be applied as store credit, each with its unapplied balance. A credit note issued against a sales invoice is included for whatever part of it that invoice did not absorb (for example a credit on an already-paid invoice); overpayment credits are included.
Get Unpaid Orders
Get all unpaid sales orders for a customer.
Allocate Sales Credit to Orders
Allocate an open sales credit to one or more sales orders. The amounts together may not exceed the credit's tax-inclusive total less what was already refunded from it, and each amount may not exceed what is still unpaid on its order.
Unallocate Sales Credit from Order
Reverse a single sales credit allocation. Deletes the allocation row, reverses the corresponding Credit-type Payment recorded against the sales order, and recalculates the credit's payment_status (paid → partially_paid or open).
Submit Orders to Starshipit
**This GET dispatches a background job** (queues a bulk submit of every open Starshipit fulfillment).
Update Starshipit Order from Fulfillment
Update an existing order in Starshipit from a sales order fulfillment.
View Starshipit Order
View the Starshipit order for a sales order fulfillment.
List SKU Mappings
Return a paginated list of SKU mappings for the specified customer. Each mapping links a customer-facing SKU code to an internal product.
Create / Upsert SKU Mapping
Create a new SKU mapping or update an existing one (upsert) for the given customer. If a mapping for customer_sku already exists, it is updated with the new product_id.
Delete SKU Mapping
Delete a specific SKU mapping by ID for the given customer.
Import SKU Mappings from CSV
Bulk-import SKU mappings for a customer from a CSV file. The CSV must have a header row with columns customer_sku and product_id. Existing mappings for the same customer_sku are updated (upsert behaviour).
Export SKU Mappings as CSV
Export all SKU mappings for a customer as a CSV file download. The response is a CSV with columns customer_sku and product_id. Use this as a template for the import endpoint.
List Customer Contacts
List all contacts attached to a customer, paginated. Supports search (title/notes), role/primary/has-email filters, advanced per-column filters, and sorting.
Create Customer Contact
Add a new contact to a customer. Fields: name (required), email, phone, role (default general), title, is_primary, notes (max 500). The first contact added to a customer automatically becomes primary; setting is_primary demotes the previous primary.
Export Contacts
Download all contacts belonging to the customer as a CSV or XLSX file. Columns: Contact ID, Name, Email, Phone, Role, Title, Primary, Notes, Created At, Updated At. The file mirrors the contacts bulk-import template, so an exported file can be edited and re-imported (rows with a Contact ID or a matching email update the existing contact; others are created).
Get Customer Contact
Get a single contact belonging to the customer. A contact id that belongs to a different customer returns 404.
Update Customer Contact
Update a contact belonging to the customer. Full update — name is required. Setting is_primary promotes this contact and demotes the previous primary.
Delete Customer Contact
Delete a contact from the customer. If the deleted contact was primary and other contacts remain, the oldest remaining contact is promoted to primary.
Set Customer Contact as Primary
Promote a contact to be the customer's primary contact, demoting the previous primary.
Get Store Credit Balance
Returns the customer's current store-credit wallet balance — the running sum of every ledger entry.
Issue Store Credit
Manually issue (or adjust) store credit for a customer.
Get Store Credit History
Paginated ledger history for the customer's store-credit wallet, newest first. Each entry records a signed movement (`amount`), the running `balance_after`, the reason, and — for system-driven entries — the polymorphic source (e.g. a POS transaction for a refund-to-credit).
Get Customer AR Summary
Returns the customer's accounts-receivable summary in one call: outstanding and overdue totals, aging buckets, open credits, net receivable, credit headroom, informational wallet balances, the most recent payment, and the head of the overdue worklist.
List Customer Receivables
Paginated receivables worklist for one customer — each row is a sales order reduced to its receivable shape.
Get Customer Statement
Returns the customer's statement of account as JSON, in one of two views selected by `type`:
Export Customer Statement
Downloads the customer's statement of account as a file. `format=pdf` (default) returns a branded PDF document (`application/pdf`); `format=csv` returns comma-separated rows (`text/csv`).
Preview Customer Statement Email
Preview the statement email that a send would produce — the exact From and Reply-To addresses, resolved recipient, subject and body — WITHOUT sending it or logging anything. Use it to show the sender and content before committing to send.
Send Customer Statement
Emails the customer a statement of account with the PDF attached, and records the send in the communications log.
Request Customer Payment
Emails the customer an account-level payment request for their outstanding balance, and records the send in the communications log. To request payment for a single order instead, use the request-payment action on that sales order (Orders collection).
List Customer AR Communications
Paginated log of outbound receivables emails sent to this customer, newest first. Entries are created by the send-statement and request-payment actions (both the account-level actions here and the per-order request-payment action in the Orders collection).
Get Customer Tax Exemption Coverage
The customer's resale / exemption certificate (tax_exempt, tax_exemption_reference, tax_exemption_state, tax_exemption_expires_on) measured against every state where the tenant is registered to collect sales tax. Each state gets a status: valid (exempt there), expired, missing (marked exempt with no certificate number), wrong_state (a single-state certificate from another state), or taxable (not marked exempt). `has_warning` is true when any registered state is expired, missing or wrong_state. `configured` is false (and `states` empty) while the tenant has no registrations.
List Customers
Paginated list of Magento 2 customers scoped to one integration instance.
Get Customer
Single customer detail. Eager-loads the integration instance, addresses, and orders_count.
Get Customer Filter Options
Aggregated dropdown options for the customers filter panel — countries (via the address rows), customer groups, and websites — each as `{value, label, count}` so the picker can render counts inline. Pulled live from the customers persisted for this instance; empty / never-synced instances surface empty lists.
Refresh Customers
Start a tracked background job that pulls Magento 2 customers and their addresses (`GET /V1/customers/search`) into SKU.io. Incremental: only customers updated since the newest one already stored are fetched. Returns the `tracked_job_log_id`; the job reports an `error` when Magento 2 refuses the request.
Refresh Single Customer
Start a tracked background job that re-fetches this one customer (and its addresses) from Magento 2. The job name shares the `Sync Magento 2 Customers: ` prefix with the bulk refresh.
Search Customers
Search-as-you-type endpoint. Delegates to the same paginated query as `List Customers` (Spatie QueryBuilder under the hood) so every filter / sort / pagination param the index supports is also accepted here. Provided as a separate route so the frontend can wire a dedicated debounce path.
List Square Customers
Paginated list of Square customers across integration instances.
Sync Square Customers
Fetch and upsert Square customers for a specific instance. Queued.