Coupon Code Generation

Coupon codes are generated in a coupon group. See Coupon Codes for an overview of coupon codes.

Coupon codes can be created in 3 ways:

1. Importing from a file
2. Automatic code generation
3. Manually using the /couponcodes Builder API Endpoints

Importing from a file

See File Uploads for uploading files to S3 ready for import.

A Coupon Code Batch is created to import coupon codes from a file. The format of coupon code files depends on if there is a user restriction or not (specified when you create the coupon batch).

No User Restriction

If you want the coupon codes to be usable by anyone (as opposed to a specific email address) the file just needs a coupon code per line. E.g.

Code1
Code2
Code3

User Restriction

If you want the coupon codes to be tied to a specific email address then the file needs to be a comma separated file with a line per entry in the format [code],[email] E.g.

Code1,user1@example.com
Code2,user2@example.com
Code3,user3@example.com

Automatic Code Generation

To generate codes you can choose the following options:

• Number of codes
• Character Count - number of characters in each code
• Character Set - the characters to use from in each code
• Prefix
• Suffix

Note, the maximum number of possible codes is limited by the character set and length (length of available characters ^ character count. E.g. for a character set of ABCD and code length 5 you have 4^5 or 1024 possible combinations). Also, you can only generate a maximum of 500000 codes in each batch.

If you start running out of available codes the generation process will fail. You can use a wider character set and/or allow a different length codes to increase the number of available permutations. You can also add a prefix/suffix to make the codes different from existing ones.

No User Restriction

An example API request to generate 100 codes is below.

curl -X 'POST' \
  'https://discounts-management.dovetech.com/couponcodebatches' \
  -H 'accept: */*' \
  -H 'x-api-key: [Builder API Key]' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "Generate",
    "groupId": "644151a7-74f1-44c7-8352-427aa28d38b3",
    "generationDetails": {
        "count": 100,
        "prefix": "",
        "suffix": "",
        "characterCount": 5,
        "characterSet": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
    }
}'

User Restriction

To generate codes tied to a specific email address, a file needs to be provided with the email addresses (email address per-line of the file).

Below is an example API request. This will create 3 codes; each code associated with an email address in the file.

{
  "type": "Generate",
  "groupId": "644151a7-74f1-44c7-8352-427aa28d38b3",
  "fileName": "983cf511397942bfaadb7a61cb3a2fa9/emails.txt",
  "codeTemplate": {
    "restrictions": ["UserRestriction"]
  },
  "generationDetails": {
    "count": 3,
    "prefix": "",
    "suffix": "",
    "characterCount": 5,
    "characterSet": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
  }
}

The contents of emails.txt looks like this:

test1@example.com
test2@example.com
test3@example.com

Coupon Codes Builder API

Coupon codes can be created using the /couponcodes API endpoint.

Below is an example request to create a code without restrictions or usage limits:

{
  "code": "BlackFriday",
  "groupId": "644151a7-74f1-44c7-8352-427aa28d38b3"
}

Below is an example request to create a code for a specific user with a usage limit of 1.

{
  "code": "UserSpecificCode",
  "groupId": "644151a7-74f1-44c7-8352-427aa28d38b3",
  "restrictions": [
    {
      "type": "UserRestriction",
      "email": "test@example.com"
    }
  ],
  "usageLimits": [
    {
      "type": "TotalUsageLimit",
      "limit": 1
    }
  ]
}

CSV File Notes

Note, due to the nature of CSV files, commas in the data need to be handled like so:

• A comma is encapsulated using quotes, so , becomes ","
• A comma and quote needs to be encapsulated and quoted, so "," becomes ""","""