Skip to main content
API docs by Redocly

Marketing campaign (1.0)

Download OpenAPI specification:Download

Allows define specific cart behaviour in set time frame.

Available customization Filter products available in cart. Define custom prices (along with price service).

Campaign is triggered by URL query parameter "mktop" while creating the cart e.g. https://my-store-url/checkout/add?mktop=my_mkt_name_example&product=ef974b53-4aa1-4378-9798-97b9168bf884

Campaign

listCampaign

Get items

Authorizations:
JWT
query Parameters
size
integer <int64>
Default: 50

Amount of items returned per pagination page

page
integer <int64>
Default: 0

Pagination page starting from 0

sort
string
Example: sort=createDate,desc

Sort list results Format: entity_field_name,order. Format entity collection: entity_sub_object_name.sub_field_name,order.

customerId
string
Example: customerId=431b946a-92ea-430a-984d-c3cd65d2bb77

Filter results by customerId

name
string

Filter results by campaign name

status
string
Example: status=ENABLED

Filter result by status

startDate
integer <uint64>
Example: startDate=1593583200000<

Search campaign which starts at specific period. In example filter campaign which starts after/or at Wed Jul 01 2020 06:00:00

endDate
integer <uint64>
Example: endDate=<1596261600000

Search campaign which ends at specific period. In example filter campaign which ends before/or at Wed Aug 01 2020 06:00:00

products.id
string <uuid4>

Filter results by product or variant id

products.matchMode
string
Example: products.matchMode=variant

Filter results by product match mode (filter mode)

Responses

Response samples

Content type
application/json
{
  • "format": "short",
  • "items": [
    ],
  • "last": false,
  • "number": 41,
  • "size": 10,
  • "totalItems": 100523,
  • "totalPages": 10053
}

createCampaign

Create an item

Authorizations:
JWT
Request Body schema: application/json
customerId
string

Associates entity to certain customer.

description
string

Marketing description. Describe marketing campaign operation.

endDate
integer <uint64>

When the marketing campaign ends. Timestamp in milliseconds. Must be greater than startDate. When omitted campaign is infinite.

Array of objects (CampaignProduct)

DEPRECATED. Use LinkedProducts instead. Products mandatory in cart (if not, marketing campaign will be DISABLED)

name
required
string

Marketing campaign name. Must be unique along with customerId (composed unique key). Name is used in URL query parameter "mktop" to create campaign cart.

Array of objects (CampaignProduct)

Campaign products filter.

startDate
required
integer <uint64>

When the marketing campaign starts. Timestamp in milliseconds.

status
required
string (CampaignStatus)

Status of marketing campaign Has two values: ENABLED, DISABLED

Responses

Request samples

Content type
application/json
{
  • "customerId": "e0436791-5866-406d-b0c8-3ba32ead438a",
  • "description": "Christman 2002 special cart, 10% off on most of products",
  • "endDate": 1596261600000,
  • "mandatoryProducts": [
    ],
  • "name": "my_mkt_name_example",
  • "products": [
    ],
  • "startDate": 1593583200000,
  • "status": "string"
}

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "error: field can't be empty",
  • "path": "/service-name/resource/36a6d3ac-207f-4b64-be01-664c1edbd38b",
  • "status": 400,
  • "timestamp": 1593769514607
}

getCampaign

Get item

Authorizations:
JWT
path Parameters
id
required
string

Entity id generated and returned in "Location" header upon creation (POST).

Responses

Response samples

Content type
application/json
{
  • "createDate": 1593683684789,
  • "customerId": "e0436791-5866-406d-b0c8-3ba32ead438a",
  • "dbVersion": 0,
  • "description": "Christman 2002 special cart, 10% off on most of products",
  • "endDate": 1596261600000,
  • "id": "d87e0973-980a-4485-a39d-682184a8988a",
  • "mandatoryProducts": [
    ],
  • "name": "my_mkt_name_example",
  • "products": [
    ],
  • "startDate": 1593583200000,
  • "status": "string",
  • "updateDate": 1593685645385
}

updateCampaign

Update item

Authorizations:
JWT
path Parameters
id
required
string

Entity id generated and returned in "Location" header upon creation (POST).

Request Body schema: application/json
createDate
integer <int64>

Entity creation time. Value is auto generated upon creation and read only. Timestamp in milliseconds.

customerId
string

Associates entity to certain customer.

dbVersion
integer <int64>

Concurrent operations check mechanism.

