Skip to main content

Client Credits

Client credits are prepaid sessions or credits that clients use to book appointments and classes, the same as Add credits on a client's profile in the app. Each call works on one grant: the credits given to one client in one go.

A grant is one of two types:

TypeWhat the client getsWhat a booking uses
session_packA number of sessions per service (and variant), for example 10 yoga classes1 session of the booked service
credit_balanceOne balance of credits for all services or selected ones, or unlimitedThe service's credits per booking

How it works:

  • Counts are what is left. count sets the remaining sessions or credits, not an amount to add. To top up, read the grant and send the new total.
  • Your own id. Send externalId (for example the order number in your shop) and POST /v1/credits with the same externalId updates that grant instead of creating a new one, so retries never give credits twice.
  • Bookings use credits automatically. Booking with appointments or classes uses a matching active grant and returns a credit object. A cancelled booking gives the credit back.
  • Status: active, expired (past expiryDate), completed (nothing left) or disabled (paused).
  • Plan: giving credits needs the Sales add-on. Reading, changing, pausing and deleting existing grants always work.

The {id} in a path is the record id returned by the API (for example 5tw9zcQkbu), not the client number shown in the app.

API regionapi.whautomate.com

List credits​

GET /v1/credits

Lists client credit grants, newest first. status is active, expired, completed or disabled.

Headers
x-api-keystringrequired
Your Whautomate API key.
Query parameters
locationIdstring
Only grants usable at this location.
clientIdstring
Only the grants of this client.
externalIdstring
The grant with your own id.
statusstring
One of active, expired, completed, disabled.
pageinteger
Page number, from 1 (default 1).
limitinteger
Results per page (default 10, max 100).
Response 200
idstring
externalIdstring
Your own id for the grant (null when not set)
codestring
clientobject
locationsobject[]

Locations where the credits can be used

expiryDatestring
YYYY-MM-DD in the account timezone, null for no expiry
statusstring (enum)
One of: active, expired, completed, disabled.
disabledboolean
Paused: booking skips the grant; a cancelled booking still gets its credit back
typestring (enum)
session_pack: sessions per service, each booking uses 1 session. credit_balance: one balance of credits used across services, each booking uses the service's creditsPerBooking. One of: session_pack, credit_balance.
sessionsobject[]

Session pack lines; empty for a credit balance

creditBalanceobject

The credit balance; null for a session pack

notesstring
createdAtstring
updatedAtstring
createdboolean
POST and PUT responses only: true when the call created the grant
Request
curl -X GET "https://api.whautomate.com/v1/credits?clientId=FLT22gHGml&limit=2" \
  -H "x-api-key: YOUR_API_KEY"
Response 200
[
  {
    "id": "taNZ9FxeQL",
    "externalId": "shop-order-1043",
    "code": "7fa050e1",
    "client": {
      "id": "FLT22gHGml",
      "name": "Priya Nair"
    },
    "locations": [
      {
        "id": "Le6dWjQF9K",
        "title": "Serene Wellness Studio"
      }
    ],
    "expiryDate": "2027-01-27",
    "status": "active",
    "disabled": false,
    "type": "credit_balance",
    "sessions": [],
    "creditBalance": {
      "remaining": 10,
      "unlimited": false,
      "appliesTo": "selected",
      "serviceIds": [
        "9g0PbP1Hau",
        "BICnvnGBgO"
      ]
    },
    "notes": "10 class credits for yoga or Pilates.",
    "createdAt": "2026-10-29T12:40:19.351Z",
    "updatedAt": "2026-10-29T12:40:19.360Z"
  },
  {
    "id": "lxOL3532D3",
    "externalId": "shop-order-1042",
    "code": "a3cf3a55",
    "client": {
      "id": "FLT22gHGml",
      "name": "Priya Nair"
    },
    "locations": [
      {
        "id": "Le6dWjQF9K",
        "title": "Serene Wellness Studio"
      }
    ],
    "expiryDate": "2027-01-27",
    "status": "active",
    "disabled": false,
    "type": "session_pack",
    "sessions": [
      {
        "serviceId": "THF7D9KbDa",
        "serviceName": "Deep Tissue Massage",
        "variantId": null,
        "variantName": null,
        "total": 6,
        "remaining": 6
      }
    ],
    "creditBalance": null,
    "notes": "Upgraded to 6 massages.",
    "createdAt": "2026-10-29T12:40:19.211Z",
    "updatedAt": "2026-10-29T12:40:19.511Z"
  }
]

