Skip to navigation
RESTAdminManagementPromotionsCoupon Codes Bulk

Import Coupon Codes

Uploads a CSV file of coupon codes to import into a bulk coupon promotion.

The request validates the whole file before it creates any codes. If the file passes, the import is queued, the codes are created in the background, and the response returns the task that tracks the import. To follow its progress, poll Get Latest Promotion Task.

CSV format

The first line must be this header: code,max_uses,max_uses_per_customer,valid_from,valid_until. Every row after it must have all five columns. Blank lines are skipped.

ColumnRequiredDescription
codeYesThe coupon code. 1 to 50 characters, using only letters, numbers, spaces, underscores, and hyphens. Cannot be 0.
max_usesNoThe maximum number of times the code can be used, as a whole number from 0 to 2147483647. 0 means unlimited. When blank, the code uses the promotion’s max_uses, or 0 if the promotion has none.
max_uses_per_customerNoThe maximum number of times one customer can use the code, as a whole number from 0 to 2147483647. 0 means unlimited. When blank, the value is 0.
valid_fromNoThe start of the code’s redemption window, as an RFC 3339 date-time with a time zone, for example 2026-08-12T04:00:00+00:00. Required when valid_until is set. When valid_from and valid_until are both blank, the code follows the promotion’s schedule.
valid_untilNoThe end of the code’s redemption window, as an RFC 3339 date-time. Must be after valid_from. Required when valid_from is set and the promotion has an end date.

A custom redemption window must fall within the promotion’s start and end dates. Dates must be after 1970-01-01T00:00:00+00:00 and no later than 2038-01-19T03:14:07+00:00.

How rows are imported

  • If any row is invalid, the request returns a 422 that lists the invalid rows, and no codes are created. At most 20 rows are reported. errors_truncated is true when more rows are invalid.
  • A code that already exists in the store, or that appears earlier in the same file, is skipped and reported in the task’s failure_details. Codes are compared case-insensitively.

Notes

  • Only bulk coupon promotions (coupon_type of BULK) accept imported codes.
  • Send the file as multipart/form-data in the importfile field. The file name must end in .csv.
  • The whole request body, including multipart encoding, must be no larger than 20 MB (20,971,520 bytes).
  • A store can run one import at a time. While an import is queued or processing, another upload returns a 429 before its contents are validated. An import that is still queued or processing more than 24 hours after it was created is treated as abandoned, and a new upload can start.
  • Uploading the same file as the store’s latest import returns a 422, unless that import failed or was abandoned. Files are compared by content, so this applies even when the promotion differs.
  • The default rate limit for this endpoint is 3 concurrent requests.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI NamePermissionParameter
Marketingmodifystore_v2_marketing
Marketingread-onlystore_v2_marketing_read_only

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access_tokens, see API Accounts and OAuth Scopes.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see API Accounts and OAuth Scopes.

For a list of API status codes, see API Status Codes.

Path parameters

promotion_idstringRequired
The ID of the associated promotion.
store_hashstringRequired
Permanent ID of the BigCommerce store.

Headers

AcceptstringRequiredDefaults to application/json

The MIME type of the response body.

Request

This endpoint expects a multipart form containing a file.
importfilefileRequired

The .csv file of coupon codes to import.

Response

The promotion task.

Coupon code import tasks

  • completed means the import created at least one code. It may not have processed every row. If the import stopped early, for example because the promotion was archived, codes_created plus codes_failed is less than codes_total.
  • failed means the import created no codes. failure_reason explains why.
  • An import that is still queued or processing more than 24 hours after it was created is treated as abandoned. Its status does not change, but a new import can start, including one with the same file.
dataobjectOptional

A long-running operation performed on a promotion, such as a coupon code import.

metaobjectOptional
Empty meta object, which may be used at a later time.

Errors

404
Not Found Error
413
Content Too Large Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error