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

API: discounts

GET /discounts

GET /discounts/{id}

POST /discounts

PUT /discounts/{id}

DELETE /discounts/{id}

Was this article helpful?