Create a sale - Shoply Documentation

Node.js

import Shoply from "@shoplygg/node";

const shoply = new Shoply({ apiKey: process.env.SHOPLY_API_KEY });

const result = await shoply.sales.create({
  name: "Autumn sale",
  value: 20,
  startsAt: "2026-11-27T00:00:00Z",
  endsAt: "2026-11-30T23:59:00Z",
});

<?php

require 'vendor/autoload.php';

$shoply = new Shoply\Client(['apiKey' => getenv('SHOPLY_API_KEY')]);

$result = $shoply->sales->create([
    'name' => 'Autumn sale',
    'value' => 20,
    'startsAt' => '2026-11-27T00:00:00Z',
    'endsAt' => '2026-11-30T23:59:00Z',
]);

import shoply

client = shoply.Client()  # reads SHOPLY_API_KEY

result = client.sales.create(
    name="Autumn sale",
    value=20,
    startsAt="2026-11-27T00:00:00Z",
    endsAt="2026-11-30T23:59:00Z",
)

curl --request POST \
  --url https://api.shoply.gg/v1/stores/{storeId}/sales \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Autumn sale",
  "value": 20,
  "startsAt": "2026-11-27T00:00:00Z",
  "endsAt": "2026-11-30T23:59:00Z",
  "discountType": "percent",
  "appliesTo": "all",
  "targets": [
    {
      "productId": "<string>",
      "variantId": "<string>"
    }
  ],
  "couponRule": "rest",
  "exceptions": [
    {
      "id": "<string>"
    }
  ],
  "enabled": true,
  "showBar": true
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.shoply.gg/v1/stores/{storeId}/sales"

	payload := strings.NewReader("{\n  \"name\": \"Autumn sale\",\n  \"value\": 20,\n  \"startsAt\": \"2026-11-27T00:00:00Z\",\n  \"endsAt\": \"2026-11-30T23:59:00Z\",\n  \"discountType\": \"percent\",\n  \"appliesTo\": \"all\",\n  \"targets\": [\n    {\n      \"productId\": \"<string>\",\n      \"variantId\": \"<string>\"\n    }\n  ],\n  \"couponRule\": \"rest\",\n  \"exceptions\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ],\n  \"enabled\": true,\n  \"showBar\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.shoply.gg/v1/stores/{storeId}/sales")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Autumn sale\",\n  \"value\": 20,\n  \"startsAt\": \"2026-11-27T00:00:00Z\",\n  \"endsAt\": \"2026-11-30T23:59:00Z\",\n  \"discountType\": \"percent\",\n  \"appliesTo\": \"all\",\n  \"targets\": [\n    {\n      \"productId\": \"<string>\",\n      \"variantId\": \"<string>\"\n    }\n  ],\n  \"couponRule\": \"rest\",\n  \"exceptions\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ],\n  \"enabled\": true,\n  \"showBar\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.shoply.gg/v1/stores/{storeId}/sales")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Autumn sale\",\n  \"value\": 20,\n  \"startsAt\": \"2026-11-27T00:00:00Z\",\n  \"endsAt\": \"2026-11-30T23:59:00Z\",\n  \"discountType\": \"percent\",\n  \"appliesTo\": \"all\",\n  \"targets\": [\n    {\n      \"productId\": \"<string>\",\n      \"variantId\": \"<string>\"\n    }\n  ],\n  \"couponRule\": \"rest\",\n  \"exceptions\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ],\n  \"enabled\": true,\n  \"showBar\": true\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": null,
  "code": null,
  "data": {
    "id": "b9f77894-db3d-4db7-8fdf-22d434957cf3",
    "name": "Autumn sale",
    "enabled": true,
    "status": "scheduled",
    "discountType": "percent",
    "value": 20,
    "appliesTo": "all",
    "targets": [],
    "startsAt": "2026-10-23T16:20:18Z",
    "endsAt": "2026-10-29T16:20:18Z",
    "couponRule": "rest",
    "exceptions": [],
    "showBar": true,
    "orders": 0,
    "revenue": 0,
    "dateCreated": "2026-10-22T16:20:18Z",
    "updatedAt": "2026-10-22T16:20:18.820Z"
  }
}

