Skip to main content

Medusa Admin API (1.0.0)

Download OpenAPI specification:Download

License: MIT

API reference for Medusa's Admin endpoints. All endpoints are prefixed with /admin.

Authentication

There are two ways to send authenticated requests to the Medusa server: Using a user's API token, or using a Cookie Session ID.

API Token

Use a user's API Token to send authenticated requests.

How to Add API Token to a User

At the moment, there's no direct way of adding an API Token for a user. The only way it can be done is through directly editing the database.

If you're using a PostgreSQL database, you can run the following commands in your command line to add API token:

psql -d <DB_NAME> -U <DB_USER>
UPDATE public.user SET api_token='<API_TOKEN>' WHERE email='<USER_EMAIL>';

Where:

  • <DB_NAME> is the name of the database schema you use for the Medusa server.
  • <DB_USER> is the name of the user that has privileges over the database schema.
  • <API_TOKEN> is the API token you want to associate with the user. You can use this tool to generate a random token.
  • <USER_EMAIL> is the email address of the admin user you want to have this API token.

How to Use the API Token

The API token can be used for Bearer Authentication. It's passed in the Authorization header as the following:

Authorization: Bearer {api_token}

In this API reference, you'll find in the cURL request samples the use of {api_token}. This is where you must pass the API token.

If you're following along with the JS Client request samples, you must provide the apiKey option when creating the Medusa client:

const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3, apiKey: '{api_token}' })

If you're using Medusa React, you can pass the apiKey prop to MedusaProvider:

<MedusaProvider
  apiKey='api_token}'
  //...
>
Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer

Cookie Session ID

Use a cookie session to send authenticated requests.

If you're sending requests through a browser, using JS Client, or using tools like Postman, the cookie session should be automatically set when the admin user is logged in.

If you're sending requests using cURL, you must set the Session ID in the cookie manually.

To do that, send a request to authenticate the user and pass the cURL option -v:

curl -v --location --request POST 'https://medusa-url.com/admin/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "user@example.com",
  "password": "supersecret"
}'

The headers will be logged in the terminal as well as the response. You should find in the headers a Cookie header similar to this:

Set-Cookie: connect.sid=s%3A2Bu8BkaP9JUfHu9rG59G16Ma0QZf6Gj1.WT549XqX37PN8n0OecqnMCq798eLjZC5IT7yiDCBHPM;

Copy the value after connect.sid (without the ; at the end) and pass it as a cookie in subsequent requests as the following:

curl --location --request GET 'https://medusa-url.com/admin/products' \
--header 'Cookie: connect.sid={sid}'

Where {sid} is the value of connect.sid that you copied.

Security Scheme Type: API Key
Cookie parameter name: connect.sid

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 products, you can retrieve their collection by passing to the expand query parameter the value collection:

curl "http://localhost:9000/admin/products?expand=collection" \
-H 'Authorization: Bearer {api_token}'

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 products, pass to the expand query parameter the value variants,collection:

curl "http://localhost:9000/admin/products?expand=variants,collection" \
-H 'Authorization: Bearer {api_token}'

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:

curl "http://localhost:9000/admin/products?expand" \
-H 'Authorization: Bearer {api_token}'

This would retrieve each 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:

curl "http://localhost:9000/admin/products?fields=title" \
-H 'Authorization: Bearer {api_token}'

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:

curl "http://localhost:9000/admin/products?fields=title&expand" \
-H 'Authorization: Bearer {api_token}'

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 products:

curl "http://localhost:9000/admin/products?fields=title,handle" \
-H 'Authorization: Bearer {api_token}'

Retrieve Only the ID

You can pass an empty fields query parameter to return only the ID of an entity. For example:

curl "http://localhost:9000/admin/products?fields" \
-H 'Authorization: Bearer {api_token}'

You can also pair with an empty expand query parameter to ensure that the relations aren't retrieved as well. For example:

curl "http://localhost:9000/admin/products?fields&expand" \
-H 'Authorization: Bearer {api_token}'

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:

curl "http://localhost:9000/admin/products?title=Shirt" \
-H 'Authorization: Bearer {api_token}'

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:

curl "http://localhost:9000/admin/products?title=Blue%20Shirt" \
-H 'Authorization: Bearer {api_token}'

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:

curl "http://localhost:9000/admin/products?offset=1" \
-H 'Authorization: Bearer {api_token}'

Boolean

You can pass a boolean value in the form of <parameter_name>=<value>.

For example:

curl "http://localhost:9000/admin/products?is_giftcard=true" \
-H 'Authorization: Bearer {api_token}'

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:

curl -g "http://localhost:9000/admin/products?created_at[lt]=2023-02-17" \
-H 'Authorization: Bearer {api_token}'

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:

curl -g "http://localhost:9000/admin/products?created_at[lt]=2023-02-17T07:22:30Z" \
-H 'Authorization: Bearer {api_token}'

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:

curl -g "http://localhost:9000/admin/products?sales_channel_id[]=sc_01GPGVB42PZ7N3YQEP2WDM7PC7&sales_channel_id[]=sc_234PGVB42PZ7N3YQEP2WDM7PC7" \
-H 'Authorization: Bearer {api_token}'

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:

curl -g "http://localhost:9000/admin/products?created_at[lt]=2023-02-17&created_at[gt]=2022-09-17" \
-H 'Authorization: Bearer {api_token}'

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:

curl "http://localhost:9000/admin/products?limit=5" \
-H 'Authorization: Bearer {api_token}'

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.

Sort Order

The order field available on endpoints supporting pagination allows you to sort the retrieved items by an attribute of that item. For example, you can sort products by their created_at attribute by setting order to created_at:

curl "http://localhost:9000/admin/products?order=created_at" \
-H 'Authorization: Bearer {api_token}'

By default, the sort direction will be ascending. To change it to descending, pass a dash (-) before the attribute name. For example:

curl "http://localhost:9000/admin/products?order=-created_at" \
-H 'Authorization: Bearer {api_token}'

This sorts the products by their created_at attribute in the descending order.

Apps

App endpoints that allow handling apps in Medusa.

List Applications

Retrieve a list of applications.

Authorizations:
API TokenCookie Session ID

Responses

Response Schema: application/json
required
Array of objects (OAuth)
Array
application_name
required
string
Example: "example"

The app's name

data
required
object or null
Example: {}

Any data necessary to the app.

display_name
required
string
Example: "Example app"

The app's display name

id
required
string
Example: "example_app"

The app's ID

install_url
required
string or null <uri>

The URL to install the app

uninstall_url
required
string or null <uri>

The URL to uninstall the app

Request samples

curl --location --request GET 'https://medusa-url.com/admin/apps' \
--header 'Authorization: Bearer {api_token}'

Response samples

Content type
application/json
{}

Generate Token for App

Generates a token for an application.

Authorizations:
API TokenCookie Session ID
Request Body schema: application/json
application_name
required
string

Name of the application for the token to be generated for.

state
required
string

State of the application.

code
required
string

The code for the generated token.

Responses

Response Schema: application/json
required
object (OAuth)

Represent an OAuth app

application_name
required
string
Example: "example"

The app's name

data
required
object or null
Example: {}

Any data necessary to the app.

display_name
required
string
Example: "Example app"

The app's display name

id
required
string
Example: "example_app"

The app's ID

install_url
required
string or null <uri>

The URL to install the app

uninstall_url
required
string or null <uri>

The URL to uninstall the app

Request samples

Content type
application/json
{
  • "application_name": "string",
  • "state": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{}

Auth

Auth endpoints that allow authorization of admin Users and manages their sessions.

Get Current User

Gets the currently logged in User.

Authorizations:
API TokenCookie Session ID

Responses

Response Schema: application/json
required
object (User)

Represents a User who can manage store settings.

api_token
required
string or null
Example: null

An API token associated with the user.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string <email>

The email of the User

first_name
required
string or null
Example: "Levi"

The first name of the User

id
required
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The user's ID

last_name
required
string or null
Example: "Bogan"

The last name of the User

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

role
required
string
Default: "member"
Enum: "admin" "member" "developer"

The user's role

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.auth.getSession()
.then(({ user }) => {
  console.log(user.id);
});

Response samples

Content type
application/json
{
  • "user": {
    }
}

User Login

Logs a User in and authorizes them to manage Store settings.

Request Body schema: application/json
email
required
string

The User's email.

password
required
string

The User's password.

Responses

Response Schema: application/json
required
object (User)

Represents a User who can manage store settings.

api_token
required
string or null
Example: null

An API token associated with the user.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string <email>

The email of the User

first_name
required
string or null
Example: "Levi"

The first name of the User

id
required
string
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The user's ID

last_name
required
string or null
Example: "Bogan"

The last name of the User

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

role
required
string
Default: "member"
Enum: "admin" "member" "developer"

The user's role

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "user": {
    }
}

User Logout

Deletes the current session for the logged in user.

Authorizations:
API TokenCookie Session ID

Responses

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.auth.deleteSession()

Response samples

Content type
application/json
Example
{
  • "message": "Discount must be set to dynamic",
  • "type": "not_allowed"
}

Batch Jobs

Batch Job endpoints that allow handling batch jobs in Medusa.

List Batch Jobs

Retrieve a list of Batch Jobs.

Authorizations:
API TokenCookie Session ID
query Parameters
limit
integer
Default: 10

The number of batch jobs to return.

offset
integer
Default: 0

The number of batch jobs to skip before results.

string or Array of strings

Filter by the batch ID

type
Array of strings