Get a credit grant​

GET /v1/credits/{creditId}

Gets a credit grant.

Headers
x-api-keystringrequired
Your Whautomate API key.
Path parameters
creditIdstringrequired
Response 200
idstring
externalIdstring
Your own id for the grant (null when not set)
codestring
clientobject
locationsobject[]

Locations where the credits can be used

expiryDatestring
YYYY-MM-DD in the account timezone, null for no expiry
statusstring (enum)
One of: active, expired, completed, disabled.
disabledboolean
Paused: booking skips the grant; a cancelled booking still gets its credit back
typestring (enum)
session_pack: sessions per service, each booking uses 1 session. credit_balance: one balance of credits used across services, each booking uses the service's creditsPerBooking. One of: session_pack, credit_balance.
sessionsobject[]

Session pack lines; empty for a credit balance

creditBalanceobject

The credit balance; null for a session pack

notesstring
createdAtstring
updatedAtstring
createdboolean
POST and PUT responses only: true when the call created the grant
Request
curl -X GET "https://api.whautomate.com/v1/credits/lxOL3532D3" \
  -H "x-api-key: YOUR_API_KEY"
Response 200
{
  "id": "lxOL3532D3",
  "externalId": "shop-order-1042",
  "code": "a3cf3a55",
  "client": {
    "id": "FLT22gHGml",
    "name": "Priya Nair"
  },
  "locations": [
    {
      "id": "Le6dWjQF9K",
      "title": "Serene Wellness Studio"
    }
  ],
  "expiryDate": "2027-01-27",
  "status": "active",
  "disabled": false,
  "type": "session_pack",
  "sessions": [
    {
      "serviceId": "THF7D9KbDa",
      "serviceName": "Deep Tissue Massage",
      "variantId": null,
      "variantName": null,
      "total": 6,
      "remaining": 6
    }
  ],
  "creditBalance": null,
  "notes": "Upgraded to 6 massages.",
  "createdAt": "2026-10-29T12:40:19.211Z",
  "updatedAt": "2026-10-29T12:40:19.511Z"
}

Give credits to a client​

POST /v1/credits

Adds credits to a client (as Add credits in the client profile), or updates the grant with the same externalId. Response includes created. Creating needs the Sales module.

Send either sessions (session pack) or creditBalance (credit balance), not both. The examples show one of each, and a second call with the same externalId that updates the grant.

Headers
x-api-keystringrequired
Your Whautomate API key.
Body
externalIdstring
Your own id (1 to 200 characters, unique in the account). POST with a known externalId updates that grant. Send an empty string to clear it.
clientIdstring
Required to create. Credits cannot move to another client.
locationIdsstring[]
Locations where the credits can be used (defaults to the client primary location). A new grant belongs to the first one.
expiryDatestring
YYYY-MM-DD in the account timezone, usable to the end of that day. Send an empty string for no expiry.
notesstring
sessionsobject[]

Session pack: sessions per service, 1 used per booking. Replaces the lines: a line with the same service and variant keeps its used count. Not with creditBalance.

creditBalanceobject

