Issue with API v41 in PHP in regards to OrderLineItems and Orders

syd · March 19, 2025, 8:15pm

I upconverted our application (ConTroll Registration Software) from v40 of the PHP API to V41, which of course required some of a rewrite.

The rewrite wasn’t hard, but I’m having an issue getting the right data to Square. In the older api:

$item->setName(string), $item->setNote(string) set the name and note in the order item.

In the new api…
$item = new OrderLineItem([ …

Square-Dev-AI · March 19, 2025, 8:15pm

I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Create Orders
Orders API
Configure the Order-Ahead Sample Application

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

syd · March 19, 2025, 8:19pm

It sent too soon, some how…

in the new api:$item = new OrderLineItem([…
‘note’ => ‘string’,
‘name’ => ‘string’.

When I dump the order itself in PHP I get in the new api:

[0] => Square\Types\OrderLineItem Object
1397778 (
1397779 [__additionalProperties:Square\Core\Json\JsonSerializableType:private] => Array
1397780 (
1397781 )
1397782
1397783 [uid:Square\Types\OrderLineItem:private] => badge1
1397784 [name:Square\Types\OrderLineItem:private] => all Membership for John Inman
1397785 [quantity:Square\Types\OrderLineItem:private] => 1
1397786 [quantityUnit:Square\Types\OrderLineItem:private] =>
1397787 [note:Square\Types\OrderLineItem:private] => 606,p1028226: memId, p/n id,
1397788 [catalogObjectId:Square\Types\OrderLineItem:private] =>
1397789 [catalogVersion:Square\Types\OrderLineItem:private] =>
1397790 [variationName:Square\Types\OrderLineItem:private] =>
1397791 [itemType:Square\Types\OrderLineItem:private] =>
1397792 [metadata:Square\Types\OrderLineItem:private] =>
1397793 [modifiers:Square\Types\OrderLineItem:private] =>
1397794 [appliedTaxes:Square\Types\OrderLineItem:private] =>
1397795 [appliedDiscounts:Square\Types\OrderLineItem:private] =>
1397796 [appliedServiceCharges:Square\Types\OrderLineItem:private] =>
1397797 [basePriceMoney:Square\Types\OrderLineItem:private] => Square\Types\Money Object

(I even added an itemType of ITEM and that didn’t help my issue

When I download the order from square, the old code has the line items correctly, the new API does not have the name or note in it. It has ‘Custom Amount’ instead.

any clue what I’m misunderstanding?

Bryan-Square · March 19, 2025, 8:40pm

What version of the SDK are you using? Also what’s your application ID?

syd · March 19, 2025, 9:15pm

the composer line that works with the old code is:
“name”: “square/square”,
“version”: “40.0.0.20250123”,

the one that doesn’t with the new code is:
“name”: “square/square”,
“version”: “41.0.0.20250220”,

I am running this in several sites:
the log file I sent you was from seattle’s site:
appid=“sq0idp-kOcJS–olIdktCPyTbMZDA”

Philadelphia’s site is:
appid=“sq0idp-wCxxyX3NcpGkf4FkTAGw4Q”

In seattle, this is an example of the older 40 api code working: (downloaded from the square site as an orders file)
Name field: all Membership for Mia
Note field: 606,n4410: memId, p/n id

API 41: Not working:
Name field: Custom Amount
Note field: Online payment from portal

The note field is the correct value for the note on the Order (not the order Item).
A section of the var_dump from the order object showing the order line item section of that not working one above:
[uid:Square\Types\OrderLineItem:private] => badge1
[name:Square\Types\OrderLineItem:private] => all Membership for
[quantity:Square\Types\OrderLineItem:private] => 1
[quantityUnit:Square\Types\OrderLineItem:private] =>
[note:Square\Types\OrderLineItem:private] => 606,n4500: memId, p/n id,

syd · March 19, 2025, 11:29pm

ps: if you want to see the entire code, it’s on github, this is the link to the V40 api;

github.com/MichaelRafferty/ConTroll

lib/cc_square.php

syddev

<?php
//  cc_square.php - library of modules to add the square php payment API to onlinereg
// uses config variables:
// [cc]
// type=square - selects that reg is to use square for credit cards
// appid=[APPID] - appliction ID from the square developer portal, be it sandbox or production
// token=[TOKEN] - auth token from the square developer portal
// location=[LOCATION] - location id from the square developer portal
// does not currently use any other config sections for credit card other than [cc]

require_once("global.php");

// draw_cc_html - exposed function to draw the credit card HTML window
//      $cc = array of [cc] section of ini file
//      $postal_code = postal code to default for form, optional
//

function draw_cc_html($cc, $postal_code = "--") {
    $sdk = $cc['webpaysdk'];
    $appid = $cc['appid'];

This file has been truncated. show original

and here is the code to the failing v41 API:

github.com/MichaelRafferty/ConTroll

lib/cc_square.php.v41

syddev

<?php
//  cc_square.php - library of modules to add the square php payment API to onlinereg
// uses config variables:
// [cc]
// type=square - selects that reg is to use square for credit cards
// appid=[APPID] - appliction ID from the square developer portal, be it sandbox or production
// token=[TOKEN] - auth token from the square developer portal
// location=[LOCATION] - location id from the square developer portal
// does not currently use any other config sections for credit card other than [cc]

require_once("global.php");

// draw_cc_html - exposed function to draw the credit card HTML window
//      $cc = array of [cc] section of ini file
//      $postal_code = postal code to default for form, optional
//

function draw_cc_html($cc, $postal_code = "--") {
    $sdk = $cc['webpaysdk'];
    $appid = $cc['appid'];

This file has been truncated. show original

Bryan-Square · March 20, 2025, 4:04pm

Thanks, taking a look.

syd · March 20, 2025, 5:07pm

having found (again) the developer sandbox, It looks like it’s not getting the order line items, even though it looks to me like I’m passing it correctly.
(PS: in my test environment I just switched from v41 to v42, just to see if that makes any difference).

What I really wish the docs had (and I can’t seem to find it), is the translation of the api element name to the php element name, like applied_money => appliedMoney. Guessing that it’s always alpha_beta_gamma => alphaBetaGamma is likely to be wrong somewhere.

I have to do a grep of all the PHP files in the SDK to try and find the mappings.

syd · March 21, 2025, 4:24pm

to test if the line items are in the order, I added the following line after doing a “new order” …

$testLineItems = $order->getLineItems();
and it returned
Square\Types\OrderLineItem Object
(
[__additionalProperties:Square\Core\Json\JsonSerializableType:private] => Array
(
)

[uid:Square\Types\OrderLineItem:private] => badge1
[name:Square\Types\OrderLineItem:private] => all Membership for lets t me
[quantity:Square\Types\OrderLineItem:private] => 1
[quantityUnit:Square\Types\OrderLineItem:private] => 
[note:Square\Types\OrderLineItem:private] => 660,p21772: memId, p/n id
[catalogObjectId:Square\Types\OrderLineItem:private] => 
[catalogVersion:Square\Types\OrderLineItem:private] => 
[variationName:Square\Types\OrderLineItem:private] => 
[itemType:Square\Types\OrderLineItem:private] => ITEM
[metadata:Square\Types\OrderLineItem:private] => 
[modifiers:Square\Types\OrderLineItem:private] => 
[appliedTaxes:Square\Types\OrderLineItem:private] => 
[appliedDiscounts:Square\Types\OrderLineItem:private] => 
[appliedServiceCharges:Square\Types\OrderLineItem:private] => 
[basePriceMoney:Square\Types\OrderLineItem:private] => Square\Types\Money Object
    (
        [__additionalProperties:Square\Core\Json\JsonSerializableType:private] => Array
            (
            )

        [amount:Square\Types\Money:private] => 1000
        [currency:Square\Types\Money:private] => USD
    )

[variationTotalPriceMoney:Square\Types\OrderLineItem:private] => 
[grossSalesMoney:Square\Types\OrderLineItem:private] => 
[totalTaxMoney:Square\Types\OrderLineItem:private] => 
[totalDiscountMoney:Square\Types\OrderLineItem:private] => 
[totalMoney:Square\Types\OrderLineItem:private] => 
[pricingBlocklists:Square\Types\OrderLineItem:private] => 
[totalServiceChargeMoney:Square\Types\OrderLineItem:private] =>

)

so I know it’s in the structure… But it’s not showing up in sandbox that way.

Bryan-Square · March 21, 2025, 4:57pm

Is the order paid for and does it have a fulfillment? Only paid orders will show in sandbox.

syd · March 21, 2025, 5:19pm

yes, we immediately pay it all in the same function call, but looking for that made me find the error, (forrest for the trees problem)…

was:
$pbodyArgs = array(
‘idempotencyKey’ => guidv4(),
‘sourceId’ => $results[‘nonce’],
‘amountMoney’ => new Money([
‘amount’ => $results[‘total’] * 100,
‘currency’ => $currency,
‘orderId’ => $order->getId(),
]),

should have been:

$pbodyArgs = array(
‘idempotencyKey’ => guidv4(),
‘sourceId’ => $results[‘nonce’],
‘amountMoney’ => new Money([
‘amount’ => $results[‘total’] * 100,
‘currency’ => $currency,
]),
‘orderId’ => $order->getId(),

In converting from v40 to v41, a line got in the wrong place on the cut/paste and I totally missed seeing it. So the order wasn’t being attached to the payment. Alas the new API doesn’t complaing about the order id being in the amountMoney not the body.

Moving the line solves the issue. I see it correctly now in the dashboard.

syd · March 21, 2025, 5:38pm

That appears to work and I want to thank you for indirectly pointing me where to look for my error.

If I may I have one final question before this thread gets locked…

Do we still need to track the API version setting in the Developer console for the application id or can it now determine same automatically…

(I’m going to have to get a lot of ‘clients’ to sign in and update their square developer application settings if its not automatic)

Bryan-Square · March 21, 2025, 5:57pm

So your going to have sellers create and configure an application in there Developer Console? That’s not ideal and we would rather recommend OAuth. However if you do take this approach each application that’s created in the Developer Console will automatically go to the latest API version.

If you need your application to be set to a specific version you can include the Square-Version in the header of your API requests and that will override the version set in the Developer Console.

syd · March 21, 2025, 6:23pm

actually they have the application in their website. We are a freely redistributable application. We don’t run it ourselves. Each organization that uses it, clones the github repository, and installs it on their own web server, sets up their own database, locations, and tokens. We don’t have a server on which we ‘run’ it except for demo and development test (and that doesn’t have a square account). Each site creates it’s own test and production instances and configures it with their own square accounts.

(We don’t even have a record of everyone who is using the application).

Welcome to the open source software world. (ConTroll is developed entirely by volunteers).

That you for the help and I’ll look to add Square-Version to the PHP api call, (we use the PHP SDK).

syd · March 21, 2025, 6:25pm

and a quick look at the code base for Square-Version in the PHP SDK:

src/SquareClient.php: ‘Square-Version’ => ‘2025-03-19’,
src/SquareClient.php: $defaultHeaders[‘Square-Version’] = $version;

So I guess it’s already doing that for us, which is good.

Thank you.

Bryan-Square · March 21, 2025, 6:33pm

Yeah, I should have realized you are using the SDK and then version is set there.

syd · March 21, 2025, 6:46pm

you can lock this thread if you want.

Thank you again for your help.

Topic		Replies	Views
Line item and Variation numbers for orders Questions orders-api	10	2827	October 19, 2020
PHP Create order and Sale notification Questions orders-api	27	7249	February 24, 2021
Trouble with Items (API) Questions orders-api , catalog-api , oauth-api	1	1314	December 4, 2021
Isit possible to access the Order Object? Questions orders-api	2	814	April 14, 2021
Line Item uid changes after adding a note? Questions orders-api	3	28	August 5, 2024

Issue with API v41 in PHP in regards to OrderLineItems and Orders

Related topics