Gift Cards

Opaque cursor from a previous products.list response. Omit for the first page; reset when search, filters, or sorting changes.

Page size from 1 to list_max_limit. Omit to use list_default_limit from Product limits. Values above the maximum are rejected.

Filter: active, scheduled, draft, or archived.

Filter: simple or variable.

Comma-separated product IDs, up to list_max_limit; returns only those products. Use it to fetch a known set in one call instead of one call per product. IDs that do not exist are left out.

Filter by assigned category ID.

Comma-separated category IDs; matches products in any listed category.

Filter by assigned vendor ID.

Comma-separated vendor IDs; matches any listed vendor.

Filter by assigned brand ID.

Comma-separated brand IDs; matches any listed brand.

Filter by assigned tag ID.

Comma-separated assigned tag IDs. Use tag_match to choose whether any or all IDs must match.

How tag_ids compose: any (default) or all.

Filter by manual or automatic collection membership.

Comma-separated collection UUIDs; matches membership in any listed collection.

Filter to products with inventory at this location.

Comma-separated location UUIDs; matches inventory at any listed location.

Return products at or below a configured low-stock threshold.

Minimum displayed available stock. Untracked products do not match.

Maximum displayed available stock. Untracked products do not match.

Minimum regular price in the store currency.

Maximum regular price in the store currency.

Search text; surrounding whitespace is removed. Text exceeding search_max_length is rejected.

Defaults to all: matches product titles, product/variant SKUs and barcodes, tags, and full-text matches in titles, descriptions, vendor names and brand names. Choose title, sku, barcode, vendor, brand, tag, or variant_sku to narrow the search. sku searches product SKUs; variant_sku searches variant SKUs. barcode searches both product and variant barcodes.

A value from sort_columns in Product limits. Defaults to created_at. Price sorts use the store currency; variable products sort by their minimum variant price. Equal values use ascending product ID as a tie-breaker; missing values sort last.

asc or desc; defaults to desc.

Bearer Store API token.

Bearer Store API token.

Product title. Required on create; cannot be empty on update. Normalized to NFC. Control characters are rejected. See title_max_length in GET /products/limits.

URL slug. Omit on create to generate it from the title. A source slug must use lowercase, hyphen-separated words and stay within slug_max_length. A duplicate source slug receives a suffix. On update, omit to keep it; changing it creates a redirect unless create_redirect is false.

Required on create: simple or variable. Cannot be changed after creation. Allowed values: simple, variable.

Product status: draft, active, scheduled, or archived. Defaults to draft. Scheduled products require publish_at. Active products are available only through their assigned sales channels. Allowed values: active, scheduled, draft, archived.

Publication time, required when the resulting status is scheduled. Accepts an ISO 8601 timestamp; include an offset for an explicit instant, or use the store timezone for a local timestamp. Stay within publish_max_days_ahead from GET /products/limits. Invalid local times during a daylight-saving change are rejected; a repeated local time uses its first occurrence. Changing to another status clears the schedule.

Rich HTML description. Unsafe HTML is removed. The sanitized HTML, including markup, must fit description_max_length.

Plain-text summary. Surrounding whitespace is removed and control characters are rejected. See short_description_max_length.

Vendor ID in this store. On create, omit if unassigned. On update, omit or send null to keep the assignment; send 0 to clear it.

Brand ID in this store. On create, omit if unassigned. On update, omit or send null to keep the assignment; send 0 to clear it.

Category IDs in this store, up to max_categories. Duplicates are removed. On update, replaces the assignment set; [] clears it and omission keeps it.

Tag IDs in this store, up to max_tags. Duplicates are removed. On update, replaces the assignment set; [] clears it and omission keeps it.

Sales-channel IDs in this store. Omission on create leaves the product unassigned. On update, replaces the assignment set; [] clears it and omission keeps it.

Attribute IDs that define the variant combinations. Required for variable products. Each variant must provide one value per declared attribute. On update, replaces the declaration, subject to the surviving variants and store limits. Variable products only.

Search-engine title. Whitespace is trimmed and control characters are rejected. See seo_title_max_length.

