Medusa
Store APIAdmin API
Store APIAdmin API
Discord
Twitter
Linkedin
Github
  1. Claims
  • Plugins
    • List Plugins
      GET
  • Auth
    • Refresh Authentication Token
      POST
    • Validate Authentication Callback
      POST
    • Generate Reset Password Token for Admin User
      POST
    • Retrieve Registration JWT Token
      POST
    • Authenticate User
      POST
    • Set Authentication Session
      POST
    • Delete Authentication Session
      DELETE
    • Reset an Admin User's Password
      POST
  • Draft Orders
    • Create a Draft Order Edit
    • Cancel Edit on Draft Order
    • Confirm an Edit on a Draft Order
    • Request Edit on Draft Order
    • Convert a Draft Order to an Order
    • Add Item to Draft Order Edit
    • Update Existing Item in Draft Order Edit
    • Remove Item from Draft Order Edit
    • Update New Item in Draft Order Edit
    • Add Promotions to Draft Order Edit
    • Remove Promotions from Draft Order Edit
    • Add Shipping Method to Draft Order Edit
    • Remove Shipping Method from Draft Order Edit
    • Update Existing Shipping Method in Draft Order Edit
    • Remove New Shipping Method from Draft Order
    • Update New Shipping Method in Draft Order Edit
    • Delete a Draft Order
    • Get a Draft Order
    • Update a Draft Order
    • Create Draft Order
    • List Draft Orders
  • Fulfillment Providers
    • List Fulfillment Options
    • List Fulfillment Providers
  • Fulfillment Sets
    • Delete Fulfillment Set
    • Add a Service Zone to a Fulfillment Set
    • Remove a Service Zone from Fulfillment Set
    • Get a Service Zone in a Fulfillment Set
    • Update the Service Zone of a Fulfillment Set
  • Inventory Items
    • Manage Inventory Levels
    • Manage Inventory Levels of Inventory Item
    • Create Inventory Level for Inventory Item
    • List Inventory Levels
    • Update an Inventory Level of an Inventory Item
    • Remove Inventory Level of Inventory Item
    • Create Inventory Item
    • List Inventory Items
    • Get a Inventory Item
    • Delete Inventory Item
    • Update an Inventory Item
  • Order Edits
    • Create Order Edit
    • Confirm Order Edit
    • Request Order Edit
    • Add Items to Order Edit
    • Update Order Item Quantity of Order Edit
    • Remove Item from Order Edit
    • Update an Item in an Order Edit
    • Add Shipping Method to Order Edit
    • Remove Shipping Method from Order Edit
    • Update Shipping Method of an Order Edit
    • Cancel Order Edit
  • Orders
    • List Changes on an Order
    • Mark a Fulfillment as Delivered.
    • Get Preview
    • Archive an Order
    • Cancel Order
    • Cancel Transfer Request
    • Create Credit Line for Order
    • Request Order Transfer
    • Complete Order
    • Update Order
    • Get an Order
    • List Line Items
    • Cancel Fulfillment
    • Create an Order Fulfillment
    • Create Shipment for an Order's Fulfillment
    • List Orders
  • Payment Collections
    • Delete a Payment Collection
    • Create Payment Collection
    • Mark a Payment Collection as Paid
  • Products
    • Create Product Import
    • Confirm Product Import
    • Export Products
    • Manage Products
    • Manage Variants in a Product
    • Associate Variant with Inventory Item
    • Remove Inventory Item Association with Product Variant
    • Update Product Variant's Inventory Details
    • Delete a Product
    • Get a Product
    • Update a Product
    • Create a Product Option
    • List a Product's Options
    • Get a Product's Option
    • Delete an Option from Product
    • Update a Product's Option
    • Get Variant of a Product
    • Delete Product Variant
    • Update a Product Variant
    • Manage Variants Inventory in a Product
    • Create a Product Variant
    • List Variants of a Product
    • Create Product
    • List Products
  • Claims
    • Get a Claim
      GET
    • Cancel a Claim
      POST
    • Add Inbound Items to a Claim
      POST
    • Remove an Inbound Item from Claim
      DELETE
    • Update Inbound Items of a Claim
      POST
    • Add an Inbound Shipping Method to a Claim
      POST
    • Cancel Claim Request
      DELETE
    • Confirm a Claim Request
      POST
    • Add Claim Items to a Claim
      POST
    • Remove a Claim Item from a Claim
      DELETE
    • Update a Claim Item
      POST
    • Remove Inbound Shipping Method from Claim
      DELETE
    • Update Inbound Shipping Method of a Claim
      POST
    • Add Outbound Items to a Claim
      POST
    • Remove an Outbound Item from Claim
      DELETE
    • Update Outbound Item of a Claim
      POST
    • Add Outbound Shipping Methods to a Claim
      POST
    • Remove Outbound Shipping Method from Claim
      DELETE
    • Update Outbound Shipping Method of a Claim
      POST
    • Create a Claim
      POST
    • List Claims
      GET
  • Currencies
    • Get a Currency
    • List Currencies
  • Exchanges
    • Get an Exchange
    • Cancel an Exchange
    • Add Inbound Items to an Exchange
    • Remove Inbound Item from Exchange
    • Update an Inbount Item of an Exchange
    • Add an Inbound Shipping Method to an Exchange
    • Cancel Exchange Request
    • Confirm an Exchange
    • Remove Inbound Shipping Method from Exchange
    • Update Inbound Shipping Method of an Exchange
    • Add Outbound Items to Exchange
    • Remove Outbound Item from Exchange
    • Update Outbound Item of an Exchange
    • Add Outbound Shipping Method to Exchange
    • Remove Outbound Shipping Method from Exchange
    • Update Outbound Shipping Method of Exchange
    • Create Exchange
    • List Exchanges
  • Fulfillments
    • Cancel a Fulfillment
    • Create Fulfillment
    • Create a Shipment for a Fulfillment
  • Invites
    • Refresh Invite Token
    • Get an Invite
    • Delete Invite
    • Accept Invite
    • Create Invite
    • List Invites
  • Notifications
    • Get a Notification
    • List Notifications
  • Payments
    • Get a Payment
    • Capture Payment
    • Refund Payment
    • List Payment Providers
    • List Payments
  • Returns
    • Cancel a return.
    • Get a Return
    • Update a Return
    • Add Damaged Items to Return
    • Remove Damaged Item from Return
    • Update Damaged Item of Return
    • Add Received Items to Return
    • Remove a Received Item from Return
    • Update a Received Item in a Return
    • Confirm Return Receival
    • Add Requested Items to Return
    • Remove Item from Return
    • Update Requested Item in Return
    • Add a Shipping Method to a Return
    • Remove Shipping Method from Return
    • Update a Shipping Method of a Return
    • Start Return Receival
    • Cancel Return Receival
    • Confirm Return Request
    • Cancel Return Request
    • Create Return
    • List Returns
  • Users
    • Get Logged-In User
    • Delete a User
    • Get a User
    • Update a User
    • List Users
  • Workflows Executions
    • Get a Workflows Execution
    • Subscribe to a Workflow's Execution
    • Get Workflow Execution's Details
    • Subscribe to Step of a Workflow's Execution
    • Fail a Step in a Workflow's Execution
    • Succeed a Step in a Workflow's Execution
    • List Workflows Executions
    • Execute a Workflow
  • Api Keys
    • Revoke API Key
    • Get API Key
    • Update an API Key
    • Delete an Api Key
    • Manage Sales Channels of a Publishable API Key
    • Create Api Key
    • List API Keys
  • Price Lists
    • Remove Products from Price List
    • Delete a Price List
    • Get a Price List
    • Update a Price List
    • Manage Prices in Price List
    • Create Price List
    • List Price Lists
  • Stores
    • Get a Store
    • Update a Store
    • List Stores
  • Tax Rates
    • Create Tax Rule for a Rate
    • Delete a Tax Rate
    • Get a Tax Rate
    • Update a Tax Rate
    • Remove Rule of Tax Rate
    • Create Tax Rate
    • List Tax Rates
  • Price Preferences
    • Delete a Price Preference
    • Get a Price Preference
    • Update a Price Preference
    • Create Price Preference
    • List Price Preferences
  • Return Reasons
    • Delete a Return Reason
    • Get a Return Reason
    • Update a Return Reason
    • Create Return Reason
    • List Return Reasons
  • Sales Channels
    • Delete a Sales Channel
    • Get a Sales Channel
    • Update a Sales Channel
    • Manage Products in Sales Channel
    • Create Sales Channel
    • List Sales Channels
  • Stock Locations
    • Delete a Stock Location
    • Get a Stock Location
    • Update a Stock Location
    • Add Fulfillment Set to Stock Location
    • Manage Fulfillment Providers of a Stock Location
    • Manage Sales Channels of a Stock Location
    • Create Stock Location
    • List Stock Locations
  • Tax Regions
    • Delete a Tax Region
    • Update a Tax Region
    • Get a Tax Region
    • Create Tax Region
    • List Tax Regions
  • Promotions
    • List Rule Attribute Options of a Rule Type
    • List Rules of a Promotion
    • List Rule Values Given a Rule Attribute
    • Manage the Buy Rules of a Promotion
    • Manage a Promotion's Rules
    • Manage Target Rules of a Promotion
    • Get a Promotion
    • Delete a Promotion
    • Update a Promotion
    • List Promotions
    • Create Promotion
  • Customer Groups
    • Get a Customer Group
    • Update a Customer Group
    • Delete a Customer Group
    • Manage Customers of a Customer Group
    • Create Customer Group
    • List Customer Groups
  • Product Tags
    • Delete a Product Tag
    • Get a Product Tag
    • Update a Product Tag
    • Create Product Tag
    • List Product Tags
  • Product Types
    • Delete a Product Type
    • Get a Product Type
    • Update a Product Type
    • Create Product Type
    • List Product Types
  • Refund Reasons
    • Get a Refund Reason
    • Update a Refund Reason
    • Delete a Refund Reason
    • Create Refund Reason
    • List Refund Reasons
  • Uploads
    • Get a File
    • Delete a File
    • Upload Files
  • Campaigns
    • Manage the Promotions of a Campaign
    • Get a Campaign
    • Delete a Campaign
    • Update a Campaign
    • List Campaigns
    • Create Campaign
  • Collections
    • Manage Products of a Collection
    • Delete a Collection
    • Get a Collection
    • Update a Collection
    • Create Collection
    • List Collections
  • Customers
    • Manage Customer Groups of Customer
    • Get a Customer
    • Delete a Customer
    • Update a Customer
    • List Addresses
    • Add a Customer Address
    • List Addresses
    • Remove an Address from Customer
    • Update a Customer's Address
    • Create Customer
    • List Customers
  • Product Categories
    • Manage Products in Product Category
    • Delete a Product Category
    • Get a Product Category
    • Update a Product Category
    • Create Product Category
    • List Product Categories
  • Reservations
    • Get a Reservation
    • Update a Reservation
    • Delete a Reservation
    • Create Reservation
    • List Reservations
  • Shipping Profiles
    • Delete a Shipping Profile
    • Get a Shipping Profile
    • Update a Shipping Profile
    • Create Shipping Profile
    • List Shipping Profiles
  • Regions
    • Get a Region
    • Delete a Region
    • Update a Region
    • Create Region
    • List Regions
  • Tax Providers
    • List Tax Providers
  • Shipping Options
    • Manage the Rules of a Shipping Option
    • Create Shipping Option
    • List Shipping Options
    • Delete a Shipping Option
    • Get a Shipping Option
    • Update a Shipping Option
  • Product Variants
    • List Product Variants
  1. Claims

