Add custom data to cart
Prerequisites
- Merchant API key
- Existing cart id
Goals
- Add custom data to a cart
- Complete checkout with the custom data attached to cart on the order
Architecture at a glance
- Add custom data to cart → Complete checkout with saved data
APIs used
- Merchant API:
https://merchantapi.geins.io/graphql
Step-by-step
Add custom data to cart
Using the setCartMerchantData mutation in the Merchant API, you can add custom data to a cart at any time before checkout. The expected format is a stringified JSON object, which allows you to store multiple key-value pairs.
Request example
mutation setCartMerchantData(
$id: String!
$merchantData: String!
$channelId: String
$languageId: String
$marketId: String
) {
setCartMerchantData(
id: $id
merchantData: $merchantData
channelId: $channelId
languageId: $languageId
marketId: $marketId
) {
id
merchantData
}
}
{
"Accept": "application/json",
"X-ApiKey": "{MERCHANT_API_KEY}"
}
{
"id": "{CART_ID}",
"merchantData": "{\"giftMessage\":\"Happy Birthday!\",\"deliveryInstructions\":\"Leave at the front door if no one is home.\"}",
"channelId": "{CHANNEL_ID}",
"languageId": "{LANGUAGE_ID}",
"marketId": "{MARKET_ID}"
}
curl -X POST https://merchantapi.geins.io/graphql \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-ApiKey: {MERCHANT_API_KEY}" \
-d '{"query":"mutation setCartMerchantData($id: String!, $merchantData: String!, $channelId: String, $languageId: String, $marketId: String) { setCartMerchantData(id: $id, merchantData: $merchantData, channelId: $channelId, languageId: $languageId, marketId: $marketId) { id merchantData } }","variables":{"id":"{CART_ID}","merchantData":"{\"giftMessage\":\"Happy Birthday!\",\"deliveryInstructions\":\"Leave at the front door if no one is home.\"}","channelId":"{CHANNEL_ID}","languageId":"{LANGUAGE_ID}","marketId":"{MARKET_ID}"}}'
channelId, languageId, and marketId arguments are optional and can be left out to use default values.Response example
200 OK{
"data": {
"setCartMerchantData": {
"id": "{CART_ID}",
"merchantData": "{\"giftMessage\":\"Happy Birthday!\",\"deliveryInstructions\":\"Leave at the front door if no one is home.\"}"
}
}
}
Complete the checkout
After adding the custom data, you can proceed to complete the checkout as usual. The custom data will be included on the cart that is attached to the order.
Options
Channel, Language, and Market
The mutation also supports optional parameters for multi-market support:
channelId, languageId, and marketId in the "how to"-article about using multi-market support..Authenticated access
While authentication is not required for this mutation, including a JWT bearer token in the Authorization header can provide personalized results based on the authenticated user's context, for example personalized pricing.
To include authentication, add the JWT bearer token to your request headers:
"Authorization": "Bearer {JWT_TOKEN}"
Common pitfalls
- Ensure the
merchantDatastring is properly formatted (e.g., valid JSON).