Loyalty Admin API

Write Call

AdjustCustomerPoints3

Give or take away one customer's points: goodwill or compensation points, corrections, returning spent points to the balance, or marking available points as spent.

Kind Write API call
Method POST
URL https://app.bubblehouse.com/api/v2023061/<shop>/AdjustCustomerPoints3
Authentication Admin Customer TokenShop Token

Pick the action by what should happen to the customer's earned points, which drive the tier:

  • give_points adds points as if the customer earned them. Earned points grow, so the tier can go up.
  • takeaway_points removes earned points. The tier can go down.
  • unspend_points moves points from spent back to available. Earned points and the tier stay as they are. If the customer has spent fewer points than requested, the rest is added as earned points. In customer support this is often the better way to return points.
  • takeaway_points_as_spent moves available or pending points to spent. Earned points and the tier stay as they are.

One adjustment per call. To apply several adjustments in one request, or for the less common actions, use AdjustCustomerState3.

Input

  • customer CustomerIdentity1 required if using a shop token

    A customer to operate upon, when using a shop token.

    If you're using a customer token and decide to pass this field (which we do not recommend), it must match the customer from the token.

  • action AdjustmentAction1 required

    What to do with the points: give_points, takeaway_points, unspend_points or takeaway_points_as_spent. There is no default.

  • points integer required

    The number of points to add or take away, a positive integer or zero.

  • description string optional

    Customer-visible description of the change.

  • private_note string optional

    Extra information about the change for the staff eyes only.

Output

A successful response has no meaningful properties and only contains an ok property always set to true:

{"ok": true}

Usage Examples

Give goodwill points

Request

{
  "action": "give_points",
  "customer": {
    "email": "alice@example.com"
  },
  "description": "Sorry for the late delivery",
  "points": 200
}

Response

{
  "ok": true
}

Specific Errors

Status Error Reason & Examples
400 adjustment_missing_required_field

The action is missing or is not one this call accepts, or points is missing.

Global Errors

Status Error Reason & Examples
400 inaccessible_global_api_version

The global API version you are trying to use is not enabled on your account.

400 obsolete_global_api_version

The global API version you are trying to use is no longer supported.

429 rate_limit_exceeded

Your usage is over the rate limit. Ensure that you're not making duplicate calls, and contact our team for a rate limit increase.

For example: You are over the read limit per second for this customer

400 invalid_global_api_version

The global API version you are trying to use has never existed.

401 invalid_token

The provided authentication token is invalid or has expired.

For example: The token has expired

Previous
AdjustCustomerMark3