Filter by the batch type

object

Date comparison for when resulting collections was confirmed, i.e. less than, greater than etc.

object

Date comparison for when resulting collections was pre processed, i.e. less than, greater than etc.

object

Date comparison for when resulting collections was completed, i.e. less than, greater than etc.

object

Date comparison for when resulting collections was failed, i.e. less than, greater than etc.

object

Date comparison for when resulting collections was canceled, i.e. less than, greater than etc.

order
string

Field used to order retrieved batch jobs

expand
string

(Comma separated) Which fields should be expanded in each order of the result.

fields
string

(Comma separated) Which fields should be included in each order of the result.

object

Date comparison for when resulting collections was created, i.e. less than, greater than etc.

object

Date comparison for when resulting collections was updated, i.e. less than, greater than etc.

Responses

Response Schema: application/json
required
Array of objects (Batch Job)
count
required
integer

The total number of items available

offset
required
integer

The number of items skipped before these items

limit
required
integer

The number of items per page

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.batchJobs.list()
.then(({ batch_jobs, limit, offset, count }) => {
  console.log(batch_jobs.length);
});

Response samples

Content type
application/json
{
  • "batch_jobs": [
    ],
  • "count": 0,
  • "offset": 0,
  • "limit": 0
}

Create a Batch Job

Creates a Batch Job.

Authorizations:
API TokenCookie Session ID
Request Body schema: application/json
type
required
string
Example: "product-export"

The type of batch job to start.

context
required
object
Example: {"shape":{"prices":[{"region":null,"currency_code":"eur"}],"dynamicImageColumnCount":4,"dynamicOptionColumnCount":2},"list_config":{"skip":0,"take":50,"order":{"created_at":"DESC"},"relations":["variants","variant.prices","images"]}}

Additional infomration regarding the batch to be used for processing.

dry_run
boolean
Default: false

Set a batch job in dry_run mode to get some information on what will be done without applying any modifications.

Responses

Request samples

Content type
application/json
{
  • "type": "product-export",
  • "context": {
    },
  • "dry_run": false
}

Response samples

Content type
application/json
{
  • "batch_job": {
    }
}

Get a Batch Job

Retrieves a Batch Job.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Batch Job

Responses

Response Schema: application/json
required
object (Batch Job)

A Batch Job.

canceled_at
required
string or null <date-time>

The date of the concellation.

completed_at
required
string or null <date-time>

The date of the completion.

confirmed_at
required
string or null <date-time>

The date when the confirmation has been done.

context
required
object or null
Example: {"shape":{"prices":[{"region":null,"currency_code":"eur"}],"dynamicImageColumnCount":4,"dynamicOptionColumnCount":2},"list_config":{"skip":0,"take":50,"order":{"created_at":"DESC"},"relations":["variants","variant.prices","images"]}}

The context of the batch job, the type of the batch job determines what the context should contain.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that created the batch job.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

dry_run
required
boolean
Default: false

Specify if the job must apply the modifications or not.

failed_at
required
string or null <date-time>

The date when the job failed.

id
required
string
Example: "batch_01G8T782965PYFG0751G0Z38B4"

The unique identifier for the batch job.

pre_processed_at
required
string or null <date-time>

The date from which the job has been pre-processed.

processing_at
required
string or null <date-time>

The date the job is processing at.

required
object or null
Example: {}

The result of the batch job.

status
required
string
Default: "created"
Enum: "created" "pre_processed" "confirmed" "processing" "completed" "canceled" "failed"

The status of the batch job.

type
required
string
Enum: "product-import" "product-export"

The type of batch job.

updated_at
required
string <date-time>

The date with timezone at which the resource was last updated.

object (User)

Represents a User who can manage store settings.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.batchJobs.retrieve(batch_job_id)
.then(({ batch_job }) => {
  console.log(batch_job.id);
});

Response samples

Content type
application/json
{
  • "batch_job": {
    }
}

Cancel a Batch Job

Marks a batch job as canceled

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the batch job.

Responses

Response Schema: application/json
required
object (Batch Job)

A Batch Job.

canceled_at
required
string or null <date-time>

The date of the concellation.

completed_at
required
string or null <date-time>

The date of the completion.

confirmed_at
required
string or null <date-time>

The date when the confirmation has been done.

context
required
object or null
Example: {"shape":{"prices":[{"region":null,"currency_code":"eur"}],"dynamicImageColumnCount":4,"dynamicOptionColumnCount":2},"list_config":{"skip":0,"take":50,"order":{"created_at":"DESC"},"relations":["variants","variant.prices","images"]}}

The context of the batch job, the type of the batch job determines what the context should contain.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that created the batch job.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

dry_run
required
boolean
Default: false

Specify if the job must apply the modifications or not.

failed_at
required
string or null <date-time>

The date when the job failed.

