# Update discount code status

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)

Endpoint: PUT /api/external/update-discount

## Request fields (application/json):

  - `customerId` (integer, required)
    Shopify customer ID (numeric). Identifies which customer owns the discount code.
Used to verify the discount code belongs to this customer before updating.
Example: 67890
    Example: 67890

  - `discountCode` (string, required)
    The discount code to update. Case-insensitive.
Must be a valid loyalty discount code that belongs to the specified customer.
Examples: "LOYALTY15OFF", "VIP20", "WELCOME10"
    Example: "LOYALTY15OFF"

  - `status` (string, required)
    New status for the discount code. Valid 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

Status transitions:
- UNUSED → USED: Normal checkout flow
- UNUSED → SUBSCRIPTION_ACTIVE: Subscription created
- SUBSCRIPTION_ACTIVE → USED: Subscription ended
- Any → EXPIRED: Manual expiration

Note: Cannot mark already USED codes as USED again.
    Enum: "USED", "UNUSED", "REFUNDED", "EXPIRED", "SUBSCRIPTION_ACTIVE", "USED", "UNUSED", "SUBSCRIPTION_ACTIVE", "EXPIRED"

## Response 200 fields (application/json):

  - `id` (integer)

  - `shop` (string, required)

  - `customerId` (integer, required)

  - `description` (string)

  - `pointTransactionId` (integer)

  - `pointRedeemRuleId` (integer)

  - `discountCode` (string, required)

  - `usedAt` (string)

  - `orderId` (integer)

  - `orderName` (string)

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

  - `createAt` (string, required)

  - `expireDate` (string)

  - `variantId` (integer)

  - `discountCodeId` (string)

  - `productData` (string)

  - `usageCount` (integer)

  - `amount` (number)

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

  - `lastExpiryReminderSentDate` (string)