CustomerAccount Resource

Use the CustomerAccount resource to access customer account data.

Resources:

CustomerAccount	Address	Order
OrderHistoryItem	LoyaltyAccount	Money

Schema type

Use customer-account to reference this resource in the template schema.

Querying

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

Be careful because using the customer account makes a template unable to be cached. Refer to this guide on how to load uncacheable resources with the template API.

Only orders originating from Square Online will populate under CustomerAccount orders

Note that a customer must be logged in for data to be available. If the customer is not logged in, the rendering engine will be provided with an empty array.

Sample Customer Account

{
  "__SO_RESOURCE_TYPE__": "customer_account", // internally used resource property. do not modify.
  "id": "127rty8l2962lbq99zq3s1mku",
  "resource_type": "CUSTOMER_ACCOUNT",
  "given_name": "Mark",
  "family_name_initial": "T",
  "orders": [
    {
      "address_to": {
        "address_line_1": "123 Elm Street",
        "administrative_district_level_1": "CA",
        "country": "US",
        "locality": "San Francisco",
        "postal_code": "94110"
      },
      "created_at": "2023-04-11T15:56:21+00:00",
      "fulfillment_method": "pickup",
      "id": "XFIABRW4WOIPJQDOPICHZLTGXIIZY",
      "items": [
        {
          "id": "Fb4hdcDkvOOPcQ3meHzkr",
          "name": "Trinket",
          "quantity": "1",
          "item_variation_id": "HATHXPJ65UAV76IB5LOB5Q75",
          "item_id": "2M36B2QDLMPWBIWVJYKFPIGE",
          "thumbnail_url": "https://squareup.com/trinket.jpeg",
          "modifiers": [
            {
              "id": "Lo3qMMckDluu9Qsb58d4CC",
              "name": "Cheese",
              "modifier_id": "CHQX7Y4KY6N5KINJKZCFURPZ",
              "modifier_list_id": "GIDYFNVGVJWLYMUA3EHMD6SZ",
              "quantity": "1",
              "base_price_money": {
                "amount": 50,
                "currency": "USD",
                "formatted": "$0.50"
              },
              "total_price_money": {
                "amount": 50,
                "currency": "USD",
                "formatted": "$0.50"
              }
            }
          ]
        }
      ],
      "location_id": "L36RW9ABXQTEE",
      "order_confirmation_url": "/store/status/XFIABRw4woipjqdOPiChzLtgXiIZY/confirmation",
      "order_date": "2023-04-11T15:56:21+00:00",
      "total_paid": {
          "amount": 0,
          "currency": "USD",
          "formatted": "$0.00"
      },
      "status": "OPEN",
      "updated_at": "2023-04-11T15:56:21+00:00"
    }
  ],
  "loyalty_account": {
    "id": "3d298055-faf9-4cdd-8d0f-07ddb8d7e7da",
    "program_id": "4495d6fa-b0ca-42a7-981a-88b77e15605b",
    "balance": 6,
    "lifetime_points": 123
  },
  "subscriptions": [
    {
      "id": "E4SAQSEMCZTV73DJ45IDTIJ2",
      "name": "Subscription Testing",
      "status": "ACTIVE",
      "charged_through_date": "2022-11-01",
      "items": [
          {
              "id": "E3M6QBTCS6YASBFTDOILOKIY",
              "square_online_id": 2,
              "name": "Shiny Pikachu",
              "thumbnail_url": "https://square-catalog-sandbox.s3.amazonaws.com/files/febae45897bdab1234dc3db23a7c0e66ddea6001/original.png"
          },
          {
              "id": "7BQA52U4O5KTALFUWAWVCCLQ",
              "square_online_id": 5,
              "name": "Jello",
              "thumbnail_url": null
          }
      ],
      "recurring_price": {
          "amount": 100,
          "currency": "USD",
          "formatted": "$1.00"
      },
      "cadence": "WEEKLY",
      "manage_url": "https://squareup.com/buyer-subscriptions/manage?buyer_management_token=EBt6C-OPRTUVWHbIZ8jDbnlCy9EQylBUnvuuOv0ovpH2usXaPWDT_6Qe7hgA_Jbl5EFjKofHix5zaN1pAuBnLMyBHq0bVgi3JWjfxTv14WCEX92_1bWAicD-_9mP8HS6Lg%3D%3D"
    }
  ],
  "profile_url": "https://profile.squareup.com"
}

CustomerAccount resources