id
required
string
Example: "batch_01G8T782965PYFG0751G0Z38B4"

The unique identifier for the batch job.

pre_processed_at
required
string or null <date-time>

The date from which the job has been pre-processed.

processing_at
required
string or null <date-time>

The date the job is processing at.

required
object or null
Example: {}

The result of the batch job.

status
required
string
Default: "created"
Enum: "created" "pre_processed" "confirmed" "processing" "completed" "canceled" "failed"

The status of the batch job.

type
required
string
Enum: "product-import" "product-export"

The type of batch job.

updated_at
required
string <date-time>

The date with timezone at which the resource was last updated.

object (User)

Represents a User who can manage store settings.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.batchJobs.cancel(batch_job_id)
.then(({ batch_job }) => {
  console.log(batch_job.id);
});

Response samples

Content type
application/json
{
  • "batch_job": {
    }
}

Confirm a Batch Job

Confirms that a previously requested batch job should be executed.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the batch job.

Responses

Response Schema: application/json
required
object (Batch Job)

A Batch Job.

canceled_at
required
string or null <date-time>

The date of the concellation.

completed_at
required
string or null <date-time>

The date of the completion.

confirmed_at
required
string or null <date-time>

The date when the confirmation has been done.

context
required
object or null
Example: {"shape":{"prices":[{"region":null,"currency_code":"eur"}],"dynamicImageColumnCount":4,"dynamicOptionColumnCount":2},"list_config":{"skip":0,"take":50,"order":{"created_at":"DESC"},"relations":["variants","variant.prices","images"]}}

The context of the batch job, the type of the batch job determines what the context should contain.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

created_by
required
string or null
Example: "usr_01G1G5V26F5TB3GPAPNJ8X1S3V"

The unique identifier of the user that created the batch job.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

dry_run
required
boolean
Default: false

Specify if the job must apply the modifications or not.

failed_at
required
string or null <date-time>

The date when the job failed.

id
required
string
Example: "batch_01G8T782965PYFG0751G0Z38B4"

The unique identifier for the batch job.

pre_processed_at
required
string or null <date-time>

The date from which the job has been pre-processed.

processing_at
required
string or null <date-time>

The date the job is processing at.

required
object or null
Example: {}

The result of the batch job.

status
required
string
Default: "created"
Enum: "created" "pre_processed" "confirmed" "processing" "completed" "canceled" "failed"

The status of the batch job.

type
required
string
Enum: "product-import" "product-export"

The type of batch job.

updated_at
required
string <date-time>

The date with timezone at which the resource was last updated.

object (User)

Represents a User who can manage store settings.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.batchJobs.confirm(batch_job_id)
.then(({ batch_job }) => {
  console.log(batch_job.id);
});

Response samples

Content type
application/json
{
  • "batch_job": {
    }
}

Collections

Collection endpoints that allow handling collections in Medusa.

List Collections

Retrieve a list of Product Collection.

Authorizations:
API TokenCookie Session ID
query Parameters
limit
integer
Default: 10

The number of collections to return.

offset
integer
Default: 0

The number of collections to skip before the results.

title
string

The title of collections to return.

handle
string

The handle of collections to return.

q
string

a search term to search titles and handles.

discount_condition_id
string

The discount condition id on which to filter the product collections.

object

Date comparison for when resulting collections were created.

object

Date comparison for when resulting collections were updated.

object

Date comparison for when resulting collections were deleted.

Responses

Response Schema: application/json
required
Array of objects (Product Collection)
count
required
integer

The total number of items available

offset
required
integer

The number of items skipped before these items

limit
required
integer

The number of items per page

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.collections.list()
.then(({ collections, limit, offset, count }) => {
  console.log(collections.length);
});

Response samples

Content type
application/json
{
  • "collections": [
    ],
  • "count": 0,
  • "offset": 0,
  • "limit": 0
}

Create a Collection

Creates a Product Collection.

Authorizations:
API TokenCookie Session ID
Request Body schema: application/json
title
required
string

The title to identify the Collection by.

handle
string

An optional handle to be used in slugs, if none is provided we will kebab-case the title.

metadata
object

An optional set of key-value pairs to hold additional information.

Responses

Response Schema: application/json
required
object (Product Collection)

Product Collections represents a group of Products that are related.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

handle
required
string or null
Example: "summer-collection"

A unique string that identifies the Product Collection - can for example be used in slug structures.

id
required
string
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The product collection's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

title
required
string
Example: "Summer Collection"

The title that the Product Collection is identified by.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

products
Array of objects

The Products contained in the Product Collection. Available if the relation products is expanded.

Request samples

Content type
application/json
{
  • "title": "string",
  • "handle": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "collection": {
    }
}

Get a Collection

Retrieves a Product Collection.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Product Collection

Responses

Response Schema: application/json
required
object (Product Collection)

