Menu

Store Credit Accounts API Routes

A store credit account is a ledger of store credit transactions for a customer. They hold the customer's store credit balance, including their credit and debit amounts. Store credit accounts allow you to build features that let customers pay for items using their store credit balance, such as gift cards or loyalty points. These API routes allow admin users to manage store credit accounts, their transactions, and more.

Store Credit Account routes are only available when the loyalty plugin is installed.

GET /admin/store-credit-accounts#

List Store Credit Accounts

Retrieve a list of store credit accounts. The store credit accounts can be filtered by fields such as id. The store credit accounts can also be sorted or paginated.

Plugin: This API route is only available when the loyalty plugin is installed in the MedusaGo application.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. The fields and relations to retrieve separated by commas. Learn more in the API reference.
idstring | string[]Optional
Filter by the store credit account's ID.
customer_idstring | string[]Optional
Filter by customer ID(s) to retrieve their store credit accounts.
currency_codestring | string[]Optional
Filter by currency code(s) to retrieve store credit accounts in specific currencies.
created_atobjectOptional
Filter by a store credit account's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a store credit account's update date. Accepts the filter operators.
$andobject[]Optional
An array of filters to apply on the entity, where each item in the array is joined with an "and" condition.
$orobject[]Optional
An array of filters to apply on the entity, where each item in the array is joined with an "or" condition.
limitnumberOptional
Limit the number of items returned in the list.
offsetnumberOptional
The number of items to skip when retrieving a list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
codestring | string[]Optional
Filter by a store credit account code.
with_deletedbooleanOptional
Whether to include deleted records in the result.

Request examples

Responses

200 OK

limitnumber
The maximum number of store credit accounts to return.
offsetnumber
The number of store credit accounts to skip before retrieving the results.
countnumber
The total number of store credit accounts available.
store_credit_accountsobject[]
The list of store credit accounts.
estimate_countnumberOptional
The store credit account's estimate count.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/store-credit-accounts#

Create Store Credit Account

Create a store credit account.

Plugin: This API route is only available when the loyalty plugin is installed in the MedusaGo application.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Request body (application/json)

currency_codestring
The store credit account's currency code.
Example: usd
customer_idstringOptional
The ID of the customer that the store credit account belongs to.
metadataobjectOptional
The store credit account's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

store_credit_accountobject
The store credit account's details.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/store-credit-accounts/{id}#

Get a Store Credit Account

Retrieve a store credit account by its ID. You can expand the store credit account's relations or select the fields that should be returned.

Plugin: This API route is only available when the loyalty plugin is installed in the MedusaGo application.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The store credit account's ID.

Query parameters

fieldsstringOptional
Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields. The fields and relations to retrieve separated by commas. Learn more in the API reference.
idstring | string[]Optional
Filter by the store credit account's ID.
customer_idstring | string[]Optional
Filter by customer ID(s) to retrieve their store credit accounts.
currency_codestring | string[]Optional
Filter by currency code(s) to retrieve store credit accounts in specific currencies.
created_atobjectOptional
Filter by a store credit account's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a store credit account's update date. Accepts the filter operators.
$andobject[]Optional
An array of filters to apply on the entity, where each item in the array is joined with an "and" condition.
$orobject[]Optional
An array of filters to apply on the entity, where each item in the array is joined with an "or" condition.
limitnumberOptional
Limit the number of items returned in the list.
offsetnumberOptional
The number of items to skip when retrieving a list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
codestring | string[]Optional
Filter by a store credit account's code.
with_deletedbooleanOptional
Whether to include deleted records in the result.

Request examples

Responses

200 OK

store_credit_accountobject
The store credit account's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/store-credit-accounts/{id}/credit#

Add Credit to Store Credit Account

Add credit to a store credit account

Plugin: This API route is only available when the loyalty plugin is installed in the MedusaGo application.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The store credit account's ID.

Request body (application/json)

amountnumber
The amount to credit the store credit account with.
notestringOptional
An additional note to add to the store credit transaction.

Request examples

Responses

200 OK

store_credit_accountobject
The store credit account's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/store-credit-accounts/{id}/debit#

Debit a Store Credit Account

Debit an amount from a store credit account, deducting it from the customer's store credit balance. The debit is recorded as a debit transaction on the account that references the authenticated admin user.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The store credit account's ID.

Request body (application/json)

amountnumber
The amount to debit from the store credit account, in the major currency unit. It's deducted from the customer's store credit balance.
notestringOptional
An additional note to add to the store credit transaction.

Request examples

Responses

200 OK

store_credit_accountobject
The store credit account's details.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/store-credit-accounts/{id}/transactions#

List Transactions

Retrieve a list of transactions in a store credit account. The transactions can be filtered by fields like FILTER FIELDS. The transactions can also be paginated.

Plugin: This API route is only available when the loyalty plugin is installed in the MedusaGo application.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The store credit account's ID.

Query parameters

idstring | string[]Optional
Filter by a transaction ID.
transaction_group_idstring | string[]Optional
Filter by a transaction group ID.
created_atobjectOptional
Filter by a transaction's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a transaction's update date. Accepts the filter operators.
limitnumberOptional
Limit the number of items returned in the list.
offsetnumberOptional
The number of items to skip when retrieving a list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
fieldsstringOptional
Comma-separated fields that should be included in the returned data. If a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. Without prefix it will replace the entire default fields.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
qstringOptional
Search query to filter the transactions by their searchable fields.
with_deletedbooleanOptional
Whether to include deleted records in the result.

Request examples

Responses

200 OK

limitnumber
The maximum number of transactions to return.
offsetnumber
The number of transactions to skip before retrieving the results.
countnumber
The total number of transactions available.
transactionsobject[]
The list of transactions.
estimate_countnumberOptional
The store credit account's estimate count.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page