Coupon

Coupons are a type of discount that a customer can apply at checkout. They can be in the form of a percent or an absolute amount, and can have a limited number of uses.

Coupons can be created for specific tags or products, and can be applied either to the individual products, or to the total order value.

See the coupon fields for more details and options.

Endpoints

POST
/stores/{store.id}/coupons
GET
/stores/{store.id}/coupons
GET
/stores/{store.id}/coupons/{coupon.id}
PATCH
/stores/{store.id}/coupons/{coupon.id}
DELETE
/stores/{store.id}/coupons/{coupon.id}

The Coupon object

Fields
Name
id
Type
flake
Tags
Description
id of the coupon
Name
store_id
Type
flake
Tags
Description
id of the store the coupon belongs to
Name
enabled
Type
boolean
Tags
Description
whether the coupon is enabled and currently usable by customers (assuming it's within the usable_at and expires_at range)
Name
code
Type
string
Tags
Description
the code that customers type in at checkout. Code is case insensitive and unique to the store. Limited to alphanumeric characters and dashes.
Name
note
Type
string
Tags
NULLABLE
Description
a note for this coupon. Only visible to the store members, not visible to the customer.
Name
apply_to_tags
Type
[]partial tag
Tags
Description
an array containing a list of tags that this coupon can apply to.
Name
apply_to_products
Type
[]partial product
Tags
Description
an array containing a list of products that this coupon can apply to.
Name
discount_type
Type
enum
Tags
Description
the type of discount this coupon 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 coupon 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
discount_apply_individually
Type
boolean
Tags
Description
whether this discount applies to individual order lines, or to the entire order
Name
discount_apply_before_sales
Type
boolean
Tags
Description
whether this discount should be applied before sales.
Name
usable_by_customer
Type
customer
Tags
NULLABLE
Description
the customer that this coupon applies to. If present, only this customer can use the coupon.
Name
minimum_order_value
Type
integer
Tags
Description
the minimum value of the order required before this coupon may be applied
Name
redeem_limit_store_enabled
Type
boolean
Tags
Description
whether the coupon redeem limit is enabled for the whole store
Name
redeem_limit_store_amount
Type
integer
Tags
Description
the number of times this coupon may be redeemed across the whole store
Name
redeem_limit_customer_enabled
Type
boolean
Tags
Description
whether the coupon redeem limit is enabled for individual customers
Name
redeem_limit_customer_amount
Type
integer
Tags
Description
the number of times this coupon may be redeemed by the same customer
Name
usable_on_one_time_purchase
Type
boolean
Tags
Description
whether the coupon may be applied to one time purchases
Name
usable_on_subscription
Type
boolean
Tags
Description
whether the coupon may be applied to a subscription
Name
usable_at
Type
timestamp
Tags
Description
timestamp of when the coupon will become usable
Name
expires_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when the coupon will expire and become unusable
Name
created_by
Type
user
Tags
Description
the user that created this coupon.
Name
created_at
Type
timestamp
Tags
Description
timestamp of when the coupon was created
Name
updated_by
Type
user
Tags
NULLABLE
Description
the user that most recently updated this coupon.
Name
updated_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when the coupon 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 Coupon object

{
  "id": "149580776499843072",
  "store_id": "94688451781206016",
  "enabled": true,
  "code": "HALF-OFF",
  "note": "gives the customers 50% off if their order $10.00 or more",
  "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,
  "discount_apply_individually": false,
  "discount_apply_before_sales": false,
  "usable_by_customer": null,
  "minimum_order_value": 1000,
  "redeem_limit_store_enabled": false,
  "redeem_limit_store_amount": 0,
  "redeem_limit_customer_enabled": true,
  "redeem_limit_customer_amount": 1,
  "usable_on_one_time_purchase": true,
  "usable_on_subscription": false,
  "usable_at": "2023-04-11T16:42:58.163471Z",
  "expires_at": "2023-06-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 Coupon

Creates a new coupon.

Parameters
Name
enabled
Type
boolean?
Tags
OPTIONAL
Description
whether the coupon is enabled and currently usable by customers (assuming it's within the usable_at and expires_at range)
Name
code
Type
string
Tags
REQUIRED
Description
the code that customers type in at checkout. Code is case insensitive and unique to the store. Limited to alphanumeric characters and dashes. Cannot start or end with a dash. Must be 1 - 50 characters.
Name
note
Type
string?
Tags
OPTIONAL
Description
a note for this coupon. Only visible to the store members, not visible to the customer.
Name
apply_to_tags
Type
[]flake?
Tags
OPTIONAL
Description
an array of IDs specifying which tags this coupon can apply to
Name
apply_to_products
Type
[]flake?
Tags
OPTIONAL
Description
an array of IDs specifying which products this coupon can apply to
Name
discount_type
Type
enum
Tags
REQUIRED
Description
the type of discount this coupon 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 coupon 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
discount_apply_individually
Type
boolean?
Tags
OPTIONAL
Description
whether this discount applies to individual order lines, or to the entire order
Name
discount_apply_before_sales
Type
boolean?
Tags
OPTIONAL
Description
whether this discount should be applied before sales.
Name
usable_by_customer_id
Type
flake?
Tags
OPTIONAL
Description
the customer that this coupon applies to. If provided, only this customer can use the coupon.
Name
minimum_order_value
Type
integer?
Tags
OPTIONAL
Description
the minimum value of the order required before this coupon may be applied
Name
redeem_limit_store_enabled
Type
boolean?
Tags
OPTIONAL
Description
whether the coupon redeem limit is enabled for the whole store
Name
redeem_limit_store_amount
Type
integer?
Tags
OPTIONAL
Description
the number of times this coupon may be redeemed across the whole store
Name
redeem_limit_customer_enabled
Type
boolean?
Tags
OPTIONAL
Description
whether the coupon redeem limit is enabled for individual customers
Name
redeem_limit_customer_amount
Type
integer?
Tags
OPTIONAL
Description
the number of times this coupon may be redeemed by the same customer
Name
usable_on_one_time_purchase
Type
boolean?
Tags
OPTIONAL
Description
whether the coupon may be applied to one time purchases
Name
usable_on_subscription
Type
boolean?
Tags
OPTIONAL
Description
whether the coupon may be applied to a subscription
Name
usable_at
Type
timestamp?
Tags
OPTIONAL
Description
timestamp of when the coupon will become usable
Name
expires_at
Type
timestamp?
Tags
OPTIONAL
Description
timestamp of when the coupon will expire and become unusable

Returns

Returns the newly created coupon.

Request

coupon_create

POST
/stores/{store.id}/coupons

Response

{
  "id": "149580776499843072",
  "store_id": "94688451781206016",
  "enabled": true,
  "code": "HALF-OFF",
  "note": "gives the customers 50% off if their order $10.00 or more",
  "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,
  "discount_apply_individually": false,
  "discount_apply_before_sales": false,
  "usable_by_customer": null,
  "minimum_order_value": 1000,
  "redeem_limit_store_enabled": false,
  "redeem_limit_store_amount": 0,
  "redeem_limit_customer_enabled": true,
  "redeem_limit_customer_amount": 1,
  "usable_on_one_time_purchase": true,
  "usable_on_subscription": false,
  "usable_at": "2023-04-11T16:42:58.163471Z",
  "expires_at": null,
  "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 Coupons

Returns all coupons in the store.

Returns

Returns an array of coupons.

Request

coupon_read

GET
/stores/{store.id}/coupons

Response

[
  {
    "id": "149580776499843072",
    "store_id": "94688451781206016",
    "enabled": true,
    "code": "HALF-OFF",
    "note": "gives the customers 50% off if their order $10.00 or more",
    "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,
    "discount_apply_individually": false,
    "discount_apply_before_sales": false,
    "usable_by_customer": null,
    "minimum_order_value": 1000,
    "redeem_limit_store_enabled": false,
    "redeem_limit_store_amount": 0,
    "redeem_limit_customer_enabled": true,
    "redeem_limit_customer_amount": 1,
    "usable_on_one_time_purchase": true,
    "usable_on_subscription": false,
    "usable_at": "2023-04-11T16:42:58.163471Z",
    "expires_at": "2023-06-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 Coupon

Returns a coupon by ID.

Returns

Returns a coupon if a valid identifier was provided.

Request

coupon_read

GET
/stores/{store.id}/coupons/{coupon.id}

Response

{
  "id": "149580776499843072",
  "store_id": "94688451781206016",
  "enabled": true,
  "code": "HALF-OFF",
  "note": "gives the customers 50% off if their order $10.00 or more",
  "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,
  "discount_apply_individually": false,
  "discount_apply_before_sales": false,
  "usable_by_customer": null,
  "minimum_order_value": 1000,
  "redeem_limit_store_enabled": false,
  "redeem_limit_store_amount": 0,
  "redeem_limit_customer_enabled": true,
  "redeem_limit_customer_amount": 1,
  "usable_on_one_time_purchase": true,
  "usable_on_subscription": false,
  "usable_at": "2023-04-11T16:42:58.163471Z",
  "expires_at": "2023-06-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 Coupon

Updates a coupon.

Parameters
Name
enabled
Type
boolean?
Tags
OPTIONAL
Description
whether the coupon is enabled and currently usable by customers (assuming it's within the usable_at and expires_at range)
Name
code
Type
string?
Tags
OPTIONAL
Description
the code that customers type in at checkout. Code is case insensitive and unique to the store. Limited to alphanumeric characters and dashes. Cannot start or end with a dash. Must be 1 - 50 characters.
Name
note
Type
string?
Tags
OPTIONAL
Description
a note for this coupon. Only visible to the store members, not visible to the customer.
Name
apply_to_tags
Type
[]flake?
Tags
OPTIONAL
Description
an array of IDs specifying which tags this coupon can apply to
Name
apply_to_products
Type
[]flake?
Tags
OPTIONAL
Description
an array of IDs specifying which products this coupon can apply to
Name
discount_type
Type
enum?
Tags
OPTIONAL
Description
the type of discount this coupon 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 coupon 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
discount_apply_individually
Type
boolean?
Tags
OPTIONAL
Description
whether this discount applies to individual order lines, or to the entire order
Name
discount_apply_before_sales
Type
boolean?
Tags
OPTIONAL
Description
whether this discount should be applied before sales.
Name
usable_by_customer_id
Type
flake?
Tags
OPTIONAL
Description
the customer that this coupon applies to. If provided, only this customer can use the coupon.
Name
minimum_order_value
Type
integer?
Tags
OPTIONAL
Description
the minimum value of the order required before this coupon may be applied
Name
redeem_limit_store_enabled
Type
boolean?
Tags
OPTIONAL
Description
whether the coupon redeem limit is enabled for the whole store
Name
redeem_limit_store_amount
Type
integer?
Tags
OPTIONAL
Description
the number of times this coupon may be redeemed across the whole store
Name
redeem_limit_customer_enabled
Type
boolean?
Tags
OPTIONAL
Description
whether the coupon redeem limit is enabled for individual customers
Name
redeem_limit_customer_amount
Type
integer?
Tags
OPTIONAL
Description
the number of times this coupon may be redeemed by the same customer
Name
usable_on_one_time_purchase
Type
boolean?
Tags
OPTIONAL
Description
whether the coupon may be applied to one time purchases
Name
usable_on_subscription
Type
boolean?
Tags
OPTIONAL
Description
whether the coupon may be applied to a subscription
Name
usable_at
Type
timestamp?
Tags
OPTIONAL
Description
timestamp of when the coupon will become usable
Name
expires_at
Type
timestamp?
Tags
OPTIONAL
Description
timestamp of when the coupon will expire and become unusable

Returns

Returns the updated coupon.

Request

coupon_update

PATCH
/stores/{store.id}/coupons/{coupon.id}

Response

{
  "id": "149580776499843072",
  "store_id": "94688451781206016",
  "enabled": true,
  "code": "HALF-OFF",
  "note": "gives the customers 50% off if their order $10.00 or more",
  "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,
  "discount_apply_individually": false,
  "discount_apply_before_sales": false,
  "usable_by_customer": null,
  "minimum_order_value": 1000,
  "redeem_limit_store_enabled": false,
  "redeem_limit_store_amount": 0,
  "redeem_limit_customer_enabled": true,
  "redeem_limit_customer_amount": 1,
  "usable_on_one_time_purchase": true,
  "usable_on_subscription": false,
  "usable_at": "2023-04-11T16:42:58.163471Z",
  "expires_at": "2023-06-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 Coupon

Deletes a coupon by ID.

Returns

Returns HTTP 204 if the specified coupon was deleted.

Request

coupon_delete

DELETE
/stores/{store.id}/coupons/{coupon.id}

Response

HTTP 204

Coupon

Endpoints

Fields

Fields

Fields

The Coupon object

Parameters

Returns

Request

Response

Returns

Request

Response

Returns

Request

Response

Parameters

Returns

Request

Response

Returns

Request

Response