Medusa Gift Cards API

openapi: 3.2.0
info:
  title: Medusa Gift Cards API
  version: 2.19.0
  description: 'Operations tagged Gift Cards across 2 of this provider''s published API definitions: medusa-admin-openapi.yaml, medusa-store-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://localhost:9000
- url: https://api.medusajs.com
tags:
- name: Gift Cards
  description: '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.

    <Note>

    Gift Card routes are only available through the [Loyalty Plugin](https://docs.medusajs.com/resources/commerce-modules/loyalty).

    </Note>

    '
  x-associatedSchema:
    $ref: '#/components/schemas/AdminGiftCard'
paths:
  /admin/gift-cards:
    get:
      operationId: GetGiftCards
      summary: List Gift Cards
      description: 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.
      x-authenticated: true
      parameters:
      - name: id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: id
            description: The gift card's ID.
          - type: array
            description: The gift card's ID.
            items:
              type: string
              title: id
              description: The id's ID.
      - name: customer_id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: customer_id
            description: Filter by a customer ID to retrieve their gift cards.
          - type: array
            description: Filter by customer IDs to retrieve their gift cards.
            items:
              type: string
              title: customer_id
              description: A customer ID.
      - name: created_at
        in: query
        description: Filter by a gift card's creation date.
        required: false
        schema:
          type: object
          description: Filter by a gift card's creation date.
          properties:
            $and:
              type: array
              description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $and
            $or:
              type: array
              description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $or
            $eq:
              oneOf:
              - type: string
                title: $eq
                description: Filter by an exact match.
              - type: array
                description: Filter by an exact match.
                items:
                  type: string
                  title: $eq
                  description: Filter by an exact match.
            $ne:
              type: string
              title: $ne
              description: Filter by values not equal to this parameter.
            $in:
              type: array
              description: Filter by values in this array.
              items:
                type: string
                title: $in
                description: Filter by values in this array.
            $nin:
              type: array
              description: Filter by values not in this array.
              items:
                type: string
                title: $nin
                description: Filter by values not in this array.
            $not:
              oneOf:
              - type: string
                title: $not
                description: Filter by values not matching the conditions in this parameter.
              - type: object
                description: Filter by values not matching the conditions in this parameter.
              - type: array
                description: Filter by values not matching the conditions in this parameter.
                items:
                  type: string
                  title: $not
                  description: Filter by values not matching the conditions in this parameter.
            $gt:
              type: string
              title: $gt
              description: Filter by values greater than this parameter. Useful for numbers and dates only.
            $gte:
              type: string
              title: $gte
              description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
            $lt:
              type: string
              title: $lt
              description: Filter by values less than this parameter. Useful for numbers and dates only.
            $lte:
              type: string
              title: $lte
              description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
            $like:
              type: string
              title: $like
              description: Apply a `like` filter. Useful for strings only.
            $re:
              type: string
              title: $re
              description: Apply a regex filter. Useful for strings only.
            $ilike:
              type: string
              title: $ilike
              description: Apply a case-insensitive `like` filter. Useful for strings only.
            $fulltext:
              type: string
              title: $fulltext
              description: Filter to apply on full-text properties.
            $overlap:
              type: array
              description: Filter arrays that have overlapping values with this parameter.
              items:
                type: string
                title: $overlap
                description: Filter arrays that have overlapping values with this parameter.
            $contains:
              type: array
              description: Filter arrays that contain some of the values of this parameter.
              items:
                type: string
                title: $contains
                description: Filter arrays that contain some of the values of this parameter.
            $contained:
              type: array
              description: Filter arrays that contain all values of this parameter.
              items:
                type: string
                title: $contained
                description: Filter arrays that contain all values of this parameter.
            $exists:
              type: boolean
              title: $exists
              description: Filter by whether a value for this parameter exists (not `null`).
          title: created_at
      - name: updated_at
        in: query
        description: Filter by a gift card's update date.
        required: false
        schema:
          type: object
          description: Filter by a gift card's update date.
          properties:
            $and:
              type: array
              description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $and
            $or:
              type: array
              description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $or
            $eq:
              oneOf:
              - type: string
                title: $eq
                description: Filter by an exact match.
              - type: array
                description: Filter by an exact match.
                items:
                  type: string
                  title: $eq
                  description: Filter by an exact match.
            $ne:
              type: string
              title: $ne
              description: Filter by values not equal to this parameter.
            $in:
              type: array
              description: Filter by values in this array.
              items:
                type: string
                title: $in
                description: Filter by values in this array.
            $nin:
              type: array
              description: Filter by values not in this array.
              items:
                type: string
                title: $nin
                description: Filter by values not in this array.
            $not:
              oneOf:
              - type: string
                title: $not
                description: Filter by values not matching the conditions in this parameter.
              - type: object
                description: Filter by values not matching the conditions in this parameter.
              - type: array
                description: Filter by values not matching the conditions in this parameter.
                items:
                  type: string
                  title: $not
                  description: Filter by values not matching the conditions in this parameter.
            $gt:
              type: string
              title: $gt
              description: Filter by values greater than this parameter. Useful for numbers and dates only.
            $gte:
              type: string
              title: $gte
              description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
            $lt:
              type: string
              title: $lt
              description: Filter by values less than this parameter. Useful for numbers and dates only.
            $lte:
              type: string
              title: $lte
              description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
            $like:
              type: string
              title: $like
              description: Apply a `like` filter. Useful for strings only.
            $re:
              type: string
              title: $re
              description: Apply a regex filter. Useful for strings only.
            $ilike:
              type: string
              title: $ilike
              description: Apply a case-insensitive `like` filter. Useful for strings only.
            $fulltext:
              type: string
              title: $fulltext
              description: Filter to apply on full-text properties.
            $overlap:
              type: array
              description: Filter arrays that have overlapping values with this parameter.
              items:
                type: string
                title: $overlap
                description: Filter arrays that have overlapping values with this parameter.
            $contains:
              type: array
              description: Filter arrays that contain some of the values of this parameter.
              items:
                type: string
                title: $contains
                description: Filter arrays that contain some of the values of this parameter.
            $contained:
              type: array
              description: Filter arrays that contain all values of this parameter.
              items:
                type: string
                title: $contained
                description: Filter arrays that contain all values of this parameter.
            $exists:
              type: boolean
              title: $exists
              description: Filter by whether a value for this parameter exists (not `null`).
          title: updated_at
      - name: limit
        in: query
        description: Limit the number of items returned in the list.
        required: false
        schema:
          type: number
          title: limit
          description: Limit the number of items returned in the list.
          externalDocs:
            url: '#pagination'
      - name: offset
        in: query
        description: The number of items to skip when retrieving a list.
        required: false
        schema:
          type: number
          title: offset
          description: The number of items to skip when retrieving a list.
          externalDocs:
            url: '#pagination'
      - name: order
        in: query
        description: 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 `-`.
        required: false
        schema:
          type: string
          title: order
          description: 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 `-`.
          externalDocs:
            url: '#pagination'
      - name: fields
        in: query
        description: 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.
        required: false
        schema:
          type: string
          title: fields
          description: 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.
          externalDocs:
            url: '#select-fields-and-relations'
      - name: $and
        in: query
        description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
        required: false
        schema:
          type: array
          description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
          items:
            type: object
          title: $and
      - name: $or
        in: query
        description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
        required: false
        schema:
          type: array
          description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
          items:
            type: object
          title: $or
      - name: with_deleted
        in: query
        description: The gift card's with deleted.
        required: false
        schema:
          type: boolean
          title: with_deleted
          description: The gift card's with deleted.
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/gift-cards'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Gift Cards
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminGiftCardsResponse'
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
      x-badges:
      - text: Loyalty Plugin
        description: 'This API route is only available through the [Loyalty Plugin](https://docs.medusajs.com/resources/commerce-modules/loyalty).

          '
    post:
      operationId: PostGiftCards
      summary: Create Gift Card
      description: Create a gift card.
      x-authenticated: true
      x-ignoreCleanup: true
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminCreateGiftCardParams'
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -X POST '{backend_url}/admin/gift-cards' \\\n-H 'Authorization: Bearer {jwt_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"code\": \"{value}\",\n  \"value\": 19,\n  \"currency_code\": \"bwp\",\n  \"expires_at\": \"2025-07-20T15:47:23.951Z\",\n  \"reference_id\": \"{value}\",\n  \"reference\": \"{value}\",\n  \"line_item_id\": \"{value}\",\n  \"customer_id\": \"{value}\",\n  \"metadata\": {}\n}'"
      tags:
      - Gift Cards
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminGiftCardResponse'
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
      x-badges:
      - text: Plugin
        description: 'This API route is only available through the [Loyalty Plugin](https://docs.medusajs.com/resources/commerce-modules/loyalty).

          '
    servers:
    - url: http://localhost:9000
    - url: https://api.medusajs.com
  /admin/gift-cards/{id}:
    get:
      operationId: GetGiftCardsId
      summary: Get a Gift Card
      description: Retrieve a gift card by its ID. You can expand the gift card's relations or select the fields that should be returned.
      x-authenticated: true
      parameters:
      - name: id
        in: path
        description: The gift card's ID.
        required: true
        schema:
          type: string
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/gift-cards/{id}'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Gift Cards
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminGiftCardResponse'
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
      x-badges:
      - text: Loyalty Plugin
        description: 'This API route is only available through the [Loyalty Plugin](https://docs.medusajs.com/resources/commerce-modules/loyalty).

          '
    post:
      operationId: PostGiftCardsId
      summary: Update a Gift Card
      description: Update a gift card's details.
      x-authenticated: true
      x-ignoreCleanup: true
      parameters:
      - name: id
        in: path
        description: The gift card's ID.
        required: true
        schema:
          type: string
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminUpdateGiftCardParams'
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: 'curl -X POST ''{backend_url}/admin/gift-cards/{id}'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Gift Cards
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminGiftCardResponse'
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
      x-badges:
      - text: Plugin
        description: 'This API route is only available through the [Loyalty Plugin](https://docs.medusajs.com/resources/commerce-modules/loyalty).

          '
    servers:
    - url: http://localhost:9000
    - url: https://api.medusajs.com
  /admin/gift-cards/{id}/orders:
    get:
      operationId: GetGiftCardsIdOrders
      summary: List Gift Card's Orders
      x-sidebar-summary: List Orders
      description: Retrieve the list of orders that a gift card was used in.
      x-authenticated: true
      parameters:
      - name: id
        in: path
        description: The gift card's ID.
        required: true
        schema:
          type: string
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/gift-cards/{id}/orders'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Gift Cards
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
      x-badges:
      - text: Loyalty Plugin
        description: 'This API route is only available through the [Loyalty Plugin](https://docs.medusajs.com/resources/commerce-modules/loyalty).

          '
    servers:
    - url: http://localhost:9000
    - url: https://api.medusajs.com
  /store/gift-cards/{idOrCode}:
    get:
      operationId: GetGiftCardsIdorcode
      summary: Get a Gift Card
      x-sidebar-summary: Get Gift Card
      description: Retrieve a gift card by its ID or code. You can expand the gift card's relations or select the fields that should be returned.
      x-authenticated: false
      x-ignoreCleanup: true
      parameters:
      - name: idOrCode
        in: path
        description: The gift card's ID or code.
        required: true
        schema:
          type: string
      - name: x-publishable-api-key
        in: header
        description: Publishable API Key created in the Medusa Admin.
        required: true
        schema:
          type: string
          externalDocs:
            url: https://docs.medusajs.com/api/store#publishable-api-key
      - name: x-medusa-locale
        in: header
        description: The locale in BCP 47 format to retrieve localized content.
        required: false
        schema:
          type: string
          example: en-US
          externalDocs:
            url: https://docs.medusajs.com/resources/commerce-modules/translation/storefront
            description: Learn more in the Serve Translations in Storefront guide.
      - name: fields
        in: query
        description: "Comma-separated fields that should be included in the returned data.\n if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields.\n without prefix it will replace the entire default fields."
        required: false
        schema:
          type: string
          title: fields
          description: 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.
          externalDocs:
            url: '#select-fields-and-relations'
      - name: locale
        in: query
        description: The locale in BCP 47 format to retrieve localized content.
        required: false
        schema:
          type: string
          example: en-US
          externalDocs:
            url: https://docs.medusajs.com/resources/commerce-modules/translation/storefront
            description: Learn more in the Serve Translations in Storefront guide.
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/store/gift-cards/{idOrCode}'' \

          -H ''Authorization: Bearer {jwt_token}'' \

          -H ''x-publishable-api-key: {your_publishable_api_key}'''
      tags:
      - Gift Cards
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
      x-badges:
      - text: Plugin
        description: 'This API route is only available through the [Loyalty Plugin](https://docs.medusajs.com/resources/commerce-modules/loyalty).

          '
    servers:
    - url: http://localhost:9000
    - url: https://api.medusajs.com
components:
  schemas:
    AdminProductOptionValue:
      type: object
      description: The product option value's details.
      x-schemaName: AdminProductOptionValue
      required:
      - id
      - value
      properties:
        id:
          type: string
          title: id
          description: The value's ID.
        value:
          type: string
          title: value
          description: The value.
        option:
          $ref: '#/components/schemas/AdminProductOption'
        option_id:
          type: string
          title: option_id
          description: The ID of the option this value belongs to.
        metadata:
          type: object
          description: The value's metadata, can hold custom key-value pairs.
          externalDocs:
            url: https://docs.medusajs.com/api/admin#manage-metadata
            description: Learn how to manage metadata
        created_at:
          type: string
          format: date-time
          title: created_at
          description: The date the value was created.
        updated_at:
          type: string
          format: date-time
          title: updated_at
          description: The date the value was updated.
        deleted_at:
          type: string
          format: date-time
          title: deleted_at
          description: The date the value was deleted.
        rank:
          type: number
          title: rank
          description: The rank of the value among other option values.
    AdminProductType:
      type: object
      description: The product type's details.
      x-schemaName: AdminProductType
      required:
      - id
      - value
      - created_at
      - updated_at
      properties:
        id:
          type: string
          title: id
          description: The type's ID.
        value:
          type: string
          title: value
          description: The type's value.
        created_at:
          type: string
          format: date-time
          title: created_at
          description: The date the type was created.
        updated_at:
          type: string
          format: date-time
          title: updated_at
          description: The date the type was updated.
        deleted_at:
          type: string
          format: date-time
          title: deleted_at
          description: The date the type was deleted.
        metadata:
          type: object
          description: The type's metadata, can hold custom key-value pairs.
          externalDocs:
            url: https://docs.medusajs.com/api/admin#manage-metadata
            description: Learn how to manage metadata
        translations:
          type: array
          description: The type's translations.
          items:
            $ref: '#/components/schemas/AdminTranslation'
        external_id:
          type: string
          title: external_id
          description: The type's external ID used for integration with third-party systems.
    BaseCollection:
      type: object
      description: The product collection's details.
      x-schemaName: BaseCollection
      required:
      - id
      - title
      - handle
      - created_at
      - updated_at
      - deleted_at
      - metadata
      properties:
        id:
          type: string
          title: id
          description: The collection's ID.
        title:
          type: string
          title: title
          description: The collection's title.
        handle:
          type: string
          title: handle
          description: The collection's handle.
        created_at:
          type: string
          format: date-time
          title: created_at
          description: The collection's creation date.
        updated_at:
          type: string
          format: date-time
          title: updated_at
          description: The collection's update date.
        deleted_at:
          type: string
          format: date-time
          title: deleted_at
          description: The collection's deletion date.
        products:
          type: array
          description: The collection's products.
          items:
            type: object
        metadata:
          type: object
          description: The collection's metadata, used to store custom key-value pairs.
          externalDocs:
            url: https://docs.medusajs.com/api/store#manage-metadata
            description: Learn how to manage metadata
        external_id:
          type: string
          title: external_id
          description: The collection's external ID used to link it with external systems.
    AdminShippingProfile:
      type: object
      description: The shipping profile's details..
      x-schemaName: AdminShippingProfile
      properties:
        id:
          type: string
          title: id
          description: The shipping profile's ID.
        name:
          type: string
          title: name
          description: The shipping profile's name.
        type:
          type: string
          title: type
          description: The shipping profile's type.
        metadata:
          type: object
          description: The shipping profile's metadata, holds custom key-value pairs.
          externalDocs:
            url: https://docs.medusajs.com/api/admin#manage-metadata
            description: Learn how to manage metadata
        created_at:
          type: string
          format: date-time
          title: created_at
          description: The date the shipping profile was created.
        updated_at:
          type: string
          format: date-time
          title: updated_at
          description: The date the shipping profile was updated.
        deleted_at:
          type: string
          format: date-time
          title: deleted_at
          description: The date the shipping profile was deleted.
      required:
      - id
      - name
      - type
      - metadata
      - created_at
      - updated_at
      - deleted_at
    AdminProductVariantInventoryItemLink:
      type: object
      description: An association between a product variant and an inventory item.
      x-schemaName: AdminProductVariantInventoryItemLink
      required:
      - id
      - variant_id
      - inventory_item_id
      properties:
        id:
          type: string
          title: id
          description: The ID of the association.
        variant_id:
          type: string
          title: variant_id
          description: The associated product variant's ID.
        variant:
          type: object
        inventory_item_id:
          type: string
          title: inventory_item_id
          description: The associated inventory item's ID.
        inventory:
          $ref: '#/components/schemas/AdminI

# --- truncated at 32 KB (104 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/medusa/refs/heads/main/openapi/medusa-gift-cards-api-openapi.yml