Loyalty Admin API

Write Call

AdjustCustomerTier3

Change one customer's tier by hand: upgrade to a tier (VIP upgrade), move to any tier including a lower one, or restart the current tier's expiration timer.

Kind Write API call
Method POST
URL https://app.bubblehouse.com/api/v2023061/<shop>/AdjustCustomerTier3
Authentication Admin Customer TokenShop Token
  • upgrade_tier raises the customer to the given tier. They keep at least that tier until it expires or another manual adjustment is made. It does nothing if the customer is already at that tier or higher.
  • reset_tier moves the customer to the given tier, higher or lower, and restarts its expiration timer. Lifetime points and spend are not zeroed, so a later automatic update can still move the customer if they qualify.
  • reset_tier_expiration restarts the expiration timer of the customer's current tier. It takes no tier.

Name the tier by subject_id or subject_slug, not both; CustomerBalance3 with include_full_program lists the shop's tiers. The call fails for a customer with the disable_tiers mark and needs a shop or customer-admin token.

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: upgrade_tier, reset_tier or reset_tier_expiration. There is no default.

  • subject_id bubbleflake either subject_id or subject_slug, except for reset_tier_expiration

    The Bubblehouse ID of the tier.

  • subject_slug string either subject_id or subject_slug, except for reset_tier_expiration

    The slug of the tier.

  • description string optional

    Customer-visible description of the change.

Output

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

{"ok": true}

Usage Examples

Upgrade a customer to Gold

Request

{
  "action": "upgrade_tier",
  "customer": {
    "email": "alice@example.com"
  },
  "description": "VIP upgrade",
  "subject_slug": "gold"
}

Response

{
  "ok": true
}

Specific Errors

Status Error Reason & Examples
403 access_denied

A customer token cannot change tiers. Use a shop token or a customer-admin token.

404 adjustment_subject_missing

The tier is missing, both subject fields were set, or the tier is unknown or not enabled in this venue.

400 adjustment_missing_required_field

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

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
AdjustCustomerState3