Document service_request_number placement on mailpieces

[stackptr]

Summary

Documents service_request_number on the mailpiece create endpoints. The field was previously undocumented in the API reference, even though the API has accepted it for some time on letters, postcards, self mailers, and checks.

Follow-up to ER-515: a customer (Wayfair) applying the USPS Integrated Technology promotion nested service_request_number inside merge_variables instead of at the top level of the payload. The API only reads the top-level field, merge_variables silently accepts arbitrary keys, so the postcards were created with no promotion applied and no error returned — the CCR code never generated. With no documentation for the field, the customer had nothing to reference for correct placement.

Changes

• New shared attribute shared/attributes/service_request_number.yml — optional, nullable string. The description:
  • States it must be a top-level field (sibling of size/front/back), not nested in merge_variables.
  • Warns that a misplaced value is silently ignored (created successfully, no promotion, no error) — the exact ER-515 failure mode.
  • Notes the SR# must be approved and cover the resource type/size/mail type, and links the USPS promotions help-center guide.
• Referenced from the four create models that accept the field per lob-api validators:
  • resources/postcards/models/postcard_editable.yml
  • resources/letters/models/letter_editable.yml
  • resources/self_mailers/models/self_mailer_editable.yml
  • resources/checks/models/check_editable_props.yml
  • (Intentionally not added to the shared form_factor/editable.yml, since that is also consumed by snap_packs and booklets, which do not accept the field.)
• Postcard create examples now include service_request_number as a sibling of size across all three request content types, so it renders in the sample payload.
• Regenerated dist/lob-api-bundled.yml.

Testing

• npm run bundle — succeeds; field resolves in all four resources.
• npm run spectral — 0 errors.
• npm run pretty:check — clean.

The resource contract tests (tests/) were not run locally — they make live HTTPS calls to lob-api.lob.com and require credentials; they'll run in CI.

Deploy note

This repo deploys to docs.lob.com only when a GitHub Release is created (per .github/workflows/deploy.yml); merging to main does not publish. A maintainer will need to cut a release to push these docs live.

[gemini-code-assist]

Code Review

This pull request introduces a new service_request_number field across various mailpiece schemas, including checks, letters, postcards, and self-mailers, to support USPS promotions. Additionally, the failure_reason schema definitions have been updated to explicitly set the type to object and ensure nullability. The reviewer provided feedback regarding the formatting of the newly created service_request_number.yml file, suggesting the removal of redundant blank lines to improve documentation conciseness.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

This extra blank line can be removed for more concise formatting. A single blank line is sufficient to create a paragraph break in the rendered documentation.

[gemini-code-assist]

This extra blank line can be removed for more concise formatting. A single blank line is sufficient to create a paragraph break in the rendered documentation.