Discounts API

Discounts represent a list of all discounts in a store.

Discount object

Attribute Type Description
id string The unique identifier for the discount.
name string The name of the discount.
code string The code customers enter to use the discount.
active_at timestamp The date the discount is active.
expires_at timestamp The date the discount expires.
requirement_type string Possible values are any_order, minimum_cart_total, or minimum_cart_quantity.
expiration_type string Possible values are never, on_date, or on_limit.
reward_type string Possible values are percent_discount, flat_rate_discount, or free_shipping.
application_type string Possible values are all, category, or product.
percent_discount integer The percentage discount amount.
flat_rate_discount decimal The flat rate discount amount.
use_limit integer The limit for how many times the discount can be used.
use_count integer The number of times the discount has been used.
minimum_cart_total decimal The minimum cart total required to use the discount.
minimum_cart_quantity integer The minimum amount of items in the cart required to use the discount.

Get all discounts

Get all discounts for an account.

GET /v1/accounts/{account-id}/discounts
{
  "data": [
    {
      "id": "1",
      "type": "discounts",
      "attributes": {
        "name": "10% Off Product Name",
        "code": "TENPERCENT",
        "active_at": "2017-02-24T15:27:00.000Z",
        "expires_at": null,
        "requirement_type": "any_order",
        "expiration_type": "never",
        "reward_type": "percent_discount",
        "application_type": "product",
        "percent_discount": 10,
        "flat_rate_discount": null,
        "use_limit": null,
        "use_count": 0,
        "minimum_cart_total": null,
        "minimum_cart_quantity": null
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/discounts/1"
      },
      "relationships": {
        "product": {
          "data": {
            "type": "products",
            "id": "1"
          }
        },
        "category": {
          "data": null
        }
      }
    },
    {
      "id": "2",
      "type": "discounts",
      "attributes": {
        "name": "Free Shipping",
        "code": "FREESHIPPING",
        "active_at": "2016-12-25T06:00:00.000Z",
        "expires_at": null,
        "requirement_type": "any_order",
        "expiration_type": "on_limit",
        "reward_type": "free_shipping",
        "application_type": "all",
        "percent_discount": null,
        "flat_rate_discount": null,
        "use_limit": 5,
        "use_count": 0,
        "minimum_cart_total": null,
        "minimum_cart_quantity": null
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/discounts/2"
      },
      "relationships": {
        "product": {
          "data": null
        },
        "category": {
          "data": null
        }
      }
    },
    {
      "id": "3",
      "type": "discounts",
      "attributes": {
        "name": "Summer sale - 20% off",
        "code": "SUMMERSALE",
        "active_at": "2017-06-01T14:18:00.000Z",
        "expires_at": "2017-08-31T05:00:00.000Z",
        "requirement_type": "any_order",
        "expiration_type": "on_date",
        "reward_type": "percent_discount",
        "application_type": "all",
        "percent_discount": 20,
        "flat_rate_discount": null,
        "use_limit": null,
        "use_count": 0,
        "minimum_cart_total": null,
        "minimum_cart_quantity": null
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/discounts/3"
      },
      "relationships": {
        "product": {
          "data": null
        },
        "category": {
          "data": null
        }
      }
    }
  ],
  "meta": {
    "count": "3"
  },
  "included": [
    {
      "id": "1",
      "type": "products",
      "attributes": {
        "name": "Product Name",
        "permalink": "product-name",
        "status": "active",
        "description": "This is a sample product description",
        "created_at": "2014-12-25T00:00:00.000Z",
        "updated_at": "2014-12-25T00:00:00.000Z",
        "default_price": "20.0",
        "on_sale": false,
        "position": 1,
        "url": "http://example.bigcartel.com/product/product-name",
        "primary_image_url": "https://images.bigcartel.com/some_resource/12345/-/example1.jpg"
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/products/1"
      },
      "relationships": {
        "options": {
          "data": [
            {
              "type": "product_options",
              "id": "1"
            },
            {
              "type": "product_options",
              "id": "2"
            }
          ]
        },
        "categories": {
          "data": [
            {
              "type": "categories",
              "id": "1"
            },
            {
              "type": "categories",
              "id": "2"
            },
            {
              "type": "categories",
              "id": "3"
            }
          ]
        },
        "artists": {
          "data": [
            {
              "type": "artists",
              "id": "1"
            }
          ]
        },
        "shipping_options": {
          "data": [
            {
              "type": "shipping_options",
              "id": "1"
            }
          ]
        },
        "images": {
          "data": [
            {
              "type": "product_images",
              "id": "1"
            },
            {
              "type": "product_images",
              "id": "2"
            },
            {
              "type": "product_images",
              "id": "3"
            }
          ]
        }
      }
    }
  ],
  "links": {}
}

