Discounts API

Manage your store's discounts programmatically through Snipcart's REST API. This resource lets you list, retrieve, create, update, and delete discounts on your account — the same discounts you can configure in the dashboard, exposed so you can drive them from your own systems.

Requests are authenticated with your secret API key, sent as the HTTP Basic username with an empty password. With curl: -u {API_KEY}:. See Authentication for details. The base URL is always https://app.snipcart.com/api.

⚠️ Important: Discounts are read and written as the raw discount object. The same object shape is used for both requests and responses, so any field documented on the response can also be sent on create/update. Many fields only apply to a specific trigger or type (see below) and are otherwise ignored or left null.

Triggers and types

A discount has two dimensions:

  • trigger — the condition that activates the discount. Determines which "trigger" fields are required.
  • type — the action the discount applies once triggered. Determines which "action" fields are required.

trigger values (string): Code, Product, Total, QuantityOfAProduct, CartContainsOnlySpecifiedProducts, CartContainsSomeSpecifiedProducts, CartContainsAtLeastAllSpecifiedProducts, CartContainsOnlyProductsFromSpecifiedCategories, CartContainsSomeProductsFromSpecifiedCategories.

type values (string): Rate, AlternatePrice, FixedAmount, Shipping, FixedAmountOnItems, GetFreeItems, RateOnItems, AmountOnSubscription, RateOnSubscription, FixedAmountOnCategory, RateOnCategory.

Which fields apply where (enforced by server-side validation):

Trigger Required field
Code code
Product itemId
Total (none required; use totalToReach for the threshold)
QuantityOfAProduct quantityOfAProduct
CartContainsOnlySpecifiedProducts, CartContainsSomeSpecifiedProducts, CartContainsAtLeastAllSpecifiedProducts triggerProductIds
CartContainsOnlyProductsFromSpecifiedCategories, CartContainsSomeProductsFromSpecifiedCategories triggerCategories
Type Required field(s)
Rate, RateOnSubscription rate
RateOnItems rate, productIds
RateOnCategory rate, categories
FixedAmount, AmountOnSubscription amount
FixedAmountOnItems amount, productIds
FixedAmountOnCategory amount, categories
AlternatePrice alternatePrice
Shipping shippingCost, shippingDescription
GetFreeItems numberOfItemsRequired, numberOfFreeItems

Table of contents

GET /discounts

Returns every discount on your account (no pagination — the full list is returned as a JSON array).

Resource URL

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

Headers

Name Required Description
Accept Yes Must be application/json.

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": "10% off everything",
        "combinable": true,
        "trigger": "Code",
        "code": "SNIP10",
        "type": "Rate",
        "rate": 10.0,
        "amount": null,
        "totalToReach": null,
        "itemId": null,
        "alternatePrice": null,
        "maxNumberOfUsages": 100,
        "maxNumberOfUsagesPerCustomer": null,
        "expires": null,
        "archived": false,
        "numberOfUsages": 12,
        "numberOfUsagesUncompleted": 1,
        "shippingDescription": null,
        "shippingCost": null,
        "shippingGuaranteedDaysToDelivery": null,
        "creationDate": "2024-01-15T18:30:00Z",
        "modificationDate": "2024-01-15T18:30:00Z"
    },
    {
        "id": "19a8d615-09f5-4808-80c2-96cd32d141f3",
        "name": "Free shipping over $150",
        "combinable": true,
        "trigger": "Total",
        "code": null,
        "type": "Shipping",
        "totalToReach": 150.0,
        "rate": null,
        "amount": null,
        "shippingDescription": "Free shipping",
        "shippingCost": 0.0,
        "shippingGuaranteedDaysToDelivery": 10,
        "maxNumberOfUsages": null,
        "expires": null,
        "archived": false,
        "numberOfUsages": 0,
        "numberOfUsagesUncompleted": 0,
        "creationDate": "2024-02-01T12:00:00Z",
        "modificationDate": "2024-02-01T12:00:00Z"
    }
]

GET /discounts/{id}

Returns a single discount by its unique identifier. Responds with 404 Not Found if no discount with that ID exists on your account.

Resource URL

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

Headers

Name Required Description
Accept Yes Must be application/json.

Path Parameters

Name Required Type Description
id Yes guid The discount's 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": "10% off everything",
    "combinable": true,
    "trigger": "Code",
    "code": "SNIP10",
    "type": "Rate",
    "rate": 10.0,
    "amount": null,
    "totalToReach": null,
    "itemId": null,
    "alternatePrice": null,
    "maxNumberOfUsages": 100,
    "maxNumberOfUsagesPerCustomer": null,
    "expires": null,
    "archived": false,
    "numberOfUsages": 12,
    "numberOfUsagesUncompleted": 1,
    "shippingDescription": null,
    "shippingCost": null,
    "shippingGuaranteedDaysToDelivery": null,
    "creationDate": "2024-01-15T18:30:00Z",
    "modificationDate": "2024-01-15T18:30:00Z"
}

POST /discounts

Creates a new discount. Returns 201 Created with the created discount. The required body fields depend on the chosen trigger and type (see Triggers and types); a 400 is returned with validation errors if a required field for the selected trigger/type is missing, or if a Code-trigger discount reuses an active code.

Resource URL

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

Headers

Name Required Description
Accept Yes Must be application/json.
Content-Type Yes Must be application/json.

