Menu

Promotions API Routes

A promotion discounts an amount or percentage off a cart's items, shipping methods, or the entire order.

Promotions have different types, such as a standard promotion that just discounts an amount, or a buyget promotion to enforce a "buy X get Y" promotion.

A promotion has rules to restrict how and when they're applied.

Promotions belong to a campaign, which sets conditions on the promotion such as when it starts and ends.

These API routes allow admin users to manage promotions.

GET /admin/promotions#

List Promotions

Retrieve a list of promotions. The promotions can be filtered by fields such as id. The promotions can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
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.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
qstringOptional
Search term to filter the promotion's searchable attributes.
codestring | string[]Optional
Filter by a promotion code.
campaign_idstring | string[]Optional
Filter by a campaign's ID to retrieve its associated promotions.
application_methodobjectOptional
Apply filters on the application methods to retrieve the promotions of the matching application methods.
created_atobjectOptional
Filter by a promotion's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a promotion's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a promotion's deletion date. Accepts the filter operators.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
with_deletedbooleanOptional
Whether to include deleted records in the result.
idstring | string[] | objectOptional
Filter by a promotion's ID. Accepts the filter operators.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
promotionsobject[]
The list of promotions.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/promotions#

Create Promotion

Create a promotion.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
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.

Request body (application/json)

codestring
The promotion's code.
is_automaticbooleanOptional
Whether the promotion is applied automatically.
type"standard" | "buyget"
The promotion's type.
campaign_idstring
The ID of the campaign that the promotion belongs to.
campaignobjectOptional
The details of a campaign to create and add the promotion to it.
application_methodobject
The promotion's application method.
rulesobject[]Optional
The promotion's rules.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

promotionobject
The promotion's details.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/promotions/rule-attribute-options/{rule_type}#

List Rule Attribute Options of a Rule Type

Retrieve a list of potential rule attributes for the promotion and application method types specified in the query parameters. Only the attributes of the rule type specified in the path parameter are retrieved:

  • If rule_type is rules, the attributes of the promotion's type are retrieved.

  • If rule_type is target-rules, the target rules' attributes of the application method's type are retrieved.

  • If rule_type is buy-rules, the buy rules' attributes of the application method's type are retrieved.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

rule_type"rules" | "target-rules" | "buy-rules"
The rule type.

Query parameters

promotion_type"standard" | "buyget"Optional
The promotion type to retrieve rules for.
application_method_type"fixed" | "percentage"Optional
The application method type to retrieve rules for.
application_method_target_type"items" | "shipping_methods" | "order"Optional
The application method target type to retrieve rules for.

Request examples

Responses

200 OK

attributesobject[]
The list of attributes.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/promotions/rule-value-options/{rule_type}/{rule_attribute_id}#

List Rule Values Given a Rule Attribute

Retrieve all potential values for promotion rules and target and buy rules based on the specified rule attribute and type. For example, if you provide the ID of the currency_code rule attribute, and set rule_type to rules, a list of currencies are retrieved in label-value pairs.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

rule_type"rules" | "target-rules" | "buy-rules"
The rule type.
rule_attribute_idstring
The rule attribute's ID.

Query parameters

offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
with_deletedbooleanOptional
Whether to include deleted records in the result.
application_method_target_typestringOptional
The application method target type to retrieve rules for.
qstringOptional
Apply a search query on the rule values' searchable properties.
valuestring | string[]Optional
Filter by a specific rule value.
fieldsstringOptional
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.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
valuesobject[]
The list of rule values.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/promotions/{id}#

Get a Promotion

Retrieve a promotion by its ID. You can expand the promotion's relations or select the fields that should be returned.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The promotion's ID.

Query parameters

fieldsstringOptional
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.

Request examples

Responses

200 OK

promotionobject
The promotion's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/promotions/{id}#

Update a Promotion

Update a promotion's details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The promotion's ID.

Query parameters

fieldsstringOptional
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.

Request body (application/json)

