Menu

Gift Cards API Routes

A gift card is a prepaid card that can be used to pay for items during checkout. Gift cards can be purchased by customers, or created by admin users. When a gift card is redeemed, its amount is added to the customer's store credit account, which can then be used to pay for items during checkout. These API routes allow admin users to manage gift cards, transfer gift cards between customers, and more.

Gift Card routes are only available through the Loyalty Plugin.

GET /admin/gift-cards#

List Gift Cards

Retrieve a list of gift cards. The gift cards can be filtered by fields such as id. The gift cards 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

idstring | string[]Optional
The gift card's ID.
customer_idstring | string[]Optional
Filter by a customer ID to retrieve their gift cards.
created_atobjectOptional
Filter by a gift card's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a gift card'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.
with_deletedbooleanOptional
The gift card's with deleted.

Request examples

Responses

200 OK

limitnumber
The maximum number of gift cards to return.
offsetnumber
The number of gift cards to skip before retrieving the results.
countnumber
The total number of gift cards available.
gift_cardsobject[]
The list of gift cards.
estimate_countnumberOptional
The gift card's estimate count.

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

POST /admin/gift-cards#

Create Gift Card

Create a gift card.

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)

codestring
The gift card's code.
valuenumber
The gift card's amount.
Example: 20
currency_codestring
The gift card's currency code.
Example: usd
expires_atstring
The date the gift card expires at.
reference_idstring
The gift card's reference ID.
referencestring
The gift card's reference.
line_item_idstring
The ID of the line item associated with the gift card.
customer_idstring
The ID of the customer associated with the gift card.
metadataobject
The gift card's metadata, can hold custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

gift_cardobject
The gift card's details.

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

GET /admin/gift-cards/{id}#

Get a Gift Card

Retrieve a gift card by its ID. You can expand the gift card'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 gift card's ID.

Request examples

Responses

200 OK

gift_cardobject
The gift card's details.

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

POST /admin/gift-cards/{id}#

Update a Gift Card

Update a gift card's details.

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 gift card's ID.

Request body (application/json)

status"pending" | "redeemed"Optional
The gift card's status.
valuenumberOptional
The gift card's amount.
customer_idstringOptional
The ID of the customer that the gift card belongs to.
currency_codestringOptional
The gift card's currency code.
Example: usd
notestringOptional
The gift card's note.
expires_atstringOptional
The date the gift card expires at.
metadataobjectOptional
The gift card's metadata. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

gift_cardobject
The gift card's details.

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

GET /admin/gift-cards/{id}/orders#

List Gift Card's Orders

Retrieve the list of orders that a gift card was used in.

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 gift card's ID.

Request examples

Responses

200 OK

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