Parameters

Name Type Required Description
filter string false Filter discounts using status
Filter example

Use status to filter discounts with a status of active or expired.

GET /v1/accounts/{account-id}/discounts?filter[status]=active

Get a discount

Get a specific discount for an account.

GET /v1/accounts/{account-id}/discounts/{discount-id}
{
  "data": {
    "id": "1",
    "type": "discounts",
    "attributes": {
      "name": "10% Off Product Name",
      "code": "TENPERCENT",
      "active_at": "2017-02-24T15:27:00.000Z",
      "expires_at": null,
      "requirement_type": "any_order",
      "expiration_type": "never",
      "reward_type": "percent_discount",
      "application_type": "product",
      "percent_discount": 10,
      "flat_rate_discount": null,
      "use_limit": null,
      "use_count": 0,
      "minimum_cart_total": null,
      "minimum_cart_quantity": null
    },
    "links": {
      "self": "https://api.bigcartel.com/v1/accounts/1/discounts/1"
    },
    "relationships": {
      "product": {
        "data": {
          "type": "products",
          "id": "1"
        }
      },
      "category": {
        "data": null
      }
    }
  },
  "included": [
    {
      "id": "1",
      "type": "products",
      "attributes": {
        "name": "Product Name",
        "permalink": "product-name",
        "status": "active",
        "description": "This is a sample product description",
        "created_at": "2014-12-25T00:00:00.000Z",
        "updated_at": "2014-12-25T00:00:00.000Z",
        "default_price": "20.0",
        "on_sale": false,
        "position": 1,
        "url": "http://example.bigcartel.com/product/product-name",
        "primary_image_url": "https://images.bigcartel.com/some_resource/12345/-/example1.jpg"
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/products/1"
      },
      "relationships": {
        "options": {
          "data": [
            {
              "type": "product_options",
              "id": "1"
            },
            {
              "type": "product_options",
              "id": "2"
            }
          ]
        },
        "categories": {
          "data": [
            {
              "type": "categories",
              "id": "1"
            },
            {
              "type": "categories",
              "id": "2"
            },
            {
              "type": "categories",
              "id": "3"
            }
          ]
        },
        "artists": {
          "data": [
            {
              "type": "artists",
              "id": "1"
            }
          ]
        },
        "shipping_options": {
          "data": [
            {
              "type": "shipping_options",
              "id": "1"
            }
          ]
        },
        "images": {
          "data": [
            {
              "type": "product_images",
              "id": "1"
            },
            {
              "type": "product_images",
              "id": "2"
            },
            {
              "type": "product_images",
              "id": "3"
            }
          ]
        }
      }
    }
  ]
}

Parameters

None.

Create a discount

Creates a new discount.

POST /v1/accounts/{account-id}/discounts

Parameters

Name Type Required Description
type string true The only option right now is discounts.
name string true The name of the discount.
code string true The code customers enter to use the discount.
active_at timestamp true The date the discount is active.
expires_at timestamp false The date the discount expires. Must be a date in the future. Required when expiration_type is set to on_date.
requirement_type string true Possible values are any_order, minimum_cart_total, or minimum_cart_quantity.
expiration_type string true Possible values are never, on_date, or on_limit.
reward_type string true Possible values are percent_discount, flat_rate_discount, or free_shipping.
application_type string true Possible values are all, category, or product.
percent_discount integer false The percentage discount amount. Must be less than 100. Required when reward_type is set to percent_discount.
flat_rate_discount decimal false The flat rate discount amount. Required when reward_type is set to flat_rate_discount.
use_limit integer false The limit for how many times the discount can be used. Required when expiration_type is set to on_limit.
minimum_cart_total decimal false The minimum cart total required to use the discount. Required when requirement_type is set to minimum_cart_total.
minimum_cart_quantity integer false The minimum amount of items in the cart required to use the discount. Required when requirement_type is set to minimum_cart_quantity.

