API: discounts

If our usual discount system isn't enough, you can leverage our REST API to push things further.

GET /discounts

This method returns all discounts for your account.

Resource URL

GET https://app.snipcart.com/api/discounts

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Example request

curl -H "Accept: application/json" \
    https://app.snipcart.com/api/discounts \
    -u {API_KEY}:

Example response

[
    {
        "id": "2223490d-84c1-480c-b713-50cb0b819313",
        "name": "Discount name",
        "trigger": "Code",
        "code": "SNIP",
        "itemId": "",
        "totalToReach": null,
        "type": "Rate",
        "rate": 30,
        "amount": null,
        "alternatePrice": null,
        "maxNumberOfUsages": 100,
        "expires": null,
        "numberOfUsages": 0,
        "numberOfUsagesUncompleted": 0,
        "shippingDescription": null,
        "shippingCost": null,
        "shippingGuaranteedDaysToDelivery": null,
    },
    ...
]

GET /discounts/{id}

This method returns a particular discount.

Resource URL

GET https://app.snipcart.com/api/discounts/{id}

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name Required? Type Description
id Yes guid The discount unique identifier.

Example request

curl -H "Accept: application/json" \
    https://app.snipcart.com/api/discounts/2223490d-84c1-480c-b713-50cb0b819313 \
    -u {API_KEY}:

Example response

{
    "id": "2223490d-84c1-480c-b713-50cb0b819313",
    "name": "Discount name",
    "trigger": "Code",
    "code": "SNIP",
    "itemId": "",
    "totalToReach": null,
    "type": "Rate",
    "rate": 30,
    "amount": null,
    "alternatePrice": null,
    "maxNumberOfUsages": 100,
    "expires": null,
    "numberOfUsages": 0,
    "numberOfUsagesUncompleted": 0,
    "shippingDescription": null,
    "shippingCost": null,
    "shippingGuaranteedDaysToDelivery": null,
}

POST /discounts

This method creates a new discount

Resource URL

POST https://app.snipcart.com/api/discounts

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.
Content-Type application/json Yes The request body needs to be JSON so we specify the content type

Parameters

Name Required? Type Description
name Yes string The discount friendly name.
expires No datetime The date when this discount should expires, if null, the discount will never expire.
maxNumberOfUsages No int The maximum number of usage for the discount, if null, customers will be able to use this discount indefinitely.
trigger Yes string Condition that will trigger the discount.
Possible values:
  • Total
  • Code
  • Product
code When trigger is Code string The code that will need to be entered by the customer.
totalToReach When trigger is Total decimal The minimum order amount.
itemId When trigger is Product string The unique ID of your product defined with data-item-id.
type Yes string The type of action that the discount will apply.
Possible values:
  • FixedAmount
  • FixedAmountOnItems
  • Rate
  • AlternatePrice
  • Shipping
  • AmountOnSubscription
  • RateOnSubscription
  • RateOnItems
  • RateOnCategory
amount When type is FixedAmount or AmountOnSubscription decimal The amount that will be deducted from order total.
productIds When type is FixedAmountOnItems string A comma separated list of unique ID of your products defined with data-item-id. The fixed amount will be deducted from each product that matches.
rate When type is Rate or RateOnSubscription or RateOnItems or RateOnCategory decimal The rate in percentage that will be deducted from order total.
alternatePrice When type is AlternatePrice string The name of the alternate price list to use.
shippingDescription When type is Shipping string The shipping method name that will be displayed to your customers.
shippingCost When type is Shipping decimal The shipping amount that will be available to your customers.
shippingGuaranteedDaysToDelivery No int The number of days it will take for shipping, you can leave it to null.
combinable No boolean This indicates if this discount can be applied when other discounts are in the cart. Also, when a cart contains a discount that isn't combinable, no others discount can be added.

Example request

curl https://app.snipcart.com/api/discounts \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u {YOUR_API_KEY}: \
  -d "{ name: 'Free shipping',
        trigger: 'Total',
        totalToReach: 150,
        type: 'Shipping',
        shippingDescription: 'Free shipping',
        shippingCost: 0,
        shippingGuaranteedDaysToDelivery: 10 }"

