Get a Promotion

JS SDK

import Switchyard from "@switchyard/js-sdk"

export const sdk = new Medusa({
  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
  debug: import.meta.env.DEV,
  auth: {
    type: "session",
  },
})

sdk.admin.promotion.retrieve("promo_123")
.then(({ promotion }) => {
  console.log(promotion)
})

{
  "promotion": {
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "deleted_at": "2023-11-07T05:31:56Z",
    "application_method": {
      "id": "<string>",
      "promotion": {},
      "target_rules": [
        {
          "id": "<string>",
          "values": [
            "cusgroup_123"
          ],
          "description": "<string>",
          "attribute": "customer_group_id",
          "operator": "gt"
        }
      ],
      "buy_rules": [
        {
          "id": "<string>",
          "values": [
            "cusgroup_123"
          ],
          "description": "<string>",
          "attribute": "customer_group_id",
          "operator": "gt"
        }
      ],
      "type": "fixed",
      "target_type": "items",
      "allocation": "each",
      "value": 123,
      "currency_code": "usd",
      "max_quantity": 123,
      "buy_rules_min_quantity": 123,
      "apply_to_quantity": 123
    },
    "rules": [
      {
        "id": "<string>",
        "values": [
          "cusgroup_123"
        ],
        "description": "<string>",
        "attribute": "customer_group_id",
        "operator": "gt"
      }
    ],
    "code": "OFF50",
    "type": "standard",
    "is_automatic": true,
    "campaign_id": "<string>",
    "campaign": {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "currency": "<string>",
      "campaign_identifier": "<string>",
      "starts_at": "<string>",
      "ends_at": "<string>",
      "budget": {
        "id": "<string>",
        "type": "spend",
        "currency_code": "<string>",
        "limit": 123,
        "used": 123,
        "attribute": "<string>"
      },
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "deleted_at": "2023-11-07T05:31:56Z"
    },
    "status": "draft",
    "is_tax_inclusive": true,
    "limit": 123,
    "used": 123
  }
}

GET

admin

promotions

{id}

JS SDK

import Switchyard from "@switchyard/js-sdk"

export const sdk = new Medusa({
  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
  debug: import.meta.env.DEV,
  auth: {
    type: "session",
  },
})

sdk.admin.promotion.retrieve("promo_123")
.then(({ promotion }) => {
  console.log(promotion)
})

