Developer notes
USPS APIs used
Section titled “USPS APIs used”All calls go to https://apis.usps.com (or https://apis-tem.usps.com in test mode). Request and response shapes follow the official OpenAPI specifications published on developers.usps.com.
| Purpose | Endpoint | Notes |
|---|---|---|
| OAuth token | POST /oauth2/v3/token |
client_credentials; cached encrypted in ?:kv_usps_tokens until shortly before expiry; one retry with a fresh token on HTTP 401. |
| Rates | POST /shipments/v3/options/search |
Shipping Options 3. mailClass ALL_OUTBOUND (domestic) or ALL (international): one request per package returns every service. |
| Address validation | GET /addresses/v3/address |
Results cached 7 days. |
| Payment authorization | POST /payments/v3/payment-authorization |
Roles PAYER and LABEL_OWNER from the account (CRID, MID, manifest MID, EPS/permit). Token cached 3 hours. |
| Domestic label | POST /labels/v3/label |
Header X-Payment-Authorization-Token; response multipart/form-data with labelMetadata (JSON) and labelImage (Base64). |
| International label | POST /international-labels/v3/international-label |
Same, with customsForm. |
| Cancel / refund | DELETE /labels/v3/label/{trackingNumber}, DELETE /international-labels/v3/international-label/{trackingNumber} |
status CANCELED or DISPUTED (+ disputeId). |
| Tracking | GET /tracking/v3/tracking/{trackingNumber}?expand=DETAIL |
status, statusCategory, statusSummary, trackingEvents[]. |
Rate selection
Section titled “Rate selection”The service code of a CS-Cart shipping service is the USPS mail class, optionally followed by | and a rate indicator for flat-rate packaging (PRIORITY_MAIL|FS). From the Shipping Options response the add-on takes the cheapest rate option of that mail class whose destinationEntryFacilityType is NONE; flat-rate and cubic indicators are skipped for plain services. International rate options without a rate indicator are matched by description. totalPrice (with extra services) is used when present, otherwise totalBasePrice.
The service class Tygh\Shippings\Services\KvUspsV3 sets calculation_currency = 'USD', so CS-Cart converts the package value into USD before the call and the price back into the store currency.
Data model
Section titled “Data model”| Table | Contents |
|---|---|
?:kv_usps_accounts |
One row per account owner (0 = store / marketplace, vendor or storefront company IDs). Client secret encrypted (AES-256-GCM, key derived from the store’s crypt key). |
?:kv_usps_tokens |
Encrypted OAuth and payment tokens with expiry. |
?:kv_usps_boxes |
Box presets. |
?:kv_usps_labels |
Labels: order, owner, tracking number, service, postage, image (longblob), metadata, void/refund state, tracking state and events. |
?:kv_usps_customs |
Remembered HS code, origin and description per product. |
?:kv_usps_cache |
Cached Shipping Options and address answers. |
?:kv_usps_log |
API log, secrets masked. |
PHP: delete_order (labels removed with the order), calculate_cart_content_after_shipping_calculation (copies the USPS commitment into the method’s delivery time so the 4.17/4.18 lite checkout shows it). Templates: orders:tabs_extra (admin USPS tab), orders:info (customer tracking card), index:scripts / index:styles (checkout address suggestion, styles). Controllers: kv_usps_v3 (admin, vendor and storefront), orders.post (admin and storefront).
Full page cache (4.21)
Section titled “Full page cache (4.21)”Checkout, the customer order page and the AJAX address endpoint are never cached. The suggestion script is loaded only on checkout pages, and the tracking card is rendered on orders.details.
Testing against a mock
Section titled “Testing against a mock”Define KV_USPS_V3_API_BASE in config.local.php to send all USPS calls to another host, for example a local mock server:
define('KV_USPS_V3_API_BASE', 'http://127.0.0.1:8790');KV_USPS_V3_CA_FILE points cURL to a CA bundle on servers without one.
File map
Section titled “File map”app/addons/kv_usps_v3/ Tygh/Addons/KvUspsV3/ Api, Http, Multipart, Rates, Catalog, Packer, Labels, Tracking, Address, Accounts, Access, Config, Log, Secret Tygh/Shippings/Services/KvUspsV3.php real-time shipping service controllers/backend/kv_usps_v3.php, orders.post.php controllers/frontend/kv_usps_v3.php, orders.post.phpdesign/backend/templates/addons/kv_usps_v3/ USPS tab, labels, account, boxes, log, method configure tabvar/themes_repository/responsive/templates/addons/kv_usps_v3/ tracking card, checkout scriptjs/addons/kv_usps_v3/ admin.js (rate quote, boxes), func.js (checkout address suggestion)