Document service_request_number placement on mailpieces (#538)

Adds a shared service_request_number attribute and references it from the
postcard, letter, self mailer, and check create models (the four resources
that accept it per lob-api validators). The field was previously undocumented,
which led a customer to nest it inside merge_variables where the API silently
ignores it — the mailpiece is created with no promotion applied and no error.

The description states the field must be top-level and must not be nested in
merge_variables, and the postcard create examples now include it as a sibling
of size. Mirrors the USPS promotions help-center language.

Follow-up to ER-515.

Author: stackptr

dist/lob-api-bundled.yml

@@ -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
@@ -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
@@ -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
@@ -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.
@@ -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.
@@ -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'
@@ -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:
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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:
@@ -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.
@@ -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:

resources/checks/models/check_editable_props.yml

@@ -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"

resources/letters/models/letter_editable.yml

@@ -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.

resources/postcards/models/postcard_editable.yml

@@ -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.

resources/postcards/postcards.yml

@@ -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
@@ -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
@@ -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

resources/self_mailers/models/self_mailer_editable.yml

@@ -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.

shared/attributes/service_request_number.yml

@@ -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.
+
+
+  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