A credit balance usable across services (each booking uses the service's creditsPerBooking). Not with sessions.

Response 200
idstring
externalIdstring
Your own id for the grant (null when not set)
codestring
clientobject
locationsobject[]

Locations where the credits can be used

expiryDatestring
YYYY-MM-DD in the account timezone, null for no expiry
statusstring (enum)
One of: active, expired, completed, disabled.
disabledboolean
Paused: booking skips the grant; a cancelled booking still gets its credit back
typestring (enum)
session_pack: sessions per service, each booking uses 1 session. credit_balance: one balance of credits used across services, each booking uses the service's creditsPerBooking. One of: session_pack, credit_balance.
sessionsobject[]

Session pack lines; empty for a credit balance

creditBalanceobject

The credit balance; null for a session pack

notesstring
createdAtstring
updatedAtstring
createdboolean
POST and PUT responses only: true when the call created the grant
Errors
StatusErrorMeaning
400Invalid parametersNeither or both of sessions and creditBalance, a count below 0, or a service that is not bookable.
403This feature is not included in your plan.Creating a grant needs the Sales add-on.
404Client not foundThe client is not in your account.
Request: Session pack
curl -X POST "https://api.whautomate.com/v1/credits" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "shop-order-1042",
    "clientId": "FLT22gHGml",
    "expiryDate": "2027-01-27",
    "notes": "Bought 5 massages in the online shop.",
    "sessions": [
      {
        "serviceId": "THF7D9KbDa",
        "count": 5
      }
    ]
  }'
Response 200: Session pack
{
  "created": true,
  "id": "lxOL3532D3",
  "externalId": "shop-order-1042",
  "code": "a3cf3a55",
  "client": {
    "id": "FLT22gHGml",
    "name": "Priya Nair"
  },
  "locations": [
    {
      "id": "Le6dWjQF9K",
      "title": "Serene Wellness Studio"
    }
  ],
  "expiryDate": "2027-01-27",
  "status": "active",
  "disabled": false,
  "type": "session_pack",
  "sessions": [
    {
      "serviceId": "THF7D9KbDa",
      "serviceName": "Deep Tissue Massage",
      "variantId": null,
      "variantName": null,
      "total": 5,
      "remaining": 5
    }
  ],
  "creditBalance": null,
  "notes": "Bought 5 massages in the online shop.",
  "createdAt": "2026-10-29T12:40:19.211Z",
  "updatedAt": "2026-10-29T12:40:19.246Z"
}
Request: Credit balance
curl -X POST "https://api.whautomate.com/v1/credits" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "shop-order-1043",
    "clientId": "FLT22gHGml",
    "expiryDate": "2027-01-27",
    "notes": "10 class credits for yoga or Pilates.",
    "creditBalance": {
      "count": 10,
      "serviceIds": [
        "9g0PbP1Hau",
        "BICnvnGBgO"
      ]
    }
  }'
Response 200: Credit balance
{
  "created": true,
  "id": "taNZ9FxeQL",
  "externalId": "shop-order-1043",
  "code": "7fa050e1",
  "client": {
    "id": "FLT22gHGml",
    "name": "Priya Nair"
  },
  "locations": [
    {
      "id": "Le6dWjQF9K",
      "title": "Serene Wellness Studio"
    }
  ],
  "expiryDate": "2027-01-27",
  "status": "active",
  "disabled": false,
  "type": "credit_balance",
  "sessions": [],
  "creditBalance": {
    "remaining": 10,
    "unlimited": false,
    "appliesTo": "selected",
    "serviceIds": [
      "9g0PbP1Hau",
      "BICnvnGBgO"
    ]
  },
  "notes": "10 class credits for yoga or Pilates.",
  "createdAt": "2026-10-29T12:40:19.351Z",
  "updatedAt": "2026-10-29T12:40:19.360Z"
}
Request: Same externalId: the grant is updated
curl -X POST "https://api.whautomate.com/v1/credits" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "shop-order-1042",
    "clientId": "FLT22gHGml",
    "notes": "Upgraded to 6 massages.",
    "sessions": [
      {
        "serviceId": "THF7D9KbDa",
        "count": 6
      }
    ]
  }'
Response 200: Same externalId: the grant is updated
{
  "created": false,
  "id": "lxOL3532D3",
  "externalId": "shop-order-1042",
  "code": "a3cf3a55",
  "client": {
    "id": "FLT22gHGml",
    "name": "Priya Nair"
  },
  "locations": [
    {
      "id": "Le6dWjQF9K",
      "title": "Serene Wellness Studio"
    }
  ],
  "expiryDate": "2027-01-27",
  "status": "active",
  "disabled": false,
  "type": "session_pack",
  "sessions": [
    {
      "serviceId": "THF7D9KbDa",
      "serviceName": "Deep Tissue Massage",
      "variantId": null,
      "variantName": null,
      "total": 6,
      "remaining": 6
    }
  ],
  "creditBalance": null,
  "notes": "Upgraded to 6 massages.",
  "createdAt": "2026-10-29T12:40:19.211Z",
  "updatedAt": "2026-10-29T12:40:19.511Z"
}
Response 400: Both sessions and creditBalance
{
  "error": "Send either sessions (session pack) or creditBalance (credit balance), not both."
}

