docs(promotions): PROMO-933 add bulk coupon code generation

add bulk coupon code generation

Author: YevenLourance

reference/promotions.v3.yml

@@ -88,13 +88,13 @@ paths:
       responses:
         '201':
           $ref: '#/components/responses/PromotionsResponse'
-        '400': 
+        '400':
           description: The request payload was invalid.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse400'
-        '403': 
+        '403':
           description: The request payload was invalid.
           content:
             application/json:
@@ -195,6 +195,74 @@ paths:
         '204':
           description: The deletion was successful or the specified resource does not exist.
           content: {}
+
+  '/promotions/{promotion_id}/codegen':
+    post:
+      tags:
+        - Coupon Codes (Bulk)
+      summary: Generate Bulk Coupon Codes
+      description: |-
+        Generate a batch of coupon codes for a particular bulk coupon promotion.
+        
+        **Note:**
+        * batch_size is limited to 250 codes per request for first version. If batch_size is not an integer or larger than 250, it will return a 400 error code.
+        * The default rate limit for this endpoint is 40 concurrent requests.
+      operationId: generatePromotionCodesBatch
+      parameters:
+        - $ref: '#/components/parameters/ContentType'
+        - $ref: '#/components/parameters/Accept'
+        - $ref: '#/components/parameters/PromotionIdPath'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              required:
+                - batch_size
+              type: object
+              properties:
+                prefix:
+                  type: string
+                  description: A prefix to add to the generated codes.
+                  example: 'PROMO'
+                suffix:
+                  type: string
+                  description: A suffix to add to the generated codes.
+                  example: '2025'
+                batch_size:
+                  type: integer
+                  description: The number of coupon codes to generate in each batch. The maximum value is 250.
+                  example: 5
+                max_uses:
+                  type: integer
+                  description: The maximum number of times each coupon code can be used. The default value is 0, which represents unlimited uses.
+                  example: 10
+                max_uses_per_customer:
+                  type: integer
+                  description: The maximum number of times a specific customer can use each coupon code. The default value is 0, which represents unlimited uses.
+                  example: 5
+        required: true
+      responses:
+        '200':
+          $ref: '#/components/responses/BulkCouponCodesResponse'
+        '400':
+          description: The request payload was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse400'
+        '403':
+          description: The request payload was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse403'
+        '422':
+          description: The request payload was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
   '/promotions/{promotion_id}/codes':
     parameters:
       - $ref: '#/components/parameters/Accept'
@@ -993,14 +1061,12 @@ components:
           properties:
             previous:
               type: string
-  
               description: >
                 Link to the previous page returned in the response.
                 This property is omitted when the result set is empty or on the first page.
               example: '?limit=5&before=eyJpZCI6IjIzNzU1NyJ9'
             next:
               type: string
-  
               description: >
                 Link to the next page returned in the response.
                 This property is omitted when the result set is empty.
@@ -1178,6 +1244,24 @@ components:
           example: '2019-01-20T22:00:00.000Z'
       required:
         - code
+
+    BulkCouponCode:
+      type: object
+      properties:
+        code:
+          type: string
+          pattern: '[a-zA-Z0-9_\ -]'
+          description: A unique code that can be used to manually apply a discount. Only letters, numbers, white spaces, underscores and hyphens are allowed.
+          example: TEST-COUPON-CODE
+          maxLength: 50
+          minLength: 12
+
+    BulkCouponCodes:
+      type: array
+      description: An array of unique coupon codes generated by bulk.
+      items:
+        $ref: '#/components/schemas/BulkCouponCode'
+
     BulkActionResponseMeta:
       title: Bulk Action Response Meta
       type: object
@@ -1499,6 +1583,31 @@ components:
               total: 5
               success: 3
               failed: 2
+
+    BulkCouponCodesResponse:
+      description: ''
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              data:
+                $ref: '#/components/schemas/BulkCouponCodes'
+              meta:
+                type: object
+                properties: {}
+                description: 'Empty meta object, which may be used at a later time.'
+          examples:
+            example-1:
+              value:
+                data:
+                  - code: "PROMO-abc123-2025"
+                  - code: "PROMO-def456-2025"
+                  - code: "PROMO-ghi789-2025"
+                  - code: "PROMO-jkl012-2025"
+                  - code: "PROMO-mno345-2025"
+                meta: {}
+
     PromotionCodeResponse:
       description: ''
       content: