Create promotions and issue gift cards

Discounts holds the store's promotions and gift cards. A promotion is a code that shoppers enter at checkout, or an automatic promotion that the cart applies by itself when its conditions are met. A gift card holds an amount in one currency and pays for orders until it is spent.

• Only owners and admins see Promotions, because a code can be a secret you hand out privately. Owners and admins also issue and change gift cards.
• Tier 1 support and above can look up gift cards and their history. A note at the top of the section says so when you cannot change them.
• A fixed amount, a minimum spend and a gift card are each in one of the store's currencies. Choose the currencies under Store in Settings.

1. In the dashboard, open the organization, then Commerce, then Marketing, then Discounts.
2. Under Promotions, select New promotion….
3. Under How shoppers get it, choose A code or Automatic. You cannot change this later.
4. For a code, enter the Code, such as SUMMER25. It takes letters, digits, - and _, up to 64 characters, and shoppers can type it in any case.
5. Optionally, enter a Description. Shoppers see it beside the discount on the cart and the order. Without one, they see what it takes off.
6. Choose the Discount:
   • Percentage: enter the Percentage off, above 0 and up to 100. Choose a Currency to offer it only to carts in that currency, or keep Any currency.
   • Fixed amount: enter the Amount off, such as 25.00, and its Currency. Only carts in that currency get it.
   • Free shipping: the shipping costs nothing.
   • Buy X get Y: under Customer buys, enter how many units the customer pays full price for, and under Customer gets, how many more of the same item get the discount, each from 1 to 99. Then choose the Discount on the units the customer gets: Free (100%), Half price (50%) or Another percentage, which asks for the Percentage off. Customer buys 1 and Customer gets 1 with Free (100%) is buy one, get one free. It takes off matching items only, so every item matches unless you choose products, variants, collections or categories. See How Buy X get Y works.
   • Free gift: search for the product under Gift, choose the variant, and enter the Units of the gift, from 1 to 10. While the conditions are met, the cart holds a line of it that costs nothing. See How a free gift works.
7. For a percentage or a fixed amount, choose what it Takes it off: The order, Matching items or Shipping.
8. Optionally, set the conditions and limits that Set conditions and limits describes. Under Conditions, you can also tick Discount shipping too or Free shipping too to take shipping off too.
9. Leave Turn it on now ticked, or untick it to save a draft that no cart can use until you turn it on.
10. Select Create promotion.

The promotion applies only when every condition you set is met.

Minimum spend

What the cart's items come to before discounts, such as 60.00. It needs the promotion's Currency.

Units of one item

From 2 to 999. The cart must hold this many units of one matching variant, such as 3 of the same shirt in the same size.

Minimum spend after discounts

The same as Minimum spend, less what the other promotions on the cart take off its items. Gift lines and gift cards do not count toward it. Use it for a free gift over an amount, so that a discount code does not bring the cart under the amount and still keep the gift.

First order only

Only for a shopper with no earlier order, by account or email. A cancelled order does not count.

Customer groups

Only signed-in shoppers in a ticked group get it. Tick none for everyone. It shows when the store has customer groups, which are made through the API.

Email addresses

Only a cart with one of these emails gets it, whether the shopper is signed in or a guest. Enter up to 500, one per line. A * stands for any characters, so *@example.org matches every address at that domain. Leave it empty for everyone.

Collections and Categories

The cart must hold an item from a ticked collection, or an item placed in a ticked category itself. A product in a category below the one you tick does not match. They show when the store has collections or categories.

Products and Variants

Search by title or SKU and add each product, or each variant for one size or colour only. The cart must hold one of the products, variants, collections or categories you chose. With Matching items, the promotion takes its discount off only those items, so choose at least one.

Leave out lines by metadata

A metadata key and a value, such as preorder and true. A cart line whose metadata has that key set to that value gets nothing from the promotion and counts toward none of its conditions, even for a promotion on the whole order. true, false and numbers match those values; anything else matches as text.

Needs these promotions

It applies only when every promotion listed here applies to the cart too, such as a code that works only with the free shipping promotion.

Uses in total and Uses per shopper

How many orders can use it, and how many times each shopper can, counted by account or email. Leave them empty for no limit.

Starts and Ends

The dates and times it runs, in your time zone. Without a start, it runs as soon as it is turned on. Without an end, it runs until you turn it off.

