This article outlines the process for Headless and Connected sellers to create promotions. It also explains how operators can access these promotions through our API, including the option to submit promotional adjustment details when creating orders via the API.
Enable Marketing Tools
Before sellers can create promos, Operators need to enable Marketing Tools access. Operators need to:
- Sign in to the Operator portal.
- Go to Sellers (Members) > Manage Sellers.
- Locate the seller you want to edit and click the edit pencil icon in the Account Name column.
- Under the Account Access section, check the Marketing Tools access box.
- Scroll to the bottom and click Update Account.
Creating Promotions in the Seller Portal
If you’re managing promotions directly in the Seller Portal, see How to create promotions in the Seller Portal for step-by-step instructions.
View a promo via GraphQL API
As an operator accessing the Marketplacer GraphQL API, you can view promotions created in both the operator and seller portal. You can query using the variables "status" and "sellerID" with the following query:
query PromotionQuery(
$status: String,
$sellerId: ID
) {
promotions(
status: $status
sellerId: $sellerId
) {
nodes {
id
seller { id, businessName, emailAddress}
name
teaser
description
startDate
endDate
minimumSpend
maximumSpend
suspended
discountType
discountAmount
freeShipping
brandsIncluded { edges { node { name } } }
brandsExcluded { edges { node { name } } }
categoriesIncluded { edges { node { displayName } } }
categoriesExcluded { edges { node { displayName } } }
advertsIncluded { edges { node { description } } }
advertsExcluded { edges { node { description } } }
variantsIncluded { edges { node { sku } } }
variantsExcluded { edges { node { sku } } }
saleItemsExcluded
}
}
}
Add a promo adjustment
You are now able to add adjustments to our orderCreate mutation, this allows operators to submit the adjustments when they are submitting orders. Below is an example query:
adjustments: [
{
adjustmentType: PROMOTION
amountCents: -1000,
amountToWithholdFromSellerRemittanceCents: 1000,
description: "$10 off!",
sourceId: "UHJvbW90aW9uLTYy",
Note these important details when adding a PROMOTION type adjustment:
- adjustmentType is mandatory and should be PROMOTION. Currently, the available adjustment types are FEE and PROMOTION.
- amountCents must be negative and the total amount of all adjustments cannot be more than the total of the invoice.
- amountToWithholdFromSellerRemittanceCents must be positive and not more than the absolute amount of amountCents. This is important, the amount to withhold means that the remaining balance of the discount will be added to the remittance. If the operator was funding the entire promotion, this would need to be 0. If the cost of the discount was being borne entirely by the seller, amountToWithholdFromSellerRemittanceCents would be the absolute value of amountCents.
- description field is mandatory, and will be what is displayed in our UI and invoices as the reason for the promotion.
- sourceId is a direct reference to the promotion. This determines if the discount is to be applied to the shipping or the item, based on the action taken when the associated promotions was created.
Example mutation
An example query is below, in this order we are purchasing one item, adding a promotion that takes $5 off the order, and withholds $1 from the seller. This means a seller will get an additional $4 added to their remittance.
mutation {
orderCreate(
input: {
order: {
address: {
address: "7 Jane St",
city: "Yarraville",
postcode: "3013",
state: { id: "U3RhdGUtMTM=" }
}
emailAddress: "hi@example.com",
firstName: "Zac",
surname: "Promotest"
},
lineItems: [
{
variantId: "VmFyaWFudC01MDQw",
quantity: 1,
cost: {
amount: 2000
tax: 300
},
postage: {
amount: 200
tax: 30
}
adjustments: [
{
adjustmentType: PROMOTION
amountCents: -500,
amountToWithholdFromSellerRemittanceCents: 100,
description: "$5 off!",
sourceId: "UHJvbW90aW9uLTYy",
}
]
},
]
}
)
Which results in the invoice below.
Related articles