Sale

Sales are a type of discount that are automatically applied at checkout. They can be in the form of a percent or an absolute amount.

Sales can be created to apply to specific tags or products.

See the sale fields for more details and options.

Endpoints

POST
/stores/{store.id}/sales
GET
/stores/{store.id}/sales
GET
/stores/{store.id}/sales/{sale.id}
PATCH
/stores/{store.id}/sales/{sale.id}
DELETE
/stores/{store.id}/sales/{sale.id}

The Sale object

Fields
Name
id
Type
flake
Tags
Description
id of the sale
Name
store_id
Type
flake
Tags
Description
id of the store the sale belongs to
Name
enabled
Type
boolean
Tags
Description
whether the sale is enabled and currently usable by customers (assuming it's within the begins_at and ends_at range)
Name
name
Type
string
Tags
Description
the name of this sale. Visible to customers.
Name
apply_to_tags
Type
[]partial tag
Tags
Description
an array containing a list of tags that this sale can apply to.
Name
apply_to_products
Type
[]partial product
Tags
Description
an array containing a list of products that this sale can apply to.
Name
discount_type
Type
enum
Tags
Description
the type of discount this sale applies.
Allowed enum values
percent
discount_amount applies as a percent
amount
discount_amount applies as an absolute amount
Name
discount_amount
Type
integer
Tags
Description
the discount amount this sale applies.
If discount_type is percent, then this is interpreted as multiples of 10 basis points (where 1000 is 100.0%)
If discount_type is amount, then this is interpreted as an absolute amount (where 1000 is $10.00)
Name
minimum_order_value
Type
integer
Tags
Description
the minimum value of the order required before this sale may be applied
Name
begins_at
Type
timestamp
Tags
Description
timestamp of when the sale will become active
Name
ends_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when the sale will end
Name
created_by
Type
user
Tags
Description
the user that created this sale.
Name
created_at
Type
timestamp
Tags
Description
timestamp of when the sale was created
Name
updated_by
Type
user
Tags
NULLABLE
Description
the user that most recently updated this sale.
Name
updated_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when the sale was last updated

Partial Tag Structure

Contains a partial set fields that refer to a tag

Fields
Name
id
Type
flake
Tags
Description
id of the tag
Name
slug
Type
string
Tags
Description
the url-safe identifier for the tag, unique to the store
Name
name
Type
string
Tags
Description
the name the tag

Partial Product Structure

Contains a partial set fields that refer to a product

Fields
Name
id
Type
flake
Tags
Description
id of the product
Name
store_id
Type
flake
Tags
Description
id of the store that this product belongs to
Name
version_id
Type
flake
Tags
Description
version id of the product
Name
slug
Type
string
Tags
Description
the url-safe identifier for the product, unique to the store
Name
name
Type
string
Tags
Description
the name the product
Name
description
Type
string
Tags
Description
the full-length description of the product
Name
price
Type
integer
Tags
Description
the price of the product
Name
created_at
Type
timestamp
Tags
Description
timestamp of when the product was created
Name
updated_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when the product was last updated

The Sale object

{
  "id": "149580776499843072",
  "store_id": "94688451781206016",
  "enabled": true,
  "name": "Big 50% off Sale!",
  "apply_to_tags": [
    {
      "id": "124248382326706176",
      "store_id": "94688451781206016",
      "slug": "food",
      "name": "Food",
      "description": "delicious foods.",
      "created_at": "2023-04-11T19:01:04.772468Z",
      "updated_at": null
    }
  ],
  "apply_to_products": [
    {
      "id": "124249183568797696",
      "store_id": "94688451781206016",
      "version_id": "149702205245493248",
      "image_url": "https://example.paynow.gg/",
      "slug": "banana",
      "name": "Banana",
      "description": "It literally goes bad after like, an hour...",
      "price": 117,
      "created_at": "2023-04-11T19:04:15.801636Z",
      "updated_at": "2023-04-12T00:45:29.064138Z"
    }
  ],
  "discount_type": "percent",
  "discount_amount": 500,
  "minimum_order_value": 0,
  "begins_at": "2023-04-11T16:42:58.163471Z",
  "ends_at": "2023-05-11T16:43:28.253320Z",
  "created_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "created_at": "2023-04-11T16:42:58.197319Z",
  "updated_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "updated_at": "2023-04-11T17:17:01.633842Z"
}

Create Sale

Creates a new sale.

Parameters
Name
enabled
Type
boolean?
Tags
OPTIONAL
Description
whether the sale is enabled and currently usable by customers (assuming it's within the begins_at and ends_at range)
Name
name
Type
string
Tags
REQUIRED
Description
the name of this sale (1 - 50 characters)
Name
apply_to_tags
Type
[]flake?
Tags
OPTIONAL
Description
an array of IDs specifying which tags this sale can apply to
Name
apply_to_products
Type
[]flake?
Tags
OPTIONAL
Description
an array of IDs specifying which products this sale can apply to
Name
discount_type
Type
enum
Tags
REQUIRED
Description
the type of discount this sale applies.
Allowed enum values
percent
discount_amount applies as a percent
amount
discount_amount applies as an absolute amount
Name
discount_amount
Type
integer
Tags
REQUIRED
Description
the discount amount this sale applies.
If discount_type is percent, then this is interpreted as multiples of 10 basis points (where 1000 is 100.0%)
If discount_type is amount, then this is interpreted as an absolute amount (where 1000 is $10.00)
Name
minimum_order_value
Type
integer?
Tags
OPTIONAL
Description
the minimum value of the order required before this sale may be applied
Name
begins_at
Type
timestamp?
Tags
OPTIONAL
Description
timestamp of when the sale will become active
Name
ends_at
Type
timestamp?
Tags
OPTIONAL
Description
timestamp of when the sale will end

Returns

Returns the newly created sale.

Request

sale_create

POST
/stores/{store.id}/sales

Response

{
  "id": "149580776499843072",
  "store_id": "94688451781206016",
  "enabled": true,
  "name": "Big 50% off Sale!",
  "apply_to_tags": [
    {
      "id": "124248382326706176",
      "store_id": "94688451781206016",
      "slug": "food",
      "name": "Food",
      "description": "delicious foods.",
      "created_at": "2023-04-11T19:01:04.772468Z",
      "updated_at": null
    }
  ],
  "apply_to_products": [
    {
      "id": "124249183568797696",
      "store_id": "94688451781206016",
      "version_id": "149702205245493248",
      "image_url": "https://example.paynow.gg/",
      "slug": "banana",
      "name": "Banana",
      "description": "It literally goes bad after like, an hour...",
      "price": 117,
      "created_at": "2023-04-11T19:04:15.801636Z",
      "updated_at": "2023-04-12T00:45:29.064138Z"
    }
  ],
  "discount_type": "percent",
  "discount_amount": 500,
  "minimum_order_value": 0,
  "begins_at": "2023-04-11T16:42:58.163471Z",
  "ends_at": "2023-05-11T16:43:28.253320Z",
  "created_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "created_at": "2023-04-11T16:42:58.197319Z",
  "updated_by": null,
  "updated_at": null
}

Get Sales

Returns all sales in the store.

Returns

Returns an array of sales.

Request

sale_read

GET
/stores/{store.id}/sales

Response

[
  {
    "id": "149580776499843072",
    "store_id": "94688451781206016",
    "enabled": true,
    "name": "Big 50% off Sale!",
    "apply_to_tags": [
      {
        "id": "124248382326706176",
        "store_id": "94688451781206016",
        "slug": "food",
        "name": "Food",
        "description": "delicious foods.",
        "created_at": "2023-04-11T19:01:04.772468Z",
        "updated_at": null
      }
    ],
    "apply_to_products": [
      {
        "id": "124249183568797696",
        "store_id": "94688451781206016",
        "version_id": "149702205245493248",
        "image_url": "https://example.paynow.gg/",
        "slug": "banana",
        "name": "Banana",
        "description": "It literally goes bad after like, an hour...",
        "price": 117,
        "created_at": "2023-04-11T19:04:15.801636Z",
        "updated_at": "2023-04-12T00:45:29.064138Z"
      }
    ],
    "discount_type": "percent",
    "discount_amount": 500,
    "minimum_order_value": 0,
    "begins_at": "2023-04-11T16:42:58.163471Z",
    "ends_at": "2023-05-11T16:43:28.253320Z",
    "created_by": {
      "id": "11084680073842688",
      "first_name": "Example",
      "last_name": "Exampleson"
    },
    "created_at": "2023-04-11T16:42:58.197319Z",
    "updated_by": {
      "id": "11084680073842688",
      "first_name": "Example",
      "last_name": "Exampleson"
    },
    "updated_at": "2023-04-11T17:17:01.633842Z"
  },
  {...},
  {...}
]

Get Sale

Returns a sale by ID.

Returns

Returns a sale if a valid identifier was provided.

Request

sale_read

GET
/stores/{store.id}/sales/{sale.id}

Response

{
  "id": "149580776499843072",
  "store_id": "94688451781206016",
  "enabled": true,
  "name": "Big 50% off Sale!",
  "apply_to_tags": [
    {
      "id": "124248382326706176",
      "store_id": "94688451781206016",
      "slug": "food",
      "name": "Food",
      "description": "delicious foods.",
      "created_at": "2023-04-11T19:01:04.772468Z",
      "updated_at": null
    }
  ],
  "apply_to_products": [
    {
      "id": "124249183568797696",
      "store_id": "94688451781206016",
      "version_id": "149702205245493248",
      "image_url": "https://example.paynow.gg/",
      "slug": "banana",
      "name": "Banana",
      "description": "It literally goes bad after like, an hour...",
      "price": 117,
      "created_at": "2023-04-11T19:04:15.801636Z",
      "updated_at": "2023-04-12T00:45:29.064138Z"
    }
  ],
  "discount_type": "percent",
  "discount_amount": 500,
  "minimum_order_value": 0,
  "begins_at": "2023-04-11T16:42:58.163471Z",
  "ends_at": "2023-05-11T16:43:28.253320Z",
  "created_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "created_at": "2023-04-11T16:42:58.197319Z",
  "updated_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "updated_at": "2023-04-11T17:17:01.633842Z"
}

Update Sale

Updates a sale.

Parameters
Name
enabled
Type
boolean?
Tags
OPTIONAL
Description
whether the sale is enabled and currently usable by customers (assuming it's within the begins_at and ends_at range)
Name
name
Type
string?
Tags
OPTIONAL
Description
the name of this sale (1 - 50 characters)
Name
apply_to_tags
Type
[]flake?
Tags
OPTIONAL
Description
an array of IDs specifying which tags this sale can apply to
Name
apply_to_products
Type
[]flake?
Tags
OPTIONAL
Description
an array of IDs specifying which products this sale can apply to
Name
discount_type
Type
enum?
Tags
OPTIONAL
Description
the type of discount this sale applies. If provided for update, you must also provide discount_amount.
Allowed enum values
percent
discount_amount applies as a percent
amount
discount_amount applies as an absolute amount
Name
discount_amount
Type
integer?
Tags
OPTIONAL
Description
the discount amount this sale applies. If provided for update, you must also provide discount_type.
If discount_type is percent, then this is interpreted as multiples of 10 basis points (where 1000 is 100.0%)
If discount_type is amount, then this is interpreted as an absolute amount (where 1000 is $10.00)
Name
minimum_order_value
Type
integer?
Tags
OPTIONAL
Description
the minimum value of the order required before this sale may be applied
Name
begins_at
Type
timestamp?
Tags
OPTIONAL
Description
timestamp of when the sale will become active
Name
ends_at
Type
timestamp?
Tags
OPTIONAL
Description
timestamp of when the sale will end

Returns

Returns the updated sale.

Request

sale_update

PATCH
/stores/{store.id}/sales/{sale.id}

Response

{
  "id": "149580776499843072",
  "store_id": "94688451781206016",
  "enabled": true,
  "name": "Big 50% off Sale!",
  "apply_to_tags": [
    {
      "id": "124248382326706176",
      "store_id": "94688451781206016",
      "slug": "food",
      "name": "Food",
      "description": "delicious foods.",
      "created_at": "2023-04-11T19:01:04.772468Z",
      "updated_at": null
    }
  ],
  "apply_to_products": [
    {
      "id": "124249183568797696",
      "store_id": "94688451781206016",
      "version_id": "149702205245493248",
      "image_url": "https://example.paynow.gg/",
      "slug": "banana",
      "name": "Banana",
      "description": "It literally goes bad after like, an hour...",
      "price": 117,
      "created_at": "2023-04-11T19:04:15.801636Z",
      "updated_at": "2023-04-12T00:45:29.064138Z"
    }
  ],
  "discount_type": "percent",
  "discount_amount": 500,
  "minimum_order_value": 0,
  "begins_at": "2023-04-11T16:42:58.163471Z",
  "ends_at": "2023-05-11T16:43:28.253320Z",
  "created_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "created_at": "2023-04-11T16:42:58.197319Z",
  "updated_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "updated_at": "2023-04-11T17:17:01.633842Z"
}

Delete Sale

Deletes a sale by ID.

Returns

Returns HTTP 204 if the specified sale was deleted.

Request

sale_delete

DELETE
/stores/{store.id}/sales/{sale.id}

Response

HTTP 204

Sale

Endpoints

Fields

Fields

Fields

The Sale object

Parameters

Returns

Request

Response

Returns

Request

Response

Returns

Request

Response

Parameters

Returns

Request

Response

Returns

Request

Response