Square PHP REST API交易未返回customer_id问题求助

我之前在对接Square API的时候也碰到过一模一样的问题——明明后台交易已经关联了客户，但接口返回的交易对象里就是没有customer_id字段。后来翻官方文档才搞明白，这个字段默认不会主动返回，得通过调整请求参数来显式获取。

下面是具体的解决步骤和代码示例：

核心：添加expand请求参数 #

Square API的设计逻辑是默认只返回基础交易信息，关联的客户数据需要通过expand参数主动请求。针对交易接口，你只需在请求里指定expand=customer，响应里就会包含对应的客户ID了。

单个交易查询的PHP代码示例 #

如果你用的是Square官方PHP SDK，获取单个交易时可以这么设置参数：

<?php
require 'vendor/autoload.php';

use Square\SquareClient;
use Square\Environment;

// 初始化Square客户端
$squareClient = new SquareClient([
    'accessToken' => '你的Square访问令牌',
    'environment' => Environment::PRODUCTION // 测试环境用Environment::SANDBOX
]);

// 调用交易查询接口，添加expand参数展开客户关联数据
$transactionResponse = $squareClient->getTransactionsApi()->retrieveTransaction(
    '你的门店ID',
    '目标交易ID',
    ['expand' => ['customer']] // 关键参数：请求返回关联的客户信息
);

// 处理接口响应
if ($transactionResponse->isSuccess()) {
    $transaction = $transactionResponse->getResult()->getTransaction();
    // 现在就能拿到customer_id了
    $customerId = $transaction->getCustomerId();
    echo "当前交易关联的客户ID：" . $customerId;
    // 接下来就可以用这个ID和CRM系统里的用户做关联了
} else {
    // 错误处理
    foreach ($transactionResponse->getErrors() as $error) {
        echo "接口错误：" . $error->getDetail() . "\n";
    }
}
?>

批量查询交易的PHP代码示例 #

如果是批量获取交易列表（listTransactions接口），同样需要添加expand参数：

$transactionsListResponse = $squareClient->getTransactionsApi()->listTransactions(
    '你的门店ID',
    [
        'begin_time' => '2024-01-01T00:00:00Z', // 可选：设置时间筛选范围
        'expand' => ['customer'] // 同样添加expand参数
    ]
);

if ($transactionsListResponse->isSuccess()) {
    $transactions = $transactionsListResponse->getResult()->getTransactions();
    foreach ($transactions as $transaction) {
        $customerId = $transaction->getCustomerId();
        echo "交易ID {$transaction->getId()} 关联客户ID：{$customerId}\n";
    }
}

额外注意事项 #

• 权限检查：确保你的Square API令牌拥有CUSTOMERS_READ和TRANSACTIONS_READ权限，否则即使加了expand参数也拿不到客户数据。
• API版本适配：如果用的是Square新推出的Orders API（官方现在更推荐用Orders替代旧的Transactions API），逻辑完全一致——获取订单时添加expand=customer参数，就能从订单对象里拿到customer_id。
• 后台关联验证：虽然你说交易已经关联客户，还是建议登录Square后台确认下交易详情页是否确实显示了关联的客户信息，排除后台关联未生效的情况。

内容的提问来源于stack exchange，提问作者DokiCRO