Permissions and scopes
API access is the intersection of the user's current SalesBinder permissions and the API key's scopes.
Effective access
An API key cannot grant its user access that the user does not already have in SalesBinder:
Effective API access
= eligible SalesBinder account
∩ current SalesBinder user permissions
∩ API key scopesEvery request checks all three layers. If the account, user permissions, or key scope denies the action, the API returns 403 Forbidden.
An API key cannot bypass a closed or otherwise restricted SalesBinder account. Create requests also follow the account's effective subscription record limit. When the limit has been reached, the API rejects the create without saving a partial record.
Scope modes
When creating a key, choose one of two scope modes.
Current permissions
All actions allowed by my current permissions does not add extra restrictions. The key can perform any API action that the user is currently permitted to perform.
Restricted scopes
Restricted scopes lets the user reduce the key's access. At least one scope must be selected. Restricted scopes never expand the user's SalesBinder permissions.
Customer scopes
| Scope | Allows |
|---|---|
customers:read | List and retrieve customers. |
customers:write | Create and update customers. |
customers:delete | Delete eligible customers. |
Scopes are independent. For example, a key can be permitted to create and update customers without being permitted to delete them.
Prospect scopes
| Scope | Allows |
|---|---|
prospects:read | List and retrieve prospects. |
prospects:write | Create and update prospects. |
prospects:delete | Delete eligible prospects. |
Customer and prospect scopes are independent. A customer scope never grants access to a prospect endpoint, and a prospect scope never grants access to a customer endpoint.
Supplier scopes
| Scope | Allows |
|---|---|
suppliers:read | List and retrieve suppliers. |
suppliers:write | Create and update suppliers. |
suppliers:delete | Delete eligible suppliers. |
Customer, prospect, and supplier scopes are independent. A scope for one account-record type never grants access to another type's endpoints.
Contact scopes
| Scope | Allows |
|---|---|
contacts:read | List and retrieve visible contacts. |
contacts:write | Create and update visible contacts. |
Contact access also requires the user's current account-management permission. Users permitted to view all account records can access contacts linked to any customer, prospect, or supplier in their account. Other users can access only contacts linked to account records assigned to them. Creating or replacing links requires every supplied account record to be visible to the user. API v3 does not support archiving or unarchiving contacts.
Inventory item scopes
| Scope | Allows |
|---|---|
items:read | List and retrieve inventory items, assigned variation attributes, variations, location-level quantities, item categories, active inventory locations, and their zones. |
items:write | Create, update, archive, and unarchive inventory items, create variations and empty variation-location rows, replace complete variation attribute combinations, update safe variation or variation-location metadata, and adjust basic-item or variation-location quantities. |
items:delete | Delete eligible unused item variations and variation-location rows. |
Inventory access also requires the user's current inventory-management permission. If the user is limited to one inventory location, API results are limited to items assigned directly to that location or stocked there through an item variation. Location discovery, zone discovery, variation lists, location rows, and aggregated quantities are also restricted to that assigned location. Item categories remain visible as account-level reference data. A key cannot use location_id to widen its user's live location permission.
Inventory writes additionally require the user's current inventory-modification permission. Location-limited users can create, update, adjust quantities, archive, and unarchive only within their assigned inventory location. Variation creation gives a location-limited user only an assigned-location inventory row; unrestricted users receive rows for all active account locations. An existing variation can be added to another active account location with all inventory balances initialized to zero. Variation metadata and complete attribute-combination updates require the variation to be stocked at the user's assigned location. Variation-location creation, metadata updates, and quantity adjustments require the item, variation, and location to belong together within the current account. A location-assigned user can create, configure, or adjust only that assigned location.
Variation and variation-location deletion additionally require the user's current inventory-delete permission. If that permission is not configured, SalesBinder may use the inventory-modification permission; an explicit denial is always respected. Location-assigned users cannot delete variations containing locations they cannot access and can delete only their assigned variation location. Variations used in documents or kits, or carrying any on-hand, reserved, incoming, or in-transit balance, cannot be deleted. A variation location cannot be deleted when it has any of those balances, is used by a document or sales-order line, or is the variation's last remaining location.
The selling price remains part of an accessible item object, but changing it or a variation's unit_price_override requires the user's current selling-price modification permission. Item cost and variation unit_cost_override fields are included or writable only when the user's current unit_costs permission allows unit-cost visibility.
Kit and bundle scopes
| Scope | Allows |
|---|---|
kits:read | List and retrieve kit definitions and components, and list existing assembly history. |
kits:build | Manually assemble kit quantities at an active permitted inventory location. |
kits:disassemble | Reverse and remove a stored assembly-history row at a permitted inventory location. |
Kit reads also require the user's current inventory-management permission. Assembly and disassembly require the current inventory-modification permission. Assembly history and changes respect the user's assigned inventory location; an explicit location_id cannot expand that access. Cost values are not included. API v3 does not support kit-definition creation, editing, or build-detail access.
Stock transfer scopes
| Scope | Allows |
|---|---|
stock_transfers:read | List and retrieve stock transfers and retrieve their stored lines. |
stock_transfers:write | Create pending stock transfers and edit pending or in-transit transfers. |
stock_transfers:send | Send pending stock transfers and move their quantities into transit. |
stock_transfers:receive | Receive in-transit stock transfers into destination inventory. |
stock_transfers:delete | Delete pending, in-transit, or transferred stock transfers and reverse moved inventory. |
Stock-transfer reads also require the user's current inventory-management permission; writes, sending, receiving, and deletion require the current inventory-modification permission. Stock transfers use account-wide location visibility, so assigned-user, origin-location, and destination-location values do not further restrict access. Creation is always pending and assigned to the current API user. Editing is limited to pending and in-transit transfers. Sending allows only pending-to-in-transit movement, and receiving allows only in-transit-to-transferred movement. Deleting a transfer reverses inventory already moved. API v3 does not support standalone reversal or setting an arbitrary transfer status.
Invoice scopes
| Scope | Allows |
|---|---|
invoices:read | List and retrieve active invoices, their current line items, and their payment history. |
invoices:write | Create invoices and update supported fields on eligible unpaid invoices. |
invoices:payments | Record manual payments against eligible invoice balances and credit notes. |
invoices:refunds | Record linked refunds against the remaining refundable amount of manual invoice payments. |
invoices:cancel | Cancel unpaid invoices that have no payment, packing, shipping, fulfillment, or drop-shipping activity. |
invoices:dispatch | Mark active invoices as dispatched without sending an email. |
invoices:delete | Delete unpaid invoices that have no payment, document-association, packing, shipping, or drop-shipping activity. |
Invoice access also requires the user's current invoice-list permission. Users permitted to view all invoices can access active invoices and payment history assigned to any user in their account. Other users can access only active invoices assigned to them. Reading payment history does not require permission to apply payments.
Invoice creation, update, dispatch, and cancellation also require the user's current invoice-modify permission. Recording a manual payment or manual refund requires the current apply-payments permission and does not require invoice-modify access. Payment, refund, dispatch, and cancellation scopes are independent, so restricted keys receive only the actions selected by their owner.
Deletion requires the current invoice-delete permission. If that permission is not configured, SalesBinder may use the invoice-modify permission; an explicit denial is always respected. Updates are limited to eligible unpaid invoices and explicitly supported fields. The API key cannot choose another salesperson, account, status, invoice number, totals, costs, or fulfillment state through the general invoice update endpoint. Inventory price overrides additionally require the current modify-selling-prices permission.
Invoice cost values are not included in API v3 responses. Manual payments and refunds recheck the available balance and update the invoice totals and status as part of the same operation. Neither endpoint contacts a payment provider; use the appropriate SalesBinder payment integration for provider-backed refunds. Dispatch sets or preserves date_sent without sending an email. Cancellation uses its dedicated endpoint. Deletion is limited to unpaid invoices with no related payment or fulfillment activity and never deletes related records. API v3 does not support invoice email delivery, archiving, restoring, setting an arbitrary status, or changing fulfillment state.
Estimate scopes
| Scope | Allows |
|---|---|
estimates:read | List and retrieve active estimates and retrieve their current line items. |
estimates:write | Create estimates and update supported fields on eligible open estimates. |
estimates:decline | Decline active, open estimates that have not been converted. |
estimates:delete | Delete active, open estimates that have not been converted. |
estimates:convert | Convert an eligible open estimate into a new unpaid invoice. |
estimates:convert_to_sales_order | Convert an eligible open estimate into a new open sales order. |
Estimate access also requires the user's current estimate-list permission. Users permitted to view all estimates can access active estimates assigned to any user in their account. Other users can access only active estimates assigned to them.
Estimate creation, update, and decline also require the user's current estimate-modify permission. Invoice conversion requires the current estimate-modify and invoice-modify permissions. Sales-order conversion requires the current estimate-modify, sales-order-list, and sales-order-modify permissions. Both require available account record capacity.
Deletion requires the current estimate-delete permission. If that permission is not configured, SalesBinder may use the estimate-modify permission; an explicit denial is always respected. Updates are limited to open estimates and explicitly supported fields. The API key cannot choose another salesperson, account, status, estimate number, totals, costs, or conversion state through the general update endpoint. Inventory price overrides additionally require the current modify-selling-prices permission.
Estimate cost values are not included in API v3 responses. Invoice and sales-order conversions create and link the new record and close the estimate as one operation. Declining preserves the estimate and its lines while refreshing availability. Deletion is limited to open, unconverted estimates and never deletes a resulting invoice or sales order. API v3 does not support sending, reopening, archiving, or restoring estimates.
Purchase order scopes
| Scope | Allows |
|---|---|
purchase_orders:read | List and retrieve active purchase orders, current line items, and payment history. |
purchase_orders:write | Create and update not-sent purchase orders with supported detail and line fields. |
purchase_orders:send | Mark eligible purchase orders as sent and schedule their incoming-inventory refresh. |
purchase_orders:receive | Record incremental inventory-line receipts against sent purchase orders. |
purchase_orders:payments | Create and delete positive manual payments for eligible purchase orders. |
purchase_orders:delete | Delete not-sent purchase orders that have no payment, receiving, drop-shipping, or related activity. |
Purchase-order access also requires the user's current purchase-order and unit-cost permissions. Users permitted to view all purchase orders can access active purchase orders assigned to any user in their account. Other users can access only active purchase orders assigned to them. Creation requires the current purchase-order-modify permission and follows any inventory-location restriction assigned to the user.
If a dedicated purchase-order permission is not configured, SalesBinder may use the corresponding inventory-modify permission. An explicit purchase-order permission denial is always respected.
Updates are limited to not-sent purchase orders and explicitly supported fields. Payment history uses purchase_orders:read and the same visibility rules as purchase-order retrieval. Creating or deleting a manual payment requires purchase_orders:payments, the account's purchase-order-payments setting, and the required purchase-order, unit-cost, visibility, and location permissions. Payments are limited to sent, partially received, or received purchase orders. Only positive manual payments can be deleted, and deletion cannot leave a negative paid balance.
Sending and receiving have their own scopes and permission checks. Receiving accepts positive incremental quantities for inventory lines on sent or partially received, non-drop-shipped purchase orders; inventory totals may update shortly after the response.
Deletion requires purchase_orders:delete and the user's current purchase-order-delete permission. It is limited to untouched not-sent drafts and never deletes related payments, sales orders, packing lists, or shipments. API v3 does not support separate purchase-order refund records, service-only receiving, archiving, or restoration.
Sales order scopes
| Scope | Allows |
|---|---|
sales_orders:read | List and retrieve sales orders, their current line items and quantities, and their packing and shipping fulfillment history. |
sales_orders:write | Create open sales orders, update supported header fields, and replace financial fields and lines before fulfillment. |
sales_orders:pack | Create packing-list fulfillments from explicit remaining sales-order quantities. |
sales_orders:ship | Mark an existing packing-list fulfillment as manually shipped. |
sales_orders:invoice | Create full or partial invoices from eligible open sales orders. |
sales_orders:delete | Delete open sales orders that have no related payment, document, or fulfillment activity. |
Sales-order access also requires the corresponding current sales-order permission. Creation requires sales-order-modify permission and follows account record limits, inventory-location restrictions, and selling-price permissions. Users permitted to view all sales orders can access sales orders assigned to any user in their account. Other users can access only sales orders assigned to them.
If a dedicated sales-order permission is not configured, SalesBinder may use the corresponding invoice permission. An explicit sales-order permission denial is always respected.
Sales-order and line-item cost data is not included in API v3 responses. Fulfillment history uses sales_orders:read and the same visibility rules as sales-order retrieval.
Packing requires sales_orders:pack, sales-order-modify permission, the account packing-list setting, and any inventory-location restriction. It accepts positive remaining quantities and protects against concurrent overpacking. Manual shipping requires sales_orders:ship and the same permission and visibility checks. It updates only an existing unshipped fulfillment and does not quote or buy shipping labels.
Listing linked invoices requires both sales_orders:read and invoices:read, with each resource's visibility rules applied independently. Financial and line updates require an untouched order. Invoicing requires sales_orders:invoice plus sales-order-modify and invoice-modify permissions. Deletion also requires the current sales-order-delete permission and never deletes related records. API v3 does not support closing, reopening, reversing a shipment, buying shipping labels, or crediting a sales order.
Record visibility
Customer, prospect, supplier, and contact results also follow the user's current record-visibility permissions. Users permitted to view all account records can access all eligible records in their account. Other users can access only account records assigned to them and contacts linked to those visible records.
The account and ownership boundary applies to list, retrieve, update, and delete operations. A record outside that boundary is not exposed by the API.
Inventory items use account and location visibility instead of customer ownership. An item outside the user's location boundary is not exposed by the API.
Invoices use the user's current invoice visibility. An invoice in another account, an invoice assigned to another user when view-all access is unavailable, or a non-invoice document is not exposed by the invoice endpoints.
Estimates use the equivalent current estimate visibility. An estimate in another account, an estimate assigned to another user when view-all access is unavailable, or a non-estimate document is not exposed by the estimate endpoints.
Purchase orders use the current purchase-order visibility. A purchase order in another account, assigned to another user when view-all access is unavailable, or belonging to another record type is not exposed by the purchase-order endpoints.
Sales orders use the current sales-order visibility. A sales order in another account or assigned to another user when view-all access is unavailable is not exposed by the sales-order endpoints.