TAtalon
Coupons

Create coupons

Changed on

[!note] Management API endpoints are not meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Create coupons according to some pattern. Up to 20.000 coupons can be created without a unique prefix. When a unique prefix is provided, up to 200.000 coupons can be created.

post/v1/applications/{applicationId}/campaigns/{campaignId}/coupons

Request

Path parameters

applicationIdinteger required

The ID of the Application. It is displayed in your Talon.One deployment URL.

campaignIdinteger required

The ID of the campaign. It is displayed in your Talon.One deployment URL.

Query parameters

silentstring

Possible values: yes or no.

  • yes: Increases the performance of the API call by returning a 204 response.
  • no: Returns a 200 response that contains the updated customer profiles.

Request body

usageLimitinteger required

The number of times the coupon code can be redeemed. 0 means unlimited redemptions but any campaign usage limits will still apply.

discountLimitnumber

The total discount value that the code can give. Typically used to represent a gift card value.

reservationLimitinteger

The number of reservations that can be made with this coupon code.

startDatestring date-time

Timestamp at which point the coupon becomes valid.

expiryDatestring date-time

Expiration date of the coupon. Coupon never expires if this is omitted.

numberOfCouponsinteger required

The number of new coupon codes to generate for the campaign. Must be at least 1.

batchIdstring

The batch ID that all coupons created by the request will bear. If omitted, a batch ID is generated automatically.

uniquePrefixstring

DEPRECATED To create more than 20,000 coupons in one request, use Create coupons asynchronously endpoint.

attributesobject

Arbitrary properties associated with this item.

recipientIntegrationIdstring

The integration ID for this coupon's beneficiary's profile.

validCharactersstring[]

List of characters used to generate the random parts of a code. By default, the list of characters is equivalent to the [A-Z, 0-9] regular expression.

couponPatternstring

The pattern used to generate coupon codes. The character # is a placeholder and is replaced by a random character from the validCharacters set.

isReservationMandatoryboolean

An indication of whether the code can be redeemed only if it has been reserved first.

implicitlyReservedboolean

An indication of whether the coupon is implicitly reserved for all customers.

supportRequestIdinteger

The identifier of the support request to link to the coupon creation. The request must exist and not yet be processed.

supportRequestNotestring

A note recorded when the linked support request is approved or rejected. Applied when supportRequestId is provided.

Example request

{
  "usageLimit": 100,
  "discountLimit": 30,
  "reservationLimit": 45,
  "startDate": "2020-01-24T14:15:22Z",
  "expiryDate": "2023-08-24T14:15:22Z",
  "limits": [
    {
      "action": "createCoupon",
      "limit": 1000,
      "period": "yearly",
      "entities": [
        "Coupon"
      ]
    }
  ],
  "numberOfCoupons": 1,
  "batchId": "3rdparty_fjsieoaa",
  "attributes": {
    "venueId": 12
  },
  "recipientIntegrationId": "URNGV8294NV",
  "validCharacters": [
    "A",
    "B",
    "G",
    "Y"
  ],
  "couponPattern": "SUMMER-#####",
  "supportRequestId": 42,
  "supportRequestNote": "Approved as compensation for the delayed order."
}

Response

OK

totalResultSizeinteger required

Example response

{
  "totalResultSize": 1,
  "data": [
    {
      "id": 6,
      "created": "2020-06-10T09:05:27.993483Z",
      "campaignId": 211,
      "value": "XMAS-20-2021",
      "usageLimit": 100,
      "discountLimit": 30,
      "reservationLimit": 45,
      "startDate": "2020-01-24T14:15:22Z",
      "expiryDate": "2023-08-24T14:15:22Z",
      "limits": [
        {
          "action": "createCoupon",
          "limit": 1000,
          "period": "yearly",
          "entities": [
            "Coupon"
          ]
        }
      ],
      "usageCounter": 10,
      "discountCounter": 10,
      "discountRemainder": 5,
      "reservationCounter": 1,
      "referralId": 326632952,
      "recipientIntegrationId": "URNGV8294NV",
      "importId": 4,
      "batchId": "32535-43255"
    }
  ]
}

Changes

  • 7ef1b9504c3aRevision changes
    • warning

      the / request property's max was set to 20000.00

    • warning

      the / request property's min was set to 1.00

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property /