The following parameters are only required when creating a discount that applies to specific categories or products - application_type will also need to be set to category or product.

Name Type Required Description
category[].type string true The only option right now is categories.
category[].id integer true The unique identifier of the category.
product[].type string true The only option right now is products.
product[].id integer true The unique identifier of the product.

Example requests

Creates a discount to give customers free shipping on all items in a specific category.

{
  "data": {
    "type": "discounts",
    "attributes": {
      "name": "Free Shipping Discount",
      "code": "FREESHIPPING",
      "active_at": "2016-12-25T00:00:00.000Z",
      "requirement_type": "any_order",
      "reward_type": "free_shipping",
      "application_type": "category",
      "expiration_type": "never"
    },
    "relationships": {
      "category": {
        "data": {
          "type": "categories",
          "id": "1"
        }
      }
    }
  }
}

Creates a discount to give customers a flat-rate discount on their entire order if they order at least 5 items.

{
  "data": {
    "type": "discounts",
    "attributes": {
      "name": "Flat Rate Discount",
      "code": "FLATRATE",
      "active_at": "2014-12-25T00:00:00.000Z",
      "requirement_type": "minimum_cart_quantity",
      "reward_type": "flat_rate_discount",
      "application_type": "all",
      "expiration_type": "never",
      "flat_rate_discount": "10.0",
      "minimum_cart_quantity": 5
    }
  }
}

Response

If successful, we’ll return a 201 Created with the location of the new discount in the Location header and the same body as getting the discount.

Update a discount

Updates a specific discount’s details.

PATCH /v1/accounts/{account-id}/discounts/{discount-id}

Parameters

Name Type Required Description
type string true The only option right now is discounts.
name string true The name of the discount.
code string true The code customers enter to use the discount.
active_at timestamp true The date the discount is active.
expires_at timestamp false The date the discount expires. Must be a date in the future. Required when expiration_type is set to on_date.
requirement_type string true Possible values are any_order, minimum_cart_total, or minimum_cart_quantity.
expiration_type string true Possible values are never, on_date, or on_limit.
reward_type string true Possible values are percent_discount, flat_rate_discount, or free_shipping.
application_type string true Possible values are all, category, or product.
percent_discount integer false The percentage discount amount. Must be less than 100. Required when reward_type is set to percent_discount.
flat_rate_discount decimal false The flat rate discount amount. Required when reward_type is set to flat_rate_discount.
use_limit integer false The limit for how many times the discount can be used. Required when expiration_type is set to on_limit.
minimum_cart_total decimal false The minimum cart total required to use the discount. Required when requirement_type is set to minimum_cart_total.
minimum_cart_quantity integer false The minimum amount of items in the cart required to use the discount. Required when requirement_type is set to minimum_cart_quantity.

The following parameters are only required when updating a discount that applies to specific categories or products - application_type will also need to be set to category or product.

Name Type Required Description
category[].type string true The only option right now is categories.
category[].id integer true The unique identifier of the category.
product[].type string true The only option right now is products.
product[].id integer true The unique identifier of the product.

Example request

{
  "data": {
  	"id": "1",
    "type": "discounts",
    "attributes": {
      "name": "Flat Rate Discount",
      "code": "FLATRATE",
      "active_at": "2014-12-25T00:00:00.000Z",
      "requirement_type": "minimum_cart_quantity",
      "reward_type": "flat_rate_discount",
      "application_type": "all",
      "expiration_type": "never",
      "flat_rate_discount": "10.0",
      "minimum_cart_quantity": 15
    }
  }
}

Response

If successful, we’ll return a 200 OK and the same body as getting the discount.

Delete a discount

Deletes a specific discount.

DELETE /v1/accounts/{account-id}/discounts/{discount-id}

Parameters

None.

If successful, we’ll return a 204 No Content response.