Configure Oracle Commerce with Oracle Subscription Management

Register the application and generate a security token

This integration uses the Commerce REST APIs to access Commerce data. You must register the integration within Commerce and generate a security token in order for the integration to be granted access to the data.

To generate a security token:

Log into the Oracle Commerce administration interface.
Click the Settings menu and select Web APIs.
Click Registered Applications from the Web APIs panel.
Click the Register Application button.
Enter a name for the integration application. Create a meaningful name that reflects the purpose of the application.
Click Save. The Application ID and Application Key are automatically generated and the application is added to the Registered Applications page.
Click on the name of the application you created.
Click the Click to reveal link to display the application key. You can copy the application key to use as the security token for the Oracle Commerce Cloud connection.

For more information on managing an application within Oracle Commerce Cloud, see Register applications in Extending Oracle Commerce.

Configure the Oracle CPQ Configuration integration

Configure and enable the Oracle CPQ Configuration integration as described in Use Oracle CPQ Cloud Features.

The configuration of Commerce items and corresponding pricing rules must be defined in Oracle CPQ. External pricing details and recurring charge details for configured items are retrieved from CPQ during order submission flow.

See Entity mappings for relationships between item properties across different systems in the integration, including Oracle CPQ.

Configure the Commerce webhooks

You must configure the Order Submit and Order Validation webhooks as follows:

The Order Submit webhook must point to the OIC Subscription Cloud integration URL.
The Order Validation webhook must point to the Subscriptions validation SSE URL https://<host>/ccstorex/custom/v1/validateSubscriptionOrder.

Follow these steps to configure the webhooks in the Commerce administration interface:

Log into the Commerce administration interface.
Click the Settings icon.
Click Web APIs and then click the Webhook tab.
Click the Order Submit (Production) webhook. Enter the OIC Subscription Cloud integration URL in the URL box and enter the OIC username and password, under Basic Authorization.
Click the Order Validation (Production) webhook. Enter https://<host>/ccstorex/custom/v1/validateSubscriptionOrder in the URL box.
Click Save.

Create custom properties

This integration requires a number of custom properties that you create with the Commerce REST APIs. This section lists the custom properties you must create for accounts, profiles, addresses, orders, and commerce items.

Account custom properties

You must create the following custom property for accounts. For details, see Create custom properties for accounts in Extending Oracle Commerce.

occ_partyId: The party ID of the account in CDM.

Profile custom properties

You must create the following custom property for profiles. For details, see Manage Shopper Profiles in Extending Oracle Commerce.

occ_partyId: The party ID of the profile in CDM.

Address custom properties

You must create the following custom property for addresses. For details, see Work with address types in Extending Oracle Commerce.

This property will be used at order level addresses, such as shipping and billing addresses. Widgets must be customized to populate these properties on the storefront. The value needs to be populated from Account’s or Contact’s address ExternalAddressId property, which holds CDM’s Address Number value.

occ_AddressNumber: The Address Number of the address in CDM.

Orders custom properties

You must create the following custom properties for orders. For details, see Create custom properties for orders in Extending Oracle Commerce. Widget changes are required for populating these properties while a shopper checks out the cart or submits the order.

occ_accountPartyId: Used to map the primary party ID value of a subscription for account-based shoppers.
occ_contactPartyId: For B2C subscriptions, used to map the primary party ID value of a subscription. For account-based subscriptions, used to map the contact value of a subscription.

Commerce item custom properties

You must create the following custom properties for commerce items. For details, see Create custom properties for line items in Extending Oracle Commerce. Widget changes are required for populating these properties while a shopper adds the item to the cart.

occ_assetActionReason: Provides a custom action reason for close, suspend and resume operations.
occ_assetActionDate: Provides a custom action date for close, suspend and resume operations.

Entity mappings

This section shows the relationships between entities across different systems in the integration. Not all entities are mapped to all systems in the integration.

B2B Account

CDM: PartyNumber
Commerce:externalOrganizationId

CDM: PartyId
Commerce: occ_partyId (custom)

B2B Contact

CDM: PartyNumber
customerContactId

CDM: PartyId
Commerce: occ_partyId (custom)

B2C Contact

CDM: PartyNumber
customerContactId

CDM: PartyId
Commerce: occ_partyId (custom)

Account/Contact Address

CDM: AddressNumber
Commerce: externalAddressId

CDM: AddressId

B2B Order Account

CDM: PartyId
Commerce: occ_accountPartyId (custom)

