Promotions via the GraphQL API

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:

1. Sign in to the Operator portal.
2. Go to Sellers (Members) > Manage Sellers.
3. Locate the seller you want to edit and click the edit pencil icon in the Account Name column.
4. Under the Account Access section, check the Marketing Tools access box.
5. Scroll to the bottom and click Update Account.

Which seller portal am I using?

Two versions of the seller portal exist, differing in appearance and menu structure. The icon in the top right-hand corner of your seller portal will tell you which instructions you need: 

Create a promo as a seller in the legacy portal

Once enabled, a seller can create a promotion via the seller portal. Go to Marketing > Promotions in the side nav and click New promotion.

New promotions

• Name: What a seller is naming their promotion.
• Start/End Dates: These are optional fields to schedule a promotion that will run within specific dates.
• Teaser: A seller may wish to add additional teaser text.
• Description: A detailed description of the promotion.
• Suspend Promotion: If turned on, the promotion will not be active on the site.

Actions

Actions refer to rewards the customer will get under this promotion. Note that your filters will not apply if you do not set an action.

• Discount
  • Dollar discount: Set the discount amount for a flat $x off the advert price.
  • Percentage discount: Set the discount percentage for a flat x% off the advert price.
• Free Shipping
  
  • Domestic only: All domestic orders receive free shipping.
  • Domestic and international: All orders, regardless of shipping address, receive free shipping.

Filters

For any of the above Actions, you can further refine the promotions to apply for the following criteria:

• Amount Spent: Set the minimum and maximum dollar amount for ads to qualify for this promotion (e.g. Free Shipping on all orders over $99).
• Limit to Brands: Select a Brand from the dropdown menu to which this promotion should apply.
• Exclude Brands: A dropdown box will appear if toggled on, and selected brands will be excluded from the promotion.
• Limit to Categories: Use the dropdown to select the Tier 1, Tier 2, Tier 3, or Tier 4 category to which this promotion should apply.

Note: There is no need to apply all four. Just apply the level to which the promotion should be restricted.

• Exclude Categories: Any products mapped to the select categories will be excluded from the promotion.
• Limit to Specific Ads: You can apply promotions to specific ads. Simply enter the ad ids in the fields supplied. The ads and all their variants will then have the promotion applied.
• Exclude Specific Ads: Provide Ad ID's to be excluded from the promotion.
• Limit to Specific Variants: You can apply promotions to specific variants of a product. Simply enter the variant ids (these can be found in the URL of the product page) in the fields supplied. A promotion should never be applied to both the parent (product) and the variants as this can cause conflicts.
• Exclude Specific Variants: You may like to exclude variants from an ad to be excluded (but ie. Mens T-Shirt might have Blue, Red and Green variants but you only want the Blue and Red to be included)
• Restrict to Loyalty Program Members: If you have membership levels set up, you can restrict it to certain tiers.
• Exclude Sale Items: Any item with a 'Sale Price' will be excluded from the promotion.

Create a promo as a seller in seller portal 2.0

Once enabled, a seller can create a promotion via the seller portal. Go to Marketing > Promotions in the side nav and click Create new promotion.

Promotion information page

• Promotion name: What a seller is naming their promotion.
• Date range: These are optional fields to schedule a promotion within specific dates.
• Teaser: A seller may wish to add additional teaser text. 
• Description: Detailed description of the promo.
• Suspend promotion: If checked, the promo deactivate.

Actions page

• Discount
  • Amount: Set the discount amount for a flat $x off the advert price.
  • Percentage: Set the discount percentage for a flat x% off the advert price.
• Free shipping
  
  • Domestic only: All domestic orders receive free shipping.
  • Domestic and international: All orders, regardless of shipping address, receive free shipping.

Filters page

Add limits and conditions to your rules.

• Amount spent: Set the minimum and maximum dollar amount for ads to qualify for this promotion (e.g. Free Shipping on all orders over $99).
• Brands: Select a Brand from the dropdown to which this promo should apply.
• Categories: Select a Category from the dropdown to which this promo should apply.
• Specific ads: You can apply promotions to specific ads. Simply enter the ad ids in the fields supplied. The ads and all their variants will then have the promotion applied.
• Specific variants: You can apply promotions to specific variants of a product. Simply enter the variant ids (these can be found in the URL of the product page) in the fields supplied. A promotion should never be applied to both the parent (product) and the variants as this can cause conflicts.
• Restrict to loyalty program members: If you have membership levels set up, you can restrict it to certain tiers.
• Sale items: Any item with a 'Sale Price' will be excluded from the promotion.

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.