Skip to content

Document service_request_number placement on mailpieces #538

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stackptr merged 1 commit into from
Jul 21, 2026
Merged

Document service_request_number placement on mailpieces #538

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 32 additions & 6 deletions dist/lob-api-bundled.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8946,6 +8946,7 @@ paths:
front: tmpl_a1234dddg
back: tmpl_a1234dddg
size: 6x9
service_request_number: '12345678'
mail_type: usps_first_class
merge_variables:
name: Harry
Expand Down Expand Up @@ -8994,6 +8995,7 @@ paths:
front: tmpl_c94e83ca2cd5121
back: tmpl_c94e83ca2cd5121
size: 6x9
service_request_number: '12345678'
mail_type: usps_first_class
merge_variables:
name: Harry
Expand Down Expand Up @@ -9055,6 +9057,7 @@ paths:
front: tmpl_a1234dddg
back: tmpl_a1234dddg
size: 6x9
service_request_number: '12345678'
mail_type: usps_first_class
merge_variables:
name: Harry
Expand Down Expand Up @@ -16026,9 +16029,10 @@ components:
source_material:
$ref: '#/components/schemas/booklet_source_material'
failure_reason:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/failure_reason'
- nullable: true
object:
type: string
description: Value is resource type.
Expand Down Expand Up @@ -18391,9 +18395,10 @@ components:
status:
$ref: '#/components/schemas/status'
failure_reason:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/failure_reason'
- nullable: true
object:
type: string
description: Value is resource type.
Expand Down Expand Up @@ -18494,6 +18499,15 @@ components:
- $ref: '#/components/schemas/tmpl_id'
- $ref: '#/components/schemas/remote_file_url'
- $ref: '#/components/schemas/local_file_path'
service_request_number:
type: string
description: |-
The service request number (SR#) of an approved USPS promotion (for example, the Integrated Technology promotion) to apply to this mailpiece. Supported on letters, postcards, self mailers, and checks.

This must be a **top-level** field in the create request, alongside `size`, `front`, and `back` — **not** nested inside `merge_variables` or any other object. A misplaced `service_request_number` is silently ignored: the mailpiece is created successfully with no promotion applied and no error returned.

The SR# must be approved for your account and cover the resource type, size, and mail type of this mailpiece for the promotion to apply. If omitted, no promotion is applied. See our <a href="https://help.lob.com/print-and-mail/building-a-mail-strategy/usps-promotions-through-lob" target="_blank">guide to USPS promotions through Lob</a> for more information.
nullable: true
check_editable_props:
allOf:
- $ref: '#/components/schemas/check_base'
Expand Down Expand Up @@ -18562,6 +18576,8 @@ components:
$ref: '#/components/schemas/billing_group_id'
use_type:
$ref: '#/components/schemas/chk_use_type'
service_request_number:
$ref: '#/components/schemas/service_request_number'
print_speed:
$ref: '#/components/schemas/print_speed'
check_editable:
Expand Down Expand Up @@ -19289,9 +19305,10 @@ components:
status:
$ref: '#/components/schemas/status'
failure_reason:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/failure_reason'
- nullable: true
object:
type: string
description: Value is resource type.
Expand Down Expand Up @@ -19687,6 +19704,8 @@ components:
$ref: '#/components/schemas/qr_code'
use_type:
$ref: '#/components/schemas/ltr_use_type'
service_request_number:
$ref: '#/components/schemas/service_request_number'
fsc:
type: boolean
description: This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `A4` and `us_legal` letter size.
Expand Down Expand Up @@ -19767,9 +19786,10 @@ components:
status:
$ref: '#/components/schemas/status'
failure_reason:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/failure_reason'
- nullable: true
object:
type: string
description: Value is resource type.
Expand Down Expand Up @@ -19846,6 +19866,8 @@ components:
$ref: '#/components/schemas/qr_code'
use_type:
$ref: '#/components/schemas/psc_use_type'
service_request_number:
$ref: '#/components/schemas/service_request_number'
fsc:
type: boolean
description: This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `4x6` or `A5` postcard sizes.
Expand Down Expand Up @@ -20326,9 +20348,10 @@ components:
campaign_id:
$ref: '#/components/schemas/campaign_id'
failure_reason:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/failure_reason'
- nullable: true
self_mailer_deletion:
description: Lob uses RESTful HTTP response codes to indicate success or failure of an API request. In general, 2xx indicates success, 4xx indicate an input error, and 5xx indicates an error on Lob's end.
properties:
Expand Down Expand Up @@ -20387,6 +20410,8 @@ components:
$ref: '#/components/schemas/qr_code'
use_type:
$ref: '#/components/schemas/sfm_use_type'
service_request_number:
$ref: '#/components/schemas/service_request_number'
fsc:
type: boolean
description: This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `11x9_bifold` self-mailer size.
Expand Down Expand Up @@ -20479,9 +20504,10 @@ components:
campaign_id:
$ref: '#/components/schemas/campaign_id'
failure_reason:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/failure_reason'
- nullable: true
color:
$ref: '#/components/schemas/color'
snap_pack_deletion:
Expand Down
3 changes: 3 additions & 0 deletions resources/checks/models/check_editable_props.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,5 +98,8 @@ allOf:
use_type:
$ref: "../attributes/chk_use_type.yml"

service_request_number:
$ref: "../../../shared/attributes/service_request_number.yml"

print_speed:
$ref: "../../../shared/attributes/print_speed.yml"
3 changes: 3 additions & 0 deletions resources/letters/models/letter_editable.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,9 @@ allOf:
use_type:
$ref: "../attributes/ltr_use_type.yml"

service_request_number:
$ref: "../../../shared/attributes/service_request_number.yml"

fsc:
type: boolean
description: This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `A4` and `us_legal` letter size.
Expand Down
3 changes: 3 additions & 0 deletions resources/postcards/models/postcard_editable.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,9 @@ allOf:
use_type:
$ref: "../attributes/psc_use_type.yml"

service_request_number:
$ref: "../../../shared/attributes/service_request_number.yml"

fsc: # Forest Stewardship Council
type: boolean
description: This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `4x6` or `A5` postcard sizes.
Expand Down
3 changes: 3 additions & 0 deletions resources/postcards/postcards.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,7 @@ post:
front: tmpl_a1234dddg
back: tmpl_a1234dddg
size: "6x9"
service_request_number: "12345678"
mail_type: usps_first_class
merge_variables:
name: Harry
Expand Down Expand Up @@ -261,6 +262,7 @@ post:
front: tmpl_c94e83ca2cd5121
back: tmpl_c94e83ca2cd5121
size: "6x9"
service_request_number: "12345678"
mail_type: usps_first_class
merge_variables:
name: Harry
Expand Down Expand Up @@ -323,6 +325,7 @@ post:
front: tmpl_a1234dddg
back: tmpl_a1234dddg
size: "6x9"
service_request_number: "12345678"
mail_type: usps_first_class
merge_variables:
name: Harry
Expand Down
3 changes: 3 additions & 0 deletions resources/self_mailers/models/self_mailer_editable.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,9 @@ allOf:
use_type:
$ref: "../attributes/sfm_use_type.yml"

service_request_number:
$ref: "../../../shared/attributes/service_request_number.yml"

fsc:
type: boolean
description: This is in beta. Contact support@lob.com or your account contact to learn more. Not available for `11x9_bifold` self-mailer size.
Expand Down
22 changes: 22 additions & 0 deletions shared/attributes/service_request_number.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
type: string

description: >-
The service request number (SR#) of an approved USPS promotion (for example,
the Integrated Technology promotion) to apply to this mailpiece. Supported on
letters, postcards, self mailers, and checks.


@gemini-code-assist gemini-code-assist Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

This must be a **top-level** field in the create request, alongside `size`,
`front`, and `back` — **not** nested inside `merge_variables` or any other
object. A misplaced `service_request_number` is silently ignored: the
mailpiece is created successfully with no promotion applied and no error
returned.


@gemini-code-assist gemini-code-assist Bot Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

The SR# must be approved for your account and cover the resource type, size,
and mail type of this mailpiece for the promotion to apply. If omitted, no
promotion is applied. See our
<a href="https://help.lob.com/print-and-mail/building-a-mail-strategy/usps-promotions-through-lob" target="_blank">guide to USPS promotions through Lob</a>
for more information.

nullable: true
Loading