Map shared data used in the integration

Learn about how data is mapped from commercetools resources to Digital River resources.

This topic describes how data is mapped from commercetools resources to Digital River resources to allow for successful sharing and synchronization of data.

Map product data

When product data is synced to Digital River, each variant on a product is mapped between Digital River and commercetools to a SKU as follows:

commercetools field	Digital River SKU field mapped to	Notes
product.id and variant.id	id	Mapped as ${product}.${variant.id}
product.name	name	Locale to use defined by connector.product-sync.locale-key. Defaults to "en."
product.description	description	Locale to use defined by connector.product-sync.locale-key. Defaults to "en."
variant.images[0].url	image
product.slug	url	Generated using String.format defined in connector.product-sync.slug-url-format or null when not defined.
variant.attributes.drEccn	eccn
variant.attributes.drTaxCode	taxCode
variant.attributes.drCountryOfOrigin	countryOfOrigin
variant.attributes.drSkuGroupId	skuGroupId
variant.attributes.drPartNumber	partNumber
See notes.	allowOversell	Always true
product.version	metadata.ctResourceVersion	Used to ensure ordering of updates

Map Drop-in Checkout session

When a commercetools payment for Digital River is created, a Drop-in Checkout session is created using data mapped from the commercetools cart and payment. This data is mapped as follows:

commercetools field	Digital River Drop-in Checkout session field mapped to	Notes
cart.id	upstreamId
cart.locale and cart.country	locale	Set as ${cart.locale}_${cart.country}.
payment.amountPlanned.currencyCode	currency
cart.customerId	customerId	When available. Not set for guest checkout.
cart.customerEmail	email
cart.custom.fields.drBusinessCustomer	customerType	Set to business when set to true, otherwise individual.
cart.shippingAddress	shipTo	See Address mapping.
cart.custom.fields.drWarehouse	shipFrom	See Warehouse mapping.
cart.lineItems[0].taxRate.includedInPrice	taxInclusive	An error will result if this value is different for any other items in the cart.
See notes	options.shippingCalloutEndpoint	This is a configuration item. See Understand integration environment variables.
payment.custom.fields.drClientIpAddress	browserIp
See notes	discount	Sum of cart and product discount amounts from cart line items. Shipping cost discounts are not supported.
cart.lineItems	items	See below.

Each lineItem is mapped to a Digital River item. The data is mapped as follows:

commercetools cart lineItem field	Digital River item field mapped to	Notes
productId and variant.id	skuId	Set as ${productId}.${variant.id}.
quantity	quantity
price.value.centAmount and quantity	aggregatePrice	Set as (price.value.centAmount * quantity) / 100.

Note: Custom line items are not supported as the data for each item must exist as a SKU in Digital River before a checkout session is created.

Map shippingMethod

When Drop-in Checkout is configured to use the standard shipping callout endpoint in the integration, available shipping methods for the cart are mapped as follows:

commercetools shipping method field	Digital River shipping method mapped to	Notes
zoneRates.shippingRates.price or zoneRates.shippingRates.tiers.price	amount	Tier rate used if one matches, otherwise falls back to matching shippingRate
name	description
custom.fields.drServiceLevel	serviceLevel

Additionally, the cart is mapped to a single shipment as follows:

commercetools cart	Digital River shipment mapped to	Notes
lineItems[]	itemIds	As list of strings using lineItem.id
cart.custom.fields.drWarehouse	shipsFrom	See Warehouse mapping

Map order

When an order is created in Digital River, the commercetools cart is updated and used to create an order. Further updates to the Digital River order, fraud, and payment states are also synchronized to the commercetools order.

Digital River order field	commercetools cart/order field mapped to	Notes
See notes.	taxMode	Set to External to allow use of taxes calculated by Digital River
billTo	billingAddress	See Address mapping
shipTo	shippingAddress	See Address mapping
shippingChoice.description and shippingChoice.serviceLevel	shippingInfo.shippingMethodName	Set as ${shippingChoice.description} (${shippingChoice.serviceLevel})
shippingChoice.amount and shippingChoice.taxAmount	shippingInfo.shippingRate.price	Sum when prices include tax, otherwise just shippingChoice.amount
See notes.	shippingInfo.taxRate.name	Always "Digital River calculated tax"
shippingChoice.amount and shippingChoice.taxAmount	shippingInfo.taxRate.amount	taxAmount / amount
See notes.	shippingInfo.taxRate.includedInPrice	Determined from taxRate.includedInPrice of first line item in commercetools cart
billTo.address.country	shippingInfo.taxRate.country
See notes.	shippingInfo.taxedPrice.totalNet	Calculated by commercetools based on rate and includedInPrice
See notes	shippingInfo.taxedPrice.totalGross	Calculated by commercetools based on rate and includedInPrice
id	custom.fields.drOrderId
state	custom.fields.drOrderState
fraudState	custom.fields.drFraudState
totalImporterTax	customLineItems	Custom line item representing this cost is added to cart
totalDuty	customLineItems	Custom line item representing this cost is added to cart
items	lineItems	See below

Each item from the Digital River order is mapped to a commercetools lineItem as follows

Digital River item field	commercetools cart/order lineItem field mapped to	Notes
id	custom.fields.drLineItemId
tax.rate	taxRate.amount
See notes	taxRate.name	Always "Digital River calculated tax"
See notes	taxRate.includedInPrice	Determined from taxRate.includedInPrice of first line item in commercetools cart
See notes	taxRate.country	Value of order.billTo.address.country for every item

