Medusa

Create a Discount

POST

/admin/discounts

Discounts

Create a Discount with a given set of rules that defines how the Discount is applied.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://api.medusa-commerce.com/admin/discounts' \
--header 'Content-Type: application/json' \
--data-raw ''

Response Example

200 - Example 1

{
  "discount": {
    "id": "disc_01F0YESMW10MGHWJKZSDDMN0VN",
    "code": "10DISC",
    "is_dynamic": false,
    "rule_id": "dru_01F0YESMVK96HVX7N419E3CJ7C",
    "is_disabled": false,
    "parent_discount_id": "disc_01G8ZH853YPY9B94857DY91YGW",
    "parent_discount": {},
    "starts_at": "2019-08-24T14:15:22Z",
    "ends_at": "2019-08-24T14:15:22Z",
    "valid_duration": "P3Y6M4DT12H30M5S",
    "usage_limit": 100,
    "usage_count": 0,
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "deleted_at": "2019-08-24T14:15:22Z",
    "metadata": {
      "car": "white"
    },
    "rule": {
      "id": "dru_01F0YESMVK96HVX7N419E3CJ7C",
      "description": "10 Percent",
      "value": 10,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "deleted_at": "2019-08-24T14:15:22Z",
      "type": "fixed",
      "allocation": "total",
      "conditions": [
        {}
      ],
      "metadata": {
        "car": "white"
      }
    },
    "regions": [
      {
        "id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
        "name": "EU",
        "tax_rate": 0,
        "tax_code": null,
        "gift_cards_taxable": true,
        "automatic_taxes": true,
        "tax_provider_id": null,
        "includes_tax": false,
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "deleted_at": "2019-08-24T14:15:22Z",
        "currency_code": "usd",
        "metadata": {
          "car": "white"
        },
        "currency": {
          "symbol": "$",
          "symbol_native": "$",
          "name": "US Dollar",
          "includes_tax": false,
          "code": "usd"
        },
        "countries": [
          {
            "id": 109,
            "name": "ITALY",
            "display_name": "Italy",
            "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
            "region": {},
            "iso_2": "it",
            "iso_3": "ita",
            "num_code": 380
          }
        ],
        "tax_provider": {
          "id": "manual",
          "is_installed": true
        },
        "payment_providers": [
          {
            "id": "manual",
            "is_installed": true
          }
        ],
        "fulfillment_providers": [
          {
            "id": "manual",
            "is_installed": true
          }
        ],
        "tax_rates": [
          {
            "id": "txr_01G8XDBAWKBHHJRKH0AV02KXBR",
            "rate": 10,
            "code": "tax01",
            "name": "Tax Example",
            "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
            "region": {},
            "product_count": 10,
            "product_type_count": 2,
            "shipping_option_count": 1,
            "created_at": "2019-08-24T14:15:22Z",
            "updated_at": "2019-08-24T14:15:22Z",
            "metadata": {
              "car": "white"
            },
            "product_types": [
              {
                "id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
                "value": "Clothing",
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "deleted_at": "2019-08-24T14:15:22Z",
                "metadata": {
                  "car": "white"
                }
              }
            ],
            "shipping_options": [
              {
                "id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
                "name": "PostFake Standard",
                "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
                "region": {},
                "profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
                "provider_id": "manual",
                "amount": 200,
                "is_return": false,
                "admin_only": false,
                "includes_tax": false,
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "deleted_at": "2019-08-24T14:15:22Z",
                "price_type": "flat_rate",
                "data": {},
                "metadata": {
                  "car": "white"
                },
                "provider": {
                  "id": "manual",
                  "is_installed": true
                },
                "requirements": [
                  {
                    "id": "sor_01G1G5V29AB4CTNDRFSRWSRKWD",
                    "shipping_option_id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
                    "shipping_option": {},
                    "amount": 100,
                    "deleted_at": "2019-08-24T14:15:22Z",
                    "type": "min_subtotal"
                  }
                ],
                "profile": {
                  "id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
                  "name": "Default Shipping Profile",
                  "created_at": "2019-08-24T14:15:22Z",
                  "updated_at": "2019-08-24T14:15:22Z",
                  "deleted_at": "2019-08-24T14:15:22Z",
                  "type": "default",
                  "products": [
                    {}
                  ],
                  "shipping_options": [
                    {}
                  ],
                  "metadata": {
                    "car": "white"
                  }
                }
              }
            ],
            "products": [
              {
                "id": "prod_01G1G5V2MBA328390B5AXJ610F",
                "title": "Medusa Coffee Mug",
                "subtitle": "string",
                "description": "Every programmer's best friend.",
                "handle": "coffee-mug",
                "is_giftcard": false,
                "thumbnail": "http://example.com",
                "profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
                "weight": null,
                "length": null,
                "height": null,
                "width": null,
                "hs_code": null,
                "origin_country": null,
                "mid_code": null,
                "material": null,
                "collection_id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
                "type_id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
                "discountable": true,
                "external_id": null,
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "deleted_at": "2019-08-24T14:15:22Z",
                "status": "draft",
                "metadata": {
                  "car": "white"
                },
                "images": [
                  {
                    "id": "img_01G749BFYR6T8JTVW6SGW3K3E6",
                    "url": "http://example.com",
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "deleted_at": "2019-08-24T14:15:22Z",
                    "metadata": {
                      "car": "white"
                    }
                  }
                ],
                "categories": [
                  {
                    "id": "pcat_01G2SG30J8C85S4A5CHM2S1NS2",
                    "name": "Regular Fit",
                    "handle": "regular-fit",
                    "mpath": "pcat_id1.pcat_id2.pcat_id3",
                    "is_internal": false,
                    "is_active": false,
                    "rank": 0,
                    "parent_category_id": null,
                    "parent_category": {},
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "category_children": [
                      {}
                    ],
                    "products": [
                      {}
                    ]
                  }
                ],
                "collection": {
                  "id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
                  "title": "Summer Collection",
                  "handle": "summer-collection",
                  "created_at": "2019-08-24T14:15:22Z",
                  "updated_at": "2019-08-24T14:15:22Z",
                  "deleted_at": "2019-08-24T14:15:22Z",
                  "products": [
                    {}
                  ],
                  "metadata": {
                    "car": "white"
                  }
                },
                "tags": [
                  {
                    "id": "ptag_01G8K2MTMG9168F2B70S1TAVK3",
                    "value": "Pants",
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "deleted_at": "2019-08-24T14:15:22Z",
                    "metadata": {
                      "car": "white"
                    }
                  }
                ],
                "profile": {
                  "id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
                  "name": "Default Shipping Profile",
                  "created_at": "2019-08-24T14:15:22Z",
                  "updated_at": "2019-08-24T14:15:22Z",
                  "deleted_at": "2019-08-24T14:15:22Z",
                  "type": "default",
                  "products": [
                    {}
                  ],
                  "shipping_options": [
                    {}
                  ],
                  "metadata": {
                    "car": "white"
                  }
                },
                "profiles": [
                  {
                    "id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
                    "name": "Default Shipping Profile",
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "deleted_at": "2019-08-24T14:15:22Z",
                    "type": "default",
                    "products": [
                      {}
                    ],
                    "shipping_options": [
                      {}
                    ],
                    "metadata": {
                      "car": "white"
                    }
                  }
                ],
                "type": {
                  "id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
                  "value": "Clothing",
                  "created_at": "2019-08-24T14:15:22Z",
                  "updated_at": "2019-08-24T14:15:22Z",
                  "deleted_at": "2019-08-24T14:15:22Z",
                  "metadata": {
                    "car": "white"
                  }
                },
                "sales_channels": [
                  {
                    "id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
                    "name": "Market",
                    "description": "Multi-vendor market",
                    "is_disabled": false,
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "deleted_at": "2019-08-24T14:15:22Z",
                    "metadata": {
                      "car": "white"
                    },
                    "locations": [
                      {
                        "id": "scloc_01G8X9A7ESKAJXG2H0E6F1MW7A",
                        "sales_channel_id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
                        "location_id": "string",
                        "sales_channel": {},
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z",
                        "deleted_at": "2019-08-24T14:15:22Z"
                      }
                    ]
                  }
                ],
                "options": [
                  {
                    "id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
                    "title": "Size",
                    "product_id": "prod_01G1G5V2MBA328390B5AXJ610F",
                    "product": {},
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "deleted_at": "2019-08-24T14:15:22Z",
                    "metadata": {
                      "car": "white"
                    },
                    "values": [
                      {
                        "id": "optval_01F0YESHR7S6ECD03RF6W12DSJ",
                        "value": "large",
                        "option_id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
                        "option": {},
                        "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
                        "variant": {},
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z",
                        "deleted_at": "2019-08-24T14:15:22Z",
                        "metadata": {
                          "car": "white"
                        }
                      }
                    ]
                  }
                ],
                "variants": [
                  {
                    "id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
                    "title": "Small",
                    "product_id": "prod_01G1G5V2MBA328390B5AXJ610F",
                    "product": {},
                    "sku": "shirt-123",
                    "barcode": null,
                    "ean": null,
                    "upc": null,
                    "variant_rank": 0,
                    "inventory_quantity": 100,
                    "allow_backorder": false,
                    "manage_inventory": true,
                    "hs_code": null,
                    "origin_country": null,
                    "mid_code": null,
                    "material": null,
                    "weight": null,
                    "length": null,
                    "height": null,
                    "width": null,
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "deleted_at": "2019-08-24T14:15:22Z",
                    "purchasable": true,
                    "metadata": {
                      "car": "white"
                    },
                    "options": [
                      {
                        "id": "optval_01F0YESHR7S6ECD03RF6W12DSJ",
                        "value": "large",
                        "option_id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
                        "option": {},
                        "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
                        "variant": {},
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z",
                        "deleted_at": "2019-08-24T14:15:22Z",
                        "metadata": {
                          "car": "white"
                        }
                      }
                    ],
                    "inventory_items": [
                      {
                        "id": "pvitem_01G8X9A7ESKAJXG2H0E6F1MW7A",
                        "inventory_item_id": "string",
                        "variant_id": "string",
                        "variant": {},
                        "required_quantity": 1,
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z",
                        "deleted_at": "2019-08-24T14:15:22Z"
                      }
                    ],
                    "prices": [
                      {
                        "id": "ma_01F0YESHRFQNH5S8Q0PK84YYZN",
                        "amount": 100,
                        "min_quantity": 1,
                        "max_quantity": 1,
                        "price_list_id": "pl_01G8X3CKJXCG5VXVZ87H9KC09W",
                        "price_list": {},
                        "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
                        "variant": {},
                        "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
                        "region": {},
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z",
                        "deleted_at": "2019-08-24T14:15:22Z",
                        "currency_code": "usd",
                        "currency": {
                          "symbol": "$",
                          "symbol_native": "$",
                          "name": "US Dollar",
                          "includes_tax": false,
                          "code": "usd"
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Request

Query Params

expand

string

optional

Comma-separated relations that should be expanded in the returned discount.

fields

string

optional

Comma-separated fields that should be retrieved in the returned discount.

Body Params application/json

code

string

required

A unique code that will be used to redeem the discount

is_dynamic

boolean

optional

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

Default:

false

is_disabled

boolean

optional

Whether the discount code is disabled on creation. If set to true, it will not be available for customers.

Default:

false

starts_at

string <date-time>

optional

The date and time at which the discount should be available.

ends_at

string <date-time>

optional

The date and time at which the discount should no longer be available.

valid_duration

string

optional

The duration the discount runs between

Example:

P3Y6M4DT12H30M5S

usage_limit

number

optional

Maximum number of times the discount can be used

regions

array[string]

required

A list of region IDs representing the Regions in which the Discount can be used.

metadata

object

optional

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

rule

object

required

The discount rule that defines how discounts are calculated

description

string

optional

A short description of the discount

value

number

required

The value that the discount represents. This will depend on the type of the discount.

type

enum<string>

required

The type of the discount, can be fixed for discounts that reduce the price by a fixed amount, percentage for percentage reductions or free_shipping for shipping vouchers.

Allowed values:

fixedpercentagefree_shipping

allocation

enum<string>

required

The scope that the discount should apply to. total indicates that the discount should be applied on the cart total, and item indicates that the discount should be applied to each discountable item in the cart.

Allowed values:

totalitem

conditions

array [object {6}]

optional

A set of conditions that can be used to limit when the discount can be used. Only one of products, product_types, product_collections, product_tags, and customer_groups should be provided based on the discount condition's type.

Examples

Responses

🟢200OK

application/json

Body

discount

object (Discount)

required

A discount can be applied to a cart for promotional purposes.

string

required

The discount's ID

Example:

disc_01F0YESMW10MGHWJKZSDDMN0VN

code

string

required

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

Example:

10DISC

is_dynamic

boolean

required

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

Example:

false

rule_id

string | null

required

The ID of the discount rule that defines how the discount will be applied to a cart.

Example:

dru_01F0YESMVK96HVX7N419E3CJ7C

is_disabled

boolean

required

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

Example:

false

parent_discount_id

string | null

required

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

Example:

disc_01G8ZH853YPY9B94857DY91YGW

parent_discount

object | null

optional

The details of the parent discount that this discount was created from.

starts_at

string <date-time>

required

The time at which the discount can be used.

ends_at

string <date-time> | null

required

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

valid_duration

string | null

required

Duration the discount runs between

Example:

P3Y6M4DT12H30M5S

usage_limit

integer | null

required

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

Example:

100

usage_count

integer

required

The number of times a discount has been used.

Default:

Example:

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.

deleted_at

string <date-time> | null

required

The date with timezone at which the resource was deleted.

metadata

object | null

required

An optional key-value map with additional details

Example:

{"car":"white"}

rule

object (Discount Rule)

optional

A discount rule defines how a Discount is calculated when applied to a Cart.

regions

array[object (Region) {19}]

optional

The details of the regions in which the Discount can be used.

🟠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

Create a Condition

List Discounts