Skip to main content
GET
Get a promo code (discount)

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string
required

Response

Success

id
integer

Discount id.

name
string

Same value as code.

code
string

The code shoppers enter at checkout. Matching is case-insensitive.

price_discount_type
enum<string>

What the code gives. percentage: takes percentage_value percent off each matching line. flat: takes flat_value off (see flat_value). free_product: adds the variants in free_variant_ids to the cart at no charge. free_shipping: waives shipping on the cart. free_enrollment_pack: makes the lines added from the packs in free_enrollment_pack_ids free. For stacking, free_shipping counts as a shipping discount and every other type counts as a product discount.

Available options:
flat,
percentage,
free_product,
free_shipping,
free_enrollment_pack
price_discount_amount
integer

For flat discounts, flat_value truncated to a whole number; flat_value itself is not returned. 0 for other types.

price_discount_percent
number

For percentage discounts, percentage_value as a number. 0 for other types.

percentage_value
string | null

Percent off as a decimal string, for example 10.0. Meaningful only for percentage discounts.

source
enum<string>

Who manages the discount. promo: a merchant promo code that shoppers can enter. droplet: created by a droplet and not redeemable at customer checkout. manual: a one-off discount an admin applied to a cart; the list endpoint never returns these. subscription_pro: a tier or offer discount that Subscription Pro manages; the list endpoint returns these only with source=subscription_pro, and update and delete refuse them.

Available options:
promo,
manual,
droplet,
subscription_pro
value_managed_by_droplet
boolean

True when a droplet computes the real discount amount at cart time.

reason
string | null

Note recorded with a manual discount, where it is required.

created_by
object | null

The admin who created the discount. Null when the creator is unknown or has no legacy company membership id.

active
boolean

Whether the code is turned on.

automatic
boolean

Whether the discount applies to eligible carts without a code.

applicable_for
enum<string> | null

Which cart lines the discount targets. everything, specific_products, except_specific_products, specific_collections, specific_enrollment_packs, or except_specific_enrollment_packs; see the request field of the same name. Null for manual discounts.

Available options:
everything,
specific_products,
specific_collections,
except_specific_products,
specific_enrollment_packs,
except_specific_enrollment_packs,
null
apply_only_once
boolean | null

Whether a flat discount applies only to the first matching line.

apply_to_subscriptions
boolean

Whether lines bought as a subscription are discounted.

apply_to_recurring_subscription_orders
boolean

Whether the discount also lowers the price of later recurring orders for subscriptions bought in the cart.

apply_to_volume
boolean

Whether the discount lowers each discounted line's CV and QV in proportion to the amount taken off.

country_filter
string | null

apply_all, apply_some (only the listed countries), or exclude_some (every country except the listed ones). The countries are in eligible_country_ids.

customer_filter
string | null

Who can use the code: all_customers, specific_customer_segment, specific_customers, first_time_customers, csv_uploaded_customers, or specific_member_types. See the request field of the same name.

shipping_method_filter
string | null

apply_all_methods or apply_some_methods (only the methods in eligible_shipping_method_ids). Affects free_shipping discounts only.

purchase_requirement
string | null

no_minimum_required, minimum_purchase_amount, minimum_purchase_quantity, or minimum_volume. See the request field of the same name.

purchase_requirement_applies_to_whole_cart
boolean

Whether the purchase minimum is measured on the whole cart (true) or per line or collection (false). A minimum quantity on a specific_collections discount is always measured per collection. See the request field of the same name.

has_end_date
boolean | null

Whether the discount has an end. False or null means it never ends.

start_date_time
string<date-time> | null

When the discount starts, in UTC.

end_date_time
string<date-time> | null

When the discount ends, in UTC. Null when it has no end.

start_date
string | null

Start date as YYYY-MM-DD, in time_zone.

start_time
string | null

Start time in time_zone, in 24-hour HH:MM format. Requests take 12-hour time with AM or PM.

end_date
string | null

End date as YYYY-MM-DD, in time_zone. Null when it has no end.

end_time
string | null

End time in time_zone, in 24-hour HH:MM format. Null when it has no end.

time_zone
string | null

Time zone for start_date, start_time, end_date, and end_time. Null means UTC.

discount_type
enum<string>