Example response

{
    "id": "19a8d615-09f5-4808-80c2-96cd32d141f3",
    "name": "Free shipping",
    "trigger": "Total",
    "code": null,
    "itemId": null,
    "totalToReach": 150,
    "type": "Shipping",
    "rate": null,
    "amount": null,
    "alternatePrice": null,
    "maxNumberOfUsages": null,
    "expires": null,
    "numberOfUsages": 0,
    "numberOfUsagesUncompleted": 0,
    "shippingDescription": "Free shipping",
    "shippingCost": 0,
    "shippingGuaranteedDaysToDelivery": 10,
}

PUT /discounts/{id}

This method updates an existing discount.

Resource URL

PUT https://app.snipcart.com/api/discounts/{id}

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.
Content-Type application/json Yes The request body needs to be JSON so we specify the content type

Parameters

Name Required? Type Description
id Yes guid The discount unique id.
name Yes string The discount frienly name.
expires No datetime The date when this discount should expires, if null, the discount will never expire.
archived No boolean Wether the discount is archived or not
combinable No boolean This indicates if this discount can be applied when other discounts are in the cart. Also, when a cart contains a discount that isn't combinable, no others discount can be added.
maxNumberOfUsages No int The maximum number of usage for the discount, if null, customers will be able to use this discount indefinitely.
trigger Yes string Condition that will trigger the discount.
Possible values:
  • Total
  • Code
  • Product
code When trigger is Code string The code that will need to be entered by the customer.
totalToReach When trigger is Total decimal The minimum order amount.
itemId When trigger is Product string The unique ID of your product defined with data-item-id.
type Yes string The type of action that the discount will apply.
Possible values:
  • FixedAmount
  • Rate
  • AlternatePrice
  • Shipping
amount When type is FixedAmount decimal The amount that will be deducted from order total.
rate When type is Rate decimal The rate in percentage that will be deducted from order total.
alternatePrice When type is AlternatePrice string The name of the alternate price list to use.
shippingDescription When type is Shipping string The shipping method name that will be displayed to your customers.
shippingCost When type is Shipping decimal The shipping amount that will be available to your customers.
shippingGuaranteedDaysToDelivery No int The number of days it will take for shipping, you can leave it to null.

Example request

curl https://app.snipcart.com/api/discounts/19a8d615-09f5-4808-80c2-96cd32d141f3 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u {YOUR_API_KEY}: \
  -X PUT \
  -d "{ name: 'Free shipping',
        trigger: 'Total',
        totalToReach: 150,
        type: 'Shipping',
        shippingDescription: 'Free shipping',
        shippingCost: 0,
        shippingGuaranteedDaysToDelivery: 10 }"

Example response

{
    "id": "19a8d615-09f5-4808-80c2-96cd32d141f3",
    "name": "Free shipping",
    "trigger": "Total",
    "code": null,
    "itemId": null,
    "totalToReach": 150,
    "type": "Shipping",
    "rate": null,
    "amount": null,
    "alternatePrice": null,
    "maxNumberOfUsages": null,
    "expires": null,
    "numberOfUsages": 0,
    "numberOfUsagesUncompleted": 0,
    "shippingDescription": "Free shipping",
    "shippingCost": 0,
    "shippingGuaranteedDaysToDelivery": 10,
}

DELETE /discounts/{id}

This method deletes an existing discount. Please note that you can not delete a discount that has been already used in a completed order.

Resource URL

DELETE https://app.snipcart.com/api/discounts/{id}

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts application/json content type, so you must always specify Accept: application/json header in each request you make.

Parameters

Name Required? Type Description
id Yes guid The discount unique id.

Example request

curl https://app.snipcart.com/api/discounts/19a8d615-09f5-4808-80c2-96cd32d141f3 \
  -H "Accept: application/json" \
  -u {YOUR_API_KEY}: \
  -X DELETE

Was this article helpful?