Medusa
Store APIAdmin API
Store APIAdmin API
Discord
Twitter
Linkedin
Github
  1. Orders
  • Auth
    • Get Current User
      GET
    • User Logout
      DELETE
    • User Login
      POST
    • User Login (JWT)
      POST
  • Apps Oauth
    • Generate Token for App
    • List Applications
  • Batch Jobs
    • Cancel a Batch Job
    • Get a Batch Job
    • Confirm a Batch Job
    • List Batch Jobs
    • Create a Batch Job
  • Currencies
    • List Currency
    • Update a Currency
  • Customers
    • Create a Customer
    • List Customers
    • Update a Customer
    • Get a Customer
  • Customer Groups
    • Remove Customers from Group
    • Add Customers to Group
    • List Customers
    • Create a Customer Group
    • List Customer Groups
    • Get a Customer Group
    • Delete a Customer Group
    • Update a Customer Group
  • Discounts
    • Create a Condition
    • Create a Discount
    • List Discounts
    • Get a Condition
    • Update a Condition
    • Delete a Condition
    • Create a Dynamic Code
    • Remove Batch Resources
    • Add Batch Resources
    • Get Discount by Code
    • Delete a Dynamic Code
    • Add Region to Discount
    • Remove Region
    • Delete a Discount
    • Update a Discount
    • Get a Discount
  • Draft Orders
    • Create a Line Item
    • Delete a Line Item
    • Update a Line Item
    • Update a Draft Order
    • Delete a Draft Order
    • Get a Draft Order
    • Create a Draft Order
    • List Draft Orders
    • Mark Paid
  • Gift Cards
    • Create a Gift Card
    • List Gift Cards
    • Delete a Gift Card
    • Get a Gift Card
    • Update a Gift Card
  • Inventory Items
    • Create an Inventory Item
    • List Inventory Items
    • List Inventory Level
    • Create an Location Level
    • Update an Inventory Item
    • Get an Inventory Item
    • Delete an Inventory Item
    • Update a Location Level
    • Delete a Location Level
  • Invites
    • Lists Invites
    • Create an Invite
    • Delete an Invite
    • Accept an Invite
    • Resend an Invite
  • Notes
    • List Notes
    • Create a Note
    • Get a Note
    • Delete a Note
    • Update a Note
  • Notifications
    • Resend Notification
    • List Notifications
  • Orders
    • Create a Reservation
      POST
    • Cancel Claim's Fulfillment
      POST
    • Ship a Claim's Fulfillment
      POST
    • Cancel Swap's Fulfilmment
      POST
    • Get Order Reservations
      GET
    • Add a Shipping Method
      POST
    • Create a Refund
      POST
    • Get an Order
      GET
    • Update an Order
      POST
    • Create a Fulfillment
      POST
    • Cancel a Swap
      POST
    • List Orders
      GET
    • Create a Swap
      POST
    • Complete an Order
      POST
    • Create a Swap Fulfillment
      POST
    • Cancel a Claim
      POST
    • Process a Swap Payment
      POST
    • Ship a Fulfillment
      POST
    • Capture an Order's Payments
      POST
    • Archive Order
      POST
    • Update a Claim
      POST
    • Request a Return
      POST
    • Create a Claim Fulfillment
      POST
    • Ship a Swap's Fulfillment
      POST
    • Cancel a Fulfilmment
      POST
    • Create a Claim
      POST
    • Cancel an Order
      POST
  • Order Edits
    • Delete a Line Item Change
    • Add a Line Item
    • Upsert Line Item Change
    • Delete Line Item
    • Cancel an Order Edit
    • Delete an Order Edit
    • Get an Order Edit
    • Update an Order Edit
    • Request Confirmation
    • Create an OrderEdit
    • List Order Edits
    • Confirm an OrderEdit
  • Payments
    • Capture a Payment
    • Get Payment details
    • Refund Payment
  • Payment Collections
    • Delete a Payment Collection
    • Get a Payment Collection
    • Update Payment Collection
    • Mark Authorized
  • Product Collections
    • Add Products to Collection
    • Remove Products from Collection
    • Get a Collection
    • Update a Collection
    • Delete a Collection
    • List Collections
    • Create a Collection
  • Product Tags
    • List Product Tags
  • Product Types
    • List Product Types
  • Product Variants
    • Get Variant's Inventory
    • List Product Variants
    • Get a Product variant
  • Price Lists
    • Delete a Product's Prices
    • List Products
    • Delete a Variant's Prices
    • Get a Price List
    • Update a Price List
    • Delete a Price List
    • Add or Update Prices
    • Delete Prices
    • Create a Price List
    • List Price Lists
  • Products
    • List Product Types
    • List Tags Usage Number
    • List a Product's Variants
    • Create a Product Variant
    • Update a Product Variant
    • Delete a Product Variant
    • Add a Product Option
    • Set Metadata
    • Delete a Product Option
    • Update a Product Option
    • List Products
    • Create a Product
    • Delete a Product
    • Update a Product
    • Get a Product
  • Product Categories
    • Create a Product Category
    • List Product Categories
    • Update a Product Category
    • Delete a Product Category
    • Get a Product Category
    • Add Products to a Category
    • Remove Products from Category
  • Publishable Api Keys
    • List Sales Channels
    • Delete Publishable API Key
    • Get a Publishable API Key
    • Revoke a Publishable API Key
    • Remove Sales Channels
    • Add Sales Channels
    • Update Publishable API Key
    • List Publishable API keys
    • Create Publishable API Key
  • Reservations
    • Delete a Reservation
    • Update a Reservation
    • Get a Reservation
    • Create a Reservation
    • List Reservations
  • Regions
    • List Fulfillment Options
    • Add Country
    • Remove Fulfillment Provider
    • Remove Payment Provider
    • Add Payment Provider
    • Delete a Region
    • Update a Region
    • Get a Region
    • List Regions
    • Create a Region
    • Add Fulfillment Provider
    • Remove Country
  • Return Reasons
    • Get a Return Reason
    • Delete a Return Reason
    • Update a Return Reason
    • List Return Reasons
    • Create a Return Reason
  • Returns
    • Receive a Return
    • List Returns
    • Cancel a Return
  • Sales Channels
    • Remove Stock Location from Sales Channels.
    • Associate a Stock Location
    • Get a Sales Channel
    • Delete a Sales Channel
    • Update a Sales Channel
    • Remove Products from Sales Channel
    • Add Products to Sales Channel
    • Create a Sales Channel
    • List Sales Channels
  • Shipping Options
    • Update Shipping Option
    • Get a Shipping Option
    • Delete Shipping Option
    • List Shipping Options
    • Create Shipping Option
  • Shipping Profiles
    • List Shipping Profiles
    • Create a Shipping Profile
    • Delete a Shipping Profile
    • Update a Shipping Profile
    • Get a Shipping Profile
  • Stock Locations
    • Get a Stock Location
    • List Stock Locations
    • Create a Stock Location
    • Update a Stock Location
    • Delete a Stock Location
  • Store
    • List Payment Providers
    • Add a Currency Code
    • Remove a Currency
    • List Tax Providers
    • Update Store Details
    • Get Store details
  • Swaps
    • Get a Swap
    • List Swaps
  • Uploads
    • Upload Files
    • Delete an Uploaded File
    • Get a File's Download URL
    • Protected File Upload
  • Tax Rates
    • Add to Shipping Options
    • Remove Shipping Options from Rate
    • Create a Tax Rate
    • List Tax Rates
    • Add to Products
    • Remove Products from Rate
    • Delete a Tax Rate
    • Get a Tax Rate
    • Update a Tax Rate
    • Add to Product Types
    • Remove Product Types from Rate
  • Users
    • Reset Password
    • Request Password Reset
    • Get a User
    • Delete a User
    • Update a User
    • Create a User
    • List Users
  1. Orders