Product Collections represents a group of Products that are related.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

handle
required
string or null
Example: "summer-collection"

A unique string that identifies the Product Collection - can for example be used in slug structures.

id
required
string
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The product collection's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

title
required
string
Example: "Summer Collection"

The title that the Product Collection is identified by.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

products
Array of objects

The Products contained in the Product Collection. Available if the relation products is expanded.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.collections.retrieve(collection_id)
.then(({ collection }) => {
  console.log(collection.id);
});

Response samples

Content type
application/json
{
  • "collection": {
    }
}

Update a Collection

Updates a Product Collection.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Collection.

Request Body schema: application/json
title
string

The title to identify the Collection by.

handle
string

An optional handle to be used in slugs, if none is provided we will kebab-case the title.

metadata
object

An optional set of key-value pairs to hold additional information.

Responses

Response Schema: application/json
required
object (Product Collection)

Product Collections represents a group of Products that are related.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

handle
required
string or null
Example: "summer-collection"

A unique string that identifies the Product Collection - can for example be used in slug structures.

id
required
string
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The product collection's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

title
required
string
Example: "Summer Collection"

The title that the Product Collection is identified by.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

products
Array of objects

The Products contained in the Product Collection. Available if the relation products is expanded.

Request samples

Content type
application/json
{
  • "title": "string",
  • "handle": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "collection": {
    }
}

Delete a Collection

Deletes a Product Collection.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Collection.

Responses

Response Schema: application/json
id
required
string

The ID of the deleted Collection

object
required
string
Default: "product-collection"

The type of the object that was deleted.

deleted
required
boolean
Default: true

Whether the collection was deleted successfully or not.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.collections.delete(collection_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "product-collection",
  • "deleted": true
}

Update Products

Updates products associated with a Product Collection

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Collection.

Request Body schema: application/json
product_ids
required
Array of strings

An array of Product IDs to add to the Product Collection.

Responses

Response Schema: application/json
required
object (Product Collection)

Product Collections represents a group of Products that are related.

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

handle
required
string or null
Example: "summer-collection"

A unique string that identifies the Product Collection - can for example be used in slug structures.

id
required
string
Example: "pcol_01F0YESBFAZ0DV6V831JXWH0BG"

The product collection's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

title
required
string
Example: "Summer Collection"

The title that the Product Collection is identified by.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

products
Array of objects

The Products contained in the Product Collection. Available if the relation products is expanded.

Request samples

Content type
application/json
{
  • "product_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "collection": {
    }
}

Remove Product

Removes products associated with a Product Collection

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Collection.

Request Body schema: application/json
product_ids
required
Array of strings

An array of Product IDs to remove from the Product Collection.

Responses

Response Schema: application/json
id
required
string

The ID of the collection

object
required
string
Default: "product-collection"

The type of object the removal was executed on

removed_products
required
Array of strings

The IDs of the products removed from the collection

Request samples

Content type
application/json
{
  • "product_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "product-collection",
  • "removed_products": [
    ]
}

Currencies

List Currency

Retrieves a list of Currency

query Parameters
code
string

Code of the currency to search for.

includes_tax
boolean

Search for tax inclusive currencies.

order
string

order to retrieve products in.

offset
number
Default: "0"

How many products to skip in the result.

limit
number
Default: "20"

Limit the number of products returned.

Responses

Response Schema: application/json
required
Array of objects (Currency)
count
required
integer

The total number of items available

offset
required
integer

The number of items skipped before these items

limit
required
integer

The number of items per page

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.currencies.list()
.then(({ currencies, count, offset, limit }) => {
  console.log(currencies.length);
});

Response samples

Content type
application/json
{
  • "currencies": [
    ],
  • "count": 0,
  • "offset": 0,
  • "limit": 0
}

Update a Currency

Update a Currency

path Parameters
code
required
string

The code of the Currency.

Request Body schema: application/json
includes_tax
boolean

[EXPERIMENTAL] Tax included in prices of currency.

Responses

Response Schema: application/json
required
object (Currency)

Currency

code
required
string
Example: "usd"

The 3 character ISO code for the currency.

name
required
string
Example: "US Dollar"

The written name of the currency

symbol
required
string
Example: "$"

The symbol used to indicate the currency.

symbol_native
required
string
Example: "$"

The native symbol used to indicate the currency.

includes_tax
boolean
Default: false

[EXPERIMENTAL] Does the currency prices include tax

Request samples

Content type
application/json
{
  • "includes_tax": true
}

Response samples

Content type
application/json
{
  • "currency": {
    }
}

Customer Groups

Customer Group endpoints that allow handling customer groups in Medusa.

List Customer Groups

Retrieve a list of customer groups.

Authorizations:
API TokenCookie Session ID
query Parameters
q
string

Query used for searching customer group names.

