PROMO-933 add bulk coupon code generation #970
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -88,13 +88,13 @@ paths: | |
| responses: | ||
| '201': | ||
| $ref: '#/components/responses/PromotionsResponse' | ||
| '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: | ||
|
|
@@ -195,6 +195,86 @@ 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 422 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: | ||
|
There was a problem hiding this comment. Lets add a |
||
| type: string | ||
| description: A prefix to add to the generated codes. | ||
| example: 'PROMO-' | ||
| minLength: 1 | ||
| maxLength: 20 | ||
| pattern: '[a-zA-Z0-9_\ -]' | ||
| suffix: | ||
|
There was a problem hiding this comment. Same here. A |
||
| type: string | ||
| description: A suffix to add to the generated codes. | ||
| example: '2025' | ||
| minLength: 1 | ||
| maxLength: 20 | ||
| pattern: '[a-zA-Z0-9_\ -]' | ||
| batch_size: | ||
| type: integer | ||
| description: The number of coupon codes to generate in each batch. The maximum value is 250. | ||
| example: 5 | ||
| minimum: 1 | ||
| maximum: 250 | ||
| max_uses: | ||
| type: integer | ||
| description: The maximum number of times each coupon code can be used. The default value is 1. | ||
|
There was a problem hiding this comment. should we default it to "0" which is unlimited usage, similar to docs/reference/promotions.v3.yml Line 248 in 9132b92 There was a problem hiding this comment. https://bigcommerce.slack.com/archives/G01623RLY87/p1749175141590099?thread_ts=1749170755.763259&cid=G01623RLY87 There was a problem hiding this comment. ah right, I forgot that discussion, should we change the minimum to 0 as it's an allowed value ? |
||
| example: 10 | ||
| minimum: 0 | ||
| maximum: 100000 | ||
| max_uses_per_customer: | ||
| type: integer | ||
| description: The maximum number of times a specific customer can use each coupon code. The default value is 1. | ||
| example: 5 | ||
| minimum: 0 | ||
| maximum: 100000 | ||
| required: true | ||
| responses: | ||
| '200': | ||
| $ref: '#/components/responses/BulkCouponCodesResponse' | ||
| '400': | ||
| description: Invalid request. | ||
| 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' | ||
|
|
@@ -206,7 +286,7 @@ paths: | |
| Get codes for a particular promotion. | ||
|
|
||
| **Note:** | ||
| The default rate limit for this endpoint is 10 concurrent requests. | ||
| operationId: getPromotionCodes | ||
| parameters: | ||
| - $ref: '#/components/parameters/PromotionIdPath' | ||
|
|
@@ -993,14 +1073,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 +1256,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 | ||
|
Comment on lines
+1263
to
+1269
There was a problem hiding this comment. not in scope of this PR: probably we can define a type for this and reuse it in many places |
||
|
|
||
| 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 +1595,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: | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
should we start with small number first ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe lets just not expose what our concurrent limits are? Since these are dynamic, probably not very useful to add a hard number in the docs