# Add points to customer account

Manually adds loyalty points to a customer's account.

Common use cases:
- Grant bonus points for special promotions
- Compensate customers for issues or complaints
- Award points for actions tracked in external systems
- Bulk point adjustments during migrations
- Manual loyalty program adjustments

Request body fields:
- customerId OR customerEmail: Identify the customer (required, provide one)
- points: Number of points to add (required, must be positive)
- note: Description/reason for points addition (optional but recommended)
- earnRuleId: Associate with an earn rule (optional, for tracking purposes)

How it works:
1. Validates customer exists and is enrolled
2. Adds points to customer's available balance immediately
3. Creates a point transaction record with status "APPROVED"
4. Logs the activity with the provided note
5. Updates customer's total credited points
6. Syncs updated points to Shopify metafields
7. Returns updated customer loyalty information

Important notes:
- Points are added to availablePoints immediately (not pending)
- Points do NOT expire unless you have expiration rules configured
- Negative points not allowed (use separate remove points endpoint if available)
- Transaction is logged with source "MANUAL_ADJUSTMENT"
- Note field appears in customer's transaction history
- earnRuleId is optional and for categorization only

Best practices:
- Always include a descriptive note explaining why points were added
- Use consistent note format for easier reporting
- Consider using earnRuleId to group similar point additions
- Verify customer ID/email before making API call
- Points are added in real-time - no undo functionality

Example notes:
- "Bonus points for email signup - January promotion"
- "Compensation for delayed shipping - Order #1234"
- "Referral bonus from external system"
- "Migration - transferred from old loyalty system"
- "Birthday bonus - 2025"

Endpoint: POST /api/external/add-points

## Header parameters:

  - `X-API-Key` (string, required)
    API key for authentication

## Request fields (application/json):

  - `customerId` (integer,null)
    Shopify customer ID (numeric). Identifies which customer receives the points.
Provide either customerId OR customerEmail, not both.
Customer must be enrolled in the loyalty program.
Example: 67890
    Example: 67890

  - `customerEmail` (string,null)
    Customer's email address. Alternative to customerId for identifying the customer.
Provide either customerId OR customerEmail, not both.
Must be a valid email address that exists in your Shopify store.
Email matching is case-insensitive.
Example: customer@example.com
    Example: "customer@example.com"

  - `points` (number, required)
    Number of points to add to the customer's account. Must be a positive number.
Points are added to availablePoints immediately (not pending).
Decimal values are supported for fractional points.
Example: 50.0
    Example: 50

  - `earnRuleId` (integer,null)
    Optional: ID of an earn rule to associate with this point addition.
Used for categorization and reporting purposes only.
Does not affect point calculation - points parameter takes precedence.
Helps group similar types of point additions in reports.
Example: 10
    Example: 10

  - `note` (string,null)
    Optional but strongly recommended: Description of why points are being added.
This note appears in the customer's transaction history and admin logs.
Best practices:
- Be specific about the reason
- Include reference numbers (order ID, ticket ID, etc.)
- Use consistent formatting for easier reporting
Examples:
- "Birthday bonus - January 2025"
- "Compensation for delayed shipping - Order #1234"
- "Referral bonus from external campaign"
- "Migration - transferred from old system"
- "Manual adjustment per support ticket #567"
    Example: "Compensation for delayed shipping - Order #1234"

## Response 200 fields (application/json):

  - `availablePoints` (number)

  - `pendingPoints` (number)

  - `creditedPoints` (number)

  - `spentAmount` (number)

  - `storeCreditBalance` (number)

  - `achievableTierId` (integer)

  - `currentVipTier` (string)

  - `vipTierExpiredAt` (string)

  - `createAt` (string)

  - `rewardedForFacebook` (boolean)

  - `rewardedForPinterest` (boolean)

  - `rewardedForTwitter` (boolean)

  - `rewardedForInstagram` (boolean)

  - `rewardedForYoutube` (boolean)

  - `rewardedForTiktok` (boolean)

  - `rewardedForNewsLetter` (boolean)

  - `rewardedForSms` (boolean)

  - `referredCompleted` (integer)

  - `referralLink` (string)

  - `customerStatus` (string)
    Enum: "ACTIVE", "INACTIVE", "EXCLUDED", "EXCLUDED_BY_CUSTOMER"

  - `dob` (string)

  - `rewards` (array)

  - `rewards.id` (integer)

  - `rewards.shop` (string, required)

  - `rewards.customerId` (integer, required)

  - `rewards.description` (string)

  - `rewards.pointTransactionId` (integer)

  - `rewards.pointRedeemRuleId` (integer)

  - `rewards.discountCode` (string, required)

  - `rewards.usedAt` (string)

  - `rewards.orderId` (integer)

  - `rewards.orderName` (string)

  - `rewards.status` (string, required)
    Enum: "USED", "UNUSED", "REFUNDED", "EXPIRED", "SUBSCRIPTION_ACTIVE"

  - `rewards.expireDate` (string)

  - `rewards.variantId` (integer)

  - `rewards.discountCodeId` (string)

  - `rewards.productData` (string)

  - `rewards.usageCount` (integer)

  - `rewards.amount` (number)

  - `rewards.rewardType` (string)
    Enum: "STORE_CREDIT", "DISCOUNT_CODE", "POINTS"

  - `rewards.lastExpiryReminderSentDate` (string)

  - `rewardedForCreatingAccount` (boolean)

  - `rewardedForSharingOnFacebook` (boolean)

  - `rewardedForSharingOnX` (boolean)