{
  "success": false,
  "message": "<string>",
  "code": "<string>",
  "data": null,
  "errors": {}
}

{
  "success": false,
  "message": "<string>",
  "code": "<string>",
  "data": null,
  "errors": {}
}

{
  "success": false,
  "message": "<string>",
  "code": "<string>",
  "data": null,
  "errors": {}
}

{
  "success": false,
  "message": "<string>",
  "code": "<string>",
  "data": null,
  "errors": {}
}

{
  "success": false,
  "message": "<string>",
  "code": "<string>",
  "data": null,
  "errors": {}
}

POST

stores

{storeId}

sales

Node.js

import Shoply from "@shoplygg/node";

const shoply = new Shoply({ apiKey: process.env.SHOPLY_API_KEY });

const result = await shoply.sales.create({
  name: "Autumn sale",
  value: 20,
  startsAt: "2026-11-27T00:00:00Z",
  endsAt: "2026-11-30T23:59:00Z",
});

<?php

require 'vendor/autoload.php';

$shoply = new Shoply\Client(['apiKey' => getenv('SHOPLY_API_KEY')]);

$result = $shoply->sales->create([
    'name' => 'Autumn sale',
    'value' => 20,
    'startsAt' => '2026-11-27T00:00:00Z',
    'endsAt' => '2026-11-30T23:59:00Z',
]);

import shoply

client = shoply.Client()  # reads SHOPLY_API_KEY

result = client.sales.create(
    name="Autumn sale",
    value=20,
    startsAt="2026-11-27T00:00:00Z",
    endsAt="2026-11-30T23:59:00Z",
)

curl --request POST \
  --url https://api.shoply.gg/v1/stores/{storeId}/sales \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Autumn sale",
  "value": 20,
  "startsAt": "2026-11-27T00:00:00Z",
  "endsAt": "2026-11-30T23:59:00Z",
  "discountType": "percent",
  "appliesTo": "all",
  "targets": [
    {
      "productId": "<string>",
      "variantId": "<string>"
    }
  ],
  "couponRule": "rest",
  "exceptions": [
    {
      "id": "<string>"
    }
  ],
  "enabled": true,
  "showBar": true
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.shoply.gg/v1/stores/{storeId}/sales"

	payload := strings.NewReader("{\n  \"name\": \"Autumn sale\",\n  \"value\": 20,\n  \"startsAt\": \"2026-11-27T00:00:00Z\",\n  \"endsAt\": \"2026-11-30T23:59:00Z\",\n  \"discountType\": \"percent\",\n  \"appliesTo\": \"all\",\n  \"targets\": [\n    {\n      \"productId\": \"<string>\",\n      \"variantId\": \"<string>\"\n    }\n  ],\n  \"couponRule\": \"rest\",\n  \"exceptions\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ],\n  \"enabled\": true,\n  \"showBar\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.shoply.gg/v1/stores/{storeId}/sales")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Autumn sale\",\n  \"value\": 20,\n  \"startsAt\": \"2026-11-27T00:00:00Z\",\n  \"endsAt\": \"2026-11-30T23:59:00Z\",\n  \"discountType\": \"percent\",\n  \"appliesTo\": \"all\",\n  \"targets\": [\n    {\n      \"productId\": \"<string>\",\n      \"variantId\": \"<string>\"\n    }\n  ],\n  \"couponRule\": \"rest\",\n  \"exceptions\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ],\n  \"enabled\": true,\n  \"showBar\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.shoply.gg/v1/stores/{storeId}/sales")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Autumn sale\",\n  \"value\": 20,\n  \"startsAt\": \"2026-11-27T00:00:00Z\",\n  \"endsAt\": \"2026-11-30T23:59:00Z\",\n  \"discountType\": \"percent\",\n  \"appliesTo\": \"all\",\n  \"targets\": [\n    {\n      \"productId\": \"<string>\",\n      \"variantId\": \"<string>\"\n    }\n  ],\n  \"couponRule\": \"rest\",\n  \"exceptions\": [\n    {\n      \"id\": \"<string>\"\n    }\n  ],\n  \"enabled\": true,\n  \"showBar\": true\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": null,
  "code": null,
  "data": {
    "id": "b9f77894-db3d-4db7-8fdf-22d434957cf3",
    "name": "Autumn sale",
    "enabled": true,
    "status": "scheduled",
    "discountType": "percent",
    "value": 20,
    "appliesTo": "all",
    "targets": [],
    "startsAt": "2026-10-23T16:20:18Z",
    "endsAt": "2026-10-29T16:20:18Z",
    "couponRule": "rest",
    "exceptions": [],
    "showBar": true,
    "orders": 0,
    "revenue": 0,
    "dateCreated": "2026-10-22T16:20:18Z",
    "updatedAt": "2026-10-22T16:20:18.820Z"
  }
}

