docs: update OAS for loyalty plugin (#12836)

* updates

* cleanup

* generate OAS

* update links
This commit is contained in:
Shahed Nasser
2025-06-26 17:22:18 +03:00
committed by GitHub
parent 2983c7c3a5
commit 7d95eb73d3
81 changed files with 463 additions and 2001 deletions

View File

@@ -58,15 +58,6 @@ tags:
url: https://docs.medusajs.com/resources/storefront-development/customers
x-associatedSchema:
$ref: '#/components/schemas/StoreCustomer'
- name: Gift Card Invitations
description: |
A gift card invitation is a way to send a gift card to a customer. They can be sent from one customer to another.
These API routes allow logged-in customers to create and manage gift card invitations.
<Note>
Gift Card Invitations are only available for Cloud users using the [Loyalty Plugin](https://docs.medusajs.com/cloud/loyalty-plugin).
</Note>
x-associatedSchema:
$ref: '#/components/schemas/StoreGiftCardInvitation'
- name: Gift Cards
description: |
A gift card is a prepaid card that customers can use to purchase products in the store.
@@ -4196,297 +4187,18 @@ paths:
$ref: '#/components/responses/500_error'
x-workflow: deleteCustomerAddressesWorkflow
x-events: []
/store/gift-card-invitations/{code}/accept:
post:
operationId: PostGiftCardInvitationsCodeAccept
summary: Accept Customer's Gift Card Invitation
x-sidebar-summary: Accept Invitation
description: Accept the logged-in customer's gift card invitation
x-authenticated: true
x-ignoreCleanup: true
parameters:
- name: code
in: path
description: The gift card invitation's 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: 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'
x-codeSamples:
- lang: Shell
label: cURL
source: |-
curl -X POST '{backend_url}/store/gift-card-invitations/{code}/accept' \
-H 'x-publishable-api-key: {your_publishable_api_key}'
tags:
- Gift Card Invitations
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreGiftCardInvitationResponse'
'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'
security:
- cookie_auth: []
- jwt_token: []
x-badges:
- text: Cloud
description: |
This API route is only available in [Medusa Cloud](https://docs.medusajs.com/cloud/loyalty-plugin).
/store/gift-card-invitations/{code}/reject:
post:
operationId: PostGiftCardInvitationsCodeReject
summary: Reject Customer's Gift Card Invitation
x-sidebar-summary: Reject Invitation
description: Reject the logged-in customer's gift card invitation
x-authenticated: true
x-ignoreCleanup: true
parameters:
- name: code
in: path
description: The gift card invitation's 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: 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'
x-codeSamples:
- lang: Shell
label: cURL
source: |-
curl -X POST '{backend_url}/store/gift-card-invitations/{code}/reject' \
-H 'x-publishable-api-key: {your_publishable_api_key}'
tags:
- Gift Card Invitations
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreGiftCardInvitationResponse'
'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'
security:
- cookie_auth: []
- jwt_token: []
x-badges:
- text: Cloud
description: |
This API route is only available in [Medusa Cloud](https://docs.medusajs.com/cloud/loyalty-plugin).
/store/gift-cards:
/store/gift-cards/{idOrCode}:
get:
operationId: GetGiftCards
summary: List Customer's Gift Cards
x-sidebar-summary: List Gift Cards
description: Retrieve a customer's 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
x-ignoreCleanup: true
parameters:
- 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: id
in: query
required: false
schema:
oneOf:
- type: string
title: id
description: Filter by a gift card ID.
- type: array
description: Filter by gift card IDs.
items:
type: string
title: id
description: A gift card's ID.
- 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: status
in: query
required: false
schema:
oneOf:
- type: string
description: Filter by a gift card's status.
enum:
- pending
- redeemed
- type: array
description: Filter by gift card statuses.
items:
type: string
description: A gift card status.
enum:
- pending
- redeemed
x-codeSamples:
- lang: Shell
label: cURL
source: |-
curl '{backend_url}/store/gift-cards' \
-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'
security:
- cookie_auth: []
- jwt_token: []
x-badges:
- text: Cloud
description: |
This API route is only available in [Medusa Cloud](https://docs.medusajs.com/cloud/loyalty-plugin).
/store/gift-cards/{id}:
get:
operationId: GetGiftCardsId
summary: Get Customer's Gift Card
operationId: GetGiftCardsIdorcode
summary: Get a Gift Card
x-sidebar-summary: Get Gift Card
description: Retrieve the logged-in customer's gift card by its ID. You can expand the gift card's relations or select the fields that should be returned.
x-authenticated: true
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: id
- name: idOrCode
in: path
description: The gift card's ID.
description: The gift card's ID or code.
required: true
schema:
type: string
@@ -4502,8 +4214,8 @@ paths:
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.
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
@@ -4515,7 +4227,8 @@ paths:
- lang: Shell
label: cURL
source: |-
curl '{backend_url}/store/gift-cards/{id}' \
curl '{backend_url}/store/gift-cards/{idOrCode}' \
-H 'Authorization: Bearer {access_token}' \
-H 'x-publishable-api-key: {your_publishable_api_key}'
tags:
- Gift Cards
@@ -4534,104 +4247,22 @@ paths:
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
security:
- cookie_auth: []
- jwt_token: []
x-badges:
- text: Cloud
description: |
This API route is only available in [Medusa Cloud](https://docs.medusajs.com/cloud/loyalty-plugin).
/store/gift-cards/{id}/invitation:
/store/gift-cards/{idOrCode}/redeem:
post:
operationId: PostGiftCardsIdInvitation
summary: Send Gift Card Invitation
x-sidebar-summary: Send Invitation
description: Send a gift card invitation to a customer's email address. The gift card must belong to the logged-in customer, and it must not have been redeemed yet.
x-authenticated: true
x-ignoreCleanup: true
parameters:
- name: id
in: path
description: The gift card's ID.
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: 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'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StoreCreateGiftCardInvitation'
x-codeSamples:
- lang: Shell
label: cURL
source: |-
curl -X POST '{backend_url}/store/gift-cards/{id}/invitation' \
-H 'x-publishable-api-key: {your_publishable_api_key}' \
-H 'Content-Type: application/json' \
--data-raw '{
"email": "Morton61@hotmail.com"
}'
tags:
- Gift Cards
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StoreGiftCardResponse'
'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'
security:
- cookie_auth: []
- jwt_token: []
x-badges:
- text: Cloud
description: |
This API route is only available in [Medusa Cloud](https://docs.medusajs.com/cloud/loyalty-plugin).
/store/gift-cards/{id}/redeem:
post:
operationId: PostGiftCardsIdRedeem
summary: Redeem Customer's Gift Card
operationId: PostGiftCardsIdorcodeRedeem
summary: Redeem a Gift Card
x-sidebar-summary: Redeem Gift Card
description: Redeem the logged-in customer's gift card
description: Redeem a gift card by its ID or code. The gift card will be added to the logged-in customer's store credit account.
x-authenticated: true
x-ignoreCleanup: true
parameters:
- name: id
- name: idOrCode
in: path
description: The gift card's ID.
description: The gift card's ID or code.
required: true
schema:
type: string
@@ -4647,8 +4278,8 @@ paths:
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.
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
@@ -4656,11 +4287,15 @@ paths:
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'
security:
- cookie_auth: []
- jwt_token: []
x-codeSamples:
- lang: Shell
label: cURL
source: |-
curl -X POST '{backend_url}/store/gift-cards/{id}/redeem' \
curl -X POST '{backend_url}/store/gift-cards/{idOrCode}/redeem' \
-H 'Authorization: Bearer {access_token}' \
-H 'x-publishable-api-key: {your_publishable_api_key}'
tags:
- Gift Cards
@@ -4683,9 +4318,6 @@ paths:
$ref: '#/components/responses/invalid_request_error'
'500':
$ref: '#/components/responses/500_error'
security:
- cookie_auth: []
- jwt_token: []
x-badges:
- text: Cloud
description: |
@@ -15295,7 +14927,6 @@ components:
required:
- line_item
- customer
- invitation
- id
- code
- status
@@ -15356,8 +14987,6 @@ components:
type: string
title: expires_at
description: The date the gift card expires at.
invitation:
$ref: '#/components/schemas/AdminGiftCardInvitation'
created_at:
type: string
format: date-time
@@ -15368,44 +14997,6 @@ components:
format: date-time
title: updated_at
description: The date the gift card was updated at.
AdminGiftCardInvitation:
type: object
description: The gift card invitation details.
required:
- gift_card
- id
- code
- status
- expires_at
- email
properties:
id:
type: string
title: id
description: The invitation's ID.
email:
type: string
title: email
description: The invitation's email.
format: email
code:
type: string
title: code
description: The invitation's code.
status:
type: string
description: The invitation's status.
enum:
- pending
- accepted
- rejected
expires_at:
type: string
title: expires_at
description: The date the invitation expires at.
gift_card:
type: object
x-schemaName: AdminGiftCardInvitation
AdminGiftCardResponse:
type: object
description: The gift card's details.
@@ -15442,6 +15033,11 @@ components:
description: The list of gift cards.
items:
$ref: '#/components/schemas/AdminGiftCard'
estimate_count:
type: number
title: estimate_count
description: The gift card's estimate count.
x-featureFlag: index_engine
AdminImportProductRequest:
type: object
description: The import's details.
@@ -21666,6 +21262,11 @@ components:
description: The list of store credit accounts.
items:
$ref: '#/components/schemas/AdminStoreCreditAccount'
estimate_count:
type: number
title: estimate_count
description: The store credit account's estimate count.
x-featureFlag: index_engine
AdminStoreCurrency:
type: object
description: The details of a store's currency.
@@ -22134,6 +21735,11 @@ components:
description: The list of transaction groups.
items:
$ref: '#/components/schemas/AdminTransactionGroup'
estimate_count:
type: number
title: estimate_count
description: The transaction group's estimate count.
x-featureFlag: index_engine
AdminTransactionsResponse:
type: object
description: The paginated list of transactions.
@@ -22161,17 +21767,11 @@ components:
description: The list of transactions.
items:
$ref: '#/components/schemas/AdminTransaction'
AdminTransferGiftCard:
type: object
description: The details of the gift card transfer request.
x-schemaName: AdminTransferGiftCard
required:
- customer_id
properties:
customer_id:
type: string
title: customer_id
description: The ID of the customer to transfer the gift card to.
estimate_count:
type: number
title: estimate_count
description: The store credit account's estimate count.
x-featureFlag: index_engine
AdminTransferOrder:
type: object
description: The details of the request to transfer the order.
@@ -30603,23 +30203,6 @@ components:
metadata:
type: object
description: The customer's metadata, can hold custom key-value pairs.
StoreCreateGiftCardInvitation:
type: object
description: The details to create a gift card invitation.
x-schemaName: StoreCreateGiftCardInvitation
required:
- email
properties:
email:
type: string
title: email
description: The email address to send the gift card invitation to.
format: email
expires_at:
type: string
title: expires_at
description: The date the gift card invitation expires.
format: date-time
StoreCreatePaymentCollection:
type: object
description: The details of the payment collection to create.
@@ -31038,7 +30621,6 @@ components:
required:
- customer
- line_item
- invitation
- id
- code
- status
@@ -31054,6 +30636,12 @@ components:
properties:
customer:
$ref: '#/components/schemas/StoreCustomer'
line_item:
$ref: '#/components/schemas/StoreOrderLineItem'
id:
type: string
title: id
description: The gift card's ID.
code:
type: string
title: code
@@ -31068,22 +30656,32 @@ components:
type: number
title: value
description: The gift card's amount.
currency_code:
type: string
title: currency_code
description: The gift card's currency code.
example: usd
customer_id:
type: string
title: customer_id
description: The ID of the customer that the gift card belongs to.
id:
type: string
title: id
description: The gift card's ID.
reference_id:
type: string
title: reference_id
description: The gift card's reference ID.
note:
type: string
title: note
description: A note with more information about the gift card.
reference:
type: string
title: reference
description: The gift card's reference.
expires_at:
type: string
title: expires_at
description: The date the gift card expires.
format: date-time
created_at:
type: string
format: date-time
@@ -31094,23 +30692,6 @@ components:
format: date-time
title: updated_at
description: The date the gift card was updated.
currency_code:
type: string
title: currency_code
description: The gift card's currency code.
example: usd
note:
type: string
title: note
description: The gift card's note.
expires_at:
type: string
title: expires_at
description: The date the gift card expires.
invitation:
type: object
line_item:
$ref: '#/components/schemas/StoreOrderLineItem'
StoreGiftCardInvitation:
type: object
description: The gift card invitation's details.
@@ -31136,15 +30717,6 @@ components:
description: The gift card invitation's status.
gift_card:
$ref: '#/components/schemas/StoreGiftCard'
StoreGiftCardInvitationResponse:
type: object
description: The gift card invitation's details.
x-schemaName: StoreGiftCardInvitationResponse
required:
- gift_card_invitation
properties:
gift_card_invitation:
$ref: '#/components/schemas/StoreGiftCardInvitation'
StoreGiftCardResponse:
type: object
description: The gift card's details.
@@ -38740,6 +38312,11 @@ components:
description: The list of store credit accounts.
items:
$ref: '#/components/schemas/StoreStoreCreditAccount'
estimate_count:
type: number
title: estimate_count
description: The store credit account's estimate count.
x-featureFlag: index_engine
StoreTransactionGroup:
type: object
description: The transaction group's details.