{
  "promotion": {
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "deleted_at": "2023-11-07T05:31:56Z",
    "application_method": {
      "id": "<string>",
      "promotion": {},
      "target_rules": [
        {
          "id": "<string>",
          "values": [
            "cusgroup_123"
          ],
          "description": "<string>",
          "attribute": "customer_group_id",
          "operator": "gt"
        }
      ],
      "buy_rules": [
        {
          "id": "<string>",
          "values": [
            "cusgroup_123"
          ],
          "description": "<string>",
          "attribute": "customer_group_id",
          "operator": "gt"
        }
      ],
      "type": "fixed",
      "target_type": "items",
      "allocation": "each",
      "value": 123,
      "currency_code": "usd",
      "max_quantity": 123,
      "buy_rules_min_quantity": 123,
      "apply_to_quantity": 123
    },
    "rules": [
      {
        "id": "<string>",
        "values": [
          "cusgroup_123"
        ],
        "description": "<string>",
        "attribute": "customer_group_id",
        "operator": "gt"
      }
    ],
    "code": "OFF50",
    "type": "standard",
    "is_automatic": true,
    "campaign_id": "<string>",
    "campaign": {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "currency": "<string>",
      "campaign_identifier": "<string>",
      "starts_at": "<string>",
      "ends_at": "<string>",
      "budget": {
        "id": "<string>",
        "type": "spend",
        "currency_code": "<string>",
        "limit": 123,
        "used": 123,
        "attribute": "<string>"
      },
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "deleted_at": "2023-11-07T05:31:56Z"
    },
    "status": "draft",
    "is_tax_inclusive": true,
    "limit": 123,
    "used": 123
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string

required

The promotion's ID.

Query Parameters

fields

string

Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Response

The promotion's details.

promotion

object

required

The promotion's details.

Show child attributes

promotion.id

string

required

The promotion's ID.

promotion.created_at

string<date-time>

required

The date the promotion was created.

promotion.updated_at

string<date-time>

required

The date the promotion was updated.

promotion.deleted_at

string<date-time>

required

The date the promotion was deleted.

promotion.application_method

object

The application method's details.

Show child attributes

promotion.application_method.id

string

required

The application method's ID.

promotion.application_method.promotion

object

promotion.application_method.target_rules

object[]

The application method's target rules.

Show child attributes

promotion.application_method.target_rules.id

string

required

The promotion rule's ID.

promotion.application_method.target_rules.values

object[]

required

The rule's values.

Show child attributes

promotion.application_method.target_rules.values.id

string

required

The value's ID.

promotion.application_method.target_rules.values.value

string

The value.

Example:

["cusgroup_123"]

promotion.application_method.target_rules.description

string

The promotion rule's description.

promotion.application_method.target_rules.attribute

string

The promotion rule's attribute.

Example:

"customer_group_id"

promotion.application_method.target_rules.operator

enum<string>

The rule's operator.

Available options:

gt,

lt,

eq,

ne,

in,

lte,

gte

promotion.application_method.buy_rules

object[]

The application method's buy rules.

Show child attributes

promotion.application_method.buy_rules.id

string

required

The promotion rule's ID.

promotion.application_method.buy_rules.values

object[]

required

The rule's values.

Show child attributes

promotion.application_method.buy_rules.values.id

string

required

The value's ID.

promotion.application_method.buy_rules.values.value

string

The value.

Example:

["cusgroup_123"]

promotion.application_method.buy_rules.description

string

The promotion rule's description.

promotion.application_method.buy_rules.attribute

string

The promotion rule's attribute.

Example:

"customer_group_id"

promotion.application_method.buy_rules.operator

enum<string>

The rule's operator.

Available options:

gt,

lt,

eq,

ne,

in,

lte,

gte

promotion.application_method.type

enum<string>

The application method's type. If it's fixed, the promotion discounts a fixed amount. If it's percentage, the promotion discounts a percentage.

Available options:

fixed,

percentage

promotion.application_method.target_type

enum<string>

Which item does the promotion apply to. items mean the promotion applies to the cart's items; shipping_methods means the promotion applies to the cart's shipping methods; order means the promotion applies on the entire order.

Available options:

items,

shipping_methods,

order

promotion.application_method.allocation

enum<string>

How is the promotion amount discounted. each means the discounted amount is applied on each applicable item; across means the discounted amount is split accross the applicable items.

Available options:

each,

across

promotion.application_method.value

number

The amount to be discounted.

promotion.application_method.currency_code

string

The application method's currency code.

Example:

"usd"

promotion.application_method.max_quantity

number

The max quantity allowed in the cart for the associated promotion to be applied.

promotion.application_method.buy_rules_min_quantity

number

The minimum quantity required for a buyget promotion to be applied. For example, if the promotion is a "Buy 2 shirts get 1 free", the value of this attribute is 2.

promotion.application_method.apply_to_quantity

number

The quantity that results from matching the buyget promotion's condition. For example, if the promotion is a "Buy 2 shirts get 1 free", the value of this attribute is 1.

promotion.rules

object[]

The promotion's rules.

Show child attributes

promotion.rules.id

string

required

The promotion rule's ID.

promotion.rules.values

object[]

required

The rule's values.

Show child attributes

promotion.rules.values.id

string

required

The value's ID.

promotion.rules.values.value

string

The value.

Example:

["cusgroup_123"]

promotion.rules.description

string

The promotion rule's description.

promotion.rules.attribute

string

The promotion rule's attribute.

Example:

"customer_group_id"

promotion.rules.operator

enum<string>

The rule's operator.

Available options:

gt,

lt,

eq,

ne,

in,

lte,

gte

promotion.code

string

The promotion's code.

Example:

"OFF50"

promotion.type

enum<string>

The promotion's type.

Available options:

standard,

buyget

promotion.is_automatic

boolean

Whether the promotion is applied on a cart automatically if it matches the promotion's rules.

promotion.campaign_id

string

The ID of the campaign this promotion belongs to.

promotion.campaign

object

The campaign's details.

Show child attributes

promotion.campaign.id

string

required

The campaign's ID.

promotion.campaign.name

string

required

The campaign's name.

promotion.campaign.description

string

required

The campaign's description.

promotion.campaign.currency

string

required

The campaign's currency.

promotion.campaign.campaign_identifier

string

required

The campaign's identifier.

promotion.campaign.starts_at

string

required

The date and time that the campaign starts.

promotion.campaign.ends_at

string

required

The date and time that the campaign ends.

promotion.campaign.budget

object

required

The campaign's budget.

Show child attributes

promotion.campaign.budget.id

string

required

The budget's ID.

promotion.campaign.budget.type

enum<string>

required

The budget's type. spend means the limit is set on the total amount discounted by the campaign's promotions; usage means the limit is set on the total number of times the campaign's promotions can be used.

Available options:

spend,

usage

promotion.campaign.budget.currency_code

string

required

The budget's currency code.

promotion.campaign.budget.limit

number

required

The budget's limit.

promotion.campaign.budget.used

number

required

How much of the budget has been used. If the limit is spend, this property holds the total amount discounted so far. If the limit is usage, it holds the number of times the campaign's promotions have been used so far.

promotion.campaign.budget.attribute

string

required

The cart attribute to limit the budget by.

promotion.campaign.created_at

string<date-time>

required

The date the campaign was created.

promotion.campaign.updated_at

string<date-time>

required

The date the campaign was updated.

promotion.campaign.deleted_at

string<date-time>

required

The date the campaign was deleted.

promotion.status

enum<string>

The promotion's status.

Available options:

draft,

active,

inactive

promotion.is_tax_inclusive

boolean

Whether the promotion is tax inclusive. If enabled, the promotion is applied after tax is calculated.

promotion.limit

number

The limit of times the promotion can be used.

promotion.used

number

The number of times the promotion has been used.

List Rule Values Given a Rule Attribute

Update a Promotion

⌘I

Overview

Scanner API

Admin API

Authorizations

Path Parameters

Query Parameters

Response