Funnels
Storefront Funnels API endpoints
Endpoints
- GET/checkout/{cart_id}/pre_purchase/fetch
- POST/checkout/{cart_id}/pre_purchase/refresh
- POST/checkout/{cart_id}/pre_purchase/{step_id}/accept
- POST/checkout/{cart_id}/pre_purchase/{step_id}/reject
- GET/checkout/{cart_id}/mid_purchase
- POST/checkout/{cart_id}/mid_purchase/refresh
- POST/checkout/{cart_id}/mid_purchase/{step_id}/accept
- POST/checkout/{cart_id}/mid_purchase/{step_id}/reject
Get the current pre purchase funnel step.
Path parameters
cart_idRequiredstringCart ID
ReturnsFunnelStep
Pre purchase current funnel step object response
curl https://api.subbly.co/storefront/v1/checkout/{cart_id}/pre_purchase/fetch \
-H 'X-API-KEY: <api-key>'Response
{
"step": {
"id": 1,
"initial": true,
"addon": true,
"addon_duration": 1,
"type": "funnel_pre_purchase",
"title": "title",
"description": "description",
"offer": {
"amount_off": 1.5,
"percent_off": 1.5,
"skip_answered_survey": true,
"type": "one_click",
"products": [
{
"id": 1,
"bundle_id": 1,
"bundle": {},
"bundle_ruleset_id": 1,
"bundle_ruleset": {},
"slug": "yellow-t-shirt-with-pokemon-print",
"type": "one_time",
"name": "Yellow T-shirt with pokemon print",
"description": "Yellow T-shirt with pokemon print",
"delivery_info": "Free shipping on orders over $100",
"collect_shipping_address": true,
"gifting_enabled": true,
"digital": false,
"images": [
{}
],
"metadata": [
{}
],
"created_at": "2022-04-01 00:00:00",
"updated_at": "2022-04-01 00:00:00",
"gift_card": false,
"gift_card_expiration": null,
"variants": [
{}
],
"options": [
{}
]
}
]
}
}
}Refresh the funnel progress.
Path parameters
cart_idRequiredstringCart ID
ReturnsFunnelStep
Pre purchase initial funnel step object response
curl -X POST https://api.subbly.co/storefront/v1/checkout/{cart_id}/pre_purchase/refresh \
-H 'X-API-KEY: <api-key>'Response
{
"step": {
"id": 1,
"initial": true,
"addon": true,
"addon_duration": 1,
"type": "funnel_pre_purchase",
"title": "title",
"description": "description",
"offer": {
"amount_off": 1.5,
"percent_off": 1.5,
"skip_answered_survey": true,
"type": "one_click",
"products": [
{
"id": 1,
"bundle_id": 1,
"bundle": {},
"bundle_ruleset_id": 1,
"bundle_ruleset": {},
"slug": "yellow-t-shirt-with-pokemon-print",
"type": "one_time",
"name": "Yellow T-shirt with pokemon print",
"description": "Yellow T-shirt with pokemon print",
"delivery_info": "Free shipping on orders over $100",
"collect_shipping_address": true,
"gifting_enabled": true,
"digital": false,
"images": [
{}
],
"metadata": [
{}
],
"created_at": "2022-04-01 00:00:00",
"updated_at": "2022-04-01 00:00:00",
"gift_card": false,
"gift_card_expiration": null,
"variants": [
{}
],
"options": [
{}
]
}
]
}
}
}Accept the pre purchase funnel step.
Path parameters
cart_idRequiredstringCart ID
step_idRequiredintegerStep ID
Request body
Accept funnel step
offersRequiredobject[]ReturnsCart
Pre purchase next funnel step object response
curl -X POST https://api.subbly.co/storefront/v1/checkout/{cart_id}/pre_purchase/{step_id}/accept \
-H 'X-API-KEY: <api-key>' \
-H 'Content-Type: application/json' \
-d '{
"offers": [
{
"product_id": 1.5,
"options": [
{
"question_id": 1,
"answers": [
{
"id": 1,
"content": "content",
"quantity": 1
}
]
}
]
}
]
}'Response
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"customer_id": 1,
"customer": {
"first_name": "John",
"last_name": "Smith",
"email": "test@test.com",
"marketing_consent": false,
"tos_consent": false,
"active_subscriptions_count": 0,
"external_id": "external_id",
"created_at": "2026-01-15T10:30:00Z"
},
"attached": true,
"shop_id": 1,
"coupon_code": "new-year-discount",
"coupon": {
"id": 1,
"coupon_id": "discount-100",
"name": "Discount for the New Year",
"amount_off": 100,
"percent_off": 20,
"duration": "once",
"duration_in_months": 2
},
"gift_card_code": "a290f1ee-6c54-4b01-90e6-d701748fc92",
"gift_card": {
"id": 1,
"code": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"amount": 100,
"balance": 20,
"message": "It's a gift for you",
"status": "redeemed"
},
"referral_id": 1,
"currency_code": "EUR",
"base_currency_code": "USD",
"shipping_method_id": 1,
"onboarding_template_id": 1,
"shipping_method": {
"id": 1,
"type": "shipping_option",
"method": {}
},
"shipping_carrier_id": 1,
"shipping_carrier": {
"id": 1,
"name": "DHL",
"service_codes": [
"STANDARD",
"EXPRESS"
]
},
"shipping_carrier_service": "STANDARD",
"shipping_address_id": 1,
"shipping_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"billing_address_id": 1,
"billing_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"payment_method_id": 1,
"payment_method": {
"id": 567,
"type": "card",
"identifier": "4242",
"card": {
"last_four": "4242",
"expiry_month": "2",
"expiry_year": "2099",
"type": "credit",
"brand": "visa"
},
"ideal": {
"bank": "ING",
"bic": "INGBNL2A",
"email": "test@subbly.co",
"name": "John Doe"
},
"bancontact": {
"email": "test@subbly.co",
"name": "John Doe"
},
"acss_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "Royal Bank of Canada",
"transit_number": "12345",
"institution_number": "123",
"last_four": "6789"
},
"us_bank_account": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "US Bank",
"last_four": "6789",
"routing_number": "123456789",
"account_type": "checking",
"account_holder_type": "individual"
},
"sepa_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"iban_last4": "6789",
"bank_code": "123456",
"country": "DE",
"branch_code": "12345"
},
"sofort": {
"email": "test@subbly.co",
"name": "John Doe",
"country": "DE"
},
"link": {
"email": "test@subbly.co",
"name": "John Doe"
},
"cashapp": {
"email": "test@subbly.co",
"name": "John Doe",
"buyer_id": "cashapp:123456789",
"cash_tag": "$subbly"
},
"created_at": "2022-04-01 00:00:00",
"updated_at": "2022-04-01 00:00:00"
},
"gift_info": {
"starts_at": "2022-04-01",
"number_of_orders": 1,
"message": "Happy Birthday",
"recipient_email": "recipient@example.com"
},
"starts_at": "2022-04-01",
"items": [
{
"id": "g290f1ee-6c54-4b01-90e6-d701748f0589",
"type": "one_time",
"status": "active",
"product": {},
"quantity": 2,
"description": "Yellow T-shirt with pokemon print",
"addon": false,
"addon_duration": 0,
"gift_card": {
"customer_email": "customer_email",
"customer_name": "customer_name",
"message": "message"
},
"bundle": {
"preferences": [
{}
],
"items": [
{}
]
},
"metadata": [
{}
],
"options": [
{
"question_id": 1,
"answers": [
"answers"
]
}
],
"amount_off": null,
"percent_off": null,
"created_at": "2022-04-01 00:00:00",
"updated_at": "2022-04-01 00:00:00"
}
],
"summary_items": [
{
"item_id": "g290f1ee-6c54-4b01-90e6-d701748f0589",
"type": "one_time",
"product_id": 8,
"quantity": 2,
"price": 799,
"total": 1458,
"sub_total": 1458,
"tax_amount": 160,
"tax_rate": 0.01,
"tax_inclusive": false,
"discount": 300,
"bundle": {},
"discounts": [
{}
],
"charge_now": true,
"subscription": {},
"created_at": "2022-04-01 00:00:00",
"updated_at": "2022-04-01 00:00:00"
}
],
"total": 1458,
"sub_total": 1558,
"discount_total": 300,
"tax_total": 16,
"tax_rate": 0.1,
"discounts": [
{
"type": "coupon",
"description": "Offer discount",
"total": 3,
"charge_now": true
}
],
"metadata": [
{
"id": 1,
"name": "Color",
"slug": "color-red",
"description": "description",
"unit": "kg",
"data_type": "single_line_string",
"preset": true,
"multiple": true,
"variant": true,
"save_behavior": "customer",
"editable": true,
"values": [
{}
]
}
],
"adjustment": 0,
"customs_fee": 0,
"future_customs_fee": 0,
"balance_change": {
"amount": 0,
"currency_code": "USD"
},
"status": "initialized",
"created_at": "2022-04-01 00:00:00",
"updated_at": "2022-04-01 00:00:00"
}Reject the pre purchase funnel step.
Path parameters
cart_idRequiredstringCart ID
step_idRequiredintegerStep ID
Returns
Pre purchase next funnel step object response
curl -X POST https://api.subbly.co/storefront/v1/checkout/{cart_id}/pre_purchase/{step_id}/reject \
-H 'X-API-KEY: <api-key>'Get the current mid purchase funnel step.
Path parameters
cart_idRequiredstringCart ID
ReturnsFunnelStep
Mid purchase current funnel step object response
curl https://api.subbly.co/storefront/v1/checkout/{cart_id}/mid_purchase \
-H 'X-API-KEY: <api-key>'Response
{
"step": {
"id": 1,
"initial": true,
"addon": true,
"addon_duration": 1,
"type": "funnel_pre_purchase",
"title": "title",
"description": "description",
"offer": {
"amount_off": 1.5,
"percent_off": 1.5,
"skip_answered_survey": true,
"type": "one_click",
"products": [
{
"id": 1,
"bundle_id": 1,
"bundle": {},
"bundle_ruleset_id": 1,
"bundle_ruleset": {},
"slug": "yellow-t-shirt-with-pokemon-print",
"type": "one_time",
"name": "Yellow T-shirt with pokemon print",
"description": "Yellow T-shirt with pokemon print",
"delivery_info": "Free shipping on orders over $100",
"collect_shipping_address": true,
"gifting_enabled": true,
"digital": false,
"images": [
{}
],
"metadata": [
{}
],
"created_at": "2022-04-01 00:00:00",
"updated_at": "2022-04-01 00:00:00",
"gift_card": false,
"gift_card_expiration": null,
"variants": [
{}
],
"options": [
{}
]
}
]
}
}
}Refresh the funnel progress.
Path parameters
cart_idRequiredstringCart ID
ReturnsFunnelStep
Mid purchase initial funnel step object response
curl -X POST https://api.subbly.co/storefront/v1/checkout/{cart_id}/mid_purchase/refresh \
-H 'X-API-KEY: <api-key>'Response
{
"step": {
"id": 1,
"initial": true,
"addon": true,
"addon_duration": 1,
"type": "funnel_pre_purchase",
"title": "title",
"description": "description",
"offer": {
"amount_off": 1.5,
"percent_off": 1.5,
"skip_answered_survey": true,
"type": "one_click",
"products": [
{
"id": 1,
"bundle_id": 1,
"bundle": {},
"bundle_ruleset_id": 1,
"bundle_ruleset": {},
"slug": "yellow-t-shirt-with-pokemon-print",
"type": "one_time",
"name": "Yellow T-shirt with pokemon print",
"description": "Yellow T-shirt with pokemon print",
"delivery_info": "Free shipping on orders over $100",
"collect_shipping_address": true,
"gifting_enabled": true,
"digital": false,
"images": [
{}
],
"metadata": [
{}
],
"created_at": "2022-04-01 00:00:00",
"updated_at": "2022-04-01 00:00:00",
"gift_card": false,
"gift_card_expiration": null,
"variants": [
{}
],
"options": [
{}
]
}
]
}
}
}Accept the pre purchase funnel step.
Path parameters
cart_idRequiredstringCart ID
step_idRequiredintegerStep ID
Request body
Accept funnel step
offersRequiredobject[]ReturnsCart
Mid purchase next funnel step object response
curl -X POST https://api.subbly.co/storefront/v1/checkout/{cart_id}/mid_purchase/{step_id}/accept \
-H 'X-API-KEY: <api-key>' \
-H 'Content-Type: application/json' \
-d '{
"offers": [
{
"product_id": 1.5,
"options": [
{
"question_id": 1,
"answers": [
{
"id": 1,
"content": "content",
"quantity": 1
}
]
}
]
}
]
}'Response
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"customer_id": 1,
"customer": {
"first_name": "John",
"last_name": "Smith",
"email": "test@test.com",
"marketing_consent": false,
"tos_consent": false,
"active_subscriptions_count": 0,
"external_id": "external_id",
"created_at": "2026-01-15T10:30:00Z"
},
"attached": true,
"shop_id": 1,
"coupon_code": "new-year-discount",
"coupon": {
"id": 1,
"coupon_id": "discount-100",
"name": "Discount for the New Year",
"amount_off": 100,
"percent_off": 20,
"duration": "once",
"duration_in_months": 2
},
"gift_card_code": "a290f1ee-6c54-4b01-90e6-d701748fc92",
"gift_card": {
"id": 1,
"code": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"amount": 100,
"balance": 20,
"message": "It's a gift for you",
"status": "redeemed"
},
"referral_id": 1,
"currency_code": "EUR",
"base_currency_code": "USD",
"shipping_method_id": 1,
"onboarding_template_id": 1,
"shipping_method": {
"id": 1,
"type": "shipping_option",
"method": {}
},
"shipping_carrier_id": 1,
"shipping_carrier": {
"id": 1,
"name": "DHL",
"service_codes": [
"STANDARD",
"EXPRESS"
]
},
"shipping_carrier_service": "STANDARD",
"shipping_address_id": 1,
"shipping_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"billing_address_id": 1,
"billing_address": {
"id": 3486,
"first_name": "John",
"last_name": "Smith",
"country_id": 230,
"region_id": 1231,
"country": "United States",
"region": "California",
"phone": "+13232380656",
"company_name": null,
"address_one": "7609 Mckinley Ave",
"address_two": null,
"city": "Los Angeles",
"zip": "90044"
},
"payment_method_id": 1,
"payment_method": {
"id": 567,
"type": "card",
"identifier": "4242",
"card": {
"last_four": "4242",
"expiry_month": "2",
"expiry_year": "2099",
"type": "credit",
"brand": "visa"
},
"ideal": {
"bank": "ING",
"bic": "INGBNL2A",
"email": "test@subbly.co",
"name": "John Doe"
},
"bancontact": {
"email": "test@subbly.co",
"name": "John Doe"
},
"acss_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "Royal Bank of Canada",
"transit_number": "12345",
"institution_number": "123",
"last_four": "6789"
},
"us_bank_account": {
"email": "test@subbly.co",
"name": "John Doe",
"bank_name": "US Bank",
"last_four": "6789",
"routing_number": "123456789",
"account_type": "checking",
"account_holder_type": "individual"
},
"sepa_debit": {
"email": "test@subbly.co",
"name": "John Doe",
"iban_last4": "6789",
"bank_code": "123456",
"country": "DE",
"branch_code": "12345"
},
"sofort": {
"email": "test@subbly.co",
"name": "John Doe",
"country": "DE"
},
"link": {
"email": "test@subbly.co",
"name": "John Doe"
},
"cashapp": {
"email": "test@subbly.co",
"name": "John Doe",
"buyer_id": "cashapp:123456789",
"cash_tag": "$subbly"
},
"created_at": "2022-04-01 00:00:00",
"updated_at": "2022-04-01 00:00:00"
},
"gift_info": {
"starts_at": "2022-04-01",
"number_of_orders": 1,
"message": "Happy Birthday",
"recipient_email": "recipient@example.com"
},
"starts_at": "2022-04-01",
"items": [
{
"id": "g290f1ee-6c54-4b01-90e6-d701748f0589",
"type": "one_time",
"status": "active",
"product": {},
"quantity": 2,
"description": "Yellow T-shirt with pokemon print",
"addon": false,
"addon_duration": 0,
"gift_card": {
"customer_email": "customer_email",
"customer_name": "customer_name",
"message": "message"
},
"bundle": {
"preferences": [
{}
],
"items": [
{}
]
},
"metadata": [
{}
],
"options": [
{
"question_id": 1,
"answers": [
"answers"
]
}
],
"amount_off": null,
"percent_off": null,
"created_at": "2022-04-01 00:00:00",
"updated_at": "2022-04-01 00:00:00"
}
],
"summary_items": [
{
"item_id": "g290f1ee-6c54-4b01-90e6-d701748f0589",
"type": "one_time",
"product_id": 8,
"quantity": 2,
"price": 799,
"total": 1458,
"sub_total": 1458,
"tax_amount": 160,
"tax_rate": 0.01,
"tax_inclusive": false,
"discount": 300,
"bundle": {},
"discounts": [
{}
],
"charge_now": true,
"subscription": {},
"created_at": "2022-04-01 00:00:00",
"updated_at": "2022-04-01 00:00:00"
}
],
"total": 1458,
"sub_total": 1558,
"discount_total": 300,
"tax_total": 16,
"tax_rate": 0.1,
"discounts": [
{
"type": "coupon",
"description": "Offer discount",
"total": 3,
"charge_now": true
}
],
"metadata": [
{
"id": 1,
"name": "Color",
"slug": "color-red",
"description": "description",
"unit": "kg",
"data_type": "single_line_string",
"preset": true,
"multiple": true,
"variant": true,
"save_behavior": "customer",
"editable": true,
"values": [
{}
]
}
],
"adjustment": 0,
"customs_fee": 0,
"future_customs_fee": 0,
"balance_change": {
"amount": 0,
"currency_code": "USD"
},
"status": "initialized",
"created_at": "2022-04-01 00:00:00",
"updated_at": "2022-04-01 00:00:00"
}Reject the pre purchase funnel step.
Path parameters
cart_idRequiredstringCart ID
step_idRequiredintegerStep ID
Returns
Mid purchase next funnel step object response
curl -X POST https://api.subbly.co/storefront/v1/checkout/{cart_id}/mid_purchase/{step_id}/reject \
-H 'X-API-KEY: <api-key>'