Skip to main content
API docs by Redocly

Automatic Promotions (v1.0)

Download OpenAPI specification:Download

License: Open API Specification - OAS Terms of Service

Use this API to manage automatic promotions in NewStore. For a guide on how to use automatic promotions via NewStore Omnichannel Manager, see this guide.

Manage promotions

Use this resource 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. This includes creating promotions for both, percentage or fixed amount discounts.

For more information on automatic promotions, see the process documentation or this guide.

Create promotion

Use this method to create an automatic promotion. You can create promotions for specific products or for the whole cart in the order.

You can create promotions that apply percentage discounts or fixed amount discounts on specified products or the cart. For more information, see the process documentation or this guide.

Authorizations:
newStoreAccessToken
header Parameters
x-request-id
string
tenant
required
string
user-id
required
string
Request Body schema: application/json

a new promotion

active
boolean

Indicates whether the promotion is active or not

name
required
string

The name of the promotion

description
string
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.

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.

Array of objects
required
object
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.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Cart level percentage promotion",
  • "description": "A promotion with type CartLevelPercentage",
  • "localizedTimezone": false,
  • "validFrom": "2022-01-01T00:00:00+01:00",
  • "validTo": "2022-04-01T00:00:00+01:00",
  • "category": {
    },
  • "currencies": [
    ]
}

Response samples

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

List promotions

Retrieves all automatic promotions created for your business via NewStore Omnichannel Manager or the create promotion method.

Authorizations:
newStoreAccessToken
query Parameters
count
required
integer

The number of promotions to get at once

page
required
integer

The page number

header Parameters
x-request-id
string
tenant
required
string
user-id
required
string

Responses

Response samples

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

Get promotion

Retrieves the specified automatic promotion by ID. To retrieve the promotion ID, use the List promotions method.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string
header Parameters
x-request-id
string
tenant
required
string
user-id
required
string

Responses

Response samples

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

Update promotion

Updates the specified promotion with new information. Use this method to switch a promotion to an active state or change the currencies that the promotion can be applied to, and so on. Given the nature of the update via the PUT method the complete object has to be passed. The only property that cannot be updated is the category.

To retrieve the promotion ID, use the List promotions method.

Authorizations:
newStoreAccessToken
path Parameters
id
required
string
header Parameters
x-request-id
string
tenant
required
string
user-id
required
string
Request Body schema: application/json

The updated promotion

tenant
string
version
required
string
active
boolean

Indicates whether the promotion is active or not

name
string

The name of the promotion

description
string
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.

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

Array of objects
object
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.

Responses

Request samples

Content type
application/json
{
  • "id": "62839b62-80ff-4000-8000-01b47275b241",
  • "name": "My Promotion",
  • "description": "My Promotion Description",
  • "localizedTimezone": false,
  • "validFrom": "2022-01-01T00:00:00+01:00",
  • "validTo": "2022-04-01T00:00:00+01:00",
  • "category": [
    ],
  • "active": true,
  • "currencies": [
    ],
  • "stores": [ ],
  • "version": "6f419b7b-1529-4c33-a5ba-a07762850db1"
}

Response samples

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

Apply promotions to a cart

Use this resource to apply existing promotions to a cart to view how pricing during checkout will be calculated based on these promotions.

Important: This resource does not impact the cart pricing or items in NewStore Associate App. Use this method only to validate if promotions are being calculated correctly for products added to a cart.

Apply promotions to a cart

Use this method to apply existing promotions to a cart to view how pricing during checkout will be calculated based on these promotions.

This method returns a version of the cart (DiscountedCart) with all specified promotions applied to it. This method is idempotent, and does not change the state of the cart or products added to the cart.

The order of the discounts in the array of discounts attached to each item in a DiscountedCart is important and should not be changed when being used in other services or contexts.

Authorizations:
newStoreAccessToken
Request Body schema: application/json

The cart without promotions applied

customerId
string

The customer id

channelType
string

Typically web or store

currency
string

The currency of the cart

couponCodes
Array of strings

The coupon codes to be applied

storeId
string

The store ID

shopId
string

The shop ID

locale
string

The locale

Array of objects

The individual items that the cart contains

Responses

Request samples

Content type
application/json
{
  • "customerId": "",
  • "channelType": "store",
  • "currency": "USD",
  • "couponCodes": [
    ],
  • "storeId": "7c9f2605-9fb3-5444-8fee-47fe51608efe",
  • "shopId": "storefront-catalog-en",
  • "locale": "en-us",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "customerId": "",
  • "channelType": "store",
  • "currency": "USD",
  • "storeId": "7c9f2605-9fb3-5444-8fee-47fe51608efe",
  • "shopId": "storefront-catalog-en",
  • "locale": "en-us",
  • "couponCodes": [
    ],
  • "items": [
    ]
}

Create a coupon code redemption

Use this method to redeem a coupon code. It redeem the coupon for legacy or for the stackable coupons according to the internal configuration for the given tenant.

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.

Authorizations:
newStoreAccessToken
Request Body schema: application/json

The redemption request

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": 0,
  • "causes": [
    ],
  • "id": "string",
  • "type": "string",
  • "code": "string"
}