Skip to main content
API docs by Redocly

Automatic Promotions (1.0)

Download OpenAPI specification:Download

Use this API to manage Automatic Promotions in NewStore, such as creating, retrieving, or updating promotions.

You can use these methods to create automatic promotions for specific products or for the whole cart, which are applied automatically during checkout in NewStore Associate App.

For a guide on how to use automatic promotions 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.

Get Promotion

Retrieves the specified automatic promotion by ID. To retrieve the promotion ID, use the list promotions API.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

The ID of the promotion.

Responses

Response samples

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

Update Promotion

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

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

The ID of the promotion.

Request Body schema: application/json

Update promotion request.

name
required
string

The name of the promotion.

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

The date the promotion 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 promotion 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 BundlePercentageCategory (object) or BundleFixedCategory (object) or FreeShipping (object)

The actual promotion kind.

active
boolean

Indicates whether the promotions is active or not.

required
Array of objects (Currency)

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

stores
Array of strings

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

localizedTimezone
boolean

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

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 promotion.

Responses

Request samples

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

Response samples

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

Create Promotion

Creates a specified automatic promotion.

Authorizations:
newStoreAccessToken
Request Body schema: application/json

Create promotion request.

name
required
string

The name of the promotion.

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

The date the promotion 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 promotion 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 BundlePercentageCategory (object) or BundleFixedCategory (object) or FreeShipping (object)

The actual promotion kind.

active
boolean

Indicates whether the promotions is active or not.

required
Array of objects (Currency)

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

stores
Array of strings

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

localizedTimezone
boolean

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

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 Promo",
  • "validFrom": "2023-11-01T00:00:00",
  • "validTo": "2023-12-01T00:00:00",
  • "category": {
    },
  • "active": true,
  • "currencies": [
    ],
  • "stores": [
    ],
  • "localizedTimezone": true,
  • "exclusive": true,
  • "segment": {
    }
}

Response samples

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

List Promotions

Retrieves all automatic promotions.

Authorizations:
newStoreAccessToken
query Parameters
count
required
integer <= 150

The number of promotions to get at once.

page
required
integer >= 1

The page number.

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": {
    }
}

Search Promotions

Searchs for the specified promotions.

Authorizations:
newStoreAccessToken
query Parameters
count
required
integer <= 150

The number of promotions to get at once.

page
required
integer >= 1

The page number.

Request Body schema: application/json

Search promotion request.

name
string

The name of the promotion.

Array of kind (string)

The promotion type.

validFrom
string^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$

The date the promotion becomes valid.

validTo
string^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$

The date the promotion becomes invalid.

active
boolean

Indicates whether the promotions is active or not.

segment
string

Indicates the Key or Value of customer profile extended attribute.

partial
boolean
Default: false

Partially returns the data of each promotion.

Responses

Request samples

Content type
application/json
{
  • "name": "promo",
  • "kind": [
    ],
  • "validFrom": "2023-11-01T00:00:00Z",
  • "validTo": "2023-12-01T00:00:00Z",
  • "active": true,
  • "segment": "member",
  • "partial": false
}

Response samples

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