Notes / February 13, 2026

UPS “ship to account” behaviour in Shopware

Carrier APIs, account numbers, and checkout UX when the bill belongs to the customer’s UPS profile.

Patterns from a carrier-heavy Shopware build (Albany-adjacent); UPS-specific details generalized where needed.

“Ship to account” usually means the customer’s UPS account is referenced for rating, routing, or billing context, while the merchant may still consolidate labels in their OMS. The failure modes are subtle: invalid account numbers, residential/commercial mismatch, and rating vs. invoicing diverging.

1. Clarify the business contract first

Before typing PHP, answer:

  1. Who pays UPS on the invoice—merchant or customer account?
  2. Is the account number used for rating only or also label billing?
  3. What happens if UPS rejects the account mid-checkout—hard block or fallback to merchant bill?

Document answers in the ticket—engineering cannot infer this safely.

2. Checkout data model

Fields

  • ups_account_number (validated string; strip spaces; max length per UPS spec)
  • Optional: ups_account_zip for account validation APIs that require postal match
  • use_shipper_account boolean if hybrid flows exist

Persistence

  • Store on order customFields and copy to shipment payload for warehouse apps.
  • Never store in session only—reload must survive.

Validation

  • Server-side regex + optional UPS API validate call (cache positive results per account+zip for TTL to reduce latency).

3. Rating vs label creation

Rating (checkout)

  • Pass negotiated rates flag / shipper numbers per UPS REST docs for your integration path.
  • Log request + response XML/JSON in redacted form for first week—carrier debug is impossible without it.

Label creation (post-order)

  • OMS or middleware may own label purchase—Shopware might only reserve the method.
  • Ensure delivery entities carry enough context for the label job (packages, weight source).

4. Multi-package and returns

  • Multi-piece shipments: account context must repeat or inherit per package—test with 3+ cartons.
  • Returns: if RMA uses merchant account but outbound used customer account, surface that to CS scripts.

5. Error UX matrix

Condition UX
Invalid format Inline field error before payment
API “account not found” Block payment + link to FAQ
Timeout calling UPS Soft warning + allow retry button; do not double-charge

6. Testing checklist

  • Accounts: valid, invalid, suspended, wrong ZIP pairing.
  • Addresses: residential vs commercial flag impact on surcharges.
  • Currency edge cases if rare cross-border attempt.

7. Security

  • Treat account numbers as sensitive PII—limit admin role visibility, mask in logs (****1234).

Resume framing

“Integrated UPS account-aware shipping in Shopware: validated capture, rating integration with logging, label hand-off to OMS, and explicit error/fallback behaviour agreed with commerce/legal.”