Medusa Java SDK

API reference for Medusa's Storefront endpoints. All endpoints are prefixed with /store.

Authentication

To send requests as an authenticated customer, you must use the Cookie Session ID.

Expanding Fields

In many endpoints you'll find an expand query parameter that can be passed to the endpoint. You can use the expand query parameter to unpack an entity's relations and return them in the response. Please note that the relations you pass to expand replace any relations that are expanded by default in the request.

Expanding One Relation

For example, when you retrieve a product, you can retrieve its collection by passing to the expand query parameter the value collection: bash curl \"http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=collection\"

Expanding Multiple Relations

You can expand more than one relation by separating the relations in the expand query parameter with a comma. For example, to retrieve both the variants and the collection of a product, pass to the expand query parameter the value variants,collection: bash curl \"http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand=variants,collection\"

Prevent Expanding Relations

Some requests expand relations by default. You can prevent that by passing an empty expand value to retrieve an entity without any extra relations. For example: bash curl \"http://localhost:9000/store/products/prod_01GDJGP2XPQT2N3JHZQFMH5V45?expand\" This would retrieve the product with only its properties, without any relations like collection.

Selecting Fields

In many endpoints you'll find a fields query parameter that can be passed to the endpoint. You can use the fields query parameter to specify which fields in the entity should be returned in the response. Please note that if you pass a fields query parameter, only the fields you pass in the value along with the id of the entity will be returned in the response. Also, the fields query parameter does not affect the expanded relations. You'll have to use the expand parameter instead.

Selecting One Field

For example, when you retrieve a list of products, you can retrieve only the titles of the products by passing title as a value to the fields query parameter: bash curl \"http://localhost:9000/store/products?fields=title\" As mentioned above, the expanded relations such as variants will still be returned as they're not affected by the fields parameter. You can ensure that only the title field is returned by passing an empty value to the expand query parameter. For example: bash curl \"http://localhost:9000/store/products?fields=title&expand\"

Selecting Multiple Fields

You can pass more than one field by seperating the field names in the fields query parameter with a comma. For example, to select the title and handle of a product: bash curl \"http://localhost:9000/store/products?fields=title,handle\"

Retrieve Only the ID

You can pass an empty fields query parameter to return only the ID of an entity. For example: bash curl \"http://localhost:9000/store/products?fields\" You can also pair with an empty expand query parameter to ensure that the relations aren't retrieved as well. For example: bash curl \"http://localhost:9000/store/products?fields&expand\"

Query Parameter Types

This section covers how to pass some common data types as query parameters. This is useful if you're sending requests to the API endpoints and not using our JS Client. For example, when using cURL or Postman.

Strings

You can pass a string value in the form of <parameter_name>=<value>. For example: bash curl \"http://localhost:9000/store/products?title=Shirt\" If the string has any characters other than letters and numbers, you must encode them. For example, if the string has spaces, you can encode the space with + or %20: bash curl \"http://localhost:9000/store/products?title=Blue%20Shirt\" You can use tools like this one to learn how a value can be encoded.

Integers

You can pass an integer value in the form of <parameter_name>=<value>. For example: bash curl \"http://localhost:9000/store/products?offset=1\"

Boolean

You can pass a boolean value in the form of <parameter_name>=<value>. For example: bash curl \"http://localhost:9000/store/products?is_giftcard=true\"

Date and DateTime

You can pass a date value in the form <parameter_name>=<value>. The date must be in the format YYYY-MM-DD. For example: bash curl -g \"http://localhost:9000/store/products?created_at[lt]=2023-02-17\" You can also pass the time using the format YYYY-MM-DDTHH:MM:SSZ. Please note that the T and Z here are fixed. For example: bash curl -g \"http://localhost:9000/store/products?created_at[lt]=2023-02-17T07:22:30Z\"

Array

Each array value must be passed as a separate query parameter in the form <parameter_name>[]=<value>. You can also specify the index of each parameter in the brackets <parameter_name>[0]=<value>. For example: bash curl -g \"http://localhost:9000/store/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7\" Note that the -g parameter passed to curl disables errors being thrown for using the brackets. Read more here.