Combines with other promotions

Unticked, it applies only on its own: the cart refuses a second code beside it, and an automatic one steps aside when anything else applies.

Other codes beside it

Shows once Combines with other promotions is ticked. From 0 to 4: while it applies, at most this many other codes apply beside it. Automatic promotions do not count. A shopper who enters one code too many is told how many it combines with.

Codes apply in the order the shopper entered them, then automatic promotions from the oldest. A promotion with Minimum spend after discounts or Needs these promotions is decided after all the others, against what they give, and applies after them. Each takes its discount off what the earlier ones left. A cart holds up to 5 codes, and a store runs up to 50 automatic promotions at once.

Takes it off picks one target, so one promotion cannot take a percentage off the order and also take shipping off. Two checkboxes under Conditions, below First order only, do both, such as 20% off plus free shipping in one code.

Discount shipping too

Takes the same percentage off shipping as the promotion takes off the order. It shows for a Percentage discount that takes off The order. The hint reads "Takes the same percentage off shipping."

Free shipping too

Makes the shipping that is left cost nothing. It shows for every discount except Free shipping, and not while the promotion takes off Shipping. The hint reads "Shipping costs nothing when this promotion applies."

Ticking one unticks the other. Choosing a discount or a Takes it off setting that does not allow a ticked option unticks it too. The list marks a promotion with an option as Shipping discounted too or Free shipping too.

A promotion with either option still applies on its own terms: it needs its conditions, its dates and its limits. One that takes off Matching items and finds no matching item in the cart does not apply, so it takes nothing off shipping either. A Buy X get Y promotion applies to a cart that holds a matching item, even before a line holds a full group, so with Free shipping too shipping costs nothing from the first matching item. A cart with nothing to ship, or with no shipping method chosen yet, has no shipping to take off.

Without a Description, the cart and the order say, for example, "20% off and free shipping" or "20% off, shipping included".

Choose Percentage, enter 99 under Percentage off, choose The order under Takes it off and tick Discount shipping too. A cart holds $50.00 of items and a shipping method that costs $12.00. The code takes $49.50 off the items and $11.88 off shipping, so the shopper pays $0.50 for the items and $0.12 for shipping, plus any tax.

Choose Percentage, enter 20, choose The order and tick Free shipping too. A cart holds $80.00 of items and a $12.00 shipping method. The code takes $16.00 off the items, and shipping costs $0.00, so the shopper pays $64.00, plus any tax.

Each promotion takes its discount off what the ones before it left, in the order that Set conditions and limits describes. Both options work on the shipping that is left after the shipping promotions that applied before them.

Say a shopper enters a code that takes 50% off Shipping, and then a second code. Both need Combines with other promotions. The first code leaves $6.00 of a $12.00 shipping method.

• With Discount shipping too at 20%, the second code takes 20% of the $6.00, which is $1.20, and shipping costs $4.80.
• With Free shipping too, the second code takes the $6.00, and shipping costs $0.00.

A shipping promotion that applies after one of these finds only what is left. When the cart has more than one shipping method, a percentage is shared between them by their prices.

If you built this before with a second promotion that Needs these promotions, tick Free shipping too on the first promotion and turn the second one off.

• A code minted from a template has the same options.
• An order counts as one use of the promotion, however much the promotion took off it. Uses in total and Uses per shopper count that one use. The amount that the promotion gave includes what it took off shipping.
• The cart shows the discount on each shipping method as its discount_total, and the sum of them as totals.shipping_discount_total. The order keeps each method's discount_total, and the order's own discount_total adds the shipping discount to the items' discounts.
• The invoice lists the shipping line with its price, its discount and what the shopper paid. A refund of shipping is limited to what the shopper paid for it after the discount.

Each cart line counts on its own. A line holds units of one variant, so each size or colour is a line of its own, and units on different lines do not add up. The same variant with different line metadata is a line of its own too, as Fill a cart describes.

On each matching line, the units count in groups of Customer buys plus Customer gets. In each whole group, the customer pays full price for the Customer buys units and the discount takes the Customer gets units. Units left over after the last whole group pay full price.

With Customer buys 1, Customer gets 1 and Free (100%), on a shirt at €20.00:

Two shirts come with one free, and so do three, because the third shirt starts the next pair. With Customer buys 2 and Customer gets 1, a line of 7 units holds two whole groups of three, so two units are free and five pay full price. With Half price (50%), the units the discount takes cost half instead: three shirts cost €50.00. The cart rounds a discount that comes to part of a cent to the nearest cent, and half a cent up.

Under How it counts, the form works out these figures for the promotion you are writing, with what each line saves, for 1 to 4 units. When Customer buys plus Customer gets comes to more than 4, it shows lines of one and of two whole groups instead, each after a line one unit shorter. It prices them with the first variant under Variants, or else the first variant of the first product under Products, and names that variant under the table. It uses the promotion's Currency, or the store's default currency for Any currency, and the variant's prices outside any region, so a region price or a price list does not show in it. With no product or variant chosen, or when the variant has no price in that currency, it uses an example price of 20 a unit, such as €20.00.

While a Free gift promotion applies, the cart holds a line of the gift, marked as a gift. The promotion takes that line's whole price off, so the gift costs nothing and is taxed on nothing, and it ships and is fulfilled like any other item. The order keeps the line, and the API marks it as a gift there too.

• The cart adds the line when the conditions are met, and removes it when they stop being met, such as when the shopper removes an item.
• The shopper cannot change the number of units or remove the line. If the shopper adds the same item, it is a line of its own, at its usual price.
• A gift that cannot be sold now is left out, and the cart still checks out. That is a gift that is not published, not in the cart's sales channel, has no price in the cart's currency or is out of stock.
• A gift line never counts toward any promotion's minimum spend, quantity or matching items, and no other promotion takes anything off it.

Mint a code for one shopper, such as an apology after a late delivery. The code copies a promotion, as its template: its discount, its conditions, whether it combines, and its description. The conditions include Discount shipping too and Free shipping too.

1. In the menu on the template's row, select Mint code….
2. Enter the email For the email. Only a cart with that email can use the code.
3. Enter how many hours it Works for, from 1 to 8,760. It is 48 unless you change it.
4. Optionally, enter what the code Starts with. Without it, the code starts with the template's code, or CODE for an automatic template. Eight random characters follow, such as SORRY-7QK3M9TX.
5. Select Mint code, then copy the Code and send it to the shopper yourself. The store does not email it.

A minted code works once, for that email, from now until it ends, and it is turned on at once. A minted code cannot be a template itself. Changing the template later does not change the codes minted from it.

The list shows each promotion's Status, its Discount with its conditions (Shipping discounted too and Free shipping too among them), how often it was Used and when it Runs. Filter it with All, Active, Drafts and Turned off, or search by the start of a code or by words in the description. Minted codes are hidden unless you set the Codes filter to Minted only or All codes; a minted code is marked Minted and names the email it is for.

Each action is in the menu on the promotion's row.

Edit promotion…

Change anything except how shoppers get it, then select Save promotion. Selecting the row opens it too. Orders already placed keep the discount they got, and the change applies to carts from then on.

Turn off…

Select Turn off promotion to confirm. Shoppers who enter the code are told that it is not active, and an automatic promotion stops applying. Orders that have it keep their discount. Turn on turns it back on.

Delete promotion…

Only a promotion that no order used can be deleted. Type its code, or delete for an automatic promotion, then select Delete promotion. Its code becomes free for a new promotion. Once an order has used a promotion, turn it off instead.

1. Under Gift cards, select Issue gift card….
2. Enter the Amount, such as 25.00, and choose the Currency. The card pays only for carts in that currency.
3. Optionally, enter the Recipient's name and Recipient's email, who it is From, and a Message. The email lets you find the card later.
4. Optionally, choose the day it Expires on. The card works to the end of that day, in your time zone. Leave it empty for a card that never expires.
5. Select Issue gift card.
6. Under Save the code now, copy the Code, then select I have saved it.

While the store is in test mode, the card you issue is a test card: it pays for test orders only. A gift card sold on the storefront is emailed to the recipient the order names, and it is listed here as Sold in an order.

1. Under Gift cards, choose All, Active, Used up, Expired or Turned off.
2. Search by the recipient's email, the full code, or its last four characters.
3. Select a card to open its page.

Under Details, the page shows the card's Balance and when it Expires, the Recipient, who it is From, the customer it is Held by, and how it was Issued. History lists each time the balance moved, newest first, such as Spent on an order or Adjusted by the store, with any note your team left. A move on an order links to it. All gift cards goes back to the list with the filters you left it with.