Used in update actions. Value is auto generated upon creation/update and read only.

Prevent for any issue during concurrent update transaction done by parallel applications. Upon spotted dbVersion incorrectness a 412 retry error is returned. Let's consider a scenario where two application are trying update same entity:

App 1: GET entity request at 00:00:00.000 Received dbVersion=0 change entity data PUT entity request at 00:00:00.009 updated automatically dbVersion=1

App 2: GET entity request with at 00:00:00.005 Received dbVersion=0 because update of App 1 haven't occurred yet change entity data update entity at 00:00:00.014 412 Error, because dbVersion=1 after update of App 1

description
string

Marketing description. Describe marketing campaign operation.

endDate
integer <uint64>

When the marketing campaign ends. Timestamp in milliseconds. Must be greater than startDate. When omitted campaign is infinite.

id
string

Entity id. Value is auto generated upon creation and read only.

Array of objects (CampaignProduct)

DEPRECATED. Use LinkedProducts instead. Products mandatory in cart (if not, marketing campaign will be DISABLED)

name
required
string

Marketing campaign name. Must be unique along with customerId (composed unique key). Name is used in URL query parameter "mktop" to create campaign cart.

Array of objects (CampaignProduct)

Campaign products filter.

startDate
required
integer <uint64>

When the marketing campaign starts. Timestamp in milliseconds.

status
required
string (CampaignStatus)

Status of marketing campaign Has two values: ENABLED, DISABLED

updateDate
integer <int64>

Entity update time. Value is auto generated upon creation/update and read only. Timestamp in milliseconds.

Responses

Request samples

Content type
application/json
{
  • "createDate": 1593683684789,
  • "customerId": "e0436791-5866-406d-b0c8-3ba32ead438a",
  • "dbVersion": 0,
  • "description": "Christman 2002 special cart, 10% off on most of products",
  • "endDate": 1596261600000,
  • "id": "d87e0973-980a-4485-a39d-682184a8988a",
  • "mandatoryProducts": [
    ],
  • "name": "my_mkt_name_example",
  • "products": [
    ],
  • "startDate": 1593583200000,
  • "status": "string",
  • "updateDate": 1593685645385
}

Response samples

Content type
application/json
{
  • "createDate": 1593683684789,
  • "customerId": "e0436791-5866-406d-b0c8-3ba32ead438a",
  • "dbVersion": 0,
  • "description": "Christman 2002 special cart, 10% off on most of products",
  • "endDate": 1596261600000,
  • "id": "d87e0973-980a-4485-a39d-682184a8988a",
  • "mandatoryProducts": [
    ],
  • "name": "my_mkt_name_example",
  • "products": [
    ],
  • "startDate": 1593583200000,
  • "status": "string",
  • "updateDate": 1593685645385
}

deleteCampaign

Delete item

Authorizations:
JWT
path Parameters
id
required
string

Entity id generated and returned in "Location" header upon creation (POST).

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthorized",
  • "message": "Unauthorized",
  • "path": "/service-name/resource/36a6d3ac-207f-4b64-be01-664c1edbd38b",
  • "status": 401,
  • "timestamp": 1593769514607
}

LinkedProducts

listLinkedProducts

Get items

Authorizations:
JWT
query Parameters
size
integer <int64>
Default: 50

Amount of items returned per pagination page

page
integer <int64>
Default: 0

Pagination page starting from 0

sort
string
Example: sort=createDate,desc

Sort list results Format: entity_field_name,order. Format entity collection: entity_sub_object_name.sub_field_name,order.

customerId
string
Example: customerId=431b946a-92ea-430a-984d-c3cd65d2bb77

Filter results by customerId

marketingCampaignId
string <uuid4>

Filter results by marketing campaign id

baseProduct.id
string <uuid4>

Filter results by base product id

baseProduct.matchMode
string
Example: baseProduct.matchMode=variant

Filter results by base product match mode (filter mode)

linkedProduct.id
string <uuid4>

Filter results by linked product id

linkedProduct.quantitySelector
string
Example: linkedProduct.quantitySelector=alignedLessOrEqual

Filter results by linked product quantity selector

Responses

Response samples

Content type
application/json
{
  • "format": "short",
  • "items": [
    ],
  • "last": false,
  • "number": 41,
  • "size": 10,
  • "totalItems": 100523,
  • "totalPages": 10053
}

createLinkedProducts

Create an item