offset
integer
Default: 0

How many groups to skip in the result.

order
string

the field used to order the customer groups.

discount_condition_id
string

The discount condition id on which to filter the customer groups.

string or Array of strings or object

Filter by the customer group ID

name
Array of strings

Filter by the customer group name

object

Date comparison for when resulting customer groups were created.

object

Date comparison for when resulting customer groups were updated.

limit
integer
Default: 10

Limit the number of customer groups returned.

expand
string

(Comma separated) Which fields should be expanded in each customer groups of the result.

Responses

Response Schema: application/json
required
Array of objects (Customer Group)
count
required
integer

The total number of items available

offset
required
integer

The number of items skipped before these items

limit
required
integer

The number of items per page

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.customerGroups.list()
.then(({ customer_groups, limit, offset, count }) => {
  console.log(customer_groups.length);
});

Response samples

Content type
application/json
{
  • "customer_groups": [
    ],
  • "count": 0,
  • "offset": 0,
  • "limit": 0
}

Create a Customer Group

Creates a CustomerGroup.

Authorizations:
API TokenCookie Session ID
Request Body schema: application/json
name
required
string

Name of the customer group

metadata
object

Metadata for the customer.

Responses

Response Schema: application/json
required
object (Customer Group)

Represents a customer group

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "cgrp_01G8ZH853Y6TFXWPG5EYE81X63"

The customer group's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "VIP"

The name of the customer group

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

customers
Array of objects

The customers that belong to the customer group. Available if the relation customers is expanded.

price_lists
Array of objects

The price lists that are associated with the customer group. Available if the relation price_lists is expanded.

Request samples

Content type
application/json
{
  • "name": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "customer_group": {
    }
}

Get a Customer Group

Retrieves a Customer Group.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Customer Group.

query Parameters
expand
string

(Comma separated) Which fields should be expanded in the customer group.

fields
string

(Comma separated) Which fields should be included in the customer group.

Responses

Response Schema: application/json
required
object (Customer Group)

Represents a customer group

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "cgrp_01G8ZH853Y6TFXWPG5EYE81X63"

The customer group's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "VIP"

The name of the customer group

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

customers
Array of objects

The customers that belong to the customer group. Available if the relation customers is expanded.

price_lists
Array of objects

The price lists that are associated with the customer group. Available if the relation price_lists is expanded.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.customerGroups.retrieve(customer_group_id)
.then(({ customer_group }) => {
  console.log(customer_group.id);
});

Response samples

Content type
application/json
{
  • "customer_group": {
    }
}

Update a Customer Group

Update a CustomerGroup.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the customer group.

Request Body schema: application/json
name
string

Name of the customer group

metadata
object

Metadata for the customer.

Responses

Response Schema: application/json
required
object (Customer Group)

Represents a customer group

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "cgrp_01G8ZH853Y6TFXWPG5EYE81X63"

The customer group's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "VIP"

The name of the customer group

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

customers
Array of objects

The customers that belong to the customer group. Available if the relation customers is expanded.

price_lists
Array of objects

The price lists that are associated with the customer group. Available if the relation price_lists is expanded.

Request samples

Content type
application/json
{
  • "name": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "customer_group": {
    }
}

Delete a Customer Group

Deletes a CustomerGroup.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Customer Group

Responses

Response Schema: application/json
id
required
string

The ID of the deleted customer group.

object
required
string
Default: "customer_group"

The type of the object that was deleted.

deleted
required
boolean
Default: true

Whether the customer group was deleted successfully or not.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.customerGroups.delete(customer_group_id)
.then(({ id, object, deleted }) => {
  console.log(id);
});

Response samples

Content type
application/json
{
  • "id": "string",
  • "object": "customer_group",
  • "deleted": true
}

List Customers

Retrieves a list of customers in a customer group

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the customer group.

query Parameters
limit
integer
Default: 50

The number of items to return.

offset
integer
Default: 0

The items to skip before result.

expand
string

(Comma separated) Which fields should be expanded in each customer.

q
string

a search term to search email, first_name, and last_name.

Responses

Response Schema: application/json
required
Array of objects (Customer)
count
required
integer

The total number of items available

offset
required
integer

The number of items skipped before these items

limit
required
integer

The number of items per page

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.customerGroups.listCustomers(customer_group_id)
.then(({ customers }) => {
  console.log(customers.length);
});

Response samples

Content type
application/json
{
  • "customers": [
    ],
  • "count": 0,
  • "offset": 0,
  • "limit": 0
}

Add Customers

Adds a list of customers, represented by id's, to a customer group.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the customer group.

Request Body schema: application/json
required
Array of objects

The ids of the customers to add

Array
id
required
string

ID of the customer

Responses

Response Schema: application/json
required
object (Customer Group)

Represents a customer group

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "cgrp_01G8ZH853Y6TFXWPG5EYE81X63"