Create a Claim

POST
/admin/claims
Create a claim. The claim is still in the request state, and the changes are only applied on the order once the claim is confirmed.
Request Request Example
JavaScript
Shell
Java
Swift
curl --location -g --request POST '{{BASE_URL}}/admin/claims' \
--header 'Content-Type: application/json' \
--data-raw '{
    "order_id": "string",
    "description": "string",
    "internal_note": "string",
    "reason_id": "string",
    "metadata": {},
    "type": "refund"
}'
Response Response Example
200 - Example 1

Request

Authorization
or
or
or
Query Params
fields
string 
fields
optional
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.
Body Params application/json
The claim's details.
order_id
string 
order_id
required
The ID of the order the claim is created for.
description
string 
description
optional
The claim's description.
internal_note
string 
internal_note
optional
A note viewed only by admin users.
reason_id
string 
reason_id
optional
The ID of the associated return reason.
metadata
object 
optional
The claim's metadata, can hold custom key-value pairs.
type
enum<string> 
required
The claim's type.
Allowed values:
refundreplace
Examples

Responses

🟢200OK
application/json
OK
Body
The created claim's details.
order
object (Order) 
required
The order change's order.
shipping_address
object (OrderAddress) 
optional
The address's details.
billing_address
object (OrderAddress) 
optional
The address's details.
id
string 
id
required
The order's ID.
version
number 
version
required
The order's version.
order_change
object 
optional
region_id
string 
region_id
optional
The ID of the region the order belongs to.
customer_id
string 
customer_id
optional
The ID of the customer that placed the order.
sales_channel_id
string 
sales_channel_id
optional
The ID of the sales channel the order was placed in.
email
string <email>
email
optional
The email of the customer that placed the order.
currency_code
string 
currency_code
required
The order's currency code.
Example:
usd
items
array[object (OrderLineItem) {43}] 
optional
The order's items.
shipping_methods
array[object (OrderShippingMethod) {21}] 
optional
The order's shipping methods.
transactions
array[object (OrderTransaction) {11}] 
optional
The order's transactions.
metadata
object 
optional
The order's metadata, can hold custom key-value pairs.
canceled_at
string <date-time>
canceled_at
optional
The date the order was canceled.
created_at
string <date-time>
created_at
required
The date the order was created.
updated_at
string <date-time>
updated_at
required
The date the order was updated.
original_item_total
number 
original_item_total
required
The order items' total including taxes, excluding promotions.
original_item_subtotal
number 
original_item_subtotal
required
The order items' total excluding taxes, including promotions.
original_item_tax_total
number 
original_item_tax_total
required
The taxes total for order items, excluding promotions.
item_total
number 
item_total
required
The order items' total including taxes and promotions.
item_subtotal
number 
item_subtotal
required
The order items' total excluding taxes, including promotions.
item_tax_total
number 
item_tax_total
required
The tax total of the order items including promotions.
original_total
number 
original_total
required
The order's total including taxes, excluding promotions.
original_subtotal
number 
original_subtotal
required
The order's total excluding taxes, including promotions.
original_tax_total
number 
original_tax_total
required
The tax total of the order excluding promotions.
total
number 
total
required
The order's total including taxes and promotions.
subtotal
number 
subtotal
required
The order's subtotal excluding taxes, including promotions.
tax_total
number 
tax_total
required
The tax total of the order including promotions.
discount_subtotal
number 
discount_subtotal
required
The total discount excluding taxes.
discount_total
number 
discount_total
required
The total discount including taxes.
discount_tax_total
number 
discount_tax_total
required
The tax total applied on the discount.
gift_card_total
number 
gift_card_total
required
The order's gift card total.
gift_card_tax_total
number 
gift_card_tax_total
required
The order's gift card tax total.
shipping_total
number 
shipping_total
required
The order's shipping total including taxes and promotions.
shipping_subtotal
number 
shipping_subtotal
required
The order's shipping total excluding taxes, including promotions.
shipping_tax_total
number 
shipping_tax_total
required
The total taxes of the order's shipping including taxes.
original_shipping_total
number 
original_shipping_total
required
The order's shipping total including taxes, excluding promotions.
original_shipping_subtotal
number 
original_shipping_subtotal
required
The order's shipping total excluding taxes, including promotions.
original_shipping_tax_total
number 
original_shipping_tax_total
required
The total taxes of the order's shipping excluding promotions.
display_id
number 
display_id
required
The order's display ID.
credit_lines
array[object (OrderCreditLine) {9}] 
optional
The order's credit lines, useful to add additional payment amounts for an order.
is_draft_order
boolean 
is_draft_order
optional
Whether the order is a draft order.
deleted_at
string <date-time>
deleted_at
optional
The date the order was deleted.
status
enum<string> 
required
The order's status.
Allowed values:
canceledrequires_actionpendingcompleteddraftarchived
summary
object 
optional
The order's summary.
claim
object (AdminClaim) 
required
The claim's details.
return
object (AdminReturn) 
required
The return's details.
order
object (AdminOrder) 
required
The order's details.
id
string 
id
required
The claim's ID.
order_id
string 
order_id
required
The ID of the order associated with the claim.
claim_items
array[object (BaseClaimItem) {10}] 
required
The order items targetted by the claim.
additional_items
array[object (BaseClaimItem) {10}] 
required
The outbound or new items of the claim.
return_id
string 
return_id
optional
The ID of the associated return.
no_notification
boolean 
no_notification
optional
Whether the customer should be notified about changes in the claim.
refund_amount
number 
refund_amount
optional
The amount to be refunded.
display_id
number 
display_id
required
The claim's display ID.
shipping_methods
array[object (AdminOrderShippingMethod) {22}] 
optional
The claim's shipping methods.
metadata
object 
optional
The claim's metadata, used to store custom key-value pairs.
created_at
string <date-time>
created_at
required
The claim's creation date.
updated_at
string <date-time>
updated_at
required
The claim's update date.
order_version
string 
order_version
required
The version of the order when the claim is applied.
created_by
string 
created_by
optional
The ID of the user that created the claim.
canceled_at
string <date-time>
canceled_at
required
The date the claim was canceled.
deleted_at
string <date-time>
deleted_at
optional
The date the claim was deleted.
transactions
array[object (BaseOrderTransaction) {9}] 
optional
The claim's transactions.
type
enum<string> 
required
The claim's type.
Allowed values:
replacerefund
🟠400Bad Request
🟠401Unauthorized
🟠404Record Not Found
🟠409409
🟠422Parameter Error
🔴500Server Error
Modified at 2025-06-17 04:10:32
Previous
Update Outbound Shipping Method of a Claim
Next
List Claims
Built with