Cart Resource

Use the Cart resource to access cart data.

Resources:

Cart	CartError	Configuration	DeliveryDetails
DeliveryWindow	Discount	Duration	Fulfillment
FulfillmentWindow	Image	LineItem	Modifier
Money	Order	PickupDetails	PickupWindow
PreorderingWindow	Recipient	Reward	ScheduledValidation
ScheduledValidationNext	Validation

Schema type

Use cart to reference this resource in the template schema.

Querying

You do not need to query for the cart. Including the cart in a template’s schema will give that template access to cart data.

Using the cart resource will make the source template render uncacheable as the cart relies on a request’s session cookie. Refer to this guide on how to load uncacheable resources with the template API.

Note that an item must be added to cart before a cart is created. If no cart exists the rendering engine will be provided with an array that looks like:

{
  "created": false
}

Total Quantity

The order.total_quantity field is added to the cart resource as a convenience to make it easy to show a cart icon with a quantity number. order.total_quantity is the sum of the quantity field for all line items in the cart.

Example

templates/components/cart.html.twig

{% if cart.created %}
    {% for item in cart.order.line_items %}
        {{ item.name }}
    {% endfor %}
{% else %}
    Empty Cart
{% endif %}

Sample Cart

{
    "__SO_RESOURCE_TYPE__": "cart", // internally used resource property. do not modify.
    "id": "11ee0ad12d8637b381682c600c83e955",
    "resource_type": "CART",
    "cart_token": "0438f0bd56a6",
    "created": true,
    "order": {
        "location_id": "L36RW9ABXQTEE",
        "fulfillment": {
            "configuration": {
                "pickup_timezone": "America/Toronto"
            },
            "type": "PICKUP",
            "pickup_details": {
                "curbside_pickup_details": null,
                "is_curbside": true,
                "time": "2023-08-21T22:08:25+00:00",
                "time_unix": 1692655705,
                "time_formatted": "Today at 6:08 PM",
                "schedule_type": "ASAP"
            }
        },
        "line_items": [
            {
                "id": "11ee0b0179f8425e81682c600c83e955",
                "name": "Coral Rocks",
                "quantity": 1,
                "square_online_item_id": "2",
                "variation_name": "Variation: XL",
                "image": {
                    "width": "679",
                    "height": "684",
                    "format": "jpeg",
                    "absolute_url": "https://769244280274161852.square.staging.weebly.net/uploads/1/2/1/7/121778831/s604497668748833845_p2_i4_w679.jpeg",
                    "absolute_urls": {
                        "80": "/uploads/1/2/1/7/121778831/s604497668748833845_p2_i4_w679.jpeg?width=80",
                        "160": "/uploads/1/2/1/7/121778831/s604497668748833845_p2_i4_w679.jpeg?width=160",
                        "320": "/uploads/1/2/1/7/121778831/s604497668748833845_p2_i4_w679.jpeg?width=320",
                        "640": "/uploads/1/2/1/7/121778831/s604497668748833845_p2_i4_w679.jpeg?width=640"
                    }
                },
                "applied_discounts": [
                    {
                        "name": "blackedout",
                        "scope": "LINE_ITEM",
                        "applied_money": {
                            "amount": 1000,
                            "currency": "USD",
                            "formatted": "$10.00"
                        }
                    }
                ],
                "fulfillment_options": [
                    "shipping"
                ],
                "is_preordered": false,
                "item_id": "ESTGKPCABDJSJIYA6LPNIMN5",
                "preordering_window": null,
                "base_price_money": {
                    "amount": 3000,
                    "currency": "USD",
                    "formatted": "$30.00"
                },
                "gross_price_money": {
                    "amount": 2000,
                    "currency": "USD",
                    "formatted": "$20.00"
                }
            },
            {
                "id": "11ee0b01fce1edb681682c600c83e955",
                "name": "Coral Rocks",
                "quantity": 1,
                "square_online_item_id": "2",
                "variation_name": "Variation: M",
                "image": {
                    "width": "679",
                    "height": "684",
                    "format": "jpeg",
                    "absolute_url": "https://769244280274161852.square.staging.weebly.net/uploads/1/2/1/7/121778831/s604497668748833845_p2_i4_w679.jpeg",
                    "absolute_urls": {
                        "80": "/uploads/1/2/1/7/121778831/s604497668748833845_p2_i4_w679.jpeg?width=80",
                        "160": "/uploads/1/2/1/7/121778831/s604497668748833845_p2_i4_w679.jpeg?width=160",
                        "320": "/uploads/1/2/1/7/121778831/s604497668748833845_p2_i4_w679.jpeg?width=320",
                        "640": "/uploads/1/2/1/7/121778831/s604497668748833845_p2_i4_w679.jpeg?width=640"
                    }
                },
                "applied_discounts": [
                    {
                        "name": "blackedout",
                        "scope": "LINE_ITEM",
                        "applied_money": {
                            "amount": 1000,
                            "currency": "USD",
                            "formatted": "$10.00"
                        }
                    }
                ],
                "fulfillment_options": [
                    "shipping"
                ],
                "is_preordered": false,
                "item_id": "APWAPGIRWE5CSHESXWEHNDZR",
                "preordering_window": null,
                "base_price_money": {
                    "amount": 1800,
                    "currency": "USD",
                    "formatted": "$18.00"
                },
                "gross_price_money": {
                    "amount": 800,
                    "currency": "USD",
                    "formatted": "$8.00"
                }
            }
        ],
        "discounts": [
            {
                "name": "blackedout",
                "scope": "LINE_ITEM",
                "applied_money": {
                    "amount": 2000,
                    "currency": "USD",
                    "formatted": "$20.00"
                }
            }
        ],
        "rewards": [],
        "total_quantity": 2,
        "total_money": {
            "amount": 2800,
            "currency": "USD",
            "formatted": "$28.00"
        },
        "subtotal_before_discounts_money": {
            "amount": 4800,
            "currency": "USD",
            "formatted": "$48.00"
        },
        "subtotal_money": {
            "amount": 4800,
            "currency": "USD",
            "formatted": "$48.00"
        },
        "total_taxes_and_fees_money": {
            "amount": 0,
            "currency": "USD",
            "formatted": "$0.00"
        }
    },
    "validation": {
        "scheduled": {
            "valid": true
        }
    },
    "cart_errors": []
}