The customer group's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "VIP"

The name of the customer group

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

customers
Array of objects

The customers that belong to the customer group. Available if the relation customers is expanded.

price_lists
Array of objects

The price lists that are associated with the customer group. Available if the relation price_lists is expanded.

Request samples

Content type
application/json
{
  • "customer_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "customer_group": {
    }
}

Remove Customers

Removes a list of customers, represented by id's, from a customer group.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the customer group.

Request Body schema: application/json
required
Array of objects

The ids of the customers to remove

Array
id
required
string

ID of the customer

Responses

Response Schema: application/json
required
object (Customer Group)

Represents a customer group

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

id
required
string
Example: "cgrp_01G8ZH853Y6TFXWPG5EYE81X63"

The customer group's ID

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

name
required
string
Example: "VIP"

The name of the customer group

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

customers
Array of objects

The customers that belong to the customer group. Available if the relation customers is expanded.

price_lists
Array of objects

The price lists that are associated with the customer group. Available if the relation price_lists is expanded.

Request samples

Content type
application/json
{
  • "customer_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "customer_group": {
    }
}

Customers

Customer endpoints that allow handling customers in Medusa.

List Customers

Retrieves a list of Customers.

Authorizations:
API TokenCookie Session ID
query Parameters
limit
integer
Default: 50

The number of items to return.

offset
integer
Default: 0

The items to skip before result.

expand
string

(Comma separated) Which fields should be expanded in each customer.

q
string

a search term to search email, first_name, and last_name.

Responses

Response Schema: application/json
required
Array of objects (Customer)
count
required
integer

The total number of items available

offset
required
integer

The number of items skipped before these items

limit
required
integer

The number of items per page

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.customers.list()
.then(({ customers, limit, offset, count }) => {
  console.log(customers.length);
});

Response samples

Content type
application/json
{
  • "customers": [
    ],
  • "count": 0,
  • "offset": 0,
  • "limit": 0
}

Create a Customer

Creates a Customer.

Authorizations:
API TokenCookie Session ID
Request Body schema: application/json
email
required
string <email>

The customer's email.

first_name
required
string

The customer's first name.

last_name
required
string

The customer's last name.

password
required
string <password>

The customer's password.

phone
string

The customer's phone number.

metadata
object

An optional set of key-value pairs to hold additional information.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "password": "pa$$word",
  • "phone": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "customer": {
    }
}

Get a Customer

Retrieves a Customer.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Customer.

query Parameters
expand
string

(Comma separated) Which fields should be expanded in the customer.

fields
string

(Comma separated) Which fields should be included in the customer.

Responses

Response Schema: application/json
required
object (Customer)

Represents a customer

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The customer's billing address ID

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string <email>

The customer's email

first_name
required
string or null
Example: "Arno"

The customer's first name

has_account
required
boolean
Default: false

Whether the customer has an account or not

id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The customer's ID

last_name
required
string or null
Example: "Willms"

The customer's last name

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

phone
required
string or null
Example: 16128234334802

The customer's phone number

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

Array of objects (Address)

Available if the relation shipping_addresses is expanded.

orders
Array of objects

Available if the relation orders is expanded.

Array of objects (Customer Group)

The customer groups the customer belongs to. Available if the relation groups is expanded.

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.customers.retrieve(customer_id)
.then(({ customer }) => {
  console.log(customer.id);
});

Response samples

Content type
application/json
{
  • "customer": {
    }
}

Update a Customer

Updates a Customer.

Authorizations:
API TokenCookie Session ID
path Parameters
id
required
string

The ID of the Customer.

query Parameters
expand
string

(Comma separated) Which fields should be expanded in each customer.

fields
string

(Comma separated) Which fields should be retrieved in each customer.

Request Body schema: application/json
email
string <email>

The Customer's email.

first_name
string

The Customer's first name.

last_name
string

The Customer's last name.

phone
string

The Customer's phone number.

password
string <password>

The Customer's password.

Array of objects

A list of customer groups to which the customer belongs.

metadata
object

An optional set of key-value pairs to hold additional information.

Responses

Response Schema: application/json
required
object (Customer)

Represents a customer

billing_address_id
required
string or null
Example: "addr_01G8ZH853YPY9B94857DY91YGW"

The customer's billing address ID

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

email
required
string <email>

The customer's email

first_name
required
string or null
Example: "Arno"

The customer's first name

has_account
required
boolean
Default: false

Whether the customer has an account or not

id
required
string
Example: "cus_01G2SG30J8C85S4A5CHM2S1NS2"

The customer's ID

last_name
required
string or null
Example: "Willms"

The customer's last name

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

phone
required
string or null
Example: 16128234334802

The customer's phone number

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

object (Address)

An address.

Array of objects (Address)

