Store Credit Module Workflows

Workflows are a series of queries and actions, called steps, that complete a task. By using workflows, you benefit from features like data consistency and a reliable roll-back mechanism.

The Store Credit Module provides workflows and steps to manage store credit accounts and their usage in carts. These are provided by the @medusajs/loyalty-plugin package.

Store Credit Account Management Workflows#

Create Store Credit Accounts#

Create new store credit accounts for customers:

Code
1import { createStoreCreditAccountsWorkflow } from "@medusajs/loyalty-plugin/workflows"2
3const { result } = await createStoreCreditAccountsWorkflow(container)4  .run({5    input: {6      customer_id: "cust_123",7      currency_code: "usd",8      code: "SC-XXXX", // optional, auto-generated if not provided9    },10  })

Claim Store Credit Account#

Claim a store credit account for a customer:

Code
1import { claimStoreCreditAccountWorkflow } from "@medusajs/loyalty-plugin/workflows"2
3const { result } = await claimStoreCreditAccountWorkflow(container)4  .run({5    input: {6      customer_id: "cust_123",7      code: "SC-XXXX",8    },9  })

Credit and Debit Operations#

Credit Store Credit Account#

Add credits to a store credit account:

Code
1import { creditStoreCreditAccountWorkflow } from "@medusajs/loyalty-plugin/workflows"2
3const { result } = await creditStoreCreditAccountWorkflow(container)4  .run({5    input: {6      account_id: "sca_123",7      amount: 100,8      note: "Refund for order #1234",9      reference: "order",10      reference_id: "order_123",11    },12  })

Credit Accounts Workflow#

Credit multiple store credit accounts:

Code
1import { creditAccountsWorkflow } from "@medusajs/loyalty-plugin/workflows"2
3const { result } = await creditAccountsWorkflow(container)4  .run({5    input: [6      {7        account_id: "sca_123",8        amount: 100,9        reference: "order",10        reference_id: "order_123",11      },12      {13        account_id: "sca_456",14        amount: 50,15        reference: "refund",16        reference_id: "refund_123",17      },18    ],19  })

Debit Store Credit Account#

Debit a single store credit account by a specified amount. The workflow validates that the amount is greater than zero and that the account exists before debiting. The debit is rejected if the account's balance doesn't cover the amount:

Code
1import { debitStoreCreditAccountWorkflow } from "@medusajs/loyalty-plugin/workflows"2
3await debitStoreCreditAccountWorkflow(container)4  .run({5    input: {6      account_id: "sca_123",7      amount: 100,8      note: "Credit issued by mistake",9      reference: "user",10      reference_id: "user_123",11    },12  })

Debit Accounts Workflow#

Debit multiple store credit accounts:

Code
1import { debitAccountsWorkflow } from "@medusajs/loyalty-plugin/workflows"2
3const { result } = await debitAccountsWorkflow(container)4  .run({5    input: [6      {7        account_id: "sca_123",8        amount: 25,9        reference: "cart",10        reference_id: "cart_123",11      },12    ],13  })

Cart Integration Workflows#

Add Store Credits to Cart#

Apply store credits to a cart as a credit line:

Code
1import { addStoreCreditsToCartWorkflow } from "@medusajs/loyalty-plugin/workflows"2
3await addStoreCreditsToCartWorkflow(container)4  .run({5    input: {6      cart_id: "cart_123",7      amount: 50, // optional, uses full balance if not provided8    },9  })

Reference Documentation#

For complete API references and additional workflows, refer to the Medusa Core Workflows reference.