Search-engine description. Whitespace is trimmed and control characters are rejected. See seo_description_max_length.

Existing product template handle for this store. Use default_product for the default template. Omit on update to keep the assignment; an empty string is invalid.

Required product SKU, including for a variable parent. ASCII letters, digits, hyphens, underscores, periods, and slashes are accepted. Trimmed, case-sensitive, and unique across products, variants, and inventory groups in the store. Case-only matches produce warnings. See sku_max_length.

Optional Barcode/GTIN for a simple product; variable products use variant barcodes. ASCII letters, digits, and hyphens are accepted. Must be unique across products and variants. See barcode_max_length. Simple products only.

Merchandise condition. Defaults to new. Variants may override the parent condition. Allowed values: new, used, refurbished.

Optional manufacturer part number. Not required to be unique. See mpn_max_length.

Set true only if the product has no manufacturer identifiers. Cannot be true with a barcode or MPN. The response’s identifier_status is provided when identifiers exist, not_applicable when this flag is true, and unknown otherwise.

Defaults to false. When true, direct cart additions are rejected with CART_GIFT_ONLY; the product can be added only as an eligible free gift. This flag does not hide the product from listings.

Defaults to false. Excludes the product from storefront search and browse listings while keeping its assigned-channel product page accessible by direct link. Does not change gift_only or channel assignments.

Defaults to true and can be changed on update. Variants follow this value unless they set their own requires_shipping. While it is false, the product and every variant that follows it reject weight, dimensions, customs fields, and per-item shipping prices; values stored earlier are kept but not used.

Positive weight within the store’s limit. Requires weight_unit.

Weight unit; required with weight. Allowed values: kg, g, lb, oz.

Positive package length within the store’s limit.

Positive package width within the store’s limit.

Positive package height within the store’s limit.

Dimension unit; required when any dimension is supplied. Allowed values: cm, mm, m, in, ft.

Customs HS code. See hs_code_max_length and the field constraints in GET /products/limits.

Two-letter ISO country code.

Simple-product inventory mode: track for per-location stock, none for untracked stock, or group for an inventory-group link. Defaults to track. Changing modes on update may require confirmation. Allowed values: track, none, group. Simple products only.

Inventory-group UUID. Required with inventory_source=group. The group must belong to this store. Simple products only.

Optional per-order quantity cap, independent of inventory mode. On update, 0 clears the explicit cap; omission or null leaves it unchanged. Without an explicit cap, the store’s default order cap may still apply.

Overall low-stock threshold for directly tracked simple products. Uses total available stock across locations. Zero is valid. On update, null disables the alert and omission keeps it. Not available for untracked or group-backed stock. Simple products only.

Simple products only. Rows are {currency_code, regular_price, sale_price?, cost_price?, sale_starts_at?, sale_ends_at?}. Amounts are JSON decimal strings with the currency’s permitted precision. Include the base currency. On update, supplying this array replaces the complete price set. A sale price may be zero but must be below the regular price. The base-currency sale schedule applies to all currency sale prices; a non-base sale requires a base sale. Omit sale prices from the replacement set to remove them.

Simple products only. Per-currency flat shipping overrides: {currency_code, price}. Send price as an exact decimal string using that currency's precision.

Gallery entries: {file_id, alt_text?, sort_order?}. Files may be images, videos, or 3D models. Non-empty file_id values require read_files. On update, the array replaces the gallery; [] clears it. The store’s max_images limit applies.

Simple products with inventory_source=track. Rows are {location_id, quantity, low_stock_threshold?, expected_quantity?}. Quantities are non-negative integers within the store’s limits. On update, only named locations change. expected_quantity is the on-hand value previously read (0 for a missing row); a mismatch returns 409 PRODUCT_VERSION_STALE. You may use merchant-managed locations or locations owned by your app’s active installation.

Per-market tax assignment: {market_id, tax_class_id}. Supplied array replaces the full set.

Values as {definition_id, value}. Definitions must target products and permit your app to write them. On update, this array replaces the set your app can write; [] clears that set. Use the dedicated metafield endpoint for writes addressed by namespace and key.

