Magento 2 Donations Suite Manual¶
Introduction¶
Magento 2 Donations Suite is the extension that makes it possible to accept online donations and support non-profits and charities you care about. Out of the box, Magento 2 doesn’t allow to add such order surcharges.
Requirements and installation¶
Donations Suite supports Open source (Community), Commerce (Enterprise) editions and Commerce cloud. The current version of the Magento installed on your website can be found in the lower right corner of any backend page.
Donations Suite has 3 separate ways of installation:
1) Copy the code (ready-to-paste package);
2) Use MageWorx Repository;
3) Use local Composer.
Extension configuration¶
Backend setup¶
The main extension’s settings can be found under STORES ⟶ Configuration ⟶ MAGEWORX ⟶ Donations.
-
Accept Donations enables / disbales the entire donations functionality in the store.
-
Enable Cart Donations adds the donations box to the shopping cart page. If disabled, the donations functionality will be disabled in the cart page on the front-end. It is possible to add donations via the backend though.
-
Enable donations in Admin Orders enables/disables the possibility to add donations from the backend.
-
Minimum Donation specifies the minimal value of the allowed donations. This will be shown on the frontend as well.
Note
Please bear in mind that this value is for the frontend only. For the orders with donations that are being created in the backend, it won't be counted.
-
Default Description allows to set the default text of the donation box, shown on the front-end.
-
Donation Amount Placeholder sets the placeholder (default text, which is shown inside the input field) for the donation amount field if the custom donation amounts are allowed:
-
Default Organization allows you to choose the default charity, which will be pre-selected on the front-end if the charity functionality is enabled.
-
Show Predefined Amounts allows you to add the predefined donation amounts available for your customers. Below this field the store owner can add these values one by one.
-
Enable Donation Custom Amount allows you to enable the feature of custom donation amounts. If enabled, your customers will be able to specify custom donation amounts on the front-end.
-
Predefined amounts allows you to add the predefined donation amounts available for your customers.
Example
This is the way how these settings can be combined to show the donations on the frontend. The predefined amounts are shown in the dropdown menu. If Custom Amount is selected, the client can specify the desired value. The donation placeholder text (Enter your donation in this case) is shown on this box.
- Enable Round Up Donation enables the round-up functionality.
Example
It provides the possibility to add some small donation amounts, calculated as round-up of the order total to the full price. In case the user's subtotal has the decimal part (like $20.40), this setting will allow to add the roundup (60 cents) to the donation.
If the subtotal doesn't have decimal part, the 'round-up' feature will add $1.
The round-up amount is added to the selected charity (if this feature is enabled).
-
Donations RoundUp Message set the message, which is shown near the 'Round-up' check-box on the front-end. You can use the following variables here: %roundupamount% - inputs the rounded amount; %charity% - inputs the selected organization.
-
Enable Gift Aid Donations enables the Gift Aid functionality.
-
Gift Aid confirmation message set the confirmation notice required to be compliant with Gift Aid. See the Gift Aid section for more details.
Track donations¶
The extension gives you the ability to see all orders with the donations on a single page. To see all orders with donations, go to SALES ⟶ MageWorx Donations ⟶ Donations. The grid has the "Donation amount" and the "Organization" column to display the added donation amount and the selected organization/charity. The orders grid is available for each organization as well.
Manage charities¶
To add or edit the organization / charities section, go to SALES ⟶ MageWorx Donations ⟶ Organizations.
To add the new Charity, click the Add New Organization button.
Under these settings you can specify the Name of the charity and its Description, upload an Image (logo), define the Sort Order and the Status of this charity.
Name, Description and the Image will be shown on the frontend. The sort order provdes the position of this charity.
The "Orders" section displays all orders with the donations for a certain charity:
Donations for back-end orders¶
You can also add the donation to the orders, created in the back-end (add the products to the order first):
When added, it will be shown in the order summary
Frontend experience¶
On frontend, the donations box is shown in the cart side bar. Please check the image below to see how the cart block looks like if all features are enabled:
Themes compatibility¶
The extension is compatible with Magento 2 Luma, Porto, Ultimo, Amasty Jet themes by default. If you have any issues with compatibility with any other 3rd party themes, please drop us a line and we will be happy to assist.
Gift Aid¶
Gift Aid is a tax relief allowing UK charities to reclaim an extra 25% in tax on every eligible donation made by a UK taxpayer. See more details on JustGiving and on Gov.uk.
The Donations Suite extension allows you to collect the donataions compliant with Gift Aid. You can enable the Gift Aid feature in the extension configuration. See the Back-end setup section.
Once the Gift Aid is enabled, the "Gift Aid" check-box will appear on the front-end. If your customers will choose it, they will have to select another check-box to confirm they are UK taxpayers. Once it is confirmed, the new field to enter their UK address will appear.
All these details are stored in the order and you can see these columns in Magento 2 native orders grid (Sales ⟶ Orders).
These columns are also added to the orders export feature in order to easily export all orders with Gift Aid.
PWA themes¶
The extension out of the box has the integrations with the following PWA themes:
- Magento 2 Venia
Note
The free compatibility addon must be installed from https://github.com/mageworx/mageworx-donations-veniapwa
Hyvä themes¶
The extension out of the box has the integrations with Hyvä themes:
Note
The free compatibility addons must be installed. See this link for more details.
GraphQL API¶
The GraphQL API is added by the free DonationsGraphQl addon.
1. mwDonationsInfo query returns the information about donations
Syntax
mwDonationsInfo: MwDonationsInfo
The MwDonationsInfo object may contain the following attributes:
min_value: Float @doc(description: "Minimum donation amount")
default_description: String @doc(description: "Donation default description")
amount_placeholder: String @doc(description: "Donation amount placeholder")
default_charity_id: Int @doc(description: "Default organization")
predefined_values: [Float] @doc(description: "Predefined donation amounts")
allow_round_up: Boolean @doc(description: "Allow Round Up Donation")
enable_round_up_by_default: Boolean @doc(description: "Enable Round Up by default")
is_gift_aid_allowed: Boolean @doc(description: "Indicates if gift aid donations are allowed")
gift_aid_message: String @doc(description: "Gift Aid confirmation message")
charities: [MwCharity] @doc(description: "An array of Charities")
The MwCharity object may contain the following attributes:
id: Int @doc(description: "Charity ID")
name: String @doc(description: "Charity name")
description: String @doc(description: "Charity description")
sort_order: Int @doc(description: "Sort Order")
Request:
{
mwDonationsInfo {
min_value
default_description
amount_placeholder
default_charity_id
predefined_values
allow_round_up
enable_round_up_by_default
is_gift_aid_allowed
gift_aid_message
charities {
id
name
description
sort_order
}
}
}
Response:
json
{
"data": {
"mwDonationsInfo": {
"min_value": 10,
"default_description": "Default Description: Default text of the donation box, shown on the front-end",
"amount_placeholder": "Enter your donation",
"default_charity_id": 3,
"predefined_values": [
15,
20,
25
],
"allow_round_up": true,
"enable_round_up_by_default": true,
"is_gift_aid_allowed": true,
"gift_aid_message": "I confirm I'm a UK taxpayer.",
"charities": [
{
"id": 2,
"name": "Don Org 1 - def_st_v - name",
"description": "Don Org 1 - def_st_v - descr",
"sort_order": 0
},
{
"id": 3,
"name": "test 2",
"description": "Description for test 2",
"sort_order": 0
}
]
}
}
}
2. The addMwDonationToCart mutation is used to add a donation to the shopping cart.
Syntax
addMwDonationToCart(input: AddMwDonationToCartInput): AddMwDonationToCartOutput
The AddMwDonationToCartInput object may contain the following attributes:
cart_id: String! @doc(description:"The unique ID that identifies the customer's cart")
charity_id: Int @doc(description: "Charity ID")
amount: Float @doc(description: "Donation amount")
round_up: Boolean @doc(description: "Round up")
uk_confirm: Boolean @doc(description: "Confirms UK Taxpayer")
gift_aid_address: String @doc(description: "UK address")
The AddMwDonationToCartOutput object contains the Cart object. We add the new attribute added_mw_donation to the Cart object.
added_mw_donation: AddedMwDonation @doc(description:"Added donation")
The AddedMwDonation object may contain the following attributes:
charity_id: Int @doc(description: "Charity ID")
charity_name: String @doc(description: "Charity name")
global_amount: Float @doc(description: "Global donation amount")
amount: Float @doc(description: "Donation amount")
round_up: Boolean @doc(description: "Round up")
gift_aid_address: String @doc(description: "UK address")
Request:
mutation {
addMwDonationToCart(
input: {
cart_id: "kPi7RAFpz6qNJMEYDmjwXenMWvj5NqSz"
charity_id: 2
amount: 20
round_up: false
uk_confirm: true
gift_aid_address: "test address. API"
}
) {
cart {
items {
id
product {
sku
stock_status
}
quantity
}
added_mw_donation {
charity_id
charity_name
global_amount
amount
round_up
gift_aid_address
}
}
}
}
Response:
json
{
"data": {
"addMwDonationToCart": {
"cart": {
"items": [
{
"id": "122",
"product": {
"sku": "24-MB02",
"stock_status": "IN_STOCK"
},
"quantity": 4
},
{
"id": "123",
"product": {
"sku": "24-MB04",
"stock_status": "IN_STOCK"
},
"quantity": 1
},
{
"id": "126",
"product": {
"sku": "MW-Gift-mail",
"stock_status": "IN_STOCK"
},
"quantity": 4
}
],
"added_mw_donation": {
"charity_id": 2,
"charity_name": "Don Org 1 - def_st_v - name",
"global_amount": 20,
"amount": 20,
"round_up": false,
"gift_aid_address": "test address. API"
}
}
}
}
}
REST/SOAP API¶
Create Charity¶
The method needs the admin authorization token.
Request Format
api
POST /V1/mw-donations/charity
Request JSON example
json
{
"charity": {
"store_ids": [
0
],
"is_active": 1,
"store_locales": [
{
"store_id": 0,
"store_name": "Org 1",
"store_description": "Org 1 description"
},
{
"store_id": 1,
"store_name": "Org 1 name - for store_id 1",
"store_description": "Org 1 description - for store_id 1"
}
]
}
}
Response JSON example
json
{
"id": 11,
"charity_id": 11,
"name": "Org 1 name - for store_id 1",
"description": "Org 1 description - for store_id 1",
"image_url": "",
"sort_order": 0,
"is_active": 1,
"date_added": "2021-09-13 12:28:17",
"date_updated": "2021-09-13 12:28:16",
"collected_amount": 0,
"store_ids": [
0
],
"store_locales": [
{
"store_id": 0,
"store_name": "Org 1",
"store_description": "Org 1 description"
},
{
"store_id": 1,
"store_name": "Org 1 name - for store_id 1",
"store_description": "Org 1 description - for store_id 1"
}
]
}
Update Charity¶
The method needs the admin authorization token.
Request Format
api
PUT /V1/mw-donations/charity
Request JSON example
json
{
"charity": {
"charity_id": 11,
"store_ids": [
1,2
]
}
}
Response JSON example
json
{
"id": 11,
"charity_id": 11,
"name": "Org 1 name - for store_id 1",
"description": "Org 1 description - for store_id 1",
"image_url": "",
"sort_order": 0,
"is_active": 1,
"date_added": "2021-09-13 12:28:17",
"date_updated": "2021-09-13 12:37:42",
"collected_amount": 0,
"store_ids": [
1,
2
],
"store_locales": [
{
"store_id": 0,
"store_name": "Org 1",
"store_description": "Org 1 description"
},
{
"store_id": 1,
"store_name": "Org 1 name - for store_id 1",
"store_description": "Org 1 description - for store_id 1"
}
]
}
Delete Charity by ID¶
The method needs the admin authorization token.
Request Format
api
DELETE /V1/mw-donations/charity/:charityId
where the "charityId" is the ID of the charity you want to remove.
Get Charities matching the specified criteria¶
The method needs the admin authorization token.
Request Format
api
GET /V1/mw-donations/charities
You should specify the searchCriteria in the Query Params like:
| key | value |
|---|---|
| searchCriteria[filter_groups][0][filters][0][field] | is_active |
| searchCriteria[filter_groups][0][filters][0][value] | 1 |
Response JSON example
json
{
"items": [
{
"id": 2,
"charity_id": 2,
"name": "Don Org 1 - def_st_v - name",
"description": "Don Org 1 - def_st_v - descr",
"image_url": "",
"sort_order": 0,
"is_active": 1,
"date_added": "2020-09-04 09:48:32",
"date_updated": "2021-09-02 10:25:46",
"collected_amount": 100,
"store_ids": [
1,
2,
15,
16
],
"store_locales": [
{
"store_id": 0,
"store_name": "Don Org 1",
"store_description": "Don Org 1 - def - descr"
},
{
"store_id": 1,
"store_name": "Don Org 1 - def_st_v - name",
"store_description": "Don Org 1 - def_st_v - descr"
}
]
},
{
"id": 3,
"charity_id": 3,
"name": "test 2",
"description": "Description for test 2",
"image_url": "https://m24.kostevich.webra.mageworx.com/media/mageworx/donations/charity/1/1/11.jpeg",
"sort_order": 0,
"is_active": 1,
"date_added": "2021-06-22 16:06:28",
"date_updated": "2021-09-01 16:19:10",
"collected_amount": 72.1,
"store_ids": [
0
],
"store_locales": [
{
"store_id": 0,
"store_name": "test 2",
"store_description": "Description for test 2"
},
{
"store_id": 2,
"store_name": "test 2 - stw2 - name",
"store_description": "test 2 - stw2 - descr"
},
{
"store_id": 15,
"store_name": "test 2 - test dis - name",
"store_description": "test 2 - test dis - descr"
}
]
}
],
"search_criteria": {
"filter_groups": [
{
"filters": [
{
"field": "is_active",
"value": "1",
"condition_type": "eq"
}
]
}
]
},
"total_count": 2
}
Add Donation to Cart for admin orders¶
The method needs the admin authorization token.
Request Format
api
PUT /V1/mw-donations/carts/:cartId/donation
where the "cartId" is the ID of the cart.
Request JSON example
json
{
"donationData": {
"charity_id": 2,
"amount": 0,
"round_up": true,
"uk_confirm": true,
"gift_aid_address": "test address. API"
}
}
If the operation was successful, the server returns true.
Add Donation to Cart for customer's orders¶
The method needs the admin authorization token.
Request Format
api
PUT /V1/mw-donations/carts/mine/donation
Request JSON example
json
{
"donationData": {
"charity_id": 2,
"amount": 0,
"round_up": true,
"uk_confirm": true,
"gift_aid_address": "test address. API"
}
}
If the operation was successful, the server returns true.
Add Donation to Cart for guest's orders¶
The method needs the admin authorization token.
Request Format
api
PUT /V1/mw-donations/carts/guest-carts/:cartId/donation
You should add the masked ID of the cart (masked_id), which can be taken from the quote_id_mask table.
api
PUT /V1/mw-donations/carts/guest-carts/kPi7RAFpz6qNJMEYDmjwXenMWvj5NqSz/donation
Request JSON example
json
{
"donationData": {
"charity_id": 2,
"amount": 0,
"round_up": true,
"uk_confirm": true,
"gift_aid_address": "test address. API"
}
}
If the operation was successful, the server returns true.
Got Questions?¶
Need help with the extensions? Feel free submit a ticket from https://www.mageworx.com/support/
Mageworx offers outstanding services developing custom-tailored solutions for Magento platform to attain your eCommerce objectives. Our professional impassioned team provides profound and custom oriented development of your project in a short timeframe.