The documentation here is hit and miss, looking for clarification as to what should be passed for the initial post request to:
https://connect.squareup.com/v2/locations/{{LOCATION_ID}}/checkouts
The documentation is fairly straightforward here, send a post request to the above and redirect users to the checkout URL that is generated and returned in the response.
Square provides the following sample for the initial POST request, but does not specify what values for 'ITEMS' should be included.
{
"redirect_url": "{{URL TO CONFIRMATION PAGE}}",
"idempotency_key": "{{UNIQUE STRING FOR THIS TRANSACTION}}",
"ask_for_shipping_address": {{true or false}},
"merchant_support_email": "{{SUPPORT EMAIL ADDRESS}}",
"order": {
"reference_id": "{{STORE ORDER ID}}",
"line_items": [
// List each item in the order as an individual line item
{
"name": "{{ITEM_1 NAME}}",
"quantity": "{{ITEM_1 QUANTITY}}",
"base_price_money": {
"amount": {{ITEM_1 COST IN BASE MONETARY UNIT}},
"currency": "{{ITEM_1 CURRENCY USED}}"
},
discounts: [
{
"name": "{{ITEM_1_DISCOUNT NAME}}",
"amount_money": {
"amount": {{ITEM_1_DISCOUNT AMOUNT}},
"currency": "{{ITEM_1_DISCOUNT CURRENCY USED}}"
}
}
],
"taxes": [
{
"name": "{{ITEM_1_TAX NAME}}",
"percentage": "{{ITEM_1_TAX PERCENTAGE}}",
"type": "{{ITEM_1_TAX TYPE}}"
}
]
},
{
"name": "{{ITEM_2 NAME}}",
"quantity": "{{ITEM_2 QUANTITY}}",
"base_price_money": {
"amount": {{ITEM_2 COST IN BASE MONETARY UNIT}},
"currency": "{{ITEM_2 CURRENCY USED}}"
}
},
. . .
{
"name": "{{ITEM_N NAME}}",
"quantity": "{{ITEM_N QUANTITY}}",
"base_price_money": {
"amount": {{ITEM_N COST IN BASE MONETARY UNIT}},
"currency": "{{ITEM_N CURRENCY USED}}"
},
discounts: [
{
"name": "{{ITEM_N_DISCOUNT NAME}}",
"percentage": "{{ITEM_N PERCENTAGE USED}}"
}
]
},
]
},
"pre_populate_buyer_email": "{{CUSTOMER CONTACT INFORMATION: EMAIL}}",
"pre_populate_shipping_address": {
"address_line_1": "{{SHIPPING ADDRESS, LINE 1}}",
"address_line_2": "{{SHIPPING ADDRESS, LINE 2}}",
"locality": "{{SHIPPING CITY/TOWNSHIP/ETC}}",
"administrative_district_level_1": "{{SHIPPING STATE/PROVINCE/ETC}}",
"postal_code": "{{SHIPPING POSTAL CODE}}",
"country": "{{SHIPPING COUNTRY}}",
"first_name": "{{CUSTOMER FIRST NAME}}",
"last_name": "{{CUSTOMER LAST NAME}}"
},
"additional_recipients":[
{
"location_id": "{{RECIPIENT_LOCATION_ID}}",
"description": "{{DESCRIPTION}}",
"amount_money" : {
"amount": {{SPLIT AMOUNT IN BASE MONETARY UNIT}},
"currency": "{{CURRENCY USED}}"
}
}
]
}
Let's look at the 'line_items' property:
"line_items": [
// List each item in the order as an individual line item
{
"name": "{{ITEM_1 NAME}}",
"quantity": "{{ITEM_1 QUANTITY}}",
"base_price_money": {
"amount": {{ITEM_1 COST IN BASE MONETARY UNIT}},
"currency": "{{ITEM_1 CURRENCY USED}}"
},
discounts: [
{
"name": "{{ITEM_1_DISCOUNT NAME}}",
"amount_money": {
"amount": {{ITEM_1_DISCOUNT AMOUNT}},
"currency": "{{ITEM_1_DISCOUNT CURRENCY USED}}"
}
}
],
"taxes": [
{
"name": "{{ITEM_1_TAX NAME}}",
"percentage": "{{ITEM_1_TAX PERCENTAGE}}",
"type": "{{ITEM_1_TAX TYPE}}"
}
]
}
Clearly, line_items is an array of objects, my question is regarding the values for 'Name'. Is this referring to the 'Variation name' or the Catalogue Item Name?
The snippet below is output from var_dump on the getItemData that is returned when using the SquareConnect\Model\CatalogItem.
object(SquareConnect\Model\CatalogItem)[2731]
protected 'name' => string 'Amusementpark' (length=11)
protected 'description' => string 'Ages 3-69' (length=9)
protected 'abbreviation' => null
protected 'label_color' => null
protected 'available_online' => boolean false
protected 'available_for_pickup' => boolean false
protected 'available_electronically' => boolean false
protected 'category_id' => string 'ZYACasdfadsA674SJRS3J' (length=24)
protected 'tax_ids' => null
protected 'modifier_list_info' => null
protected 'image_url' => string 'https://square-production.s3.amazonaws.com/files/9f5f5b061adsfadsfa603622eab14904f6950431e/original.png' (length=102)
protected 'variations' =>
array (size=1)
0 =>
object(SquareConnect\Model\CatalogObject)[2732]
protected 'type' => string 'ITEM_VARIATION' (length=14)
protected 'id' => string '7XasdfasdfaUIKWNKGAJBA4SE' (length=24)
protected 'updated_at' => string '2018-03-10T21:39:05.18Z' (length=23)
protected 'version' => int 1520723945180
protected 'is_deleted' => boolean false
protected 'catalog_v1_ids' => null
protected 'present_at_all_locations' => boolean true
protected 'present_at_location_ids' => null
protected 'absent_at_location_ids' => null
protected 'item_data' => null
protected 'category_data' => null
protected 'item_variation_data' =>
object(SquareConnect\Model\CatalogItemVariation)[2733]
protected 'item_id' => string 'INdeee6OVT2YLOW7LKDKLN' (length=24)
protected 'name' => string 'Regular' (length=7)
protected 'sku' => null
protected 'upc' => null
protected 'ordinal' => int 1
protected 'pricing_type' => string 'FIXED_PRICING' (length=13)
protected 'price_money' =>
object(SquareConnect\Model\Money)[2734]
protected 'amount' => int 3400
protected 'currency' => string 'USD' (length=3)
protected 'location_overrides' =>
array (size=1)
0 =>
object(SquareConnect\Model\ItemVariationLocationOverrides)[2735]
protected 'location_id' => string 'CNCadafdA3TZA' (length=13)
protected 'price_money' => null
protected 'pricing_type' => null
protected 'track_inventory' => boolean true
protected 'inventory_alert_type' => string 'LOW_QUANTITY' (length=12)
protected 'inventory_alert_threshold' => int 50
protected 'track_inventory' => null
protected 'inventory_alert_type' => null
protected 'inventory_alert_threshold' => null
protected 'user_data' => null
protected 'service_duration' => null
protected 'tax_data' => null
protected 'discount_data' => null
protected 'modifier_list_data' => null
protected 'modifier_data' => null
protected 'product_type' => string 'REGULAR' (length=7)
protected 'skip_modifier_screen' => boolean false
If there is only one variation for the item, 'Regular' is returned for the variation name under item_variation_data.
If there is more than one variation on the item, the actual variation name value is returned.
The question is should the variation name Regular be passed as the name property in the line_items array, or should the item name be passed Amusementpark in this example?
At first I was thinking this wouldn't matter, but if 'Regular' is passed for all items with no way to distinguish which item the variation refers to, that would be confusing from within the Square dashboard. What item was purchased...
I'm not sure if our implementation should pass the Item Name if there is only one variation Amusementpark, and then pass the variation name only if there is more than one variation for the item.
This seems like there's a gap in the documentation, but if anyone has encountered this some direction would be appreciated.
Does the square checkout page handle the selection of variation items? I wouldn't think so because the pricing information needs to be passed to the initial post request... Or should I simply use the item name and set the price to be equal to the variation the user selects?