CPQ: Customer

SMC: PrimaryPartyId

B2B Order Contact

CDM: PartyId
Commerce: occ_contactPartyId (custom)

CPQ: _asset_custom_contactPartyId (custom)

SMC: QuoteToContactId

B2B Order Address

CDM: AddressNumber
Commerce: occ_AddressNumber (custom)

AR: CustomerAccountId
CPQ: accountNumber_t

SMC: BillToAccountId

AR: CustomerAccountSite > CustomerAccountSiteUse > SiteUseId
CPQ: billToSiteUseId_t

SMC: BillToSiteId

B2C Order Contact

CDM: PartyId
Commerce: occ_contactPartyId (custom)

CPQ: customer

SMC: PrimaryPartyId

B2C Order Address

CDM: AddressNumber
Commerce: occ_AddressNumber (custom)

Configure the server-side extensions

The following table shows the relationships between products and SKUs across systems.

Product Hub	Commerce	CPQ	Subscription Management Cloud
ItemId	N/A	PartnerPartId	InventoryItemId
ItemNumber	SkuId	PartNumber	ProductName
ItemDescription	DisplayName	Description	N/A

The subscription integration functionality is provided through server-side extensions that run on the Node.js server associated with your Commerce environment. Download each extension from the Commerce administration server, then configure the extension and upload it to your Node.js server. The server-side extensions implement custom REST endpoints, which have the prefix /ccstorex/custom for the Commerce storefront and /ccagentx/custom for Oracle Commerce Agent.

For the Agent extensions, shopperProfileId should be included in the X-CCAgentContext header. For account-based shoppers, the X-CCOrganization header should also be present.

This section describes the server-side extensions that are included with the integration. For details about server-side extensions and how to develop them for use with Commerce, see Develop server-side extensions in Extending Oracle Commerce.

subscriptions-app-store.zip Provides endpoints that fetch subscriptions and subscription products for the Commerce storefront. Also provides an endpoint that validates the order for both the storefront and the Agent console.
subscriptions-app-agent.zip Provides endpoints that fetch subscriptions and subscription products for the Agent.
subscriptions-assets-store.zip Provides endpoints that use Oracle CPQ to view and perform asset-based ordering actions on subscription assets. This extension is for the Commerce storefront.
subscriptions-assets-agent.zip Provides endpoints that use Oracle CPQ to view and perform asset-based ordering actions on subscription assets. This extension is for the Agent.

Each ZIP file includes readme.md files that describe classes and endpoints and include information about how to install and extend the extensions.

Create environment variables

This section describes how to set environment variables required by the server-side extensions. The integration requires the following environment variables:

OIC_USERNAME: Specifies the basic authentication username of OIC.
OIC_PASSWORD: Specifies the basic authentication password of OIC.
CPQ_USERNAME: Specifies the basic authentication username for requests that go directly to Oracle CPQ.
CPQ_PASSWORD: Specifies the basic authentication password for requests that go directly to Oracle CPQ.
OSS_USERNAME: Specifies the basic authentication username for requests that go directly to Oracle Subscription Management.
OSS_PASSWORD: Specifies the basic authentication password for requests that go directly to Oracle Subscription Management.

The following example issues a POST request to the doCreateExtensionVariable endpoint that sets the OSS_USERNAME:

/ccadmin/v1/extensionEnvironmentVariables   POST
 {
	"name": "OSS_USERNAME",
	"value": "conmgr"
}

Work with the SSE endpoints

This section describes the storefront and Agent endpoints included in the server-side extensions. All the endpoints are authenticated URLs and all requests must be sent via HTTPS.

/ccstorex/custom/v1/subscriptions?q={query param}
/ccagentx/custom/v1/subscriptions?q={query param}

Issue a GET request to return the details about a particular shopper’s subscriptions.
/ccstorex/custom/v1/subscriptions/{subscriptionNumber}
/ccagetx/custom/v1/subscriptions/{subscriptionNumber}

Issue a GET request to return the details of a subscription.
/ccstorex/custom/v1/subscriptions/{subscriptionNumber}/products?q={query param}
/ccagentx/custom/v1/subscriptions/{subscriptionNumber}/products?q={query param}

Issue a GET request to return the line items of a subscription.
/ccstorex/custom/v1/subscriptions/{subscriptionNumber}/products/ {subscriptionProductPuid}
/ccagentx/custom/v1/subscriptions/{subscriptionNumber}/products/ {subscriptionProductPuid}

