> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upwell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer requirements

> Read effective required documents and shipper rules, including organization defaults and customer overrides.

# 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](https://docs.upwell.com/api-guides/syncing-foundation-entities.md#customers). It requires access to both customers and rules in your organization; roles without rule-read access cannot use it.

```bash theme={null}
curl 'https://api.upwell.com/api/rest/customers/cus_example/requirements' \
  -H 'Authorization: YOUR_API_KEY'
```

The response has one `customerRequirements` object:

| Field | Meaning |
| - | - |
| `customerId` | The Upwell customer ID. |
| `documentRequirements.receivable` | Effective customer-invoice document requirements and related checks. |
| `documentRequirements.carrier` | Effective carrier-invoice document requirements and related checks. |
| `shipperRules` | Effective global and customer shipper rules, including disabled and suppressed rules. |

## Document requirements and overrides

Each document setting includes its stable `exceptionType`, relevant `documentTypes`, effective `enabled` toggle, `status`, `configuration`, and human-readable `applicability`.

| `status` | How to interpret it |
| - | - |
| `required` | The baseline setting requires the document or check. Read `applicability` for alternatives and exemptions. |
| `conditional` | The setting depends on a charge, shipment mode, or configured exemption. Do not request the document for every shipment. |
| `not_required` | The setting is absent, disabled, waived, or an additional-document check has an empty configured list. |

`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:

```json theme={null}
{
  "exceptionType": "CUSTOMER_INVOICE_MISSING_BOL",
  "documentTypes": ["BILL_OF_LADING"],
  "enabled": false,
  "status": "not_required",
  "source": "customer",
  "ruleId": "rul_waiver",
  "overrideRuleId": "rul_waiver",
  "configuration": null,
  "applicability": "BOL; configuration may exempt TONU/TORD loads or allow a signed POD (customer override only). Prepaid invoices and invoices delivered outside Upwell are exempt."
}
```

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`.

## Conditional and related checks

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:

```json theme={null}
{ "customerRequirements": null }
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.