[POST] Create offer

* Authentication

Required Authorization Bearer •••••••••••

Limit throttle:30,1

Endpoint [POST] - /shop-api/pre-order/create

Headers

Header	Required	Description
Authorization	Yes	Shop public API key Bearer token
Content-Type	Yes	application/json

1. Request Payload

Required fields

Field	Type	Required	Description
offer_name	string	Yes	Offer name (max 255 characters)
start_date	date	Yes	Pre-order start date/time
apply_to	string	Yes	Target scope: product, collection, or all
products	array	apply_to = product	min:1 | max:50 item
products.*.product_id	number	with products	Shopify product ID
products.*.variant_id	number	with products	Shopify variant ID
products.*.limit	number | null	No	min:1
collection_id	number	apply_to = collection	Shopify collection ID

Optional fields

Field	Type	Default / Notes	Description
end_date	date | null	—	Must be after start_date if provided
countdown_before_preorder_start	boolean	false	Show countdown before start
countdown_before_preorder_end	boolean	false	Show countdown before end
preorder_condition_inventory	string	now	Inventory trigger: now, outofstock, instock
fulfillment_status	string	—	ON_HOLD, UNFULFILLMENT, SCHEDULED
fulfillment_shipping_date	date	—	Exact shipping/fulfillment date
fulfillment_after_checkout	number	—	Days after checkout (max 60)
turn_on_continue_selling_when_preorder_start	boolean	false	Auto-enable continue selling when offer starts
turn_off_continue_selling_when_preorder_end	boolean	false	Auto-disable continue selling when offer ends
full_payment_discount_type	string	percentage	percentage or fixed
full_payment_discount_value	number	0	Required with type; max 100 (percentage) or 1000000 (fixed); min 1 when sent
partial_payment_value	number	—	Deposit/partial amount; enables partial payment when > 0
partial_payment_type	string	—	Create validation field: percentage or fixed (see note below)
partial_payment_value_type	string	percentage	Used when mapping to selling plan / response shape
partial_payment_discount_type	string	percentage	percentage or fixed
partial_payment_discount_value	number	0	Discount on partial payment
partial_payment_remaining_balance_charge_date	date	—	Remaining balance charge date (exact time)

Important rules

1. apply_to

   • product → send products (1–50 items). Variants are validated against Shopify; only found variants are kept.

   • collection → send collection_id (must exist).

   • all → no products / collection_id.

2. Fulfillment timing is mutually exclusive:

   • If fulfillment_shipping_date is set → exact-date fulfillment.

   • Else if fulfillment_after_checkout is set → days-after-checkout fulfillment.

3. Partial payment is enabled when any partial-payment field is present and partial_payment_value > 0.

4. New offers are created with status = 1 (active). Product sync / selling-plan setup may run asynchronously (processing).

Field name note: Create validation currently uses partial_payment_type, while list/get/update and internal mapping use partial_payment_value_type. Prefer aligning with partial_payment_value_type for consistency with other endpoints.

Example — apply to products

{
    "status": 1, // 1 is active, 0 is draft
    "offer_name": "Summer Pre-order",
    "start_date": "2026-08-01 00:00:00",
    "end_date": "2026-09-30 23:59:59",
    "countdown_before_preorder_start": true,
    "countdown_before_preorder_end": false,
    "apply_to": "product",
    "products": [
        {"product_id": 7890123456789,"variant_id": 4567890123456,"limit": 100}
    ],
    "preorder_condition_inventory": "outofstock",
    "fulfillment_status": "ON_HOLD",
    "fulfillment_shipping_date": "2026-10-15",
    "turn_on_continue_selling_when_preorder_start": true,
    "turn_off_continue_selling_when_preorder_end": true,
    "full_payment_discount_type": "percentage",
    "full_payment_discount_value": 10,
    "partial_payment_value": 30,
    "partial_payment_value_type": "percentage",
    "partial_payment_discount_type": "percentage",
    "partial_payment_discount_value": 5,
    "partial_payment_remaining_balance_charge_date": "2026-10-01"
}

Example — apply to collection

{
    "offer_name": "Collection Pre-order",
    "start_date": "2026-08-01",
    "apply_to": "collection",
    "collection_id": 123456789,
    "preorder_condition_inventory": "now"
}

Example — apply to all products

{"offer_name": "Storewide Pre-order","start_date": "2026-08-01","apply_to": "all"}

2. Success Response 200

{
"success": true,
"message": "Pre-order offer created",
"data": 
    {
    "id": 123,
    "offer_name": "Summer Pre-order",
    "start_date": "2026-08-01 00:00:00",
    "end_date": "2026-09-30 23:59:59",
    "countdown_before_preorder_start": true,
    "countdown_before_preorder_end": false,
    "apply_to": "product",
    "preorder_condition_inventory": "outofstock",
    "fulfillment_status": "ON_HOLD",
    "fulfillment_shipping_date": "2026-10-15",
    "turn_on_continue_selling_when_preorder_start": true,
    "turn_off_continue_selling_when_preorder_end": true,
    "status": 1,
    "products": [
        {
            "product_id": 7890123456789,
            "variant_id": 4567890123456,
            "limit": 100
        }
    ],
    "full_payment_discount_type": "percentage",
    "full_payment_discount_value": 10,
    "partial_payment_value": 30,
    "partial_payment_value_type": "percentage",
    "partial_payment_discount_value": 5,
    "partial_payment_discount_type": "percentage",
    "partial_payment_remaining_balance_charge_date": "2026-10-01"
    }
}

---

3. Response Keys & Fields

Top-level

Key	Type	Description
success	boolean	true when the offer is created
message	string	"Pre-order offer created"
data	object	Created offer (same shape as Get Offer / List item)

data offer object

Field	Type	Description
id	integer	Newly created offer ID
offer_name	string	Offer name
start_date	string | null	Start datetime
end_date	string | null	End datetime; null if not set
countdown_before_preorder_start	boolean	Countdown before start
countdown_before_preorder_end	boolean	Countdown before end
apply_to	string	product | collection | all
preorder_condition_inventory	string	now | outofstock | instock
fulfillment_status	string | null	ON_HOLD | UNFULFILLMENT | SCHEDULED
fulfillment_shipping_date	string	Present when exact-date fulfillment is used
fulfillment_after_checkout	number	Present when days-after-checkout is used
turn_on_continue_selling_when_preorder_start	boolean	Auto continue-selling on start
turn_off_continue_selling_when_preorder_end	boolean	Auto turn-off continue-selling on end
status	integer	1 (active) for newly created offers
products	array	Only when apply_to = product
collection_id	integer	Only when apply_to = collection
collection_name	string	Collection title (when available)
full_payment_discount_type	string	Full payment discount type
full_payment_discount_value	number	Full payment discount value
partial_payment_*	mixed	Present when partial payment is enabled

products[] item

Field	Type	Description
product_id	integer	Shopify product ID
variant_id	integer	Shopify variant ID
limit	integer | null	Pre-order unit limit

4. Failed Response

Validation error — HTTP 200

{
    "success": false,
    "message": {
        "offer_name": ["The offer name field is required."],
        "apply_to": ["The selected apply to is invalid."],
        "end_date": ["The end date must be a date after start date."]
    }
}

Condition	Response
apply_to = product but products empty	{ "success": false, "message": "Products are required" }
No variants exist on Shopify	{ "success": false, "message": "Product variants not found" }
apply_to = collection but collection_id empty	{ "success": false, "message": "Collection is required" }
Collection not found on Shopify	{ "success": false, "message": "Collection not found" }

Unexpected server error — HTTP 200

{"success": false,"message": "Pre-order offer not created"}