Create a Claim

POST
/admin/orders/{id}/claims
Orders
Create a Claim for an order. If a return shipping method is specified, a return will also be created and associated with the claim. If the claim's type is refund, the refund is processed as well.
Request Request Example
Shell
JavaScript
Java
Swift
curl --location -g --request POST '{{BASE_URL}}/admin/orders//claims' \
--header 'Content-Type: application/json' \
--data-raw '{
    "refund_amount": 0,
    "no_notification": true,
    "type": "replace",
    "metadata": {},
    "return_shipping": {
        "option_id": "string",
        "price": 0
    },
    "additional_items": [
        {
            "variant_id": "string",
            "quantity": 0
        }
    ],
    "shipping_methods": [
        {
            "id": "string",
            "option_id": "string",
            "price": 0,
            "data": {}
        }
    ],
    "claim_items": [
        {
            "item_id": "string",
            "quantity": 0,
            "note": "string",
            "reason": "missing_item",
            "tags": [
                "string"
            ],
            "images": [
                "string"
            ]
        }
    ],
    "shipping_address": {
        "first_name": "Arno",
        "last_name": "Willms",
        "phone": 16128234334802,
        "company": "string",
        "address_1": "14433 Kemmer Court",
        "address_2": "Suite 369",
        "city": "South Geoffreyview",
        "province": "Kentucky",
        "postal_code": 72093,
        "country_code": "st",
        "metadata": {
            "car": "white"
        }
    }
}'
Response Response Example
200 - Example 1