codestringOptional
The promotion's code.
is_automaticbooleanOptional
Whether the promotion is applied automatically.
type"standard" | "buyget"Optional
The promotion's type.
campaign_idstring
The ID of the campaign that the promotion belongs to.
application_methodobjectOptional
The properties to update in the application method.
additional_dataobjectOptional
Pass additional custom data to the API route. This data is passed to the underlying workflow under the additional_data parameter.

Request examples

Responses

200 OK

promotionobject
The promotion's details.

400, 401, 404, 409, 422, 500: an error response is returned.

DELETE /admin/promotions/{id}#

Delete a Promotion

Delete a promotion.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The promotion's ID.

Request examples

Responses

200 OK

idstring
The promotion's ID.
objectstring
The name of the deleted object.

Default: "promotion"

deletedboolean
Whether the promotion was deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/promotions/{id}/buy-rules/batch#

Manage the Buy Rules of a Promotion

Manage the buy rules of a buyget promotion to create, update, or delete them.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The promotion's ID.

Query parameters

promotion_type"standard" | "buyget"Optional
The promotion's type.
application_method_type"fixed" | "percentage"Optional
The promotion's application method type.
application_method_target_type"items" | "shipping_methods" | "order"Optional
The promotion's application method target type.

Request body (application/json)

createobject[]Optional
The buy rules to create.
updateobject[]Optional
The buy rules to update.
deletestring[]Optional
The buy rules to delete.

Request examples

Responses

200 OK

createdobject[]
The created buy rules.
updatedobject[]
The updated buy rules.
deletedobject
The details of the deleted buy rules.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/promotions/{id}/rules/batch#

Manage a Promotion's Rules

Manage the rules of a promotion to create, update, or delete them.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The promotion's ID.

Query parameters

promotion_type"standard" | "buyget"Optional
The promotion's type.
application_method_type"fixed" | "percentage"Optional
The promotion's application method type.
application_method_target_type"items" | "shipping_methods" | "order"Optional
The promotion's application method target type.

Request body (application/json)

createobject[]Optional
The rules to create.
updateobject[]Optional
The rules to update.
deletestring[]Optional
The rules to delete.

Request examples

Responses

200 OK

createdobject[]
The created rules.
updatedobject[]
The updated rules.
deletedobject
The details of the deleted buy rules.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/promotions/{id}/target-rules/batch#

Manage Target Rules of a Promotion

Manage the target rules of a promotion to create, update, or delete them.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The promotion's ID.

Query parameters

promotion_type"standard" | "buyget"Optional
The promotion's type.
application_method_type"fixed" | "percentage"Optional
The promotion's application method type.
application_method_target_type"items" | "shipping_methods" | "order"Optional
The promotion's application method target type.

Request body (application/json)

createobject[]Optional
The target rules to create.
updateobject[]Optional
The target rules to update.
deletestring[]Optional
The target rules to delete.

Request examples

Responses

200 OK

createdobject[]
The created target rules.
updatedobject[]
The updated target rules.
deletedobject
The details of the deleted target rules.

400, 401, 404, 409, 422, 500: an error response is returned.

GET /admin/promotions/{id}/{rule_type}#

List Rules of a Promotion

Retrieve a list of rules in a promotion. The type of rules retrieved depend on the value of the rule_type path parameter:

  • If rule_type is rules, the promotion's rules are retrivied. - If rule_type is target-rules, the target rules of the promotion's application method are retrieved.

  • If rule_type is buy-rules, the buy rules of the promotion's application method are retrieved.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The promotion's ID.
rule_type"rules" | "target-rules" | "buy-rules"
The type of rules to retrieve.

Query parameters

fieldsstringOptional
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.
promotion_type"standard" | "buyget"Optional
The type
application_method_type"fixed" | "percentage"Optional
The promotion's application method type.
application_method_target_type"items" | "shipping_methods" | "order"Optional
The promotion's application method target type.

Request examples

Responses

200 OK

rulesobject[]
The list of promotion rules.

400, 401, 404, 409, 422, 500: an error response is returned.

Found a problem with this page?Report Issue
Edited Nov 14·Edit this page