Cart resources

Cart

Field	Type	Description
cart_token	String	Cart token
created	Boolean	Whether a cart has been created or not. If no cart has been started, this will be the only field present
id	String	ID of the order
order	Order	Details about the order
resource_type	String	The resource type identifier
validation	Validation	Validation on the cart. Note that this is deprecated, and we recommend using cart_errors instead
cart_errors	CartError[]	Errors applicable to the cart. Empty array if there are none

Back to top

CartError

Field	Type	Description
translated	String	Translated error string you can use to display to the buyer. This is based off the site language set in the Square Online dashboard
next	ScheduledValidationNext	The next valid time if the error is related to scheduling, otherwise excluded

Back to top

Configuration

Information about a fulfillment.

Field	Type	Description
pickup_timezone	String	Timezone of the store location the order is being picked up from, for example: America/Toronto.

Back to top

DeliveryDetails

Information about a DELIVERY-type fulfillment.

Field	Type	Description
is_no_contact_delivery	Boolean	Whether the delivery should be contactless.
note	String	Order note information provided to the seller.
order_delivery_fee_total	Money	Total price for the delivery fee.
recipient	Recipient	Recipient for the delivery.
schedule_type	Boolean	Type of schedule for the delivery: “ASAP” or “SCHEDULED”.
time	String	RFC3339 timestamp for the start of the delivery time range, for example: 2023-10-16T16:28:50+00:00.
time_formatted	String	Formatted text for the delivery time range.
time_unix	Number	Unix timestamp for the start of the delivery time range.
window_duration	Duration	The delivery time range duration.