Request

Path Params
id
string 
required
The ID of the Order.
Query Params
expand
string 
optional
Comma-separated relations that should be expanded in the returned order.
fields
string 
optional
Comma-separated fields that should be included in the returned order.
Body Params application/json
refund_amount
integer 
optional
The amount to refund the customer. This is used when the claim's type is refund.
no_notification
boolean 
optional
If set to true no notification will be send related to this Claim.
type
enum<string> 
required
The type of the Claim. This will determine how the Claim is treated: replace Claims will result in a Fulfillment with new items being created, while a refund Claim will refund the amount paid for the claimed items.
Allowed values:
replacerefund
metadata
object 
optional
An optional set of key-value pairs to hold additional information.
return_shipping
object 
optional
Optional details for the Return Shipping Method, if the items are to be sent back. Providing this field will result in a return being created and associated with the claim.
option_id
string 
optional
The ID of the Shipping Option to create the Shipping Method from.
price
integer 
optional
The price to charge for the Shipping Method.
additional_items
array [object {2}] 
optional
The new items to send to the Customer. This is only used if the claim's type is replace.
variant_id
string 
required
The ID of the Product Variant.
quantity
integer 
required
The quantity of the Product Variant.
shipping_methods
array [object {4}] 
optional
The Shipping Methods to send the additional Line Items with. This is only used if the claim's type is replace.
id
string 
optional
The ID of an existing Shipping Method
option_id
string 
optional
The ID of the Shipping Option to create a Shipping Method from
price
integer 
optional
The price to charge for the Shipping Method
data
object 
optional
An optional set of key-value pairs to hold additional information.
claim_items
array [object {6}] 
required
The Claim Items that the Claim will consist of.
item_id
string 
required
The ID of the Line Item that will be claimed.
quantity
integer 
required
The number of items that will be returned
note
string 
optional
Short text describing the Claim Item in further detail.
reason
enum<string> 
optional
The reason for the Claim
Allowed values:
missing_itemwrong_itemproduction_failureother
tags
array[string]
optional
A list of tags to add to the Claim Item
images
array[string]
optional
A list of image URL's that will be associated with the Claim
shipping_address
object (AddressPayload) 
optional
Address fields used when creating/updating an address.
first_name
string 
optional
First name
Example:
Arno
last_name
string 
optional
Last name
Example:
Willms
phone
string 
optional
Phone Number
Example:
16128234334802
company
string 
optional
address_1
string 
optional
Address line 1
Example:
14433 Kemmer Court
address_2
string 
optional
Address line 2
Example:
Suite 369
city
string 
optional
City
Example:
South Geoffreyview
province
string 
optional
Province
Example:
Kentucky
postal_code
string 
optional
Postal Code
Example:
72093
country_code
string 
optional
The 2 character ISO code of the country in lower case
Example:
st
metadata
object 
optional
An optional key-value map with additional details
Example:
{"car":"white"}
Examples

Responses