Variable products only; required (at least one variant). The initial variant set, validated together: combination uniqueness against the declared attributes, attribute coverage, at least one variant, and store-wide SKU uniqueness. Each entry:

• sku (string, required) — unique across the entire store.
• attribute_values (array, required) — One entry per declared attribute: {attribute_id, option_id}, choosing one of that attribute's options. Attribute and option ids come from GET /attributes (the product's attribute_ids must cover every attribute_id used). Two variants can never share the same combination.
• prices (array, required) — per-currency rows {currency_code, regular_price, sale_price?, cost_price?, sale_starts_at?, sale_ends_at?}; the base currency row is required. Amounts are decimal strings.
• title (string, optional) — auto-composed from option labels ("Red / M") unless supplied.
• barcode is variant-specific. condition, mpn, and no_manufacturer_identifiers can override the parent’s values. identifier_status describes whether identifiers are provided, unknown, or not applicable; use the identifier fields and declaration consistently.
• weight, weight_unit, length, width, height, dimension_unit, hs_code, country_of_origin — physical overrides.
• requires_shipping (boolean or null, optional) — this variant's own shipping setting, for example a hardcover that ships beside a PDF that does not. Omit it or send null to follow the product. A variant that does not ship cannot have weight, dimensions, customs fields, or shipping_prices.
• inventory_source (track | none | group), inventory (per-location rows {location_id, quantity, low_stock_threshold?, expected_quantity?} when tracking), inventory_group_id (when group).
• image_file_id (string, optional) — Media-library upload UUID; non-empty values require read_files in addition to write_products. image_id selects an existing product gallery row and does not require read_files.
• max_order_quantity is an optional per-order cap; overall_low_stock_threshold applies only to directly tracked stock.

Create supplies the initial set here. Later edits use the delta fields on Product update; read operations use the paginated Variant endpoints.

Bearer Store API token.

Bearer Store API token.

Bearer Store API token.

Accept Gift Cards at checkout.

Apply automatic expiry to cards from paid orders.

Days until cards from paid orders expire.

Maximum Gift Cards accepted on one order.

Page number.

Page size.

Last four code characters, recipient name, or recipient email.

Lifecycle status.

Issuance source: manual or order.

ISO 4217 currency code.

Sort field from list_sort_columns in the limits response: code_last4, status, balance, initial_amount, currency_code, recipient_name, source, issued_at or expires_at. Defaults to issued_at. Without a currency_code filter, amount sorts group cards by currency first.

asc or desc. Defaults to desc.

Bearer Store API token.

Bearer Store API token.

ISO 4217 currency code: the store's base currency or another currency enabled in Settings > Currencies.

Initial value in the selected currency.

Merchant-visible issuance reason.

Recipient name.

Recipient email.

Validated international phone number including its calling code.

Message sent with the card.

Future delivery and activation time.

Future expiry time, later than scheduled_at when both are present.

Choose manual, email or phone from delivery_options. Manual does not send and cannot be scheduled. Email and phone require the corresponding recipient.

Links the card to an existing customer of this store. Requires the read_customers scope in addition to write_gift_cards.

Gift Card UUID.

Bearer Store API token.

Gift Card UUID.

History section: events, deliveries or movements.

The next_cursor of the previous page. Omit for the newest page.

Page size, 1 to 50.

Bearer Store API token.

Gift Card UUID.

Bearer Store API token.

Recipient name.

Recipient email.

Validated international phone number including its calling code.

Message sent with the card.

Future delivery and activation time.

Future expiry time, later than scheduled_at when both are present.

ID of a delivery eligible for retry. Does not issue another card.

Remove the delivery schedule.

Remove the expiry.

Gift Card UUID.

Bearer Store API token.

New status: active, disabled, or cancelled.

Merchant-visible reason recorded in the audit log.

Bearer Store API token.

Gift Card UUIDs, 1 to bulk_max_count, without duplicates.

New status: active or disabled.

Merchant-visible reason recorded in each card's audit log.