promotions-usages

• promotions-usages.find
• promotions-usages.add
• promotions-usages.count
• promotions-usages.delete

promotions-usages.find

Lists the usages of the given one time per customer promotion.

Request

Admin SDK
Admin.api('commerce.promotions-usages.find', request, function(response) { … });

HTTP POST
/api/v13/commerce.promotions-usages.find

{
  "conditions" : { // returns the promotions …
    "promotion" : 43, // for the promotion with this identifier (required) -- int(1…)
    "after" : "holmes@inv-london.com" // … with identifier after this value - string(3…120)
  },
  "fields" : [ "email", "order" … ], // fields to return - string
  "order" : [ "email" ], // sort order of returned promotion usages, can contain "email", "-email", "usedAt", "-usedAt" - string(3…120)
  "limit" : 10, // maximum number of promotion usages to return - int(1…)
  "first" : 0 // index of the first promotion usage to return - int(0…)
}

Response

{
  "status" : "ok",
  "usages" : [ {
    "email" : "holmes@inv-london.com", // email address that used the promotion - string(3…120)
    "usedAt" : "2025-09-12 12:35:27", // date and time on which the promotion has been used - datetime
    "order" : 1771949227 // order (ID) for which the promotion has been used - int(1…)
  }, … ]
}

Errors

promotions-usages.count

Number of usages for the given promotion.

Request

Admin SDK
Admin.api('commerce.promotions-usages.count', request, function(response) { … });

HTTP POST
/api/v13/commerce.promotions-usages.count

{
  "promotion" : 43
}

Response

{
  "status" : "ok",
  "count" : 7 // number of promotion usages - int(0…)
}

Errors

promotions-usages.add

Add usage to the given one time per customer promotion.

Request

Admin SDK
Admin.api('commerce.promotions-usage.add', request, function(response) { … });

HTTP POST
/api/v13/commerce.promotions-usages.add

{
  "promotion" : 43, // identifier of the promotion - int(1…)
  "email" : "holmes@inv-london.com", // email address that used the promotion - string(3…120)
  "order" : 1771949227 // identifier of the order for which the promotion has been used - int(1…)
}

Response

{
  "status" : "ok"
}

Errors

promotions-usage.delete

Deletes one or more promotion usages.

Request

Admin SDK
Admin.api('commerce.promotions-usages.delete', request, function(response) { … });

HTTP POST
/api/v13/commerce.promotions-usages.delete

{
  "promotion" : 43, // identifier of the promotion (required) - int(1…)
  "emails" : [ "holmes@inv-london.com", … ] // Email addresses of the usages to remove (required) - string(3…120)+
}

Response

{
  "status" : "ok"
}