Admin APIs

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Updates the status of a customer's discount code after checkout or subscription events.

Primary use case: Mark a discount code as "USED" after a customer completes checkout with the code. This prevents the code from being used again and keeps reward tracking accurate.

Request body:

• customerId: Shopify customer ID (required)
• discountCode: The discount code to update (required)
• status: New status for the code (required)

Valid status values:

• USED: Mark code as used after checkout (most common)
• SUBSCRIPTION_ACTIVE: Mark code as active for subscription renewals
• UNUSED: Reset code to unused state (use carefully)
• EXPIRED: Manually expire a code

What happens when you update status:

1. Validates discount code exists and belongs to customer
2. Updates the reward status in database
3. Syncs status to Shopify discount code system
4. Updates customer metafields in Shopify
5. Logs activity for audit trail
6. For subscriptions: manages discount code lifecycle

Subscription handling (SUBSCRIPTION_ACTIVE):

• When subscription is created: Set to SUBSCRIPTION_ACTIVE
• System automatically manages code for each renewal
• When subscription ends: Can revert to USED or delete
• Code may be deleted/recreated for each billing cycle

Common workflows:

One-time checkout:

1. Customer applies loyalty code at checkout
2. Order is created in Shopify
3. Call this endpoint with status="USED"
4. Code is now marked as used and can't be reused

Subscription checkout:

1. Customer applies code to subscription
2. Subscription is created
3. Call with status="SUBSCRIPTION_ACTIVE"
4. Code stays active for renewals
5. When subscription cancelled, call with status="USED"

Important notes:

• Marking code as USED is irreversible in normal operations
• SUBSCRIPTION_ACTIVE codes can be used for recurring orders
• System prevents using USED codes even if status is reset
• Activity log tracks all status changes
• Metafield sync updates customer data in Shopify theme

Error scenarios:

• Code already USED: Cannot mark as USED again (400 error)
• Code not found: Invalid discount code or customer (400 error)
• Wrong customer: Code belongs to different customer (400 error)

Best practices:

• Always call this after order creation webhooks
• Use order confirmation webhooks to trigger status update
• Handle 400 errors gracefully (code may already be marked used)
• For subscriptions, track subscription lifecycle events
• Don't call multiple times for same order (idempotency)

Validates a discount code for a specific customer before checkout.

When to use this:

• During checkout when customer enters a loyalty discount code
• Before applying discount to verify it belongs to the customer
• To check discount status and expiry
• To retrieve discount details (type, value, restrictions)

Request body:

• customerId: Shopify customer ID (required)
• discountCode: The discount code to validate (required, case-insensitive)

What this endpoint checks:

• Discount code exists in the system
• Code belongs to the specified customer
• Code status is "UNUSED" or "ACTIVE"
• Code has not expired
• Code is valid for current context

Response includes:

• Discount type (PERCENTAGE, FIXED_AMOUNT, FREE_SHIPPING, FREE_PRODUCT)
• Discount value (percentage or fixed amount)
• Expiry date
• Usage restrictions (minimum purchase, specific products, etc.)
• Points that were redeemed for this code
• Shopify discount code ID for reference

Discount statuses:

• UNUSED: Code has not been used yet (valid)
• ACTIVE: Code is being used in an active subscription (valid for renewals)
• USED: Code has already been redeemed (invalid)
• EXPIRED: Code has passed expiry date (invalid)

Integration pattern:

1. Customer enters loyalty code at checkout
2. Call this endpoint to validate the code
3. If 200 response, apply discount in checkout
4. After order is placed, call update-discount to mark as USED
5. Handle 400/404 by showing error message to customer

Common scenarios:

• Valid code: 200 with full discount details
• Wrong customer: 404 (code exists but for different customer)
• Already used: 400 with "Discount already used" message
• Expired: 400 with expiry information
• Invalid code: 404 (code doesn't exist)

Approves pending point transactions and converts them to available points.

When points are pending:

• Orders with pending fulfillment
• High-risk transactions requiring manual review
• Bulk point grants awaiting approval
• Refund/return waiting periods
• Custom approval workflows

Two approval modes:

Mode 1: Approve all pending transactions

• Set approveAllPendingTransactions=true
• Request body is ignored
• Approves ALL pending transactions for the shop
• Use for bulk approvals or automated workflows

Mode 2: Approve specific transactions

• Set approveAllPendingTransactions=false (or omit parameter)
• Provide pendingPointsApprovalList in request body
• Each item needs: customerId, points, transaction details
• Approves only specified transactions
• Use for selective/manual approval

How approval works:

1. Validates pending transactions exist
2. Queues approval process (asynchronous via AWS Step Functions)
3. Returns 204 immediately (doesn't wait for completion)
4. Background process:
   • Updates transaction status from PENDING to APPROVED
   • Adds points to customer's availablePoints
   • Updates creditedPoints total
   • Syncs to Shopify metafields
   • Logs approval activity
   • Triggers any applicable notifications

Important notes:

• This is an ASYNCHRONOUS operation
• Returns 204 immediately, processing happens in background
• Points may take a few seconds to appear in customer account
• No rollback after 204 response
• Cannot approve already-approved transactions
• Cannot approve rejected transactions

Request body structure (for specific approvals):

[
  {
    "customerId": 12345,
    "points": 50.0,
    "transactionId": 98765,
    "note": "Order fulfilled, approving points"
  }
]

Best practices:

• Use approveAllPendingTransactions=true for scheduled/automated approvals
• Use specific approval list for manual review workflows
• Monitor for completion by checking customer point balance
• Set up webhooks/polling to detect when approval completes
• Don't call repeatedly - it's queued asynchronously
• Consider rate limiting on your side for bulk approvals

Common use cases:

• Approve points after order fulfillment
• Batch approval at end of day/week
• Manual approval after fraud review
• Approve after return/refund window closes
• Integration with external approval systems

Error handling:

• 204: Success, approval queued (this is success, not an error)
• 400: Invalid request format or missing required data
• 401: Invalid API key

Processes a point redemption request and generates a discount code or reward.

How it works:

1. Validates customer has sufficient available points
2. Deducts points from customer's balance
3. Creates a discount code in Shopify (if applicable)
4. Creates a reward record with status "UNUSED"
5. Logs the transaction for audit trail
6. Returns updated customer loyalty information

Request body fields:

• customerId OR customerEmail: Identify the customer (provide one, not both)
• redeemRuleId: ID of the redemption rule to use (required)
• points: Number of points to redeem (optional - uses rule default if not provided)
• variantId: Product variant ID for product-specific rewards (optional, required for product rewards)

Redemption rule types:

• Fixed discount: Creates discount code for fixed amount off
• Percentage discount: Creates discount code for percentage off
• Free shipping: Creates free shipping discount code
• Free product: Creates discount code for free product (requires variantId)
• Store credit: Adds credit to customer's account

Important validation rules:

• Customer must have >= points required for redemption
• Customer must be enrolled in loyalty program
• Redemption rule must be active
• For product rewards, variantId is required
• Points are deducted immediately (transaction is atomic)

Common errors:

• "Insufficient points": Customer doesn't have enough available points
• "Redemption rule not found": Invalid redeemRuleId
• "Customer not found": Invalid customer ID/email
• "Variant ID required": Missing variantId for product reward
• "Customer not enrolled": Customer hasn't been enrolled in loyalty program

Best practices:

• Always check customer's availablePoints before attempting redemption
• Use GET /api/external/point-redeem-rules to get available redemption options
• Store the returned discount code for customer to use at checkout
• Monitor for 400 errors and handle insufficient points gracefully

Enrolls a customer into the loyalty program for a specific shop.

What this endpoint does:

• Activates loyalty features for the customer
• Allows the customer to start earning and redeeming points
• Creates necessary customer records in the loyalty system
• May trigger welcome rewards if configured

When to use this:

• After a new customer signs up on your store
• When enabling loyalty for existing customers
• During bulk customer migrations

Important notes:

• Customer must exist in Shopify before enrollment
• If customer is already enrolled, returns success without error
• Idempotent operation - safe to call multiple times
• Customer ID must be the Shopify customer ID (numeric)

Authentication: Requires X-API-Key header. Get your API key from the Loyalty app settings in your Shopify admin.

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"