Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Loyalty

  • Create loyalty account

  • Search loyalty accounts

  • Retrieve loyalty account

  • Accumulate loyalty points

  • Adjust loyalty points

  • Search loyalty events

  • Retrieve loyalty program

  • Calculate loyalty points

  • List loyalty promotions

  • Create loyalty promotion

  • Retrieve loyalty promotion

  • Cancel loyalty promotion

  • Create loyalty reward

  • Search loyalty rewards

  • Delete loyalty reward

  • Retrieve loyalty reward

  • Redeem loyalty reward

  • Webhooks

  • loyalty.account.created

  • loyalty.account.deleted

  • loyalty.account.updated

  • loyalty.event.created

  • loyalty.program.created

  • loyalty.program.updated

  • loyalty.promotion.created

  • loyalty.promotion.updated

<- Loyalty API

Loyalty API

All versions ->

Create loyalty account

POST

 /v2/loyalty/accounts

Creates a loyalty account.

To create a loyalty account, you must provide the program_id and a mapping with the phone_number of the buyer.

Permissions:LOYALTY_WRITE

Guide

Create loyalty account

Try in API Explorer
Link to section

Request body

Example code

Link to section

loyalty_account

Required

The loyalty account to create.

Link to section

idempotency_key

string

Required

A unique string that identifies this CreateLoyaltyAccount request. Keys can be any valid string, but must be unique for every request.

Min Length
1
Max Length
128
Link to section

Response fields

Link to section

errors

Any errors that occurred during the request.

Link to section

loyalty_account

The newly created loyalty account.

Link to section

Examples

All versions ->

POST /v2/loyalty/accounts
curl https://connect.squareup.com/v2/loyalty/accounts \ -X POST \ -H 'Square-Version: 2026-09-16' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "loyalty_account": { "mapping": { "phone_number": "+14155551234" }, "program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd" }, "idempotency_key": "ec78c477-b1c3-4899-a209-a4e71337c996" }'

Response JSON

{ "loyalty_account": { "id": "79b807d2-d786-46a9-933b-918028d7a8c5", "mapping": { "id": "66aaab3f-da99-49ed-8b19-b87f851c844f", "phone_number": "+14155551234", "created_at": "2020-05-08T21:44:32Z" }, "program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd", "balance": 0, "lifetime_points": 0, "customer_id": "QPTXM8PQNX3Q726ZYHPMNP46XC", "created_at": "2020-05-08T21:44:32Z", "updated_at": "2020-05-08T21:44:32Z" } }

Error descriptions

400 Bad request

{ "errors": [ { "code": "INVALID_PHONE_NUMBER", "category": "INVALID_REQUEST_ERROR" } ] }