Body Parameters

Name Required Type Description
name Yes string The discount's friendly name.
trigger Yes string Condition that activates the discount. One of the trigger values.
type Yes string Action the discount applies. One of the type values.
code When trigger is Code string The code the customer must enter. Must be unique among active discounts.
totalToReach When trigger is Total decimal The minimum order amount that activates the discount.
itemId When trigger is Product string The product's unique ID (data-item-id).
quantityOfAProduct When trigger is QuantityOfAProduct int Quantity threshold for the targeted product(s).
triggerProductIds When trigger is one of the CartContains*SpecifiedProducts values string Comma-separated product IDs that must be in the cart.
triggerCategories When trigger is one of the CartContains*Categories values string Comma-separated category names that must be in the cart.
rate When type is Rate, RateOnSubscription, RateOnItems, or RateOnCategory decimal The percentage deducted (e.g. 10 for 10%).
amount When type is FixedAmount, AmountOnSubscription, FixedAmountOnItems, or FixedAmountOnCategory decimal The fixed amount deducted.
productIds When type is FixedAmountOnItems or RateOnItems string Comma-separated product IDs (data-item-id) the discount applies to.
categories When type is FixedAmountOnCategory or RateOnCategory string JSON-encoded array of category names the discount applies to.
alternatePrice When type is AlternatePrice string The name of the alternate price list to use.
shippingCost When type is Shipping decimal The shipping cost offered to the customer (use 0 for free shipping).
shippingDescription When type is Shipping string The shipping method name shown to the customer.
shippingGuaranteedDaysToDelivery No int Estimated delivery time in days for a Shipping discount.
numberOfItemsRequired When type is GetFreeItems int Items required in cart before free items are granted.
numberOfFreeItems When type is GetFreeItems int Number of free items granted.
maxNumberOfUsages No int Maximum total uses. If null, the discount can be used indefinitely.
maxNumberOfUsagesPerCustomer No int Maximum uses per customer. Must be ≥ 0.
maxAmountToReach No decimal Cap on the total discount applied when the discount is combinable.
combinable No boolean Whether this discount can coexist with other discounts in the cart. Defaults to true. A non-combinable discount in the cart blocks all others.
currency No string Restricts the discount to a single currency (omitted from the response when not set).
expires No datetime When the discount expires. If null, it never expires. Interpreted in your account's time zone.
appliesOnAllRecurringOrders No boolean For subscription discount types, whether the discount applies to all recurring orders or only the first payment.

⚠️ Important: When type is Shipping, creating the discount also creates an associated custom shipping rate from shippingCost, shippingDescription, and shippingGuaranteedDaysToDelivery.

Example request 

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

Example response 

{
    "id": "19a8d615-09f5-4808-80c2-96cd32d141f3",
    "name": "Free shipping over $150",
    "combinable": true,
    "trigger": "Total",
    "code": null,
    "itemId": null,
    "totalToReach": 150.0,
    "type": "Shipping",
    "rate": null,
    "amount": null,
    "alternatePrice": null,
    "maxNumberOfUsages": null,
    "maxNumberOfUsagesPerCustomer": null,
    "expires": null,
    "archived": false,
    "numberOfUsages": 0,
    "numberOfUsagesUncompleted": 0,
    "shippingDescription": "Free shipping",
    "shippingCost": 0.0,
    "shippingGuaranteedDaysToDelivery": 10,
    "creationDate": "2024-02-01T12:00:00Z",
    "modificationDate": "2024-02-01T12:00:00Z"
}

PUT /discounts/{id}

Updates an existing discount. Returns 200 OK with the updated discount, or 404 Not Found if the discount doesn't exist on your account. Send the full discount object: the same body fields as POST apply, plus archived.

Resource URL

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

Headers

Name Required Description
Accept Yes Must be application/json.
Content-Type Yes Must be application/json.

Path Parameters

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

Body Parameters

Same fields as POST /discounts. In addition:

Name Required Type Description
archived No boolean Whether the discount is archived. Archived discounts are inactive but kept for history.

Example request 

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

Example response 

{
    "id": "19a8d615-09f5-4808-80c2-96cd32d141f3",
    "name": "Free shipping over $150",
    "combinable": true,
    "trigger": "Total",
    "code": null,
    "itemId": null,
    "totalToReach": 150.0,
    "type": "Shipping",
    "rate": null,
    "amount": null,
    "alternatePrice": null,
    "maxNumberOfUsages": null,
    "expires": null,
    "archived": false,
    "numberOfUsages": 0,
    "numberOfUsagesUncompleted": 0,
    "shippingDescription": "Free shipping",
    "shippingCost": 0.0,
    "shippingGuaranteedDaysToDelivery": 10,
    "creationDate": "2024-02-01T12:00:00Z",
    "modificationDate": "2024-02-01T13:45:00Z"
}

DELETE /discounts/{id}

Deletes an existing discount. Returns 204 No Content on success, or 404 Not Found if the discount doesn't exist on your account.

⚠️ Important: A discount that has already been used in a completed order cannot be deleted (numberOfUsages > 0) — the request returns 400 Bad Request. Archive it instead via PUT.

Resource URL

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

Headers

Name Required Description
Accept Yes Must be application/json.

Path Parameters

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

Example request 

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

Was this article helpful?