--- title: "Bulk-create VoucherCodes" method: POST path: "/shop/voucher-codes/bulk" tags: ["VoucherCodes"] --- # Bulk-create VoucherCodes `POST /shop/voucher-codes/bulk` Imports an array of pre-existing voucher codes in a single request, creating each as a `VoucherCode` on the given site. This endpoint is intended for migrating voucher codes from a third-party system into Trybe — each code must be alphanumeric and unique within the organisation. Every code in the batch is validated before any are written. If validation fails the entire request is rejected with a `422` and a per-field error map so you can correct and re-submit without wondering which records were written. On success, all created `VoucherCode` objects are returned in the same order as the request array. The endpoint also creates an internal `Import` record that can be cross-referenced with the Trybe dashboard's import history. Required permission: `settings:manage`. ## Query parameters - `site_id` string, required ## Request body - BulkCreateVoucherCodesRequest — Request body for `actionBulkCreateVoucherCodes`. - `vouchers` BulkCreateVoucherCodeItem[], required — The voucher codes to import. Must contain at least one item. - `code` string, required — The redemption code. Must be alphanumeric, distinct within this request, and unique within the organisation. - `amount` number, float, required — The face value of the voucher as a decimal number (e.g. `50.00` for £50). Minimum `0.01`. - `balance` number, float — The current remaining balance as a decimal number. Must be between `0` and `amount`. Defaults to `amount` when omitted. - `voucher_type_id` string, object-id, required — The ID of the `VoucherType` to associate the voucher code with. - `valid_until` string, date, nullable — The expiry date for the voucher in `Y-m-d` format. Omit to create a voucher with no expiry. - `revenue_amount` number, float, nullable — Optional revenue value override in decimal form. When provided this is used for revenue reporting instead of `amount`. ## Response `200` All voucher codes were successfully created. - object - `data` VoucherCode[], required - `id` string, object-id, required — The ID of the voucher code. - `code` string, required — The redemption code itself. Display this to the customer or recipient — they will quote it back to redeem against an order. - `status` 'unredeemed' | 'partially_redeemed' | 'redeemed' | 'revoked' | 'expired', required — The lifecycle state of the voucher. `unredeemed` is the starting state; vouchers transition to `partially_redeemed`, `redeemed`, `expired`, or `revoked` over their life. - `valid_from_date` string, date-time, required — The first date on which the voucher can be redeemed. - `valid_to_date` string, date-time, nullable, required — The last date on which the voucher can be redeemed. Updating this date past today on an `expired` voucher will move it back to `unredeemed` (or `partially_redeemed` if it has prior redemptions). - `amount_type` 'cash' | 'discount_to_zero', required — Whether the voucher represents a fixed `cash` value or discounts the order it is redeemed against to zero (`discount_to_zero`). - `amount` integer, required — The face value of the voucher, in the smallest unit of the voucher's currency (e.g. pence for GBP). - `balance` integer, required — The remaining balance of the voucher, in the smallest unit of the voucher's currency. `discount_to_zero` vouchers report their balance as zero once redeemed. - `currency` string, required — The ISO-4217 currency code. - `value` integer, required — Alias of `amount`, retained for backwards compatibility with older clients. - `partially_redeemable` boolean, required — Whether the voucher can be redeemed across multiple transactions. `discount_to_zero` vouchers are never partially redeemable. - `uses_total` integer, nullable, required — For multi-use `discount_to_zero` codes only: the total number of redemptions the code allows. `null` when the parent `VoucherType` has `quantity` of `null` or `1`, and for all `cash` vouchers. - `uses_remaining` integer, nullable, required — For multi-use `discount_to_zero` codes only: how many redemptions are still available. Decrements by 1 each time the code is successfully redeemed; restored by 1 if a redemption is refunded. `null` when the parent `VoucherType` has `quantity` of `null` or `1`, and for all `cash` vouchers. - `imported` boolean, required — Whether this voucher was imported from a previous system rather than issued through Trybe. - `fulfillment_status` string, nullable, required — Tracks physical fulfilment for vouchers that need posting. Common values are `needs_dispatching`, `dispatched`, and `not_required` for digital deliveries. - `voucher_type` VoucherCodeVoucherTypeRef, required - `id` string, object-id, required — The ID of the `VoucherType` the voucher was issued against. - `name` string, required — The customer-facing name of the `VoucherType`. - `recipient` VoucherCodeRecipient, required — Recipient details captured at purchase time for gift vouchers. All fields are nullable — for self-purchase or digital vouchers the block may be entirely empty. - `name` string, nullable, required - `email` string, nullable, required - `custom_message` string, nullable, required — A free-form message the purchaser left for the recipient. - `address_line1` string, nullable, required - `address_line2` string, nullable, required - `city` string, nullable, required - `county` string, nullable, required - `country` string, nullable, required - `postcode` string, nullable, required - `delivery` VoucherCodeDelivery, required — How and when the voucher should be delivered to the recipient. - `method` string, nullable, required — The delivery channel — typically `email`, `post`, or the special value `print_at_home` for self-service downloads. - `option` VoucherDeliveryOption - `id` string, uuid, required — The unique identifier for the voucher delivery option - `name` string, required — A name to identify this voucher delivery option - `description` string, nullable, required — A description of this voucher delivery option - `site_id` string, uuid, required — The site ID that this voucher delivery option belongs to - `archived` boolean, required — When 'true', only archived voucher delivery options will be returned - `price` number, required — The price of the voucher delivery option as an integer of the smallest unit eg pence. - `revenue_centre` string, nullable, required — Contains the revenue centre ID if this line is for revenue. - `date` string, date-time, nullable, required — The date the voucher should be delivered on. - `order` VoucherCodeOrderRef, required — The order the voucher was purchased on. - `id` string, object-id, nullable, required — The ID of the parent order. - `customer_id` string, object-id, nullable, required — The ID of the purchasing customer. - `order_ref` string, nullable, required — The human-readable reference of the parent order. - `item_cost` integer, nullable, required — The amount paid for the voucher itself (which may differ from the voucher's face value for promotional pricing) in the smallest unit of the order currency. - `submitted_at` string, date-time, nullable, required — When the parent order was submitted. - `redemptions` VoucherCodeRedemption[] — Per-redemption breakdown — present on the `getVoucherCode` response, omitted from list responses for performance. - `payment_id` string, object-id, required — The ID of the `Payment` that records this redemption. - `amount` integer, required — The amount redeemed against the voucher in this transaction, in the smallest unit of the voucher's currency. - `refunded_amount` integer, required — Of `amount`, the portion that was later refunded back to the voucher (restoring its balance). - `paid_at` string, date-time, nullable, required — When the redemption was applied. - `payable_id` string, object-id, required — The ID of the object the redemption was applied to. - `order_ref` string — If the redemption was against an order, the human-readable order reference. - `created_at` string, date-time, required — When then resource was created. - `issued_at` string, date-time, nullable, required — When the voucher was issued to the customer. Vouchers that have been purchased but not yet issued (e.g. scheduled for a future delivery date) will have `issued_at` set to `null`. ## Other responses - `401` — The user is unauthenticated - `403` — The authenticated user does not have permission. - `422` — The request didn't pass validation --- [API](https://skmtc.dev/try/apis/trybe-api.md) · [All operations](https://skmtc.dev/try/apis/trybe-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/try/trybe-api/revisions/f37f92702da5/schema)