Open edX Ecommerce

Get Ecommerce working on your Open edX native build. This post is a supplement to the official documentation, “How to Install and Start the E-Commerce Service in Native Installations“, covering installation and configuration, Django configuration, Nginx considerations, and PayPal integration.


The Open edX Ecommerce module is actually a 3rd party Django project named Oscar that the Open edX team fully integrated into the platform by fusing the user lists together with Oauth. While recently setting up the Ecommerce module on a Gingko.2 installation I found myself stumbling through some the steps in the official documentation while disagreeing entirely with others. What follows is a modified procedure that I followed to get Ecommerce running on a Ginkgo.2 installation. Hopefully this will save you some time.

Setup Procedure

1. Verify that the Ecommerce module is running

If you followed the documented instructions from “Native Open edX Ubuntu 16.04 64 bit Installation” for Gingko or later then the Ecommerce module is automatically installed and should be running on your instance. You can verify this by running the following command from a terminal window connected to your Ubuntu instance.

sudo /edx/bin/supervisorctl status

If you see the “Ecommerce” module in a running state then you can ignore the first two steps of the official documentation, or at least when running these you should notice that both steps are benign. If for any reason you decide to execute the first two steps of the official documentation then be forewarned that step #2 is tantamount to upgrading your entire platform and could thus bring unintended consequences beyond the scope of the Ecommerce module setup.

Moreover, if the Ecommerce module is not currently running then you should think carefully about your next steps. If your installation is not version Ginkgo or later then you should consider upgrading your entire platform before proceeding simply to ensure that your code base doesn’t venture too far into the unknown. You can read my blog post on Upgrading Open edX for more detail on what’s involved in upgrading and how to prepare.

2. Configure edX

There are a handful of things to configure in the LMS via the eponymous configuration file /edx/app/edxapp/lms.env.json. Refer to the screen shots below for guidance on the subject matter and approximate locations of each section. You’ll need to restart the LMS for these changes to take effect:

sudo /edx/bin/supervisorctl restart edxapp:

Briefly summarizing the purpose of each section:

  • ENABLE_OAUTH2_PROVIDER – This enables the LMS as a provider of Oauth2 authentication services. The Ecommerce module will leverage Oauth2 rather than host its own user list and passwords. For example, as an end user if you’ve ever elected to “Login with Facebook” then this flag makes your LMS the “Facebook” of that proposition.
  • JWT_AUTH – This is the URL of the JSON Web Token authorizer. In our case it’s exactly the same as the issuer.
  • JWT_ISSUER – This is the URL of the JSON Web Token issuer
  • OAUTH_OIDC_ISSUER – This is the URL of the Open ID issuer (eg your LMS platform)
  • PAID_COURSE_REGISTRATION_CURRENCY – The Ecommerce module reads this value to determine which currency symbol to display along side products. This value is also passed to the payment gateway.
  • PDF_RECEIPT_ – All of the salient text for customer receipts is stored in these fields.
3. Setup Oauth between the CMS and the Ecommerce module

It wasn’t initially apparent to me but, setting configuration parameters in lms.env.json only indicates to the LMS that you want to use it as part of an Oauth authentication; you still have to setup Oauth itself. We’ll use the Django admin console for this. For the Python/Django uninitiated, Django apps like LMS and CMS come with a “back end” admin console where additional configuration parameters are available beyond what you’ll find in the four JSON files in /edx/app/edxapp/. Refer to this screen shot for the URL path and guidelines for creating an Oauth client.

4. Configure Django to use Oscar Ecommerce

This is the definitive step in “activating” the Ecommerce module. Refer to the following screen shot for parameter values and the desired outcome.

5. Configure Oscar Ecommerce

This step essentially binds together the Django configurations you created in the previous two steps 3 & 4 so that the Oscar Ecommerce module works seamlessly with our LMS.

sudo su ecommerce -s /bin/bash
cd ~/ecommerce
source ../ecommerce_env
python makemigrations
python migrate
python create_or_update_site \
	--site-id=1 \ \
	--partner-code=edX \
	--partner-name='Open edX' \
	--lms-url-root= \
	--payment-processors=paypal \
	--client-id=ecommerce-key \
	--client-secret=ecommerce-secret \ \

Following is how these command line arguments map to the two Django configuration screens from the previous step.

6. Navigate to Oscar Ecommerce Dashboard

If everything is working as it should then you’ll be able to navigate to the Ecommerce dashboard where you can begin setting up your products. You can refer to the Oscar Ecommerce Official Documentation for further instructions on setting up products, payment gateways, etcetera.

Trouble Shooting

  • Firewall. You should pay close attention to the unorthodox port assignments used by the Ecommerce module. By default the Oscar Ecommerce module runs on port 8002 and the LMS “Course Discovery” API runs on port 18381. You might need to open these ports on your firewall.
  • Port Settings. Take note that ports have changed over time. The official documentation makes multiple references to ports 18020 and 18130; neither of which seem to be in use on Ginkgo.
  • Nginx. If you’re using SSL on your site then you might need to make adjustments to one or more of the Nginx virtual server configurations located in /edx/app/nginx/sites-available/.

I hope you found this helpful. Please help me improve this article by leaving a comment below. Thank you!

By | 2018-05-10T16:01:44+00:00 April 25th, 2018|Categories: Dev Ops, Open edX|5 Comments

About the Author:

Lawrence is a full stack developer specializing in web and mobile development using AngularJS, Ionic, Wordpress and Amazon Web Services. He has worked as a freelance technology consultant since 1999. He earned a BS in computer science and mathematics with minors in physics and English from University of North Texas.


  1. Luis April 29, 2018 at 11:47 am - Reply

    Very well explained, thanks!!

  2. luis April 29, 2018 at 12:28 pm - Reply

    do you have any official information about configuring ssl on opedx?

  3. Eric Mensah May 22, 2018 at 11:04 pm - Reply

    Hi Lawrence,

    I am a bit confused about the “ecommerce-key” and “ecommerce-secret”

    Does one has to generate any sort of random strings or where do we get them from?


    • admin May 23, 2018 at 6:48 am - Reply

      hi eric. technically speaking, no, it is not necessary. in the illustration in step 3 you can see that “Client id” is defaulted to the value “ecommerce-key” and that “Client secret” is defaulted to “ecommerce-secret”. these work. they are arbitrary values, and on an aside these are probably not the greatest values to use, so you might consider changing one or both to something more secure. the important thing to remember is that you must be consistent in the values that you choose: whatever values you choose in the LMS oAuth setup you need to duplicate in the Django Oscar setup.

Leave A Comment