Available if the relation shipping_addresses is expanded.

orders
Array of objects

Available if the relation orders is expanded.

Array of objects (Customer Group)

The customer groups the customer belongs to. Available if the relation groups is expanded.

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "phone": "string",
  • "password": "pa$$word",
  • "groups": [
    ],
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "customer": {
    }
}

Discounts

Discount endpoints that allow handling discounts in Medusa.

List Discounts

Retrieves a list of Discounts

Authorizations:
API TokenCookie Session ID
query Parameters
q
string

Search query applied on the code field.

object

Discount Rules filters to apply on the search

is_dynamic
boolean

Return only dynamic discounts.

is_disabled
boolean

Return only disabled discounts.

limit
number
Default: "20"

The number of items in the response

offset
number
Default: "0"

The offset of items in response

expand
string

Comma separated list of relations to include in the results.

Responses

Response Schema: application/json
required
Array of objects (Discount)
count
required
integer

The total number of items available

offset
required
integer

The number of items skipped before these items

limit
required
integer

The number of items per page

Request samples

import Medusa from "@medusajs/medusa-js"
const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
// must be previously logged in or use api token
medusa.admin.discounts.list()
.then(({ discounts, limit, offset, count }) => {
  console.log(discounts.id);
});

Response samples

Content type
application/json
{
  • "discounts": [
    ],
  • "count": 0,
  • "offset": 0,
  • "limit": 0
}

Creates a Discount

Creates a Discount with a given set of rules that define how the Discount behaves.

Authorizations:
API TokenCookie Session ID
query Parameters
expand
string

(Comma separated) Which fields should be expanded in the results.

fields
string

(Comma separated) Which fields should be retrieved in the results.

Request Body schema: application/json
code
required
string

A unique code that will be used to redeem the Discount

required
object

The Discount Rule that defines how Discounts are calculated

regions
required
Array of strings

A list of Region ids representing the Regions in which the Discount can be used.

is_dynamic
boolean
Default: false

Whether the Discount should have multiple instances of itself, each with a different code. This can be useful for automatically generated codes that all have to follow a common set of rules.

is_disabled
boolean
Default: false

Whether the Discount code is disabled on creation. You will have to enable it later to make it available to Customers.

starts_at
string <date-time>

The time at which the Discount should be available.

ends_at
string <date-time>

The time at which the Discount should no longer be available.

valid_duration
string
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

usage_limit
number

Maximum times the discount can be used

metadata
object

An optional set of key-value pairs to hold additional information.

Responses

Response Schema: application/json
required
object (Discount)

Represents a discount that can be applied to a cart for promotional purposes.

code
required
string
Example: "10DISC"

A unique code for the discount - this will be used by the customer to apply the discount

created_at
required
string <date-time>

The date with timezone at which the resource was created.

deleted_at
required
string or null <date-time>

The date with timezone at which the resource was deleted.

ends_at
required
string or null <date-time>

The time at which the discount can no longer be used.

id
required
string
Example: "disc_01F0YESMW10MGHWJKZSDDMN0VN"

The discount's ID

is_disabled
required
boolean
Example: false

Whether the Discount has been disabled. Disabled discounts cannot be applied to carts

is_dynamic
required
boolean
Example: false

A flag to indicate if multiple instances of the discount can be generated. I.e. for newsletter discounts

metadata
required
object or null
Example: {"car":"white"}

An optional key-value map with additional details

parent_discount_id
required
string or null
Example: "disc_01G8ZH853YPY9B94857DY91YGW"

The Discount that the discount was created from. This will always be a dynamic discount

rule_id
required
string or null
Example: "dru_01F0YESMVK96HVX7N419E3CJ7C"

The Discount Rule that governs the behaviour of the Discount

starts_at
required
string <date-time>

The time at which the discount can be used.

updated_at
required
string <date-time>

The date with timezone at which the resource was updated.

usage_count
required
integer
Default: 0
Example: 50

The number of times a discount has been used.

usage_limit
required
integer or null
Example: 100

The maximum number of times that a discount can be used.

valid_duration
required
string or null
Example: "P3Y6M4DT12H30M5S"

Duration the discount runs between

object (Discount Rule)

Holds the rules that governs how a Discount is calculated when applied to a Cart.

parent_discount
object or null

Available if the relation parent_discount is expanded.

Array of objects (Region)

The Regions in which the Discount can be used. Available if the relation regions is expanded.

Request samples

Content type
application/json
{
  • "code": "string",
  • "is_dynamic": false,
  • "rule": {
    },
  • "is_disabled": false,
  • "starts_at": "2019-08-24T14:15:22Z",
  • "ends_at": "2019-08-24T14:15:22Z",
  • "valid_duration": "P3Y6M4DT12H30M5S",
  • "regions": [
    ],
  • "usage_limit": 0,
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "discount": {