Owners and admins find these actions in the menu on the card's row, and at the top of the card's page: Adjust balance… and Edit card…, with Turn off… or Turn on in the menu beside them.

Adjust balance…

Choose Add or Take away, enter the amount, and optionally a Note, such as a goodwill credit for a late delivery. Only your team sees the note. Select Save balance. The balance cannot go below zero, and a used-up card that you add to can pay for orders again.

Edit card…

Change the Recipient's name, the Recipient's email or the day it Expires on, then select Save card. To bring back an expired card, choose a later day. A day in the past is refused: to stop a card now, turn it off.

Turn off…

Select Turn off card to confirm. The card cannot pay for anything until it is turned on again, and its balance stays on it. Turn on needs a balance above zero, so add to the balance first.

• A promotion that is turned on applies to carts from its start, and its Used count grows with each order.
• A gift card pays for carts in its currency while it is active, unexpired and has a balance. A test card pays only for test orders, and a live card only for live ones.

Promotions is missing

Only owners and admins see it. The note at the top of the section names your role.

The dialog says another promotion has this code

Codes are unique across the organization, whatever their case. Choose another code, or delete the other promotion if no order used it.

A new automatic promotion cannot be turned on

The store already runs 50 automatic promotions. Turn one off first.

Delete promotion… cannot be selected

Orders used the promotion, so it can only be turned off.

A shopper's code is refused

The Store API gives the reason, such as that the promotion has ended, that the cart does not reach its minimum, that the code is for other email addresses, or that it combines with fewer codes. Check the promotion's Status, its dates, its Currency and its conditions.

Discount shipping too is missing

It shows only for a Percentage discount that takes off The order.

Free shipping too is missing

A Free shipping discount and a promotion that takes off Shipping already take shipping off, so neither shows it.

A promotion with a shipping option takes nothing off shipping

The cart needs a shipping address and a chosen shipping method. The promotion must apply too, and an earlier shipping promotion may have taken all of the shipping already, because both options take only what is left.

A free gift is not in the cart

The gift cannot be sold now, or the cart no longer meets the conditions. Check that the gift's product is published, in the cart's sales channel, has a price in the cart's currency and is in stock.

A Buy X get Y promotion takes nothing off two different sizes

Each size or colour is a cart line of its own, and each line counts on its own. A line gets the discount once it holds Customer buys plus Customer gets units of one variant. See How Buy X get Y works.

A minted code does not appear in the list

Minted codes are hidden by default. Set the Codes filter to Minted only.

Turn on cannot be selected on a gift card

The card's balance is zero. Add to it with Adjust balance… first.

A gift card's code is lost

The store cannot show it again. Turn the card off, then issue a new card for its balance.

• Manage your store's customers
• Add and edit your store's products
• Change your store's settings

Promotions are under https://api.coritan.com/api/v1/orgs/{org_slug}/commerce/promotions and gift cards under /commerce/gift-cards. The API also makes the customer groups and collections that conditions point at, and gift card products the storefront can sell. Offer promotions and gift cards has the details.

To take shipping off too, set include_shipping or free_shipping to true in the promotion's conditions:

curl -X POST "https://api.coritan.com/api/v1/orgs/acme/commerce/promotions" \
  -H "X-API-Key: $ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "SHIP99", "status": "active", "value_type": "percentage", "percentage": 99, "target": "order", "conditions": {"include_shipping": true}}'

• include_shipping is for a percentage promotion whose target is order. It takes the same percentage off the shipping that is left.
• free_shipping is for a percentage, fixed, buy_x_get_y or free_gift promotion whose target is order or items. The shipping that is left costs nothing.
• We store each only when it is true. Setting both to true answers 422 with field set to conditions.free_shipping. Setting include_shipping anywhere else answers 422 with field set to conditions.include_shipping, and free_shipping on a free_shipping promotion or a shipping target answers 422 with field set to conditions.free_shipping.
• The shipping discount shows on the cart and the order as each shipping method's discount_total.

curl "https://api.coritan.com/api/v1/orgs/acme/commerce/gift-cards?q=luka@example.com" \
  -H "Authorization: Bearer $CORITAN_TOKEN"