Cart
Storefront Cart API endpoints
An api call to initialize cart.
Request body
Store cart body
referral_idoptionalintegerReferral Id
currency_codeoptionalstringcoupon_codeoptionalstringgift_card_codeoptionalstringReturnsCart
Cart object response
curl -X POST https://api.subbly.co/storefront/v1/cart \
-H 'X-API-KEY: <api-key>' \
-H 'Authorization: Bearer <access-token>' \
-H 'Content-Type: application/json' \
-d '{
"referral_id": 1,
"currency_code": "currency_code",
"coupon_code": "coupon_code",
"gift_card_code": "gift_card_code"
}'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"
}A detailed description of the cart with all discounts and amounts.
Path parameters
cart_idRequiredstringCart ID
ReturnsCart
Cart object response
curl https://api.subbly.co/storefront/v1/cart/{cart_id} \
-H 'X-API-KEY: <api-key>' \
-H 'Authorization: Bearer <access-token>'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"
}An api call to update main cart fields
Path parameters
cart_idRequiredstringCart ID
Request body
Update cart body
referral_idoptionalintegercurrency_codeoptionalstringcoupon_codeoptionalstringgift_card_codeoptionalstringgift_infooptionalGiftDatastarts_atoptionalstring | nullSubscription start date (Y-m-d). Prohibited together with gift_info.
Format: date.
customeroptionalCustomerDatashipping_addressoptionalAddresspickup_infooptionalPickupInfobilling_addressoptionalAddresspayment_method_idoptionalintegerApplicable only after authentication.
shipping_address_idoptionalintegerApplicable only after authentication. Required with shipping_method_id
shipping_method_idoptionalintegerApplicable only after authentication. Required with shipping_address_id
shipping_carrier_idoptionalinteger | nullRequired when the shipping method is dynamic. Prohibited otherwise.
shipping_carrier_serviceoptionalstring | nullRequired when the shipping method is dynamic. Prohibited otherwise.
onboarding_template_idoptionalinteger | nullbilling_address_idoptionalintegerApplicable only after authentication.
metadataoptionalobject[] | nullList of metadata and its values
ReturnsCart
Cart object response
curl -X PATCH https://api.subbly.co/storefront/v1/cart/{cart_id} \
-H 'X-API-KEY: <api-key>' \
-H 'Authorization: Bearer <access-token>' \
-H 'Content-Type: application/json' \
-d '{
"referral_id": 1,
"currency_code": "currency_code",
"coupon_code": "coupon_code",
"gift_card_code": "gift_card_code",
"gift_info": {
"starts_at": "2022-04-01",
"number_of_orders": 1,
"message": "Happy Birthday",
"recipient_email": "recipient@example.com"
},
"starts_at": "2026-01-15",
"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"
},
"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"
},
"pickup_info": {
"id": 3487,
"first_name": "John",
"last_name": "Smith",
"phone": "+13232380656",
"pickup_point": {
"id": 12,
"external_id": "FR-123456",
"country_id": 74,
"country_code": "FR",
"country_name": "France",
"type": "mondial_relay",
"city": "Paris",
"address_one": "1 Rue de Rivoli",
"address_two": null,
"zip": "75001"
}
},
"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,
"shipping_address_id": 1,
"shipping_method_id": 1,
"shipping_carrier_id": 1,
"shipping_carrier_service": "shipping_carrier_service",
"onboarding_template_id": 1,
"billing_address_id": 1,
"metadata": [
{
"id": 1,
"values": [
{
"id": 10,
"value": "Blue"
}
]
}
]
}'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"
}Available gifting dates.
Path parameters
cart_idRequiredstringCart ID
ReturnsStartDates
Gifting dates object
curl https://api.subbly.co/storefront/v1/cart/{cart_id}/gifting_dates \
-H 'X-API-KEY: <api-key>'Response
{
"available_dates": [
"2022-01-01"
],
"range": [
"2022-01-01",
"2022-12-01"
]
}Available subscription start dates.
Path parameters
cart_idRequiredstringCart ID
ReturnsStartDates
Start dates object
curl https://api.subbly.co/storefront/v1/cart/{cart_id}/start_dates \
-H 'X-API-KEY: <api-key>'Response
{
"available_dates": [
"2022-01-01"
],
"range": [
"2022-01-01",
"2022-12-01"
]
}Available shipping methods for the current address.
Path parameters
cart_idRequiredstringCart ID
Query parameters
country_idRequiredintegerregion_idoptionalintegerIf empty will be looked up by country and zip
zipRequiredstringfirst_nameoptionalstringlast_nameoptionalstringphoneoptionalstringaddress_oneoptionalstringaddress_twooptionalstringcityoptionalstringexpandoptionalstring[]Expandable relations (e.g. carrier)
ReturnsCartShippingMethod[]
Array of shipping methods objects
curl https://api.subbly.co/storefront/v1/cart/{cart_id}/shipping_methods \
-H 'X-API-KEY: <api-key>'Response
[
{
"id": 1,
"service": "STANDARD",
"carrier_id": 1,
"carrier": {
"id": 1,
"name": "DHL",
"service_codes": [
"STANDARD",
"EXPRESS"
]
},
"type": "shipping_option",
"method": {
"name": "US Free shipping method",
"duration": "2-3 days",
"type": "flat_price",
"provider": "flavorcloud"
},
"shipping_fee": 10,
"future_shipping_fee": 0,
"customs_fee": 0,
"future_customs_fee": 0,
"prohibited_products": [
1
]
}
]Available local pickups.
Path parameters
cart_idRequiredstringCart ID
ReturnsCartShippingMethod[]
Array of local pickup objects
curl https://api.subbly.co/storefront/v1/cart/{cart_id}/local_pickups \
-H 'X-API-KEY: <api-key>'Response
[
{
"id": 1,
"service": "STANDARD",
"carrier_id": 1,
"carrier": {
"id": 1,
"name": "DHL",
"service_codes": [
"STANDARD",
"EXPRESS"
]
},
"type": "shipping_option",
"method": {
"name": "US Free shipping method",
"duration": "2-3 days",
"type": "flat_price",
"provider": "flavorcloud"
},
"shipping_fee": 10,
"future_shipping_fee": 0,
"customs_fee": 0,
"future_customs_fee": 0,
"prohibited_products": [
1
]
}
]The validation of the cart to be sure it will be valid when purchase.
Path parameters
cart_idRequiredstringCart ID
ReturnsCart
Cart object response
curl -X POST https://api.subbly.co/storefront/v1/cart/{cart_id}/validate \
-H 'X-API-KEY: <api-key>' \
-H 'Authorization: Bearer <access-token>'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"
}Attach the customer to the current cart.
Path parameters
cart_idRequiredstringCart ID
ReturnsCart
Cart object response
curl -X POST https://api.subbly.co/storefront/v1/cart/{cart_id}/attach_customer \
-H 'X-API-KEY: <api-key>' \
-H 'Authorization: Bearer <access-token>'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"
}