Enable punchout for an account

Understand the punchout account setup and enablement tasks

To best understand the account setup and punchout enablement processes for the punchout feature, it’s good to know at a high level the tasks that need to be completed. These tasks are:

Create the punchout account (if this has not been done already).
Enable punchout on the punchout account.
Generate an authorization code. This code will be shared with the procurement system in completing the account connection details to Oracle Commerce.
Download and customize the punchout server-side extensions, then upload them to your Node.js server. See Work with the punchout server-side extension for more information.
Set the punchout cart time setting.

The next sections provide details on how to complete these tasks.

Create the punchout account

Whenever you want to set up a new business buyer for a punchout account, you first need to go through the usual steps required in creating the business account that will use punchout (if you have not done so already).

This process includes designating contract info, providing addresses, choosing catalogs, selecting price groups, etc. Refer to Configure Business Accounts for more complete information on this task.

Note: For this release, no contacts can be set up for punchout accounts as Oracle Commerce does not persist the profile of punchout shoppers. To learn more about how punchout handles the profile of punchout shoppers, refer to Learn about the generic punchout shopper profile.

Additionally, merchants should define a relatively small set of business contacts in Oracle Commerce under whose profiles the procurement system will submit orders after approving them. (For example, these could be the profiles of the approvers at the procurement system.)

You have the following choices to help you define the small set of contacts:

Import the profiles of users whom they expect to submit orders
Customize a server side extension to create profiles on the fly when Oracle Commerce receives a purchase order

Profiles created in either of these ways will be regular contacts, just like the ones created by administrators. They can access the account/site directly just like any other contact on the account.

Enable punchout on the punchout account

After you have set up your punchout account, the next step is to enable punchout on that account. Since not every account will use punchout, this is the way to distinguish punchout accounts from non-punchout accounts.

Use the following steps to enable punchout for an account by using the administration interface:

In the administration interface, click the Accounts icon to go to the Accounts page.
Select the account that you want to use the punchout feature.
From the Account page of that account, select the Punchout tab.
Select Allow Punchout Shopping to enable the punchout feature for that account. This property:
- Allows the designated account to accept punchout (cXML only) shopping requests if the account has an integration to a procurement system.
- Is inheritable. All sub-accounts inherit this field by default.
- Is not site-specific.
- Is unchecked by default.
Select Enable Authorization Code to enable the account to have the ability to generate a punchout authorization code. A Generate button appears. This property:
- Allows you to generate the code that an external system provides in each cXML punchout or purchase order request for authentication purposes. This is the authorization code that will be shared with the procurement system that is using punchout.
The account’s account ID and URL are also shared with the procurement system.
- Is inheritable. All sub-accounts inherit this field by default.
- Is not site-specific.
- Is unchecked by default.

Generate an authorization code

Punchout transactions are signed so that the system receiving the event can verify their authenticity. Once you select Enable Authorization Code on the Punchout tab, the Generate button appears below this option on the administration user interface. This button gives you the ability to generate a punchout authorization code for that account. This is the code that an external system provides in each cXML punchout or purchase order request for authentication purposes. This code can be regenerated at any time if need be.

The authorization code is shared with the procurement system implementing punchout. You must manually communicate this code (for example, via phone or email) to someone on the procurement side during implementation of the procurement system integration. After this is done, the procurement system sends it to Oracle Commerce with each request.

To generate the punchout authorization code, do the following

In the administration interface, click the Accounts icon to go to the Accounts page.
Select the account that has the punchout feature enabled.
Select the Punchout tab of the particular punchout account that requires an authorization code.
Click the Generate button to generate a unique authorization code. A warning appears that tells you that if you continue, the new authorization code will be saved immediately. If you have already generated a code before, this code will replace the existing code. If this is the case, make sure you update any external sources that are using the existing code to access this account.
Click Save to save the code that you have generated. The authorization code is shared with the procurement system implementing punchout. You must manually communicate this code (for example, via phone or email) to someone on the procurement side during implementation of the procurement system integration. After this is done, the procurement system sends it to Oracle Commerce with each request.

Set the punchout cart time setting