Back to top

DeliveryWindow

Window for delivery hours

Field	Type	Description
start	FulfillmentWindow	Start of the window for the delivery hours.
end	FulfillmentWindow	End of the window for the delivery hours.

Back to top

Discount

A discount for an order.

Field	Type	Description
applied_money	Money	The amount of money discounted from each line item the discount applies to, based on the scope.
name	String	Display name of the discount
scope	String	Indicates the level at which the discount applies

Back to top

Duration

Duration.

Field	Type	Description
in_minutes	Number	Duration in minutes.
rfc3339_interval	String	Duration in RFC3339 format.

Back to top

Fulfillment

A fulfillment for an order.

Field	Type	Description
configuration	Configuration	Fulfillment configuration details
pickup_details	PickupDetails	Pickup details for the order. These values will be null if not a pickup or delivery order
delivery_details	DeliveryDetails	Delivery details for the order. These values will be null if not a delivery order
type	String	Fulfillment type for the order, for example: PICKUP

Back to top

FulfillmentWindow

Window for fulfillment hours

Field	Type	Description
time	String	RFC3339 formatted date-time.
time_formatted	String	Human-readable label for time.
time_unix	Number	UNIX timestamp of pickup/delivery time.

Back to top

Image

An image for a line item.

Field	Type	Description
absolute_url	String	Absolute url for item image
absolute_urls	AbsoluteUrls	Dictionary of absolute urls for various sizes. The key is the image width in pixels, the value is the URL
format	String	The format of the media file, if applicable. For example, gif.
height	Number	Height of the item image
width	Number	Width of the item image

Back to top

LineItem

A line item in an order. A line item references an item in the item catalog and includes order-related information.

Field	Type	Description
applied_discounts	Discount[]	Any discounts that apply to this line item
base_price_money	Money	The unit price of the selected variation (without modifiers)
fulfillment_options	String[]	All the fulfillment options available for this item
gross_price_money	Money	The original unit price, plus modifiers, times quantity with discounts included
id	String	Item ID
image	Image	Line item’s image
is_preordered	Boolean	Whether the buyer is pre-ordering this item to be fulfilled at a later date
item_id	String	The ID for the base item resource independent of any modifiers/variations/options
modifiers	Modifier[]	Any modifiers applied to the line item
name	String	Name of the item
preordering_window	PreorderingWindow	The pre-ordering window available for this item
quantity	Number	Number of this item ordered
square_online_item_id	String	The Square Online ID for the base item resource independent of any modifiers/variations/options
variation_name	String	Variation name
variation_id	String	Variation ID
is_alcoholic	Boolean	Whether the item is alcoholic

Back to top

Modifier

A modifier applied to the line item.

Field	Type	Description
base_price_money	Money	Unit price for the modifier
modifier_list_id	String	The ID of the modifier list from the item
modifier_list_name	String	The name of the list the modifier is grouped into
name	String	Modifier name
quantity	Number	How many of the modifier are applied to the item, if applicable
total_price_money	Money	Total price for the modifier
user_submitted_value	String	If the modifier requires a text value from the user, i.e. for custom printing
type	String	The type of the modifier

Money

Information about monetary amounts.

Field	Type	Description
amount	Number	Amount in the smallest subunit of the given currency
currency	String	The ISO 4217 three-letter currency code
formatted	String	Amount formatted with the symbol of the given currency. Formatted according to the site’s locale

Back to top

Order

An order in the cart.

Field	Type	Description
discounts	Discount[]	Any discounts applied to the order
fulfillment	Fulfillment	Order fulfillment details
line_items	LineItem[]	Line items associated with the order
location_id	String	The Square ID of the store location that this order is associated with.
rewards	Reward[]	Loyalty rewards applied to the order
subtotal_before_discounts_money	Money	Amount owed BEFORE discounts and BEFORE any coupons, gift cards, taxes, tips, or fees
subtotal_money	Money	Amount owed AFTER discounts BEFORE any coupons, gift cards, taxes, tips, or fees
total_money	Money	Total amount owed for the order
total_quantity	Number	Total number of line items
total_taxes_and_fees_money	Money	Amount of taxes and service fees owed

