Skip to main content
API docs by Redocly

Coupons (1.0)

Download OpenAPI specification:Download

Use this API to manage Coupons in NewStore, such as creating, retrieving, or updating coupons and coupon codes.

You can use these methods to create coupons and coupon codes for specific products or for the whole cart, which are applied manually in NewStore Associate App.

For a guide on how to use coupons via NewStore Omnichannel Manager, see this guide. Also you can find additinal information in process documentation

Create Coupon

Creates a specified coupon.

header Parameters
tenant
required
string
Example: test-tenant

The test tenant name.

user-id
required
string
Example: test-userid

The test user ID.

Request Body schema: application/json

Create coupon request.

name
required
string

The name of the coupon.

validFrom
required
string(?:^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$)|(?:...

The date the coupon becomes valid. If localizedTimezone is false, timezone can be indicated at the end of the string.

validTo
string(?:^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$)|(?:...

The date the coupon becomes invalid. If localizedTimezone is false, timezone can be indicated at the end of the string.

required
CartLevelPercentageCategory (object) or CartLevelFixedCategory (object) or ProductLevelPercentageCategory (object) or ProductLevelFixedCategory (object) or BogoPercentageCategory (object) or BogoFixedCategory (object) or FreeShipping (object)

The actual promotion kind.

active
boolean

Indicates whether the coupon is active or not.

required
Array of objects (Currency)

A list of conditions on currencies to satisfy in order for the coupon to be applied.

singleUse
boolean

Indicates whether the coupon codes are single use or not.

localizedTimezone
boolean

Optional, this property determines local timezone validity for the coupon. If true, UTC is assumed with no timezone required in "validFrom" and "validTo". If false, timezone must be specified in those fields.

stores
Array of strings

Indicates in which stores the coupon can be used. A list of IDs states that the coupon can be used in the given stores while an empty array states that the coupon can be used in any store.

consumers
Array of strings <= 10000 items

Indicates by which consumers the coupon can be used. A list of IDs states that the coupon can be used by the given consumers while an empty array states that the coupon can be used by any consumers.

externalId
string

Optional, The identifier of the corresponding coupon/voucher on the caller’s system.

exclusive
boolean

Indicates whether the promotion is exclusive or not.

object or null (Segment)

A customer segmentation.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Black Friday Coupon",
  • "validFrom": "2023-11-01T00:00:00",
  • "validTo": "2023-12-01T00:00:00",
  • "category": {
    },
  • "active": true,
  • "currencies": [
    ],
  • "stores": [
    ],
  • "localizedTimezone": true,
  • "singleUse": false,
  • "consumers": [
    ],
  • "exclusive": true,
  • "segment": {
    }
}

Response samples

Content type
application/json
Example
{
  • "links": {
    },
  • "coupon": {
    }
}

List Coupons

Retrieves all coupons.

query Parameters
count
required
integer <= 150

The number of coupons to get at once.

page
required
integer >= 1

The page number.

name
string

The names of the coupons you want to get (it can be a list of comma separated values)

code
string

The codes for which you want to get the coupons (it can be a list of comma separated values)

partial
boolean
Deprecated
Default: true

This flag should be always present with true value as codes property of the coupon object is deprecated. It prevents the load of coupon codes. DEPRECATION NOTE: From November 1st 2024, this parameter will be removed and used as default to true for all the queries. This means that whether the parameter is present or not, with either true or false value, it will be treated as if it is present with the value of true.

kind[]
string
Enum: "CartLevelFixed" "CartLevelPercentage" "ProductLevelFixed" "ProductLevelPercentage" "BogoFixed" "BogoPercentage" "FreeShippingFixed" "FreeShippingPercentage"
Example: kind[]=CartLevelFixed

The type of the coupon you want to get

active
boolean
Example: active=true

This flag should be set to true to return running, planned and past coupons. If set to false it will return only disabled coupons.

validFrom
string(?:^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$)|(?:...
Example: validFrom=2023-09-03T00:00:00

By setting this field, you will only get coupons which are valid from this date onward.

validTo
string(?:^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$)|(?:...
Example: validTo=2023-09-11T23:59:59

By setting this field, you will only get coupons which are valid up to this date.

segment
string
Example: segment=member

Indicates the Key or Value of customer profile extended attribute.

partial-category
boolean
Default: true
Example: partial-category=true

This flag should be always present with true value , it prevents loads of categories.

header Parameters
tenant
required
string
Example: test-tenant

The test tenant name.

user-id
required
string
Example: test-userid

The test user ID.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "links": {
    },
  • "pagination": {
    }
}

Get Coupon

Retrieves the specified coupon by ID. To retrieve the coupon ID, use the list coupon API.

path Parameters
id
required
string

The ID of the coupon.

query Parameters
partial
boolean
Deprecated
Default: true

This flag should be always present with true value as codes property of the coupon object is deprecated. It prevents the load of coupon codes. DEPRECATION NOTE: From November 1st 2024, this parameter will be removed and used as default to true for all the queries. This means that whether the parameter is present or not, with either true or false value, it will be treated as if it is present with the value of true.

header Parameters
tenant
required
string
Example: test-tenant

The test tenant name.

user-id
required
string
Example: test-userid

The test user ID.

Responses

Response samples

Content type
application/json
Example
{
  • "links": {
    },
  • "coupon": {
    }
}

Update Coupon

Updates the specified coupon with new information. The only property that cannot be updated is the category.

path Parameters
id
required
string

The ID of the coupon.

header Parameters
tenant
required
string
Example: test-tenant

The test tenant name.

user-id
required
string
Example: test-userid

The test user ID.

Request Body schema: application/json

Update coupon request.

name
required
string

The name of the coupon.

validFrom
required
string(?:^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$)|(?:...

The date the coupon becomes valid. If localizedTimezone is false, timezone can be indicated at the end of the string.

validTo
string(?:^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$)|(?:...

The date the coupon becomes invalid. If localizedTimezone is false, timezone can be indicated at the end of the string.

required
CartLevelPercentageCategory (object) or CartLevelFixedCategory (object) or ProductLevelPercentageCategory (object) or ProductLevelFixedCategory (object) or BogoPercentageCategory (object) or BogoFixedCategory (object) or FreeShipping (object)

The actual promotion kind.

active
boolean

Indicates whether the coupon is active or not.

required
Array of objects (Currency)

A list of conditions on currencies to satisfy in order for the coupon to be applied.

singleUse
boolean

Indicates whether the coupon codes are single use or not.

localizedTimezone
boolean

Optional, this property determines local timezone validity for the coupon. If true, UTC is assumed with no timezone required in "validFrom" and "validTo". If false, timezone must be specified in those fields.

stores
Array of strings

Indicates in which stores the coupon can be used. A list of IDs states that the coupon can be used in the given stores while an empty array states that the coupon can be used in any store.

consumers
Array of strings <= 10000 items

Indicates by which consumers the coupon can be used. A list of IDs states that the coupon can be used by the given consumers while an empty array states that the coupon can be used by any consumers.

externalId
string

Optional, The identifier of the corresponding coupon/voucher on the caller’s system.

exclusive
boolean

Indicates whether the promotion is exclusive or not.

object or null (Segment)

A customer segmentation.

version
required
string

A UUID representing the version of the coupon.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Black Friday Coupon",
  • "validFrom": "2023-11-01T00:00:00",
  • "validTo": "2023-12-01T00:00:00",
  • "category": {
    },
  • "active": true,
  • "currencies": [
    ],
  • "stores": [
    ],
  • "localizedTimezone": true,
  • "version": "a43a5a2d-1424-4c80-a252-992d489062eb",
  • "singleUse": false,
  • "consumers": [
    ],
  • "exclusive": true,
  • "segment": {
    }
}

Response samples

Content type
application/json
Example
{
  • "links": {
    },
  • "coupon": {
    }
}

Create coupon codes

Use this method to create coupon codes associated to a coupon definition. To retrieve the coupon ID, use the List coupons method. You don't need the Label property in the request payload while creating coupons.

path Parameters
id
required
string

The ID of the coupon.

header Parameters
tenant
required
string
Example: test-tenant

The test tenant name.

user-id
required
string
Example: test-userid

The test user ID.

Request Body schema: application/json

Create coupon code request.

codes
required
Array of strings

A list of new coupon codes.

Responses

Request samples

Content type
application/json
{
  • "codes": [
    ]
}

Response samples

Content type
application/json
{
  • "links": [
    ],
  • "codes": [
    ]
}

Get Coupon Codes

Use this method to retrieve coupon codes.

path Parameters
id
required
string

The ID of the coupon.

query Parameters
count
required
integer <= 150

The number of coupons to get at once.

page
required
integer >= 1

The page number.

header Parameters
tenant
required
string
Example: test-tenant

The test tenant name.

user-id
required
string
Example: test-userid

The test user ID.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "links": {
    },
  • "pagination": {
    }
}

Update Coupon Codes

Use this method to update the specified coupon code, you can switch a coupon code to an active state or not.

path Parameters
id
required
string

The ID of the coupon.

code_id
required
string

The ID of the coupon code.

header Parameters
tenant
required
string
Example: test-tenant

The test tenant name.

user-id
required
string
Example: test-userid

The test user ID.

Request Body schema: application/json
id
string
name
string[a-zA-Z0-9-%_@&!]
redemptions
number
active
boolean

Responses

Request samples

Content type
application/json
{
  • "id": "629868d2-58ac-4000-8000-3766e65e2e3d",
  • "name": "CODE1",
  • "redemptions": 0,
  • "active": true
}

Response samples

Content type
application/json
Example
{
  • "message": "not found",
  • "status": 404
}

Create Coupon Codes Import

Use this method to create coupon codes by importing a CSV file.

Important: if you want to import large quantities of codes, please do not provide one single big file, but split them into multiple files with 50-100k codes, in order not to overload the system.

path Parameters
id
required
string

The ID of the coupon.

header Parameters
tenant
required
string
Example: test-tenant

The test tenant name.

user-id
required
string
Example: test-userid

The test user ID.

Request Body schema: multipart/form-data

Create coupon codes import request by importing a CSV file containing coupon codes.

import
required
string <binary> [a-zA-Z0-9-%_@&!]

CSV file.

Responses

Response samples

Content type
application/json
{
  • "codesImport": {
    }
}

List Coupon Codes Import

Use this method to retrieve a list of coupon codes imports.

path Parameters
id
required
string

The ID of the coupon.

query Parameters
count
required
integer <= 150

The number of coupons to get at once.

page
required
integer >= 1

The page number.

header Parameters
tenant
required
string
Example: test-tenant

The test tenant name.

user-id
required
string
Example: test-userid

The test user ID.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "links": {
    },
  • "pagination": {
    }
}

Get Coupon Codes Import

Use this method to retrieve a specified coupon codes import.

path Parameters
id
required
string

The ID of the coupon.

import_id
required
string

The ID of the imported coupon code.

header Parameters
tenant
required
string
Example: test-tenant

The test tenant name.

user-id
required
string
Example: test-userid

The test user ID.

Responses

Response samples

Content type
application/json
{
  • "links": {
    },
  • "codesImport": {
    }
}

Create Coupon Code Redemption

Use this method to redeem a coupon code.

This method is not idempotent and should be called when the coupon was used. If the order for which this coupon was used failes, the coupon is unredeemed automatically at a later stage.

After a successful execution a 200 status is returned.

header Parameters
tenant
required
string
Example: test-tenant

The test tenant name.

user-id
required
string
Example: test-userid

The test user ID.

Request Body schema: application/json

A coupon code redemption request.

codes
required
Array of strings
consumerId
string
channelType
string
catalogTotal
number
currency
string
orderId
required
string

Responses

Request samples

Content type
application/json
{
  • "codes": [
    ],
  • "consumerId": "consumer-id-123",
  • "channelType": "store",
  • "catalogTotal": 100,
  • "currency": "USD",
  • "orderId": "2b89a5e0-1f1f-4374-b6d3-272341193cc7"
}

Response samples

Content type
application/json
Example
{
  • "message": "not found",
  • "status": 404
}

Coupon Code Unredemption

Use this method to unredeem a coupon code based on order id.

header Parameters
tenant
required
string
Example: test-tenant

The test tenant name.

user-id
required
string
Example: test-userid

The test user ID.

Request Body schema: application/json

A coupon code unredemption request. It is required to use either sales_order_uuid or orderId. If sales_order_uuid is provided, we use that for unredemption, otherwise we use orderId.

orderId
string
Deprecated
sales_order_uuid
string

Responses

Request samples

Content type
application/json
{
  • "orderId": "2b89a5e0-1f1f-4374-b6d3-272341193cc7",
  • "sales_order_uuid": "bf6a0288-d64e-4cb6-b534-a8a6c4724d06"
}

Response samples

Content type
application/json
Example
{
  • "message": "not found",
  • "status": 404
}