When an order.invoice.created webhook is received this is mapped to the commercetools order as follows

Digital River webhook field	commercetools order field mapped to	Notes
invoice.fileId	custom.fields.drInvoiceUrls	Digital River file service is used to create a public URL for the fileId, and this is added to the set on the commercetools order

When an order.credit_memo.created webhook is received this is mapped to the commercetools order as follows:

Digital River webhook field	commercetools order field mapped to	Notes
invoice.fileId	custom.fields.drCreditMemoUrls	Digital River file service is used to create a public URL for the fileId, and this is added to the set on the commercetools order

Map payment data

When an order is created in Digital River, the corresponding order in commercetools is updated as follows:

Digital River order field	commercetools cart/order lineItem field mapped to	Notes
charges[].amount	amountPlanned	Summed. This may be different from the original amountPlanned when using tax exclusive prices
charges[].amount	amountPaid	Summed
charges[0].state.value	paymentStatus.interfaceCode
charges[]	transactions[]	See below.

For each charge, a transaction is added

Digital River charge field	commercetools transaction field mapped to	Notes
See notes	type	Always "Authorization"
id	interactionId
amount	amount
state	state	"pending" maps to "Pending". "failed" maps to "Failure". Other states map to "Success"
createdTime	timestamp

Map charge/capture data

When an order.charge.capture.pending, order.charge.capture.complete or order.charge.capture.failed webhook is received a charge transaction is created/updated for each capture as follows:

Digital River webhook field	commercetools transaction field mapped to	Notes
charge.captures[].id	interactionId	Used to find existing transaction. Will be set if none found
See notes	type	Always "Charge". Only set on new transactions
charge.captures[].amount and charge.currency	amount	Only set on new transactions
charge.captures[].createdTime	timestamp	Only set on new transactions
charge.captures[].state	state	"Pending" for "pending", "Success" for "complete" and "Failure" for "failed"

Map cancelAuthorization data

When an order.charge.cancel.complete or order.charge.cancel.failed webhook is received a cancel authorization transaction is created/updated for each cancel as follows:

Digital River webhook field	commercetools transaction field mapped to	Notes
charge.cancels[].id	interactionId	Used to find existing transaction. Will be set if none found
See notes	type	Always "CancelAuthorization". Only set on new transactions
charge.cancels[].amount and charge.currency	amount	Only set on new transactions
charge.cancels[].createdTime	timestamp	Only set on new transactions
charge.cancels[].state	state	"Success" for "complete" and "Failure" for "failed"

Map refund data

When an Initial refund transaction is added to a commercetools payment, the Digital River order is refunded using data from the commercetools order and transaction:

commercetools field	Digital River refund field mapped to	Notes
order.custom.fields.drOrderId	orderId
transaction.amount.currencyCode	currency
transaction.amount.centAmount	amount	Divided by 100

The refund transaction is updated with data from the Digital River response

Digital River response field	commercetools transaction field mapped to	Notes
id	interactionId
See notes	state	Always "Pending"

When a refund.pending, refund.complete, or refund.failed webhook is received, a refund transaction is created/updated as follows:

Digital River webhook field	commercetools transaction field mapped to	Notes
refund.id	interactionId	Used to find existing transaction. Will be set if none found
See notes	type	Always "Refund". Only set on new transactions
refund.amount and refund.currency	amount	Only set on new transactions
refund.createdTime	timestamp	Only set on new transactions
refund.state	state	"Pending" for "pending", "Success" for "succeeded" and "Failure" for "failed"

Map customer data

When a registered customer is updated or a checkout session is initiated, a Digital River customer is created or updated.

commercetools field	Digital River field mapped to	Notes
email	email
Default shipping address	shipping	When defined. See the "Map Address data" table below.
locale	locale
custom.fields.drBusinessCustomer	customerType	business if set to true otherwise individual
See notes	enabled	Always true

Additionally, if the update contains a tax certificate in custom.fields.drTaxCertificateFileContents, these fields are set

commercetools field	Digital River field mapped to	Notes
See notes	taxCertificate.id	Id of the Digital River file created from custom.fields.drTaxCertificateFileContents. Copied to custom.fields.drTaxCertificateFileId
custom.fields.drTaxCertificateStartDate	taxCertificate.startDate
custom.fields.drTaxCertificateStartDate	taxCertificate.endDate
custom.fields.drTaxCertificateAuthority	taxCertificate.taxAuthority
companyName	taxCertificate.companyName

Map address data

Where a commercetools address is mapped to or from a Digital River address the mapping is as follows:

commercetools field	Digital River field mapped to	Notes
firstName and lastName	name	Joined with a space on the way to Digital River, split on space on the way back
streetName	address.line1
additionalStreetInfo	address.line2
city	address.city
postalCode	address.postal_code
country	address.country
region or state	address.state	Depends on value of connector.mapping.address-state-from which defaults to REGION but can be set to STATE
phone	phone
email	email

Map warehouse custom data

Where a warehouse custom object is mapped to a Digital River address, the mapping is as follows warehouse.line1, warehouse.line2, warehouse.city, warehouse.postalCode, warehouse.stateProvince, warehouse.country.

Custom object value field	Digital River field mapped to
line1	address.line1
line2	address.line2
city	address.city
postalCode	address.postalCode
stateProvince	address.state
country	address.country