> For the complete documentation index, see [llms.txt](https://docs.digitalriver.com/commercetools-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalriver.com/commercetools-1/configure-the-integration/configure-commercetools.md). # Configure commercetools Learn how to configure commercetools for use in the Digital River commercetools integration. You need to complete some basic configuration tasks for commercetools to interact successfully with Digital River. Make sure that you have [configured Digital River](/commercetools-1/configure-the-integration/configure-digital-river-in-dashboard.md) before you complete the configuration procedures in this topic. To integrate with Digital River, the commercetools integration requires some configuration. This task requires making changes to some configuration settings and adding some customizations. These changes are made in the following areas: * [API Extension Setup](#api-extension-setup) * Payment Create * Payment Update * Customer Update * [Google Cloud Subscription Setup](#gcloudsubscriptionsetup) * [Resource Customizations](#resourcecustomisations) * Payment * Product * Cart/Order * Line Item * Customer * Shipping Method * [Pricing](#pricing) * [Terraform scripts](#terraform) Refer to the [commercetools documentation](https://docs.commercetools.com/docs/) on how to apply these specific changes and customizations or see the [Terraform ](#terraform)section below. The information that follows goes over each specific area and describes the changes that must be made. ## API Extension setup This section explains the settings needed for the API Extension area features to run successfully in the integration. ### Payment Create This feature creates a Digital River drop-in checkout session when a payment is initialized in commercetools. Use the following configuration settings: | Property | Value | Note | | -------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | key | dr-payment-create | | | type | HTTP | Only HTTP destinations are supported | | url | {baseUrl}/api/v1/payments/create | The baseUrl will be defined by where you deploy the plugin. You should front the plugin with HTTPS in production | | actions | Create | | | resourceTypeId | payment | | | timeoutInMs | 2000 | May be increased if required, commercetools now supports up to 5000ms for payment extensions | ### Payment Update This feature is used to update Digital River when a payment is updated in commercetools. Updates may consist of, for example, a refund of a payment when a **Refund** transaction is added to the commercetools payment. Use the following configuration settings: | Property | Value | Note | | -------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | key | dr-payment-update | | | type | HTTP | Only HTTP destinations are supported | | url | {baseUrl}/api/v1/payments/update | The baseUrl will be defined by where you deploy the reference application. You should front the plugin with HTTPS in production | | actions | Update | | | resourceTypeId | payment | | | timeoutInMs | 2000 | May be increased if required, commercetools now supports up to 5000ms for payment extensions | ### Customer Update This feature is used to update Digital River when a customer is updated in commercetools. Updates may consist of * Setting email and default shipping address on the Digital River customer * Attaching a tax certificate to the Digital River customer * Attaching a payment source to the Digital River customer Use the following configuration settings: | Property | Value | Note | | -------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | key | dr-customer-update | | | type | HTTP | Only HTTP destinations are supported | | url | {baseUrl}/api/v1/customers/update | The baseUrl will be defined by where you deploy the reference application. You should front the plugin with HTTPS in production | | actions | Update | | | resourceTypeId | customer | | | timeoutInMs | 2000 | | For production use, it is recommended to set the `authentication.type` and `authentication.headerValue` properties to send a basic `auth` header in the requests from commercetools. These headers must be present and validated before the request is passed to the integration. ## Google Subscription setup (for gCloud deployments) This section explains the settings needed for subscriptions in gCloud deployments to run successfully in the integration. A subscription is required to synchronize product updates from commercetools to Digital River. | Property | Value | Note | | -------------- | ------------------------------------ | -------------------------------------------------------- | | key | product\_sync\_subscription | | | type | GoogleCloudPubSub | | | projectId | Your Google Cloud project id. | | | topic | commercetools\_product\_publish | May be changed, but must match value used in deployment. | | resourceTypeId | product | | | types | ProductPublished, ProductUnpublished | | ## Resource customizations This section explains customizations that need to be done to specific resource values in order for the integration to run successfully. The integration software relies on a number of custom fields being available on various resources. Most of these are values that are set for you to read if needed. You may need, however, to change some of these to different values before you can begin a checkout (see below). The names of the custom type and fields are configurable. The tables below list the default values for the various resources. If you are already using custom types for any of these resources, you need to add the fields to your type and set the type key in the integration configuration so that the integration can write to these fields. ### Payment This table lists the default type and field values for the Payment resource. | Type | Key | Purpose | | ------- | --------- | ---------------------------------------------------------------- | | product | Any value | Passing additional payment information to and from Digital River | #### **Fields** | Field | Type | Constraint | Required | Description | Source | | ----------------- | ------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | drEccn | enum | SameForAll | true | Export control classification number. Value must be in [Digital River appoved list](https://www.digitalriver.com/legal-other/approved-eccns) | Merchant Center / PIM | | drCountryOfOrigin | enum or lenum | SameForAll | true | Country of origin for product. Use an lenum if you need i18n support in the Merchant Center | Merchant Center / PIM | | drTaxCode | enum | SameForAll | true | Tax code. See [Digital River tax codes](https://docs.digitalriver.com/digital-river-api/skus/creating-and-updating-skus#tax-code) | Merchant Center / PIM | | drPartNumber | text | Unique | false | Part number | Merchant Center / PIM | | drSkuGroupId | text or enum | SameForAll | false | Sku group id. Only required if you are using [sku groups](https://docs.digitalriver.com/digital-river-api/skus/setting-up-sku-groups). You may want to use an enum that specifies your valid sku group ids | Merchant Center / PIM | ### Product This table lists the default type and field values for the Product resource. | Type | Key | Purpose | | ------- | --------------- | ---------------------------------------------------------------- | | payment | drPaymentFields | Passing additional payment information to and from Digital River | **Fields** | Field | Type | Description | Source | | ------------------- | ------ | ---------------------------------------------------- | -------------- | | drClientIpAddress | String | Set to the IP address of the browser making payment | Implementation | | drCheckoutSessionId | String | Drop in checkout session id, used to render checkout | Connector | ### Cart/order This table lists the default type and field values for the Cart/Order resource. | Type | Key | Purpose | | ---- | ------------ | ----------------------------------------------------------------------- | | cart | drCartFields | Passing additional cart and order information to and from Digital River | **Fields** | Field | Type | Description | Source | | ------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------- | | drOrderId | String | Id of the order created in Digital River, set once checkout is complete. Used by the integration to look up the commercetools order | Integration | | drOrderState | String | State of the order in Digital River, set once checkout is complete and updated as webhooks are received | Integration | | drFraudState | String | Fraud state of the order in Digital River, set once checkout is complete and updated as webhooks are received | Integration | | drWarehouse | key-value-document reference | Id of the warehouse to be used as the shipFrom address in Digital River. Must be set on the cart before commencing checkout | Implementation | | drInvoiceUrls | Strings | URL(s) for the Digital River invoice(s) for the order. Set after an order is marked as fulfilled | Integration | | drCreditNotes | Strings | URL(s) for the Digital River credit notes(s) for the order. Set after a refund is processed | Integration | | drBusinessCustomer | Boolean | Flag indicating if the customerType should be set to `business` when creating checkout session | Implementation | ### Line item This table lists the default type and field values for the Line Item resource. | Type | Key | Purpose | | --------- | ---------------- | -------------------------------------------------------- | | line-item | drLineItemFields | Map commercetools line items to Digital River line items | **Fields** | Field | Type | Description | Source | | ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | drLineItemId | String | Id of the line item created in Digital River, set once checkout is complete. Used by the integration when processing fulfillments and cancels | Integration | ### Customer | Type | Key | Purpose | | -------- | ---------------- | ------------------------------------------------------------- | | customer | drCustomerFields | Used to pass additional customer information to Digital River | **Fields** | Field | Type | Description | Source | | ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ | -------------- | | drTaxCertificateAuthority | String | Name of the tax certificate authority. Used when adding a tax certificate. | Implementation | | drTaxCertificateStartDate | Date | Start date of tax certificate validity. Used when adding a tax certificate. | Implementation | | drTaxCertificateEndDate | Date | End date of tax certificate validity. Used when adding a tax certificate. | Implementation | | drTaxCertificateFileName | String | File name certificate authority. Used when adding a tax certificate. | Implementation | | drTaxCertificateFileContents | String | Contents of the tax certificate, Base64 encoded. Used when adding a tax certificate. Cleared once processed. | Both | | drTaxCertificateFileId | String | File id of the tax certificate. Set once processing is complete. | Integration | | drAttachSource | String | Id of a payment source to attach (save) to the customer. | Implementation | | drDetachSource | String | Id of a payment source to detach from the customer. | Implementation | | drSources | Set | Strings containing JSON representation of saved payment sources | Integration | | drBusinessCustomer | Boolean | When true sets DR customerType to `business`, otherwise `individual` | Implementation | ### Shipping method This table lists the default type and field values for the Shipping Method resource. | Type | Key | Purpose | | --------------- | ---------------------- | --------------------------------------------------------------------- | | shipping-method | drShippingMethodFields | Used to pass additional shipping method information to Digital River. | **Fields** | Field | Type | Description | Source | | -------------- | ------ | -------------------------------------------------------------------------- | -------------- | | drServiceLevel | String | Value to be passed to Digital River along with other shipping method data. | Implementation | ## Pricing Digital River handles the calculation of taxes so you do not need to configure multiple rates on your tax categories unless you have a requirement to display taxes before the checkout. You can simply use a single rate per country with an amount of 0.0 and `includedInPrice` set to `True`or `False,` depending on how you want Digital River to perform the tax calculation for you. Where you sell into multiple countries, you can set `includedInPrice` differently for each country. It is not possible, however, to check out multiple products that have differing values for `includedInPrice`. ## Terraform scripts [Terraform ](https://www.terraform.io/)scripts can be used to configure your commercetools project. To use the scripts, you need a commercetools API key with the following scopes: | Scope | | ------------------------- | | manage\_types | | manage\_products | | manage\_subscriptions | | manage\_project\_settings | | manage\_extensions | | manage\_api\_clients | | manage\_shipping\_methods | | manage\_orders | ### Google Cloud scripts The following Google Cloud Terraform scripts can be used to configure your commercetools project: | Resource | Terraform script | | --------------- | ------------------- | | API Client | api\_client.tf | | API Extensions | api\_extensions.tf | | Subscription | subscription.tf | | Payment | payment.tf | | Product | product.tf | | Cart/Order | cart\_order.tf | | Line Item | cart\_order.tf | | Customer | customer.tf | | Shipping Method | shipping\_method.tf | To use these scripts, you need to set the following Terraform variables: | Variable | Value | Notes | | ---------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------ | | api\_url | API URL for your commercetools project | e.g. | | auth\_url | Auth URL for your commercetools project | e.g. | | client\_id | Client id of the API key with the above scopes | | | client\_secret | Client secret of the API key with the above scopes | | | payment\_create\_url | {base\_url}/api/v1/payments/create | | | payment\_update\_url | {base\_url}/api/v1/payments/update | | | customer\_update\_url | {base\_url}/api/v1/customers/update | | | project\_key | Your commercetools project key | | | scopes | Space separated list of scopes above with project key | e.g. manage\_types:your-project-key manage\_products:your-project-key... | | product\_sync\_topic | commercetools\_product\_publish | Unless changed. Must match value in deployment | | google\_cloud\_project | Project connector is deployed to | Used for topic/subscription configuration for gCloud deployments |