🟢200OK
application/json
Body
order
object (Order) 
required
An order is a purchase made by a customer. It holds details about payment and fulfillment of the order. An order may also be created from a draft order, which is created by an admin user.
id
string 
required
The order's ID
Example:
order_01G8TJSYT9M6AVS5N4EMNFS1EK
display_id
integer 
required
The order's display ID
Example:
2
cart_id
string  | null 
required
The ID of the cart associated with the order
Example:
cart_01G8ZH853Y6TFXWPG5EYE81X63
cart
object  | null 
optional
The details of the cart associated with the order.
customer_id
string 
required
The ID of the customer associated with the order
Example:
cus_01G2SG30J8C85S4A5CHM2S1NS2
customer
object  | null 
optional
The details of the customer associated with the order.
email
string <email>
required
The email associated with the order
billing_address_id
string  | null 
required
The ID of the billing address associated with the order
Example:
addr_01G8ZH853YPY9B94857DY91YGW
shipping_address_id
string  | null 
required
The ID of the shipping address associated with the order
Example:
addr_01G8ZH853YPY9B94857DY91YGW
region_id
string 
required
The ID of the region this order was created in.
Example:
reg_01G1G5V26T9H8Y0M4JNE3YGA4G
tax_rate
number  | null 
required
The order's tax rate
Example:
0
draft_order_id
string  | null 
required
The ID of the draft order this order was created from.
Example:
null
draft_order
object  | null 
optional
The details of the draft order this order was created from.
canceled_at
string <date-time> | null 
required
The date the order was canceled on.
no_notification
boolean  | null 
required
Flag for describing whether or not notifications related to this should be send.
Example:
false
external_id
string  | null 
required
The ID of an external order.
Example:
null
sales_channel_id
string  | null 
optional
The ID of the sales channel this order belongs to.
Example:
null
shipping_total
integer 
optional
The total of shipping
Example:
1000
raw_discount_total
integer 
optional
The total of discount
Example:
800
discount_total
integer 
optional
The total of discount rounded
Example:
800
tax_total
integer 
optional
The total of tax
Example:
0
refunded_total
integer 
optional
The total amount refunded if the order is returned.
Example:
0
total
integer 
optional
The total amount of the order
Example:
8200
subtotal
integer 
optional
The subtotal of the order
Example:
8000
paid_total
integer 
optional
The total amount paid
Example:
8000
refundable_amount
integer 
optional
The amount that can be refunded
Example:
8200
gift_card_total
integer 
optional
The total of gift cards
Example:
0
gift_card_tax_total
integer 
optional
The total of gift cards with taxes
Example:
0
created_at
string <date-time>
required
The date with timezone at which the resource was created.
updated_at
string <date-time>
required
The date with timezone at which the resource was updated.
status
enum<string> 
required
The order's status
Allowed values:
pendingcompletedarchivedcanceledrequires_action
Default:
pending
fulfillment_status
enum<string> 
required
The order's fulfillment status
Allowed values:
not_fulfilledpartially_fulfilledfulfilledpartially_shippedshippedpartially_returnedreturnedcanceledrequires_action
Default:
not_fulfilled
payment_status
enum<string> 
required
The order's payment status
Allowed values:
not_paidawaitingcapturedpartially_refundedrefundedcanceledrequires_action
Default:
not_paid
currency_code
string 
required
The 3 character currency code that is used in the order
Example:
usd
payments
array [object] 
optional
The details of the payments used in the order.
fulfillments
array [object] 
optional
The details of the fulfillments created for the order.
returns
array [object] 
optional
The details of the returns created for the order.
claims
array [object] 
optional
The details of the claims created for the order.
refunds
array [object] 
optional
The details of the refunds created for the order.
swaps
array [object] 
optional
The details of the swaps created for the order.
edits
array [object] 
optional
The details of the order edits done on the order.
idempotency_key
string  | null 
required
Randomly generated key used to continue the processing of the order in case of failure.
metadata
object  | null 
required
An optional key-value map with additional details
Example:
{"car":"white"}
gift_card_transactions
array[object (Gift Card Transaction) {9}] 
optional
The gift card transactions made in the order.
currency
object (Currency) 
optional
Currency
sales_channel
object (Sales Channel) 
optional
A Sales Channel is a method a business offers its products for purchase for the customers. For example, a Webshop can be a sales channel, and a mobile app can be another.
billing_address
object (Address) 
optional
An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
shipping_address
object (Address) 
optional
An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.
shipping_methods
array[object (Shipping Method) {20}] 
optional
The details of the shipping methods used in the order.
region
object (Region) 
optional
A region holds settings specific to a geographical location, including the currency, tax rates, and fulfillment and payment providers. A Region can consist of multiple countries to accomodate common shopping settings across countries.
gift_cards
array[object (Gift Card) {15}] 
optional
The details of the gift card used in the order.
discounts
array[object (Discount) {18}] 
optional
The details of the discounts applied on the order.
items
array[object (Line Item) {42}] 
optional
The details of the line items that belong to the order.
returnable_items
array[object (Line Item) {42}] 
optional
The details of the line items that are returnable as part of the order, swaps, or claims
🟠400Client Error or Multiple Errors
🟠401User is not authorized. Must log in first
🟠404Not Found Error
🟠409Invalid State Error
🟠422Invalid Request Error
🔴500Server Error
Modified at 2023-10-10 11:56:36
Previous
Cancel a Fulfilmment
Next
Cancel an Order
Built with