Skip to main content
API docs by Redocly

Manage Stackable Coupons (v1.0)

Download OpenAPI specification:Download

License: Open API Specification - OAS Terms of Service

Use this API to manage stackable coupons for your business.

Important: This resource is different than the legacy coupons resource, which is used to create legacy coupons and coupon definitions in the platform.

Create coupon

Use this method to create a coupon definition for your business.

You can create a coupon of any of the promotion types, and they are applied via coupon codes associated to the coupon definition.

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

a new coupon definition

active
boolean

Indicates whether the coupon is active or not

name
required
string

The name of the coupon

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
singleUse
boolean

Indicates whether the coupon codes are single use or not.

required
object
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

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.

Responses

Request samples

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

Response samples

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

List coupons

Retrieves all coupons created for your business via NewStore Omnichannel Manager or the Create coupon method.

Authorizations:
newStoreAccessToken
query Parameters
count
required
integer

The number of promotions to get at once

page
required
integer

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)

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

Responses

Response samples

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

Get coupons

Retrieves the specified coupon definition by ID. To retrieve the coupon ID, use the List coupons 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
{
  • "coupon": {
    },
  • "links": {
    }
}

Update coupon

Updates the specified coupon definition with new information. Use this method to switch a coupon to an active state or change the currencies that the coupon can be applied to, and so on.

Given the nature of the update, the complete object needs to be passed in the request. The only property that cannot be updated is the category.

To retrieve the coupon ID, use the List coupons 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 coupon

tenant
string
version
required
string
active
boolean

Indicates whether the coupon is active or not

name
string

The name of the coupon

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
singleUse
boolean

Indicates whether the coupon codes associated to this coupon definition are single use or not.

object
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

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.

Responses

Request samples

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

Response samples

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

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
header Parameters
x-request-id
string
tenant
required
string
user-id
required
string
Request Body schema: application/json

a list of new coupon codes

codes
required
Array of strings

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
header Parameters
x-request-id
string
tenant
required
string
user-id
required
string

Responses

Response samples

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

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
coupon_id
required
string
code_id
required
string
header Parameters
x-request-id
string
tenant
required
string
user-id
required
string
Request Body schema: application/json

The updated coupon codes

Responses

Request samples

Content type
application/json
{
  • "id": "6398b3a3-9ff8-4000-8000-c557ac5c2432",
  • "name": "TESTCODE1",
  • "redemptions": 0,
  • "active": false
}

Response samples

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

Create Coupon Codes Import

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

Authorizations:
newStoreAccessToken
path Parameters
id
required
string

The ID of the coupon.

header Parameters
tenant
required
string
user-id
required
string
Request Body schema: multipart/form-data

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

import
required
string <application/octet-stream> [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
query Parameters
count
required
integer

The number of coupon codes imports to get at once

page
required
integer

The page number

header Parameters
tenant
required
string
user-id
required
string

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.

header Parameters
tenant
required
string
user-id
required
string

Responses

Response samples

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

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