Update a credit grant​

PUT /v1/credits/{creditId}

Updates a grant. Only the fields you send change. Sent sessions replace the lines, but a line for the same service and variant keeps the sessions already used. Switching a session pack to creditBalance drops its session lines. A grant cannot move to another client.

Headers
x-api-keystringrequired
Your Whautomate API key.
Path parameters
creditIdstringrequired
Body
externalIdstring
Your own id (1 to 200 characters, unique in the account). POST with a known externalId updates that grant. Send an empty string to clear it.
clientIdstring
Required to create. Credits cannot move to another client.
locationIdsstring[]
Locations where the credits can be used (defaults to the client primary location). A new grant belongs to the first one.
expiryDatestring
YYYY-MM-DD in the account timezone, usable to the end of that day. Send an empty string for no expiry.
notesstring
sessionsobject[]

Session pack: sessions per service, 1 used per booking. Replaces the lines: a line with the same service and variant keeps its used count. Not with creditBalance.

creditBalanceobject

A credit balance usable across services (each booking uses the service's creditsPerBooking). Not with sessions.

Response 200
idstring
externalIdstring
Your own id for the grant (null when not set)
codestring
clientobject
locationsobject[]

Locations where the credits can be used

expiryDatestring
YYYY-MM-DD in the account timezone, null for no expiry
statusstring (enum)
One of: active, expired, completed, disabled.
disabledboolean
Paused: booking skips the grant; a cancelled booking still gets its credit back
typestring (enum)
session_pack: sessions per service, each booking uses 1 session. credit_balance: one balance of credits used across services, each booking uses the service's creditsPerBooking. One of: session_pack, credit_balance.
sessionsobject[]

Session pack lines; empty for a credit balance

creditBalanceobject

The credit balance; null for a session pack

notesstring
createdAtstring
updatedAtstring
createdboolean
POST and PUT responses only: true when the call created the grant
Request
curl -X PUT "https://api.whautomate.com/v1/credits/lxOL3532D3" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expiryDate": "2027-02-26",
    "notes": "Expiry extended as a goodwill gesture."
  }'
Response 200
{
  "created": false,
  "id": "lxOL3532D3",
  "externalId": "shop-order-1042",
  "code": "a3cf3a55",
  "client": {
    "id": "FLT22gHGml",
    "name": "Priya Nair"
  },
  "locations": [
    {
      "id": "Le6dWjQF9K",
      "title": "Serene Wellness Studio"
    }
  ],
  "expiryDate": "2027-02-26",
  "status": "active",
  "disabled": false,
  "type": "session_pack",
  "sessions": [
    {
      "serviceId": "THF7D9KbDa",
      "serviceName": "Deep Tissue Massage",
      "variantId": null,
      "variantName": null,
      "total": 6,
      "remaining": 6
    }
  ],
  "creditBalance": null,
  "notes": "Expiry extended as a goodwill gesture.",
  "createdAt": "2026-10-29T12:40:19.211Z",
  "updatedAt": "2026-10-29T12:40:19.814Z"
}

Pause a credit grant​

POST /v1/credits/{creditId}/disable

Pauses a grant (e.g. while unpaid): booking skips it, a cancelled booking still gets its credit back. No request body.

Headers
x-api-keystringrequired
Your Whautomate API key.
Path parameters
creditIdstringrequired
Response 200
idstring
externalIdstring
Your own id for the grant (null when not set)
codestring
clientobject
locationsobject[]

Locations where the credits can be used

expiryDatestring
YYYY-MM-DD in the account timezone, null for no expiry
statusstring (enum)
One of: active, expired, completed, disabled.
disabledboolean
Paused: booking skips the grant; a cancelled booking still gets its credit back
typestring (enum)
session_pack: sessions per service, each booking uses 1 session. credit_balance: one balance of credits used across services, each booking uses the service's creditsPerBooking. One of: session_pack, credit_balance.
sessionsobject[]

