Create Rule Promotion Codes

POST 
https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes

Creates new promotion codes for a specific rule promotion, allowing customers to redeem discounts based on predefined conditions.

• Supports bulk creation of multiple promotion codes in a single request.
• Each code can have individual usage limits.
• Can optionally assign codes to specific users to enforce targeted promotions.
• The promotion codes are case-insensitive.

note

Regarding first time shopper limitations:

• Orders without payment transactions do not count as completed purchases.
• Canceling or refunding an order does not reinstate first-time shopper status.
• A first-time shopper coupon code cannot have limited uses or be assigned to specific users, meaning the code cannot be restricted by the number of times it can be used or tied to a specific customer ID.

A successful request returns a 201 Created response with details of the generated promotion codes.

Duplicate Codes

Duplicate promotion codes are supported across different promotions in the store, regardless of their statuses and validity dates. However, duplicate codes cannot be created within the same promotion. This means that shoppers can apply a single coupon code to trigger multiple promotions if those promotions share common coupon codes.

Codes that share the same name can serve different purposes. For example, one code may have per_application with a limited number of uses, while another identical code can have per_checkout with unlimited use.

Duplicate Code Handling:

• If a duplicate code is detected within the same promotion, the request will return a 422 Duplicate code error.
• When creating duplicate codes, a message appears with the successful response indicating the duplication.

Please refer to the OpenAPI examples section on this page for sample request structures.

Request

Path Parameters

promotionID stringrequired

The unique identifier of the rule promotion.

Header Parameters

Authorization Bearerrequired

The Bearer token required to get access to the API.

application/json

Bodyrequired

data object
typestring
Possible values: [promotion_codes]
codes object[]
Specifies the code details in an array of objects.
Array [
codestring
Specifies the string to use as a code for the promotion.
usesinteger
Specifies the number of times the code can be used. If no value is set, the customer can use the code any number of times.
userstring
Specifies the customer ID of the shopper who can use the code. For more information, see the Create a customer section.
consume_unitstring
Specifies whether the code is consumed per application or per checkout. With per_checkout, the code is used once for each checkout, regardless of the number of items in the cart. When set to per_application, the code is used per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage. For example, in a store that offers 50% off on SKU1, SKU2, and SKU3, and limits the maximum usage of the promotion code to two, a shopper can apply the promotion up to two quantities. If the cart contains two or more quantities of SKU1, the promotion is applied 2 times to SKU1, and other quantities and items are at the regular price. If the cart contains one quantity of SKU1, one quantity of SKU2, and one quantity of SKU3, the promotion is applied once to SKU1 and once to SKU2. The code usage is applied at checkout and the code is considered consumed at that point.
Possible values: [per_application, per_checkout]
max_users_per_shopper object
Object for setting max uses per shopper. Only include this object, when you want to set limit per shopper.
max_usesinteger
Sets max number of times the code can be used by a shopper. NOTE - This cannot be set with per_application consume unit.
includes_guestsboolean
The flag to include guest shoppers for the discount with max use restriction. If this field is provided, the max_uses value is required. When set to true, guest shoppers must have an email associated with the cart to use the code. A guest cart without an email cannot use the code. When set to false, guest shoppers cannot use the promo code, even if the cart has an associated guest email.
Default value: false
is_for_new_shopperboolean
A flag indicating whether the coupon is for first-time shoppers. If set to true, the discount will only apply if the shopper has never made a payment on any order in the store. If set to false or left unset, it will be a regular discount that applies to all shoppers. When this flag is set to true, the coupon cannot have usage limitations or be assigned to specific users.
]

Responses

201

Created

application/json

Schema

Schema

data object[]
Array [
typestring
Possible values: [promotion_codes]
codestring
usesinteger
userstring
consume_unitstring
Possible values: [per_application, per_checkout]
max_usesinteger
max_users_per_shopper object
Object for setting max uses per shopper. Only include this object, when you want to set limit per shopper.
max_usesinteger
Sets max number of times the code can be used by a shopper. NOTE - This cannot be set with per_application consume unit.
includes_guestsboolean
The flag to include guest shoppers for the discount with max use restriction. If this field is provided, the max_uses value is required. When set to true, guest shoppers must have an email associated with the cart to use the code. A guest cart without an email cannot use the code. When set to false, guest shoppers cannot use the promo code, even if the cart has an associated guest email.
Default value: false
is_for_new_shopperboolean
]
messages object[]
Array [
source object
Information about the affected promotion codes.
typestring
Indicates that the affected entity is a promotion code.
Possible values: [promotion_codes]
Example: promotion_codes
codesstring[]
A list of promotion codes that triggered the message.
titlestring
A brief title summarizing the message.
Example: Duplicate code names
descriptionstring
A detailed explanation of the message.
Example: Code names duplicated in other promotions
]

Example (auto)

{
  "data": [
    {
      "type": "promotion_codes",
      "code": "string",
      "uses": 0,
      "user": "string",
      "consume_unit": "per_application",
      "max_uses": 0,
      "max_users_per_shopper": {
        "max_uses": 0,
        "includes_guests": false
      },
      "is_for_new_shopper": true
    }
  ],
  "messages": [
    {
      "source": {
        "type": "promotion_codes",
        "codes": [
          "spring2024"
        ]
      },
      "title": "Duplicate code names",
      "description": "Code names duplicated in other promotions"
    }
  ]
}

PromotionCodeCreatedResponse

Response When a Promotion Code is Successfully Created