Object

Object parameters must be passed as separate query parameters in the form <parameter_name>[<key>]=<value>. For example: bash curl -g \"http://localhost:9000/store/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17\"

Pagination

Query Parameters

In listing endpoints, such as list customers or list products, you can control the pagination using the query parameters limit and offset. limit is used to specify the maximum number of items that can be return in the response. offset is used to specify how many items to skip before returning the resulting entities. You can use the offset query parameter to change between pages. For example, if the limit is 50, at page 1 the offset should be 0; at page 2 the offset should be 50, and so on.

For example, to limit the number of products returned in the List Products endpoint: bash curl \"http://localhost:9000/store/products?limit=5\"

Response Fields

In the response of listing endpoints, aside from the entities retrieved, there are three pagination-related fields returned: count, limit, and offset. Similar to the query parameters, limit is the maximum number of items that can be returned in the response, and field is the number of items that were skipped before the entities in the result. count is the total number of available items of this entity. It can be used to determine how many pages are there. For example, if the count is 100 and the limit is 50, you can divide the count by the limit to get the number of pages: 100/50 = 2 pages.

Automatically generated by the Swagger Codegen

Requirements

Building the API client library requires:

1. Java 1.7+
2. Maven/Gradle

Installation

To install the API client library to your local Maven repository, simply execute:

mvn clean install

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

mvn clean deploy

Refer to the OSSRH Guide for more information.

Maven users

Add this dependency to your project's POM:

<repositories>
  <repository>
      <id>jitpack.io</id>
      <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependency>
    <groupId>com.github.AppcentMobile</groupId>
    <artifactId>medusa-java-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle users

Add this dependency to your project's build file:

allprojects {
  repositories {
    ...
    maven { url 'https://jitpack.io' }
  }
}

implementation 'com.github.AppcentMobile:medusa-java-sdk:1.0.1'

Others

At first generate the JAR by executing:

mvn clean package

Then manually install the following JARs:

• target/medusa-java-sdk-1.0.1.jar
• target/lib/*.jar

Getting Started

Please follow the installation instruction and execute the following Java code:

import mobi.appcent.medusa.store.MedusaSdkClient;
import mobi.appcent.medusa.store.ApiException;
import mobi.appcent.medusa.store.api.AuthApi;
import mobi.appcent.medusa.store.model.response.StoreAuthRes;
import mobi.appcent.medusa.store.model.response.StoreGetAuthEmailRes;
import mobi.appcent.medusa.store.model.response.StorePostAuthReq;

public class AuthApiExample {

    public static void main(String[] args) {
        MedusaSdkClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: cookie_auth
        ApiKeyAuth cookie_auth = (ApiKeyAuth) defaultClient.getAuthentication("cookie_auth");
        cookie_auth.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //cookie_auth.setApiKeyPrefix("Token");

        AuthApi apiInstance = new AuthApi();
        try {
            apiInstance.deleteAuth();
        } catch (ApiException e) {
            System.err.println("Exception when calling AuthApi#deleteAuth");
            e.printStackTrace();
        }
    }
}
import mobi.appcent.medusa.store.*;
        import mobi.appcent.medusa.store.auth.*;
        import mobi.appcent.medusa.store.model.*;
        import mobi.appcent.medusa.store.api.AuthApi;

        import java.io.File;
        import java.util.*;

public class AuthApiExample {

    public static void main(String[] args) {
        MedusaSdkClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: cookie_auth
        ApiKeyAuth cookie_auth = (ApiKeyAuth) defaultClient.getAuthentication("cookie_auth");
        cookie_auth.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //cookie_auth.setApiKeyPrefix("Token");

        AuthApi apiInstance = new AuthApi();
        try {
            StoreAuthRes result = apiInstance.getAuth();
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AuthApi#getAuth");
            e.printStackTrace();
        }
    }
}
import mobi.appcent.medusa.store.*;
        import mobi.appcent.medusa.store.auth.*;
        import mobi.appcent.medusa.store.model.*;
        import mobi.appcent.medusa.store.api.AuthApi;

        import java.io.File;
        import java.util.*;

public class AuthApiExample {

    public static void main(String[] args) {

        AuthApi apiInstance = new AuthApi();
        String email = "email_example"; // String | The email to check if exists.
        try {
            StoreGetAuthEmailRes result = apiInstance.getAuthEmail(email);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AuthApi#getAuthEmail");
            e.printStackTrace();
        }
    }
}
import mobi.appcent.medusa.store.*;
        import mobi.appcent.medusa.store.auth.*;
        import mobi.appcent.medusa.store.model.*;
        import mobi.appcent.medusa.store.api.AuthApi;

        import java.io.File;
        import java.util.*;

public class AuthApiExample {

    public static void main(String[] args) {

        AuthApi apiInstance = new AuthApi();
        StorePostAuthReq body = new StorePostAuthReq(); // StorePostAuthReq | 
        try {
            StoreAuthRes result = apiInstance.postAuth(body);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling AuthApi#postAuth");
            e.printStackTrace();
        }
    }
}

Documentation for API Endpoints

All URIs are relative to https://api.medusa-commerce.com/store

Class	Method	HTTP request	Description
AuthApi	deleteAuth	DELETE /auth	Customer Log out
AuthApi	getAuth	GET /auth	Get Current Customer
AuthApi	getAuthEmail	GET /auth/{email}	Check if email exists
AuthApi	postAuth	POST /auth	Customer Login
CartApi	deleteCartsCartDiscountsDiscount	DELETE /carts/{id}/discounts/{code}	Remove Discount
CartApi	deleteCartsCartLineItemsItem	DELETE /carts/{id}/line-items/{line_id}	Delete a Line Item
CartApi	deleteCartsCartPaymentSessionsSession	DELETE /carts/{id}/payment-sessions/{provider_id}	Delete a Payment Session
CartApi	getCartsCart	GET /carts/{id}	Get a Cart
CartApi	postCart	POST /carts	Create a Cart
CartApi	postCartsCart	POST /carts/{id}	Update a Cart
CartApi	postCartsCartComplete	POST /carts/{id}/complete	Complete a Cart
CartApi	postCartsCartLineItems	POST /carts/{id}/line-items	Add a Line Item
CartApi	postCartsCartLineItemsItem	POST /carts/{id}/line-items/{line_id}	Update a Line Item
CartApi	postCartsCartPaymentSession	POST /carts/{id}/payment-session	Select a Payment Session
CartApi	postCartsCartPaymentSessionUpdate	POST /carts/{id}/payment-sessions/{provider_id}	Update a Payment Session
CartApi	postCartsCartPaymentSessions	POST /carts/{id}/payment-sessions	Create Payment Sessions
CartApi	postCartsCartPaymentSessionsSession	POST /carts/{id}/payment-sessions/{provider_id}/refresh	Refresh a Payment Session
CartApi	postCartsCartShippingMethod	POST /carts/{id}/shipping-methods	Add a Shipping Method
CartApi	postCartsCartTaxes	POST /carts/{id}/taxes	Calculate Cart Taxes
CollectionApi	getCollections	GET /collections	List Collections
CollectionApi	getCollectionsCollection	GET /collections/{id}	Get a Collection
CustomerApi	deleteCustomersCustomerAddressesAddress	DELETE /customers/me/addresses/{address_id}	Delete an Address
CustomerApi	getCustomersCustomer	GET /customers/me	Get a Customer
CustomerApi	getCustomersCustomerOrders	GET /customers/me/orders	List Orders
CustomerApi	getCustomersCustomerPaymentMethods	GET /customers/me/payment-methods	Get Payment Methods
CustomerApi	postCustomers	POST /customers	Create a Customer
CustomerApi	postCustomersCustomer	POST /customers/me	Update Customer
CustomerApi	postCustomersCustomerAddresses	POST /customers/me/addresses	Add a Shipping Address
CustomerApi	postCustomersCustomerAddressesAddress	POST /customers/me/addresses/{address_id}	Update a Shipping Address
CustomerApi	postCustomersCustomerPasswordToken	POST /customers/password-token	Request Password Reset
CustomerApi	postCustomersResetPassword	POST /customers/password-reset	Reset Password
GiftCardApi	getGiftCardsCode	GET /gift-cards/{code}	Get Gift Card by Code
InviteApi	postOrdersCustomerOrderClaim	POST /orders/batch/customer/token	Claim an Order
OrderApi	getOrders	GET /orders	Look Up an Order
OrderApi	getOrdersOrder	GET /orders/{id}	Get an Order
OrderApi	getOrdersOrderCartId	GET /orders/cart/{cart_id}	Get by Cart ID
OrderApi	postOrdersCustomerOrderClaimsCustomerOrderClaimAccept	POST /orders/customer/confirm	Verify an Order Claim
OrderEditApi	getOrderEditsOrderEdit	GET /order-edits/{id}	Retrieve an OrderEdit
OrderEditApi	postOrderEditsOrderEditComplete	POST /order-edits/{id}/complete	Completes an OrderEdit
OrderEditApi	postOrderEditsOrderEditDecline	POST /order-edits/{id}/decline	Decline an OrderEdit
PaymentCollectionApi	getPaymentCollectionsPaymentCollection	GET /payment-collections/{id}	Get a PaymentCollection
PaymentCollectionApi	postPaymentCollectionsPaymentCollectionPaymentSessionsSession	POST /payment-collections/{id}/sessions/{session_id}	Refresh a Payment Session
PaymentCollectionApi	postPaymentCollectionsPaymentCollectionSessionsBatch	POST /payment-collections/{id}/sessions/batch	Manage Payment Sessions
PaymentCollectionApi	postPaymentCollectionsSessions	POST /payment-collections/{id}/sessions	Manage a Payment Session
PaymentCollectionApi	postPaymentCollectionsSessionsBatchAuthorize	POST /payment-collections/{id}/sessions/batch/authorize	Authorize PaymentSessions
PaymentCollectionApi	postPaymentCollectionsSessionsSessionAuthorize	POST /payment-collections/{id}/sessions/{session_id}/authorize	Authorize Payment Session
ProductApi	getProducts	GET /products	List Products
ProductApi	getProductsProduct	GET /products/{id}	Get a Product
ProductApi	postProductsSearch	POST /products/search	Search Products
ProductCategoryApi	getProductCategories	GET /product-categories	List Product Categories
ProductCategoryApi	getProductCategoriesCategory	GET /product-categories/{id}	Get a Product Category
ProductTagApi	getProductTags	GET /product-tags	List Product Tags
ProductTypeApi	getProductTypes	GET /product-types	List Product Types
ProductVariantApi	getVariants	GET /variants	Get Product Variants
ProductVariantApi	getVariantsVariant	GET /variants/{variant_id}	Get a Product Variant
RegionApi	getRegions	GET /regions	List Regions
RegionApi	getRegionsRegion	GET /regions/{id}	Get a Region
ReturnApi	postReturns	POST /returns	Create Return
ReturnReasonApi	getReturnReasons	GET /return-reasons	List Return Reasons
ReturnReasonApi	getReturnReasonsReason	GET /return-reasons/{id}	Get a Return Reason
ShippingOptionApi	getShippingOptions	GET /shipping-options	Get Shipping Options
ShippingOptionApi	getShippingOptionsCartId	GET /shipping-options/{cart_id}	List for Cart
SwapApi	getSwapsSwapCartId	GET /swaps/{cart_id}	Get by Cart ID
SwapApi	postSwaps	POST /swaps	Create a Swap

Documentation for Models

Documentations for models

cookie_auth

• Type: API key
• API key parameter name: connect.sid
• Location: URL query string

Recommendation

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.