Session pack lines; empty for a credit balance

creditBalanceobject

The credit balance; null for a session pack

notesstring
createdAtstring
updatedAtstring
createdboolean
POST and PUT responses only: true when the call created the grant
Request
curl -X POST "https://api.whautomate.com/v1/credits/lxOL3532D3/disable" \
  -H "x-api-key: YOUR_API_KEY"
Response 200
{
  "id": "lxOL3532D3",
  "externalId": "shop-order-1042",
  "code": "a3cf3a55",
  "client": {
    "id": "FLT22gHGml",
    "name": "Priya Nair"
  },
  "locations": [
    {
      "id": "Le6dWjQF9K",
      "title": "Serene Wellness Studio"
    }
  ],
  "expiryDate": "2027-02-26",
  "status": "disabled",
  "disabled": true,
  "type": "session_pack",
  "sessions": [
    {
      "serviceId": "THF7D9KbDa",
      "serviceName": "Deep Tissue Massage",
      "variantId": null,
      "variantName": null,
      "total": 6,
      "remaining": 6
    }
  ],
  "creditBalance": null,
  "notes": "Expiry extended as a goodwill gesture.",
  "createdAt": "2026-10-29T12:40:19.211Z",
  "updatedAt": "2026-10-29T12:40:19.898Z"
}

Resume a credit grant​

POST /v1/credits/{creditId}/enable

Turns a paused grant back on for booking (status refreshed). No request body.

Headers
x-api-keystringrequired
Your Whautomate API key.
Path parameters
creditIdstringrequired
Response 200
idstring
externalIdstring
Your own id for the grant (null when not set)
codestring
clientobject
locationsobject[]

Locations where the credits can be used

expiryDatestring
YYYY-MM-DD in the account timezone, null for no expiry
statusstring (enum)
One of: active, expired, completed, disabled.
disabledboolean
Paused: booking skips the grant; a cancelled booking still gets its credit back
typestring (enum)
session_pack: sessions per service, each booking uses 1 session. credit_balance: one balance of credits used across services, each booking uses the service's creditsPerBooking. One of: session_pack, credit_balance.
sessionsobject[]

Session pack lines; empty for a credit balance

creditBalanceobject

The credit balance; null for a session pack

notesstring
createdAtstring
updatedAtstring
createdboolean
POST and PUT responses only: true when the call created the grant
Request
curl -X POST "https://api.whautomate.com/v1/credits/lxOL3532D3/enable" \
  -H "x-api-key: YOUR_API_KEY"
Response 200
{
  "id": "lxOL3532D3",
  "externalId": "shop-order-1042",
  "code": "a3cf3a55",
  "client": {
    "id": "FLT22gHGml",
    "name": "Priya Nair"
  },
  "locations": [
    {
      "id": "Le6dWjQF9K",
      "title": "Serene Wellness Studio"
    }
  ],
  "expiryDate": "2027-02-26",
  "status": "active",
  "disabled": false,
  "type": "session_pack",
  "sessions": [
    {
      "serviceId": "THF7D9KbDa",
      "serviceName": "Deep Tissue Massage",
      "variantId": null,
      "variantName": null,
      "total": 6,
      "remaining": 6
    }
  ],
  "creditBalance": null,
  "notes": "Expiry extended as a goodwill gesture.",
  "createdAt": "2026-10-29T12:40:19.211Z",
  "updatedAt": "2026-10-29T12:40:20.020Z"
}

Delete a credit grant​

DEL /v1/credits/{creditId}

Deletes a credit grant (soft delete, as the app does).

Headers
x-api-keystringrequired
Your Whautomate API key.
Path parameters
creditIdstringrequired
Response 200
idstring
removedboolean
Request
curl -X DELETE "https://api.whautomate.com/v1/credits/taNZ9FxeQL" \
  -H "x-api-key: YOUR_API_KEY"
Response 200
{
  "id": "taNZ9FxeQL",
  "removed": true
}
Last updated on