Issue a GET request to return the details of a subscription order line item.
/ccstorex/custom/v1/validateSubscriptionOrder
Issue a POST request to validate a subscription order. This endpoint can be used for both storefront and Agent orders.
/ccstorex/custom/v1/assets
/ccagentx/custom/v1/assets

Issue a GET request to get all assets for a particular shopper.
/ccstorex/custom/v1/assets/{assetId}
/ccagentx/custom/v1/assets/{assetId}

Issue a GET request to get an asset based on asset ID.
/ccstorex/custom/v1/assets/{assetId}/modify
/ccagentx/custom/v1/assets/{assetId}/modify

Issue a POST request to modify an asset(with CPQ punch-in).
/ccstorex/custom/v2/assets/{assetId}/modify
/ccagentx/custom/v2/assets/{assetId}/modify

Issue a POST request to modify an asset (with CPQ configurator API).
/ccstorex/custom/v1/assets/{assetId}/renew
/ccagentx/custom/v1/assets/{assetId}/renew

Issue a POST request to renew an asset.
/ccstorex/custom/v1/assets/{assetId}/resume
/ccagentx/custom/v1/assets/{assetId}/resume

Issue a POST request to resume an asset.
/ccstorex/custom/v1/assets/{assetId}/upgrade
/ccagentx/custom/v1/assets/{assetId}/upgrade

Issue a POST request to upgrade an asset. (with CPQ punchin).
/ccstorex/custom/v2/assets/{assetId}/upgrade
/ccagentx/custom/v2/assets/{assetId}/upgrade

Issue a POST request to upgrade an asset. (with CPQ configurator API).
/ccstorex/custom/v1/assets/{assetId}/terminate
/ccagentx/custom/v1/assets/{assetId}/terminate

Issue a POST request to terminate an asset.
/ccstorex/custom/v1/assets/{assetId}/suspend
/ccagentx/custom/v1/assets/{assetId}/suspend

Issue a POST request to suspend an asset.

Create SSE routes to validate billing addresses

Oracle Subscription Management expects an account level address for a business account subscription. If an address which is linked to a contact is passed, Subscription Management rejects it with an appropriate error.

You should design your storefront in a way that allows contacts to select only account addresses when placing subscription orders. In the case where a contact is allowed to enter a contact-level address instead, it is a good idea to validate the billing address before the order is submitted.

If a contact enters their billing address instead of the account’s billing address when creating a subscription order, the integration fails and the following error is logged: The value of the attribute Billing Account is invalid. (OKC-195787).

Since the billing details can be updated even after order validation, this validation can’t be handled as part of the order validation logic and hence this validation is not available by default. You can avoid this error by adding validation code to the payment webhook (genericCardPayment webhook for credit card payments and genericPayment wehook for invoice payments) and creating a new SSE route (/v1/validateSubscriptionOrderBillingAddress) to perform the validation. Point the webhook to the newly created route.

For details about account and contact addresses, see Manage an Account-based Storefront in Using Oracle Commerce.

Configure payments

In this release of the integration, Commerce shoppers can pay for subscription orders with either a credit card or an invoice. For credit cards, create a custom CyberSource integration using the Generic Payment webhook. A payment gateway configured with the Generic Payment webhook handles stored credit cards and tokens, which , which are required for this integration. See Create a Generic Payment Gateway Integration in Extending Oracle Commerce for more information.

Credit card payments

For credit card payments to work properly, Commerce must send a multi- use token to Oracle Subscription Management.

Commerce does not store the complete credit card data. Instead, when a shopper stores a credit card, the payment processor associated with the payment gateway sends back a token that represents the card number. The token is used for each transaction associated with a subscription payment.

When the shopper submits a subscription order, Commerce, through the gateway, authorizes a one-time payment against the card. When you implement this integration, you should populate the muilti use token for the credit card used to pay for the order in statusProps.

After the initial one-time charge, further subscription and billing is not authorized by Commerce. Instead, Commerce will send the multi-use token to Oracle Subscription Management, which, in turn, sends the token to the Oracle Accounts Receivable module.

As part of the payment integration, you need to return back a reusable credit card token to the generic payment webhook response in the property token under statusProps under authorizationStatus. This value will be sent to Oracle Subscription Management for the periodic billing.

"paymentGroups": [
  {
    "authorizationStatus": [
      {
        "amount": 50,
        "statusProps": {
          "token": "12345678"
        }
      }
    ]
  }
]