{
  "data": [
    {
      "id": "8a1c73bc-7c15-41c3-a3ed-a0aa398c3984",
      "code": "one_per_shopper",
      "user": "5abb8d4e-57c0-459b-91d5-c4e6f77e9c5e",
      "max_uses_per_shopper": {
        "max_uses": 1,
        "includes_guests": false
      },
      "consume_unit": "per_checkout"
    }
  ]
}

FullyConsumedPromotionCodeResponse

Response When a Promotion Code Has Been Fully Used

{
  "messages": [
    {
      "source": {
        "type": "rule_promotion",
        "id": "38861a5c-81bb-43bc-8934-e30cde108579",
        "code": "one_per_shopper"
      },
      "title": "Fully Consumed",
      "description": "You've already fully consumed this promotion code"
    }
  ]
}

DuplicateCodeNameResponse

Message Response When Creating a Duplicate Promotion Code Name

{
  "messages": [
    {
      "source": {
        "type": "promotion_codes",
        "codes": [
          "duplicate-code"
        ]
      },
      "title": "Duplicate code names",
      "description": "Code names duplicated in other promotions"
    }
  ]
}

400

Bad Request

application/json

Schema

Schema

errors object[]
Array [
statusinteger
Example: 400
sourcestring
Example: data.codes.0.max_uses_per_shopper
titlestring
Example: missing_dependency
detailstring
Example: Has a dependency on max_uses
]

Example (auto)

{
  "errors": [
    {
      "status": 400,
      "source": "data.codes.0.max_uses_per_shopper",
      "title": "missing_dependency",
      "detail": "Has a dependency on max_uses"
    }
  ]
}

MissingMaxUsesDependencyError

Error When max_uses_per_shopper.includes_guests is Provided Without max_uses

{
  "errors": [
    {
      "status": 400,
      "source": "data.codes.0.max_uses_per_shopper",
      "title": "missing_dependency",
      "detail": "Has a dependency on max_uses"
    }
  ]
}

FirstTimeShopperCodeError

Error When Setting Usage Limits While Assigning First-Time Shopper Codes

{
  "errors": [
    {
      "status": 400,
      "source": "",
      "title": "Invalid Code",
      "detail": "Code - first_time_uses can't have limited uses or assigned to users since it's for first-time shoppers."
    }
  ]
}

422

Unprocessable Entity

application/json

Schema

Schema

errors object[]
Array [
statusinteger
Example: 422
sourcestring
Example:
titlestring
Example: Unsupported consume unit
detailstring
Example: Consume unit 'per_application' is not supported when using 'max_uses_per_shopper' features.
]

Example (auto)

{
  "errors": [
    {
      "status": 422,
      "source": "",
      "title": "Unsupported consume unit",
      "detail": "Consume unit 'per_application' is not supported when using 'max_uses_per_shopper' features."
    }
  ]
}

UnsupportedConsumeUnitError

Error When max_uses_per_shopper.max_uses is Used with per_application

{
  "errors": [
    {
      "status": 422,
      "source": "",
      "title": "Unsupported consume unit",
      "detail": "Consume unit 'per_application' is not supported when using 'max_uses_per_shopper' features."
    }
  ]
}

NoCodesAllowedForAutomaticPromotion

Error When Attempting to Create Promotion Codes for Automatic Promotions

{
  "errors": [
    {
      "status": 422,
      "title": "No codes allowed",
      "detail": "Cannot add codes to automatic promotion"
    }
  ]
}

DuplicatePromotionCodeError

Error When Creating a Promotion Code That Already Exists

{
  "errors": [
    {
      "status": 422,
      "title": "Duplicate code",
      "detail": "Promotion code already in use"
    }
  ]
}

Authorization: http

name: BearerAuthtype: httpscheme: bearer

• csharp
• curl
• dart
• go
• http
• java
• javascript
• kotlin
• c
• nodejs
• objective-c
• ocaml
• php
• powershell
• python
• r
• ruby
• rust
• shell
• swift

• HTTPCLIENT
• RESTSHARP

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://useast.api.elasticpath.com/v2/rule-promotions/:promotionID/codes");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "Bearer <token>");
var content = new StringContent("{\n  \"data\": {\n    \"type\": \"promotion_codes\",\n    \"codes\": [\n      {\n        \"code\": \"string\",\n        \"uses\": 0,\n        \"user\": \"string\",\n        \"consume_unit\": \"per_application\",\n        \"max_users_per_shopper\": {\n          \"max_uses\": 0,\n          \"includes_guests\": false\n        },\n        \"is_for_new_shopper\": true\n      }\n    ]\n  }\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Request Collapse all

Base URL

https://useast.api.elasticpath.com

Auth

Bearer Token

Parameters

promotionID — pathrequired

Authorization — headerrequired

Body required

• Example (from schema)
• CreateCodes
• SingleUsePerShopperIncludingGuests
• MaxUsesLimitWithPerShopperRestriction
• MaxUsesForSpecificShopper
• MaxUsesForSpecificRegisteredShopper
• FirstTimeShopperCodeRequest

{
  "data": {
    "type": "promotion_codes",
    "codes": [
      {
        "code": "string",
        "uses": 0,
        "user": "string",
        "consume_unit": "per_application",
        "max_users_per_shopper": {
          "max_uses": 0,
          "includes_guests": false
        },
        "is_for_new_shopper": true
      }
    ]
  }
}

ResponseClear

Click the Send API Request button above and see the response here!