Skip to main content

Send Closeout Offer

POST 

/api/v2/closeout/offer

Check that the offer can reach someone, then queue a closeout offer email to each selected customer, listing the selected products with units and prices. Emails go out in a background job, one per customer, to the customer's email (or billing email when the main one is missing or invalid). They use the store's editable Closeout offer email template (Settings → Email Templates); if that template is switched off, no email is sent. Customers without a valid address, or whose store has the template switched off, are skipped and listed in the response. Each sent offer is logged on the customer's activity history. Before anything is queued the request is refused with 422 when the selection matches no products with stock (on selection), when none of the customers can be emailed (on customer_ids, saying how many have no valid address and how many belong to stores with the template switched off), or when the linesheet is needed - attach_linesheet, or a template that links to it - but no Closeout linesheet PDF template exists (on attach_linesheet).

Required scope: products:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Body:

  • customer_ids (required, array of existing customer ids, 1–500). More than 500 is refused with 422: "One offer can go to at most 500 customers. Remove some, then send the rest as a second offer."
  • selection (optional, object): which products to offer, using the selection fields below (selection.product_ids, selection.lifecycle_states, and so on). Default: in-stock Discontinued products.
  • expires_on (optional, date Y-m-d, today or later): offer expiry shown in the email and linesheet.
  • attach_linesheet (optional, boolean, default true): attach the PDF linesheet (requires a Closeout linesheet PDF template).

Selection fields (all optional):

  • product_ids (array of integers, max 2000): explicit products. A matrix parent id brings in all its variants. When sent, the lifecycle_states, season_ids, brand_ids and search filters are ignored.
  • sell_through_query (object, optional): the query of a List Lifecycle Sell-through request - its filter[...], filter_groups and sort keys, flat ({"filter[lifecycle_status.is_one_of]": "stalled", "sort": "-stock_value"}) or nested. Used when product_ids is omitted: the selection becomes the rows that query returns, in its order, up to 2,000. When sent, the lifecycle_states, season_ids, brand_ids and search filters are ignored; in_stock_only and the price tiers still apply.
  • lifecycle_states (array of lifecycle state keys, each max 40 chars): used when product_ids and sell_through_query are omitted. Default: ["discontinued"].
  • season_ids (array of integers): only products in any of these seasons.
  • brand_ids (array of integers): only products of these brands.
  • search (string, max 255): partial match on SKU or name.
  • in_stock_only (boolean, default true): only products with available units across all warehouses.
  • wholesale_tier_id (integer, existing pricing tier id): the tier for the wholesale price column. Default: the unarchived tier named exactly "Wholesale" (any case), else the oldest unarchived tier whose name contains "wholesale" (e.g. "Wholesale EU").
  • msrp_tier_id (integer, existing pricing tier id): the tier for the MSRP column. Default: the default pricing tier.

Archived products, matrix parents and bundles are never included (they hold no stock). At most 2,000 products, ordered by SKU.

Response data: queued (true), tracked_job_log_id (the background job sending the emails; follow it with the tracked job endpoints - null when the request has no user), customer_count (customers the offer will be emailed to), skipped [{customer_id, customer_name, reason (no_email or template_off), message}] (customers who will not get it, and why).

Requires a Bearer token with the products read/write scope and the customers.send_communications permission.

Request​

Responses​

OK

Response Headers
    Content-Type