Back to top

PickupDetails

Information about a PICKUP-type fulfillment.

Field	Type	Description
curbside_pickup_details	String	“How to recognize you” text for curbside pickup added during checkout.
is_curbside	Boolean	Whether the order will be picked up curbside or not.
time	String	RFC3339 timestamp for when the buyer wants to pickup their order, for example: 2023-10-16T16:28:50+00:00. Start of the time range for a pickup window.
time_formatted	String	Formatted text for when the buyer wants to pickup their order.
time_unix	Number	Unix timestamp for when the buyer wants to pickup their order. Start of the time range for a pickup window.
schedule_type	Boolean	Type of schedule for the pickup: “ASAP” or “SCHEDULED”.

Back to top

PickupWindow

Window for pickup hours

Field	Type	Description
start	FulfillmentWindow	Start of the window for the pickup hours.
end	FulfillmentWindow	End of the window for the pickup hours.

Back to top

PreorderingWindow

The pre-ordering window available for a line item.

Field	Type	Description
availability_cutoff_at	Number	Cutoff time for pre-ordering for the current fulfillment window.
end_at	Number	When the pre-ordering fulfillment window ends, as a Unix timestamp.
start_at	Number	When the pre-ordering fulfillment window starts, as a Unix timestamp.

Back to top

Recipient

The recipient for delivery_details

Field	Type	Description
address_line_1	String
address_line_2	String
address_line_3	String
administrative_district_level_1	String
administrative_district_level_2	String
administrative_district_level_3	String
country	String
locality	String
postal_code	String
sub_locality	String
sub_locality_2	String
sub_locality_3	String

Back to top

Reward

Loyalty rewards applied to an order

Field	Type	Description
id	String	ID of the loyalty reward
loyalty_reward_tier_name	String	The name of the loyalty reward tier
loyalty_reward_tier_id	String	The ID of the loyalty reward tier
discount_type	String	Either FIXED_PERCENTAGE or FIXED_AMOUNT
applied_amount_money	Money	The discount amount applied to the order/item for the reward tier
maximum_amount_money	Money	Only included if the discount_type is a FIXED_PERCENTAGE. Indicates the maximum discount amount that can be applied to the order/item. null if there is no maximum.
percentage	Number	Only included if the discount_type is a FIXED_PERCENTAGE. Indicates the percentage discount for the order/item
item_id	String	Only included if the loyalty reward tier is item based. ID of the item the loyalty reward is being applied to
item_variation_id	String	Only included if the loyalty reward tier is item based. Variation ID of the item the loyalty reward is being applied to

Back to top

ScheduledValidation

Validation done for a SCHEDULED order.

Field	Type	Description
valid	Boolean	Whether or not the pickup_at or deliver_at time is still valid
next	ScheduledValidationNext	The next valid time if valid is false and an error did not occur. null if valid is true
error	[String]	If an error occurred attempting to update the fulfillment time on the cart, this will be populated with the error reason

Back to top

ScheduledValidationNext

The next valid time for a SCHEDULED order.

Field	Type	Description
time	String	RFC3339 formatted date-time.
time_formatted	String	Human-readable label for time. Dependent on fulfillment type.
time_unix	Number	UNIX timestamp of pickup/delivery time.
date	String	RFC3339 date based on the store location’s timezone.
label	String	Prescribed localized time-only label for use in buyer-facing time selectors.
prep_time_duration	Duration	Details about Prep time duration.
pickup_window	PickupWindow	Included if using a window for pickup hours.
delivery_window	DeliveryWindow	Included if the fulfillment is delivery.

Back to top

Validation

Validation done for the order on the cart.

Field	Type	Description
scheduled	ScheduledValidation	Provided if the fulfillmentType is SCHEDULED or ASAP

Back to top