Authorizations:
JWT
Request Body schema: application/json
required
object (BaseProduct)

Defines a mandatory product in the cart

customerId
string

Associates entity to certain customer.

required
object (LinkedProduct)

Defines a dependant product (product removed if base product not present in the cart)

marketingCampaignId
required
string

Marketing Campaign id. Links to unique campaign

Responses

Request samples

Content type
application/json
{
  • "baseProduct": {
    },
  • "customerId": "e0436791-5866-406d-b0c8-3ba32ead438a",
  • "linkedProduct": {
    },
  • "marketingCampaignId": "bda56683-4641-4d8a-af46-28a73394a2ae"
}

Response samples

Content type
application/json
{
  • "error": "Bad Request",
  • "message": "error: field can't be empty",
  • "path": "/service-name/resource/36a6d3ac-207f-4b64-be01-664c1edbd38b",
  • "status": 400,
  • "timestamp": 1593769514607
}

getLinkedProducts

Get item

Authorizations:
JWT
path Parameters
id
required
string

Entity id generated and returned in "Location" header upon creation (POST).

Responses

Response samples

Content type
application/json
{
  • "baseProduct": {
    },
  • "createDate": 1593683684789,
  • "customerId": "e0436791-5866-406d-b0c8-3ba32ead438a",
  • "dbVersion": 0,
  • "id": "d87e0973-980a-4485-a39d-682184a8988a",
  • "linkedProduct": {
    },
  • "marketingCampaignId": "bda56683-4641-4d8a-af46-28a73394a2ae",
  • "updateDate": 1593685645385
}

updateLinkedProducts

Update item

Authorizations:
JWT
path Parameters
id
required
string

Entity id generated and returned in "Location" header upon creation (POST).

Request Body schema: application/json
required
object (BaseProduct)

Defines a mandatory product in the cart

createDate
integer <int64>

Entity creation time. Value is auto generated upon creation and read only. Timestamp in milliseconds.

customerId
string

Associates entity to certain customer.

dbVersion
integer <int64>

Concurrent operations check mechanism.

Used in update actions. Value is auto generated upon creation/update and read only.

Prevent for any issue during concurrent update transaction done by parallel applications. Upon spotted dbVersion incorrectness a 412 retry error is returned. Let's consider a scenario where two application are trying update same entity:

App 1: GET entity request at 00:00:00.000 Received dbVersion=0 change entity data PUT entity request at 00:00:00.009 updated automatically dbVersion=1

App 2: GET entity request with at 00:00:00.005 Received dbVersion=0 because update of App 1 haven't occurred yet change entity data update entity at 00:00:00.014 412 Error, because dbVersion=1 after update of App 1

id
string

Entity id. Value is auto generated upon creation and read only.

required
object (LinkedProduct)

Defines a dependant product (product removed if base product not present in the cart)

marketingCampaignId
required
string

Marketing Campaign id. Links to unique campaign

updateDate
integer <int64>

Entity update time. Value is auto generated upon creation/update and read only. Timestamp in milliseconds.

Responses

Request samples

Content type
application/json
{
  • "baseProduct": {
    },
  • "createDate": 1593683684789,
  • "customerId": "e0436791-5866-406d-b0c8-3ba32ead438a",
  • "dbVersion": 0,
  • "id": "d87e0973-980a-4485-a39d-682184a8988a",
  • "linkedProduct": {
    },
  • "marketingCampaignId": "bda56683-4641-4d8a-af46-28a73394a2ae",
  • "updateDate": 1593685645385
}

Response samples

Content type
application/json
{
  • "baseProduct": {
    },
  • "createDate": 1593683684789,
  • "customerId": "e0436791-5866-406d-b0c8-3ba32ead438a",
  • "dbVersion": 0,
  • "id": "d87e0973-980a-4485-a39d-682184a8988a",
  • "linkedProduct": {
    },
  • "marketingCampaignId": "bda56683-4641-4d8a-af46-28a73394a2ae",
  • "updateDate": 1593685645385
}

deleteLinkedProducts

Delete item

Authorizations:
JWT
path Parameters
id
required
string

Entity id generated and returned in "Location" header upon creation (POST).

Responses

Response samples

Content type
application/json
{
  • "error": "Unauthorized",
  • "message": "Unauthorized",
  • "path": "/service-name/resource/36a6d3ac-207f-4b64-be01-664c1edbd38b",
  • "status": 401,
  • "timestamp": 1593769514607
}