shipping_discount for free_shipping discounts and product_discount for every other type. other_product_discounts and other_shipping_discounts refer to these groups.

Available options:
product_discount,
shipping_discount
description
string | null

Merchant-only note about the promo code. Never shown to shoppers.

Maximum string length: 1000
total_usage
integer

Number of completed checkouts that used the discount. When limit_usage_of_code is true, the code stops working once this reaches customer_usage_limit.

free_variant_ids
integer[]

Variants a free_product discount adds to the cart at no charge.

free_enrollment_pack_ids
integer[]

Enrollment packs whose lines a free_enrollment_pack discount makes free.

waive_enrollment_fee
boolean

Whether a free_enrollment_pack discount also waives the enrollment fee.

exclude_free_items_from_volume
boolean
applicable_product_ids
integer[]

The discount's product list. Returns the same list as inapplicable_product_ids and product_ids; read applicable_for to know whether these products are included or excluded.

inapplicable_product_ids
integer[]

The discount's product list. Returns the same list as applicable_product_ids and product_ids; read applicable_for to know whether these products are included or excluded.

applicable_collection_ids
integer[]

Collections targeted when applicable_for is specific_collections. Same list as collection_ids.

applicable_enrollment_pack_ids
integer[]

Enrollment packs targeted when applicable_for is specific_enrollment_packs. Empty for any other applicable_for.

inapplicable_enrollment_pack_ids
integer[]

Enrollment packs excluded when applicable_for is except_specific_enrollment_packs. Empty for any other applicable_for.

collection_ids
integer[]

Same list as applicable_collection_ids.

product_ids
integer[]

Same list as applicable_product_ids.

customer_ids
integer[]

Same list as eligible_customer_ids.

country_codes
string[]

ISO country codes of the countries in eligible_country_ids.

eligible_customer_ids
integer[]

Customers who can use the code when customer_filter is specific_customers. Same list as customer_ids.

csv_uploaded_customer_emails
string[]

Lowercased email addresses that can use the code when customer_filter is csv_uploaded_customers. Set with the customer_emails request field. Not returned by the list endpoint.

eligible_country_ids
integer[]

The discount's country list. Returns the same list as ineligible_country_ids; read country_filter to know whether these countries are included or excluded.

ineligible_country_ids
integer[]

The discount's country list. Returns the same list as eligible_country_ids; read country_filter to know whether these countries are included or excluded.

eligible_shipping_method_ids
integer[]

Shipping methods a free_shipping discount waives when shipping_method_filter is apply_some_methods.

eligible_customer_segments
string[]

Segments that can use the code when customer_filter is specific_customer_segment: user (a rep), customer (a signed-in customer), or guest.

member_type_ids
string[]

Member type ids that can use the code when customer_filter is specific_member_types. Present only for companies with member-type discounts enabled.

minimum_purchase_requirement_amount
number

Minimum subtotal for minimum_purchase_amount, in the base currency (USD). 0 when not set.

minimum_purchase_requirement_amount_max
number | null

Maximum subtotal for minimum_purchase_amount, in the base currency (USD). Null or 0 means no ceiling.

minimum_purchase_requirement_quantity
integer

Minimum number of items for minimum_purchase_quantity. 0 when not set.

minimum_cv
integer | null

Minimum cart CV, enrollment-pack CV included, when purchase_requirement is minimum_volume.

maximum_cv
integer | null

Inclusive maximum cart CV when purchase_requirement is minimum_volume. Null or 0 means no ceiling.

customer_usage_limit
integer

The total number of uses allowed across all customers (the use_limit request field), not a per-customer limit. Enforced only when limit_usage_of_code is true.

minimum_amount_cents
integer

Despite the name, minimum_purchase_requirement_amount truncated to whole units of the base currency (USD), not cents. 0 when not set.

limit_usage_of_code
boolean

Whether total uses across all customers are capped at customer_usage_limit.

limit_usage_per_customer
boolean

Whether each email address can use the code only once.

other_shipping_discounts
boolean

Whether this code can share a cart with free_shipping discounts.

other_product_discounts
boolean

Whether this code can share a cart with product discounts (every type except free_shipping).

created_at
string<date-time>

When the discount was created.

updated_at
string<date-time>

When the discount was last changed.

meta
object