>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3615071. --> Reported by: [introfini](https://www.drupal.org/user/42293) >>> <h3>Problem/Motivation</h3> <p>Issue <span class="drupalorg-gitlab-issue-link drupalorg-gitlab-link-wrapper"><a href="https://git.drupalcode.org/project/commerce_ups/-/work_items/3433436" class="drupalorg-gitlab-link">https://git.drupalcode.org/project/commerce_ups/-/work_items/3433436</a></span> gives the backoffice transmit, label recovery and void against the v2409 Shipping API. The collection itself is still manual: once the waybill is generated from Drupal, somebody has to remember to book the pickup on ups.com or by phone. On an on-demand account that step is easy to forget, and forgetting it leaves labelled parcels that nobody comes to collect.</p> <p>A UPS on-demand pickup is booked for an <strong>address on a date</strong>. The driver collects whatever is ready when they arrive, and the request is not tied to any tracking number. Each request carries a fee. So a site transmitting five shipments in a day needs <strong>one</strong> pickup, not five.</p> <h3>Proposed resolution</h3> <ul> <li><code>UPSSdk::createPickup()</code> and <code>::cancelPickup()</code>, against <code>/api/pickupcreation/v2409/pickup</code> and <code>/api/shipments/v2409/pickup/02</code>.</li> <li><code>UPSPickupRequest</code>, which builds the <code>PickupCreationRequest</code> payload and dispatches <code>UPSPickupRequestEvent</code> so sites can alter it, mirroring <code>UPSShipmentRequest</code>.</li> <li><code>PickupStore</code>, an expirable key-value ledger keyed by account, pickup address and date. This is what enforces one pickup per address and day: the first transmission of the day creates it, later ones attach to it.</li> <li>An optional "Schedule pickup" section on the transmit form (date, ready time, close time) that books the pickup after a successful ship. A pickup failure never undoes the transmission: the waybill already exists at UPS by then, so it degrades to a warning plus a log entry.</li> <li>On void, the shipment detaches from its pickup, and when the last waybill leaves, the operator is offered a cancel route keyed by PRN. Cancellation is never automatic, because the booking is address level and parcels from another source may still be waiting for the same driver.</li> <li>A new <code>pickup</code> settings group (contact name, contact phone, pickup point, default close time), plus a <code>hook_update_N</code> so existing sites get the defaults.</li> </ul> <h3>Remaining tasks</h3> <p>The branch is stacked on <code>3433436-shipping-api-v2409</code>, because the pickup flow builds on the transmit form, the fulfillment method resolver and the SDK that MR !29 introduces. A merge request will follow once !29 lands, so that it stays small and reviewable instead of growing !29 further.</p> <p>Branch: <a href="https://git.drupalcode.org/issue/commerce_ups-3433436/-/tree/3433436-pickup-api">3433436-pickup-api</a></p> <h3>Notes from validating against the CIE sandbox</h3> <p>Two findings that may save someone else time with the Pickup API:</p> <ul> <li>The pickup service code is <strong>the shipping service code left padded to three digits</strong>: <code>11</code> becomes <code>011</code>, <code>65</code> becomes <code>065</code>. There is no renumbering. The list is in the <a href="https://developer.ups.com/api/reference/pickup/appendix">Pickup Appendix</a> under Service Codes, and the sandbox rejects anything absent from it with <code>9500509: Missing or invalid ServiceCode</code>.</li> <li>That code has to come from the service the shipment is being <strong>transmitted as</strong>, not from <code>$shipment-&amp;gt;getShippingService()</code>. Once transmission is decoupled from the method the customer chose, the two differ: a shipment on a flat rate method carries no UPS service at all.</li> </ul> <h3>API changes</h3> <p>Additive only. Two methods on <code>UPSSdkInterface</code>, two services (<code>commerce_ups.pickup_store</code> and <code>commerce_ups.pickup_request</code>), one event, one route, and a <code>pickup</code> mapping in <code>commerce_ups.settings</code>.</p>