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

DISCLAIMER: Coupon fields should not contain any PII, this information may be removed.

Create Coupon

Creates a specified coupon.

Authorizations:
newStoreAccessToken
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.

Authorizations:
newStoreAccessToken
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.

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.

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

The type of the coupon you want to get

segment
string
Example: segment=member

Indicates the Key or Value of the 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.

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.

Authorizations:
newStoreAccessToken
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.

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.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

The ID of the coupon.

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.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

The ID of the coupon.

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.

Authorizations:
newStoreAccessToken
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.

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.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

The ID of the coupon.

code_id
required
string

The ID of the coupon code.

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.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

The ID of the coupon.

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.

Authorizations:
newStoreAccessToken
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.

Responses

Response samples

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

Get Coupon Codes Import

Use this method to retrieve a specified coupon codes import.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

The ID of the coupon.

import_id
required
string

The ID of the imported coupon code.

Responses

Response samples

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