Skip to main content

Customer requirements

Use GET /api/rest/customers/{id}/requirements to read the settings that apply to a customer in Upwell. It combines organization-wide Required Documents settings with customer overrides and includes the customer’s effective Shipper Rules, with their saved Name and Description. This read-only endpoint uses your existing API key. Supply the Upwell customer ID returned by the customer API. It requires access to both customers and rules in your organization; roles without rule-read access cannot use it.
The response has one customerRequirements object:

Document requirements and overrides

Each document setting includes its stable exceptionType, relevant documentTypes, effective enabled toggle, status, configuration, and human-readable applicability. source is global for an inherited organization setting, customer when a customer row controls it, and null when no setting exists. An explicit customer waiver is returned with enabled: false, status: "not_required", and source: "customer". It is not omitted. ruleId is the effective evaluator rule ID. overrideRuleId identifies a customer row replacing a global rule. Carrier and shipper overrides retain the global ruleId or id; receivable document overrides use the selected customer row’s ID. Customer-only rules have no overrideRuleId. For example, this entry within documentRequirements.receivable represents a customer BOL waiver:
The configuration contains effective saved configuration after applying the app’s override behavior. Optional fields retain application defaults rather than being populated with invented values:
  • Receivable document overrides replace the global configuration with the customer snapshot, including an empty or null configuration.
  • Carrier document overrides normally use the customer configuration when present, otherwise the global configuration. When global POD address matching is configured, the app merges its fields with the customer configuration.
  • An absent receivable podRiskProfile means inherited document marking; only an explicit customer profile changes that qualification. For carrier POD, an explicit profile takes precedence over legacy requireSignature. Without a profile, requireSignature: true means STRICT; false or absent means NO_SIGNATURE_REQUIRED.
This endpoint describes settings; it does not evaluate a particular invoice or shipment and does not report which documents are currently missing. Continue using invoice exceptions and missing-document responses for that workflow.
  • Lumper and washout receipts depend on matching charges. Carrier checks also consider bill lines. Washout accepts a wash receipt or accessorial receipt.
  • Carrier rate confirmation applies to TL/FTL shipments and checks document presence, not signature validation.
  • BOL and POD configuration may exempt TONU/TORD loads. Receivable POD may also exempt all-ocean shipments. Receivable requirements exempt prepaid invoices and invoices delivered outside Upwell; invoice-copy checks also exempt McLeod order-charge drafts. Carrier invoice-copy checks exempt owner-operator carriers.
  • documentTypes identifies relevant types, not every way a check can be satisfied. Standard checks can accept alternatives listed in applicability. Carrier POD requires documents that qualify as payables POD (isPod); a document merely typed PROOF_OF_DELIVERY is insufficient. Receivable POD follows its separate document-marking/customer-profile behavior.
  • Additional carrier documents use configuration.requiredDocumentTypes. The result’s documentTypes removes invalid values and duplicates. Every listed type must be supplied, but scale and weight tickets satisfy each other. An empty list means no requirement even if the saved toggle is enabled.
  • The unclassified-document hold and shipment signed-by check return documentTypes: []: they are checks shown alongside required documents, not requests for a new document type.

Shipper rules: Name and Description

Each shipperRules entry returns id, name, description, enabled, source, overrideRuleId, and the effective condition. name is the saved Name or null. description uses the saved Description, then the saved English summary displayed by the rule editor, then null. Upwell does not generate descriptions during the request. Customer overrides match global rules by their validation expression. A NEVER override returns one suppressed global rule with enabled: false, retaining its original global Name and Description rather than the override marker’s text. Other overrides return the effective customer text and condition. Matched overrides retain the global enabled toggle, consistent with the app; customer-only rules use their own toggle. Arbitrary shipper conditions remain expressions. Do not turn every shipper rule into an unconditional document requirement or use this endpoint as an invoice approval decision.

Missing customers and errors

Missing, archived, and inaccessible customers all return HTTP 200 with:
No global settings are returned in that case. An unauthorized role or invalid API key is rejected by the API. As with other custom API reads, a resolver failure can return HTTP 200 with an error body. Check for errors and a non-null customerRequirements result before reading its fields; do not treat a failed request as an empty list of requirements. Re-read the endpoint when your integration needs current settings. Changes made in the app are reflected on subsequent reads; this endpoint does not modify settings.