Promotions

In this example we take you through how you can use promotions to provide discounts to your customers.

  3 minute read  

What you’ll learn

  • What are promotions
  • GraphQL examples used to work with promotions

What are promotions?

Promotions can be created by either the Operator or Seller to enable the application of discounts on a customer order. It is at the discretion of the Operator whether they want to apply any promotions created (including those created by the Seller), so it is advisable to check with your Operator how promotions are handled before you start creating them.

How to create a promotion

To create a promotion via the API you can use the promotionUpsert mutation, an example is shown below:

mutation CreateAPromotion{
	promotionUpsert(
		input: {
			attributes: {
				name: "10% Off"
				description: "10% off the listed price"
				discountAmount: 10
				discountType: PERCENT
				# You can obtain Brand Ids via the "brands" query
				brandsExcludedIds: ["QnJhbmQtNA==", "QnJhbmQtMTk="]
				# You can obtain Taxon Ids via the "taxons" or "prototypes" queries
				categoriesIncludedIds: ["VGF4b24tNzg="]
			}
		}
	) {
		errors {
			field
			messages
		}
		promotion {
			id
			name
		}
	}
}

In the above example we have not included every possible configuration, refer to the promotionInput type for more information.

Querying Promotions

Having created promotions in Marketplacer, you can query them using the promotions query as shown below:

query ReturnPromotions {
	promotions(status: "active") {
		nodes {
			id
			seller {
				id
				businessName
			}
			name
			teaser
			description
			startDate
			endDate
			minimumSpend
			maximumSpend
			suspended
			discountType
			discountAmount
			freeShipping
			costPercentageBorneByMarketplace
			loyaltyProgramLevels {
				nodes {
					name
				}
			}
			freeShippingDomesticOnly
			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
		}
	}
}

Application of promotions

It is at the discretion of the marketplace operator as to how promotions may be applied. If promotions are being used by the operator, you can read about how this works in the following article.

Understanding adjustments on your invoices (aka orders)

Promotions are 1 type of adjustment that can be applied to your orders. The other type of adjustment is a custom fee, (e.g. additional fee for delivering to an inaccessible area).

Again check with your marketplace operator as to whether these are being used. You can obtain any adjustments that may have been applied to your orders in the following way:

query GetMyOrders {
  node(id: "SW52b2ljZS0xMzU2Ng==") {
    ... on Invoice {
      legacyId
      id
      discountCents
      subtotalCents
      totalCents
      commissionAmountCents
      statusFlags
      adjustments {
        ...adjuistmentFrgament
      }
      lineItems {
        id
        legacyId
        quantity
        status
        adjustments {
          ...adjuistmentFrgament
        }
      }
    }
  }
}
fragment adjuistmentFrgament on Adjustment {
  id
  amountCents
  adjustmentType
  appliesTo
  description
  amountToWithholdFromSellerRemittanceCents
}

This would result in a response similar to the following:

{
  "data": {
    "node": {
      "legacyId": 13566,
      "id": "SW52b2ljZS0xMzU2Ng==",
      "discountCents": -3000,
      "subtotalCents": 20000,
      "totalCents": 17000,
      "commissionAmountCents": 1000,
      "statusFlags": [
        "PAID"
      ],
      "adjustments": [],    👈 Custom Fees would appear here     
      "lineItems": [
        {
          "id": "TGluZUl0ZW0tMzk1Ng==",
          "legacyId": 3956,
          "quantity": 1,
          "status": "ALLOCATED",
          "adjustments": [    👈 Promotions appear here 
            {
              "id": "QWRqdXN0bWVudC00Mzky",
              "amountCents": -2000,
              "adjustmentType": "PROMOTION",
              "appliesTo": "SUBTOTAL_DISCOUNT",
              "description": "10% off promotion",
              "amountToWithholdFromSellerRemittanceCents": 0
            },
            {
              "id": "QWRqdXN0bWVudC00Mzkz",
              "amountCents": -1000,
              "adjustmentType": "PROMOTION",
              "appliesTo": "SUBTOTAL_DISCOUNT",
              "description": "5% off coupon",
              "amountToWithholdFromSellerRemittanceCents": 0
            }
          ]
        }
      ]
    }
  }
}