CustomerAccount

A customer account.

Field	Type	Description
`id`	`String`	Customer Account ID
`resource_type`	`String`	The resource type identifier
`given_name`	`String`	Customer’s given name
`family_name_initial`	`String`	Customer’s family name initial
`orders`	`Order[]`	Order history for the customer account
`subscriptions`	`Subscription[]`	Customer’s subscriptions
`loyalty_account`	`LoyaltyAccount`	Loyalty account details

Address

A physical address.

Field	Type	Description
`address_line_1`	`String`	The first line of the address
`address_line_2`	`String`	The second line of the address, if any
`administrative_district_level_1`	`String`	A civil entity within the address’s country. In the US, this is the state
`country`	`String`	The address’s country, in the two-letter format of ISO 3166. For example, US or FR
`first_name`	`String`	First name
`label`	`String`	Address type label. Can be `Billing` or `Shipping`
`last_name`	`String`	Last name
`locality`	`String`	The city or town of the address
`phone`	`Phone`	Phone associated with the address
`postal_code`	`String`	The address’s postal code

Order

An order purchased by a customer.

Field	Type	Description
`address_to`	`Address`	Address associated with the order
`created_at`	`String`	Timestamp when the order was created
`fulfillment_method`	`String`	Fulfillment method
`id`	`String`	Order ID
`items`	`OrderHistoryItem[]`	Line items for the order
`location_id`	`String`	Store location ID
`order_confirmation_url`	`String`	URL to the order confirmation page
`order_date`	`String`	Timestamp when the order was placed
`status`	`String`	Order status
`total_paid`	`Money`	Total amount of money
`updated_at`	`String`	When the order was last updated

OrderHistoryItem

A line item in a purchased order.

Field	Type	Description
`id`	`String`	Item ID that’s representative of the line item only within the order. This does not match up with an `Item` resource
`name`	`String`	The name of the Item
`quantity`	`String`	The count, or measurement, of a line item being purchased
`item_variation_id`	`String`	The ItemVariation ID
`item_id`	`String`	The Item ID
`modifiers`	`OrderHistoryItemModifier[]`	The modifiers that have been applied to this line item.
`thumbnail_url`	`String`	Absolute URL to the item’s primary image

OrderHistoryItemModifier

The modifiers that have been applied to this line item.

Field	Type	Description
`id`	`String`	A unique ID that identifies the modifier only within this order.
`name`	`String`	Modifier name
`modifier_id`	`String`	Modifier ID
`modifier_list_id`	`String`	ModifierList ID
`quantity`	`String`	Quantity of modifiers
`base_price_money`	`Money`	The price of the individual item modifier
`total_price_money`	`Money`	The total price of the item modifier for its line item. This is the modifier’s base_price_money multiplied by the line item’s quantity.

Subscription

A subscription purchased by a customer.

Field	Type	Description
`id`	`String`	Subscription ID
`name`	`String`	Subscription name
`status`	`String`	Current status of the subscription. Enum: PENDING, ACTIVE, CANCELED, DEACTIVATED, PAUSED
`charged_through_date`	`String`	The `YYYY-MM-DD`-formatted date up to when the subscriber is invoiced for the subscription
`items`	`SubscriptionItem[]`	Items included in the subscription
`recurring_price`	`Money`	Money paid on reoccurring basis
`cadence`	`String`	Cadence of the subscription. Enum: WEEKLY, EVERY_TWO_WEEKS, MONTHLY, QUARTERLY, ANNUAL
`manage_url`	`String`	URL for the customer to manage their subscription

SubscriptionItem

A line item in a purchased subscription.

Field	Type	Description
`id`	`String`	Subscription ID
`square_online_id`	`String`	Subscription ID for online store
`name`	`String`	Name of the subscription line item
`thumbnail_url`	`String`	URL to the subscription line item thumbnail

LoyaltyAccount

A customer’s loyalty account details. Note: this field will be null if the customer does not have a loyalty account.

Field	Type	Description
`id`	`String`	Loyalty Account ID
`program_id`	`String`	ID of the seller’s loyalty program to which the account belongs
`balance`	`Number`	The available point balance in the loyalty account
`lifetime_points`	`Number`	The total points accrued during the lifetime of the account
`available_reward_tiers`	`RewardTier`	The available reward tiers for the account’s balance
`upcoming_reward_tiers`	`RewardTier`	The upcoming reward tiers for the account’s balance

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