{
  "success": false,
  "message": "<string>",
  "code": "<string>",
  "data": null,
  "errors": {}
}

{
  "success": false,
  "message": "<string>",
  "code": "<string>",
  "data": null,
  "errors": {}
}

{
  "success": false,
  "message": "<string>",
  "code": "<string>",
  "data": null,
  "errors": {}
}

{
  "success": false,
  "message": "<string>",
  "code": "<string>",
  "data": null,
  "errors": {}
}

{
  "success": false,
  "message": "<string>",
  "code": "<string>",
  "data": null,
  "errors": {}
}

Authorizations

Authorization

string

header

required

A secret API key, made under Developers in the dashboard: Authorization: Bearer shoply_sk_...

Headers

Idempotency-Key

string

A word of your own for this one change, up to 180 letters, digits, dots, dashes, underscores and colons. Sent again with the same key, the request is not carried out twice: the first answer comes back, with Idempotent-Replay: true.

Path Parameters

storeId

string

required

The store's ID. A key reaches the store it was made in: GET /key answers which.

Query Parameters

string

The time zone startsAt and endsAt are read in when they name none, as an IANA name. Left out, UTC.

Example:

"Europe/Berlin"

Body

application/json

name

string

required

What the sale is called, up to 60 characters. Buyers see it on the storefront's countdown.

Example:

"Autumn sale"

value

number

required

How much comes off: above 0 and up to 100 for percent, an amount with at most 2 decimals for fixed.

Example:

20

startsAt

string

required

When it starts, as a date and time.

Example:

"2026-11-27T00:00:00Z"

endsAt

string

required

When it ends, as a date and time. After startsAt, and not already past.

Example:

"2026-11-30T23:59:00Z"

discountType

enum<string>

default:percent

A share of each price, or an amount in the store's currency.

Available options:

percent,

fixed

appliesTo

enum<string>

default:all

Every product, or only the ones in targets.

Available options:

all,

some

targets

object[]

The products on sale when appliesTo is some. Each names a product, and optionally one variant of it.

Show child attributes

couponRule

enum<string>

default:rest

What coupons do while the sale runs. rest: a coupon counts only the items in the cart that are not on sale. all: coupons work on sale items too. none: no coupon works anywhere in the store.

Available options:

rest,

all,

none

exceptions

object[]

Up to 100 coupons or coupon categories that couponRule is turned around for.

Show child attributes

enabled

boolean

default:true

Whether the sale runs when its time comes.

showBar

boolean

default:true

Whether the storefront shows the sale's countdown bar.

Response

It worked.

success

boolean

message

unknown

code

unknown

data

object

Show child attributes