The administration user interface also lets you set a time period after which the system removes a punchout cart with its items. Specifically, this setting is used to clear off old carts which have not been punched out and are no longer needed. This is done as follows:

In the administration interface, click the Settings icon.
Select Order Settings.
In the Punchout Carts section of the page, enter the number of days you wish as the time period after which the system removes a punchout cart. 7 days is the default value. You may enter values up to 99 days.
Click Save to save your setting.
Configure the service that runs periodically to remove incomplete punchout orders that have exceeded the time limit you specified. See Set the frequency of incomplete punchout order clean up.

This setting is global across all sites and appears if there is at least one business account.

Set the frequency of incomplete punchout order clean up

A service runs periodically to review the order repository and remove any incomplete punchout orders that have exceeded the time limit specified in the Days Until a Punchout Cart is Removed setting. (See Set the punchout cart time setting.) To set the initial frequency of the order cancellation service, you issue a POST request to the scheduledJobs endpoint, with a payload that specifies the PunchoutOrderScheduledJob component and the schedule, an example of which is provided below. To update the schedule, you issue a PUT request to the same endpoint.

POST /ccadmin/v1/merchant/scheduledJobs

{
"componentPath": "PunchoutOrderScheduledJob",
"scheduleType": "periodic",
"schedule":
  {
   "period" : 1000000
  }
}

The scheduleType and schedule properties determine the frequency used when running the service. Setting these properties is described in detail in the Configure the scheduled order service section.

Learn about the generic punchout shopper profile

For each account that uses punchout, a generic punchout shopper profile is created. Even though Oracle Commerce receives an email address and name in the shopping request from the procurement system, these are only for the purpose of displaying to the shopper (should the merchant decide to customize a widget to do so). From the perspective of Oracle Commerce, the generic punchout shopper profile is associated with all punchout shopping requests.

The generic punchout shopper profile contains the following information:

Last Name = “User”
First Name = “Punchout”
email address = punchoutuser@organizationId.com

This generic punchout shopper is created when the first valid request is received from the procurement system. The generic punchout shopper is also returned by the contact APIs.

In the top-level Contacts list in the administration user interface, the Account Contacts list in the administration user interface, and the Account Contacts widget in Storefront, you can see the last name, first name, and email address of the generic punchout shopper in the list view. This is the same as for a regular shopper. No link is provided to open the contact details, however.

For the top-level Contacts list in the administration user interface, if there is a generic punchout shopper in any account, you will see a message stating that the list may include system-generated punchout contacts that are read-only. You will also see this message in the Account Contacts list in the administration user interface and the Account Contacts widget if the account has a generic punchout shopper.

This following is some additional information about the generic punchout user profile:

A user who knows the URL of the contact details of the generic shopper profile can view it.
The API can operate on the generic punchout shopper just as on any other contact.
A generic punchout shopper profile cannot receive emails.
A generic punchout shopper cannot log into the Storefront except programmatically as part of the punchout session.
If the punchout shopper’s session expires, the shopper will have to return to the procurement system and then punch out again.
If an account stops using punchout and then later re-starts using punchout, when the system receives the first new punchout request, it will ensure that the account’s generic punchout shopper is in place correctly. For example:
- If someone had used an API to remove the generic shopper profile from the account, the system puts it back under the account.
- If someone had used an API to deactivate the generic shopper profile, the system re-activates it.
When you choose to add an existing contact to an account, a dropdown of existing contacts is displayed to choose from, remove other accounts’ generic punchout shoppers from the dropdown list.

Learn more about using punchout

The following are recommendations and notes to keep in mind when enabling the punchout feature:

Commerce does not collect shipping information and does not calculate taxes for a punchout cart.
Commerce does not currently store the punchout shopper’s first name, last name, or email address on carts. Persisted punchout carts are tracked using the order ID.
The punchout shopper’s first name, last name, and email address are currently not mandatory. A merchant can display them, however, if needed. See Display information about a punchout shopper in a widget for more information.
By default, an order originating from a punchout account can be paid using the invoice payment method only. However, merchants can customize the server side extensions to support other payment methods.