Guide · Gift certificate import
Gift certificates
Move a store's outstanding gift certificates without emailing anybody and without handing money back. This is the only import here that carries a live balance, so one column decides whether it is safe.
Commands
| Command | Description | Behaviour |
|---|---|---|
| MERGE | Create or update. | The default. Updates the certificate if the code exists, issues it otherwise. |
| NEW | Issue a new certificate. | Fails if one with that code already exists. |
| UPDATE | Update an existing certificate. | Fails if there is none — it never issues one. |
| DELETE | Delete a certificate. | 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. | Fails the row. Re-creating a certificate issues a new code — voiding whatever the customer is holding — and resets the balance, handing back money already spent. Use UPDATE. |
Columns
| Column | Notes |
|---|---|
Code | The redemption code the customer types. Unique, and at most 20 characters — see below. |
Gift Certificate ID | Exact, and preferred when both are given. |
To Name, To Email | The recipient. Both required on a create. |
From Name, From Email | Who bought it. Both required on a create. |
Amount | What the certificate was issued for. Required on a create. |
Balance | What is left to spend. Required on a create by this importer — see the warning above. |
Status | active, pending, expired or disabled. |
Currency Code | Three-letter ISO 4217. The currency must already exist on the store, and the certificate is only spendable when the cart transacts in it. |
Customer ID | Ties the certificate to a customer account. |
Message | The note that would appear in the email, e.g. "Congratulations". |
Template | The email theme: birthday.html, boy.html, girl.html, celebration.html, christmas.html, general.html. Friendly spellings like birthday are accepted. |
Expiry Date, Purchase Date | Any date this app can read — see below. |
Order ID | Written by the export for information. BigCommerce sets it for a storefront purchase and it is read-only, so the importer ignores this column. |
A minimal file
Command,Code,To Name,To Email,From Name,From Email,Amount,Balance,Status
MERGE,GIFT-A1B2C3,Ana,ana@example.com,Ben,ben@example.com,100,100,active
MERGE,GIFT-D4E5F6,Cara,cara@example.com,Ben,ben@example.com,50,17.50,activeThe second row is a certificate that has already been spent down to £17.50. Stating that is the whole point of the column.
The code is trimmed silently, so a long one is refused
Dates: two formats for one field
Export
An export writes one row per certificate, in the columns the importer reads.
Two things it always writes, both for the same reason — a file that omits either is dangerous rather than merely incomplete:
Balance, because a blank one means BigCommerce restores the full amount.Code, because BigCommerce generates one when a create omits it. A file without codes would issue a whole new set of certificates instead of updating the existing ones, and the export warns if any certificate in the store has no code to write.
The export also counts how many certificates have been partly redeemed and says so, so it is obvious that the Balance column in that file is load-bearing.
One thing the importer deliberately never does: the code is not re-sent on an update. It is the certificate's identity, so changing it would void whatever the customer is holding — an UPDATE row uses the code to find the certificate and then leaves that field alone.