Guide · Coupon import

Coupons

Load discount codes into a BigCommerce store from a spreadsheet. Coupons are the one entity here where a partial update does not merge cleanly, so there is a rule worth knowing before you edit an existing coupon.

Commands

Command	Description	Behaviour
MERGE	Create or update.	The default. Updates the coupon if the code exists, creates it otherwise.
NEW	Create a new coupon.	Fails if a coupon with that code or name already exists.
UPDATE	Update an existing coupon.	Fails if there is none — it never creates.
DELETE	Delete a coupon.	Fails if there is none, rather than reporting a success.
IGNORE	Skip this row.	Does nothing, and is recorded as skipped rather than as a success.
REPLACE	Refused for coupons.	Fails the row. Re-creating a coupon gives it a new id and resets its redemption count, losing the record of how often it had been used. Use UPDATE.

Columns

Column	Notes
`Code`	The code a customer types. Unique on BigCommerce, up to 50 characters, letters, numbers, spaces, hyphens and underscores.
`Name`	The coupon's name in the control panel. Also unique, so either it or the code identifies exactly one coupon.
`Coupon ID`	Exact, and preferred when several identifiers are given.
`Type`	One of five values — see below.
`Amount`	What the discount is worth. Its meaning depends on the type: a percentage for `percentage_discount`, a currency amount otherwise.
`Applies To Entity`	`categories` or `products`. Defaults to `categories` when the column is absent but `Applies To IDs` is filled.
`Applies To IDs`	The ids it applies to, separated by `;` or `,`. `0` means everything in that entity.
`Min Purchase`	Minimum cart value before the coupon applies.
`Expires`	Any date this app can read — see below.
`Enabled`	`true` or `false`.
`Max Uses`, `Max Uses Per Customer`	Redemption limits.
`Restricted To Countries`	Country codes the coupon is limited to.
`Shipping Methods`	Shipping methods the coupon applies to, separated by `;`.
`Num Uses`	Written by the export for information. BigCommerce maintains it and refuses to be told it, so the importer ignores this column.

The five types

Type	What it does
`percentage_discount`	Takes a percentage off. `Amount` is the percentage.
`per_total_discount`	Takes a fixed amount off the cart total.
`per_item_discount`	Takes a fixed amount off each matching item.
`shipping_discount`	Discounts shipping by `Amount`.
`free_shipping`	Makes shipping free.

Friendly spellings are accepted — Percentage Discount, percent, Free Shipping, per-item all resolve — and anything that cannot be resolved fails the row before the API call, naming the five valid values. BigCommerce's own error for a bad type is not specific enough to act on.

A minimal file

Command,Code,Name,Type,Amount,Applies To Entity,Applies To IDs
MERGE,SUMMER20,Summer sale,percentage_discount,20,categories,23;24
MERGE,FREESHIP,Free shipping,free_shipping,0,categories,0

A create must carry Code, Name, Type, Amount and Applies To IDs: BigCommerce requires all five, and its error names none of them usefully, so a row missing one fails first with the columns listed.

Expiry dates

Codes and names are unique

BigCommerce refuses a second coupon with the same code, and a second with the same name. That has three useful consequences:

A lookup by code or by name can never be ambiguous, unlike a product name or a blog post title. So a row can update or delete by code with no Coupon ID.
NEW on a code that already exists fails, and says to use MERGE or UPDATE.
If two workers on one file — or you in one tab and the BigCommerce admin in another — try to create the same code at once, one of them loses. A MERGE row that loses that race is turned into the update it would have done anyway, rather than failing.

Export

An export writes one row per coupon, in the columns the importer reads, so it can be edited in a spreadsheet and imported straight back.

Two details are handled on the way out:

Amount is trimmed. BigCommerce answers "20.0000" for twenty percent. Written out unchanged, a round trip would rewrite your 20 as 20.0000 — accepted, but not the number you typed. Trimming never rounds: 12.5000 stays 12.5.
Expired coupons are exported as they are, and the export tells you how many there were. Re-importing the file will not reactivate them, since their dates are still in the past.