buy Function
Used for a Buy Now flow that immediately adds an item variation with modifiers to cart and redirects to checkout. Always works off of a new cart instance so a provided order_id will be ignored.
Certain modifiers appended to a line item are weebly_ids rather than square_ids as the text, gift_wrap, and gift_message modifier types are not yet synced to Square.
Request Body
location_id
-
string required
Location ID where the cart is expected to be fulfilled
{ "location_id": "LXGG1JK52W3Z8" }
line_item
- object required
-
quantity number required
Number of line items to add to cart
{ "quantity": 8 } -
item_id string required
Item to add to cart
{ "item_id": "Y6O2RDH3UKTIYJQUAFKGCJ4M", } -
variation_id string required
Variation of item to add to cart
{ "variation_id": "RD5IDT6RBS4H7XT43G3CXWKY", } -
price_override object
Provide an override amount (in subunits) with a supported currency for custom donation amounts on a donation item type.
{ "price_override": { "amount": 1000, // $10.00 "currency": "USD" } } -
modifiers object
Modifiers applied to the line_item grouped by modifier types. Each modifier type can have different values. The top-level keys in each modifier type are the modifier IDs.
CHOICE- choice_selections Array of choice selection IDs ``` { "CHOICE": { "6WVGAE3PKEHRWZHF54KR2PIN": { "choice_selections": ["E3MWZ3PJ3VZDQWGW4G3KFZGW", "GKCUYTB7ARN25J7BTRTOSVHO"] } } } ``` `TEXT` - text_entry Text applied to each text-based modifier ``` { "TEXT": { "11ede91fbff63a3ab4dbde667deefb9b": { "text_entry": "my t-shirt-text" } } } ```GIFT_WRAP- choice_selections Array of choice selection IDs specific to `GIFT_WRAP` type modifiers ``` { "GIFT_WRAP": { "11ee185ca1cd3e98a25c9e3d692ffefb": { "choice_selections": ["11ee185ca1cd7daebd029e3d692ffefb"] // weebly_id } } } ```GIFT_MESSAGE- text_entry Gift message text ``` { "GIFT_MESSAGE": { "11ee185ca17973e490449e3d692ffefb": { "text_entry": "happy bday" } } } ```
-
fulfillment
- object required
-
fulfillment_type string required
Fulfillment type being applied to the cart. Each fulfillment type has corresponding options that can be provided.
Values:
SHIPMENT,MANUAL,PICKUP,DELIVERY -
pickup_details object
Required if fulfillment_type is PICKUP.
-
schedule_type string
Type of scheduling used for the PICKUP order.
Values:
ASAP,SCHEDULED -
curbside_pickup_requested boolean
Denotes whether the pickup will be done curbside.
-
curbside_pickup_details object
-
curbside_details string
Contains details of the curbside pickup
-
-
pickup_at string
RFC3339 date-time string for the scheduled pickup. Ignored if
schedule_typeisASAP.
{ "pickup_details": { "schedule_type": "ASAP", "curbside_pickup_requested": true, "curbside_pickup_details": { "curbside_details": "Coming in a white t-shirt with black jeans" }, "pickup_at": "2023-08-21T22:08:25+00:00" } } -
-
delivery_details object
Required if fulfillment_type is DELIVERY.
-
schedule_type string
Type of scheduling used for the DELIVERY order.
Values:
ASAP,SCHEDULED -
recipient object
Contains delivery address information.
{ "recipient": { "address": { "locality": "New York", "country": "US", "postal_code": "10013", "administrative_district_level_1": "New York", "administrative_district_level_2": "New York County", "administrative_district_level_3": "Town of New york", "sub_locality": "District 7", "sub_locality_2": "Neighborhood", "sub_locality_3": "Housing colony", "address_line_1": "100 6th Avenue", "address_line_2": "", "address_line_3": "" } } } -
no_contact_delivery boolean
Denotes whether the delivery should done with no contact
-
note string
Order note information provided to the seller
-
deliver_at string
RFC3339 date-time string for the scheduled delivery. Ignored if
schedule_typeisASAP.
{ "delivery_details": { "schedule_type": "ASAP", "no_contact_delivery": true, "note": "Please include a place setting", "recipient": { "address": { "locality": "New York", "country": "US", "postal_code": "10013", "administrative_district_level_1": "New York", "administrative_district_level_2": "New York County", "administrative_district_level_3": "Town of New york", "sub_locality": "District 7", "sub_locality_2": "Neighborhood", "sub_locality_3": "Housing colony", "address_line_1": "100 6th Avenue", "address_line_2": "", "address_line_3": "" } } } } -
-
Example
fetch('/s/api/v1/cart/buy', {
method: 'POST',
headers: {
'X-CSRF-TOKEN': 'csrf_token_from_csrf_meta_tag',
},
body: JSON.stringify({
"location_id": "LXGG1JK52W3Z8",
"line_item": {
"quantity": 8,
"item_id": "Y6O2RDH3UKTIYJQUAFKGCJ4M",
/**
* Optional - The variation ID tied to the subscription plan to apply to the line item.
* Providing this value will redirect to /s/subscription-checkout.
* Only available on the Buy Now endpoint
*/
"subscription_variation_id": "JUYNRIFU4YTOTB3DW3T2EEYO",
/**
* Optional - Provide an override amount (in subunits) with a supported currency for
* custom donation amounts on a donation item type.
*/
"price_override": {
"amount": 1000, // $10.00
"currency": "USD"
},
"variation_id": "RD5IDT6RBS4H7XT43G3CXWKY",
"modifiers": {
"CHOICE": {
"6WVGAE3PKEHRWZHF54KR2PIN": {
"choice_selections": ["E3MWZ3PJ3VZDQWGW4G3KFZGW", "GKCUYTB7ARN25J7BTRTOSVHO"]
}
},
"TEXT": {
"11ede91fbff63a3ab4dbde667deefb9b": {
"text_entry": "my t-shirt-text"
}
},
"GIFT_WRAP": {
"11ee185ca1cd3e98a25c9e3d692ffefb": {
"choice_selections": ["11ee185ca1cd7daebd029e3d692ffefb"] // weebly_id
}
},
"GIFT_MESSAGE": {
"11ee185ca17973e490449e3d692ffefb": {
"text_entry": "happy bday"
}
}
}
},
"fulfillment": {
"fulfillment_type": "SHIPMENT"
}
})
})
.then((response) => ...);
You can use the Site Theme SDK instead of calling the Cart API directly. The SDK is intended to simplify cart actions.