django-oscar / django-oscar-api

RESTful JSON API for django-oscar

Domain-driven e-commerce for Django

Oscar is an e-commerce framework for Django designed for building domain-driven sites. It is structured such that any part of the core functionality can be customised to suit the needs of your project. This allows a wide range of e-commerce requirements to be handled, from large-scale B2C sites to complex B2B sites rich in domain-specific business logic.

Contents:

local

Further reading:

• Official homepage
• Sandbox site (automatically deployed via the official docker sandbox image)
• Documentation on the excellent readthedocs.org
• Docker image on http://hub.docker.com/
• django-oscar group - mailing list for questions and announcements
• Twitter account for news and updates
• Discord
• PyPI page
• Transifex project - translating Oscar made easy

Continuous integration status:

PyPI status:

Docs status:

Core team:

• David Winterbottom (Twitter @codeinthehole)
• Maik Hoepfel (Twitter @maikhoepfel)
• Markus Bertheau
• Michael van Tellingen
• Alexander Gaevsky
• Samir Shah

Supported versions

The currently supported versions of Oscar are:

Version	End of support
3.2 LTS	January 2026
3.1	April 2022
3.0	May 2021
2.2 LTS	August 2023

Supported versions are eligible for fixes for data loss bugs and security issues. Releases designated as Long-term support (LTS) releases will receive support for an extended period of 3 years from their release date.

Screenshots

Sandbox

These are screenshots from the 'sandbox' example site that ships with Oscar. It sports a simple design built with Twitter's Bootstrap and provides a good starting point for rapidly building elegant e-commerce sites.

The sandbox site is also available to browse at https://latest.oscarcommerce.com.

The sandbox site can be set-up locally in 5 commands. Want to make changes? Check out the contributing guidelines.

Extensions

The following extensions are stable and ready for use:

• django-oscar-api - RESTful JSON API for django-oscar
• django-oscar-odin - Odin Resources and mappings to Oscar models
• django-oscar-adyen - Integration with the Adyen payment gateway
• django-oscar-datacash - Integration with the DataCash payment gateway
• django-oscar-paypal - Integration with PayPal. This currently supports both Express Checkout and PayFlow Pro.
• django-oscar-paymentexpress - Integration with the Payment Express payment gateway
• django-oscar-accounts - Managed accounts (can be used for giftcard functionality and loyalty schemes)
• django-oscar-stores - Physical stores integration (opening hours, store locator etc)
• django-oscar-sagepay-direct - Integration with "DIRECT" part of Sagepay's API
• django_oscar_docdata - Integration with Docdata payment gateway.
• django_oscar_invoices - Invoices or receipts generation for the Oscar

The following are community-written extensions:

• django-oscar-payments - Pluggable payments for Oscar
• oscar-sagepay - Payment integration with Sage Pay
• django-oscar-support - Customer services and ticketing plugin for Oscar
• django-oscar-api-checkout - Oscar API Checkout is a layer on top of django-oscar and django-oscar-api, adding support for more complex and multiple payment options during an API checkout.
• django-oscar-bundles - Oscar Bundles adds multi-product bundles to django-oscar.
• django-oscar-bluelight - Bluelight Specials is a layer on-top of django-oscar that adds support for more complex offers and vouchers, including conjunctive and disjunctive compound conditions.
• django-oscar-cch - Oscar CCH is a plugin for django-oscar adding support for calculating taxes using the Wolters Kluwer CCH Sales Tax Office SOAP API.
• django-oscar-cybersource - Oscar CyberSource is a plugin for Oscar API Checkout that makes it possible to use CyberSource Secure Acceptance Silent Order Post as an order payment method.
• django-oscar-wfrs - Oscar WFRS is a plugin for django-oscar-api-checkout that makes it possible to use Wells Fargo Retail Services as an order payment method.
• django-oscar-zarinpal-gateway - Payment gateway integration for Zarinpal Payments in django-oscar. Zarinpal Payments is a large payment gateway based in The I.R. Iran .

Let us know if you're writing a new one!

Videos

Videos with talks about Oscar:

• An introduction to Django-oscar by David Winterbottom, DjangoCon Europe 2014
• Oscar and the art of transactional Django applications by David Winterbottom, PyCon PL 2014
• The Tale of Oscar and the API by Kees Hink, PyGrunn 2017

License

Oscar is released under the permissive New BSD license (see summary).

Contributing to the Project

We welcome contributions to the project! Whether it's a bug fix, a new feature, or just some documentation improvements, your contributions are greatly appreciated.

To contribute, please follow these steps:

Fork the project repository on GitHub. Clone your forked repository to your local machine. Create a new branch for your changes. Make your changes, and commit them with clear commit messages. Push your changes to your forked repository. Open a pull request on the original project repository, explaining your changes. Please note that all contributions are subject to review, and may be modified or rejected if they do not meet the project's standards.

Code of Conduct

We want everyone involved in the project to feel safe and respected, regardless of their background or identity. As such, we have adopted the following Code of Conduct:

Our Pledge

In the interest of fostering an open and welcoming environment, we pledge to:

Be friendly and welcoming to all contributors. Respect differing viewpoints and experiences. Accept constructive criticism and feedback graciously. Focus on what is best for the community and the project.

Our Standards

We expect all contributors to:

Use welcoming and inclusive language. Be respectful of differing viewpoints and experiences. Gracefully accept constructive criticism. Focus on what is best for the community and the project.

Our Responsibilities

Project maintainers are responsible for:

Enforcing the Code of Conduct. Investigating and addressing reported violations of the Code of Conduct. Making clear and fair decisions about disciplinary actions for violations of the Code of Conduct. Scope This Code of Conduct applies to all contributors, both online and offline, in all project spaces, including but not limited to project forums, mailing lists, GitHub repositories, and in-person events.

Enforcement

If you witness or experience unacceptable behavior, or have any other concerns, please notify the project maintainers at [email protected] & [email protected]. All reports will be kept confidential, and the project maintainers will work with you to determine a resolution.

We reserve the right to take any action deemed necessary to enforce this Code of Conduct, including but not limited to warning the offender, banning the offender from the project's spaces, or reporting the offender to relevant authorities. Case studies ------------

Oscar is still in active development but is used in production by a range of companies, from large multinationals to small, boutique stores. See http://oscarcommerce.com/cases.html for an overview.

Many more on the way. If you use Oscar in production, please let us know.

Looking for commercial support?

If you are interested in having an Oscar project built for you, or for development of an existing Oscar site then please get in touch via [email protected].

django-oscar-api's Issues

No module names api

I was using oscar api but after a while,'magically' following problem arose

ImportError: No module named 'api'

but, 'oscarapi' is in Installed apps,
and urls are defined as :

from oscarapi.app import application as api
 url(r'^api/', include('api.urls')),   

Q: Use Oscar via API only in React app

I would like to integrate django-oscar-api into an existing django-rest-framework <--> React project.

In the django-oscar-api documentation, I'm finding bits and pieces talking about "mixing an Oscar stand-alone website and the API".

Therefore my question: Is it at all possible to make use of Oscar API only?

How do you deal with API version?

So, I am deploying a mobile application with the present version of django-oscar-api.
Tomorrow there might be an update in the structure. The old mobile application might crash or functionalities might not work.

How is django-oscar-api architected?
Are you thinking of make django-oscar-api-v2, v3 versions when there are big changes?

Add a Category API and a way to filter products based on categories

I started working with the api and I discovered that the Category is missing. There is no code to return the categories. And how can I show products based on selected category

pip release ?

Depends on #37

Tests fail with postgresql

The oscarapi tests pass with sqlite as a db backend, and fail when run with postgres:

$ virtualenv env
$ . env/bin/activate
(env)web@vagrant-ubuntu-trusty-64:~$ git clone [email protected]:django-oscar/django-oscar-api.git
(env)web@vagrant-ubuntu-trusty-64:~$ cd django-oscar-api/
(env)web@vagrant-ubuntu-trusty-64:~$ make test
...
Ran 43 tests in 10.923s

OK

• Swap out DATABASES in sandbox/settings.py with a postgresql configuration: ''ENGINE': 'django.db.backends.postgresql_psycopg2',' along with a working set of settings
  • pip install psycopg2
• and re-run:

(env)web@vagrant-ubuntu-trusty-64:~$ make test
 ...
Ran 43 tests in 11.163s

FAILED (errors=3, failures=14)

The full output is pretty long. Here is one of the errors:

======================================================================
ERROR: A regular or anonymous user should not be able to fetch someone elses basket.
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/web/django-oscar-api/oscarapi/tests/testbasket.py", line 169, in test_basket_read_permissions
    self.assertEqual(str(b.owner), 'nobody')
  File "/home/web/env/local/lib/python2.7/site-packages/django/db/models/fields/related.py", line 572, in __get__
    rel_obj = qs.get()
  File "/home/web/env/local/lib/python2.7/site-packages/django/db/models/query.py", line 357, in get
    self.model._meta.object_name)
DoesNotExist: User matching query does not exist.

AttributeError at /api/basket/ 'ApiBasketMiddleWare' object has no attribute 'request'

AttributeError is thrown on ApiBasketMiddleWare line 214. Steps to reproduce:

1. Clear all cookies.
2. Add item to cart using stock oscar "add to basket" button.
3. Request the basket endpoint from oscarapi.

Replace serializers.HyperlinkedIdentityField with PriceSerializer

How do I replace serializers.HyperlinkedIdentityField with PriceSerializer? How do I do it? Is it good or bad method to follow? I want to display price in the list view.

Support and test against python 3.5 and django 1.9

Any issues with this? Do we want 1.7 tests still (which is no longer a supported version)? I can test things out and do a pull request if this is ok.

Products by Category

hi im currently working on a mobile app and realized that i cant find any code to get products by specified category. How could i implement this?

Oscar API is not Django 1.9 compatible

This is caused that Travis is downgrading Django to 1.8 so the test results are not correct.

use tastypie

seriously. do it.

is_quantity_allowed() does not return an error message.

I think is_quantity_allowed() should return an error message instead of quantity.

django-oscar-api/oscarapi/views/basket.py

Line 83 in 978b378

return False, quantity

Oscarapi structure

Like oscar's dashboard and core apps, could we have sub-apps for the api as well? For example we could have the oscarapi/basket app which will have it's own app.py, serializers.py and views.py. This should be easy enough to do.

This could also help address the issue of extensibility. There was an attempt to make oscar's get_classes function work with modules that aren't present in oscar's core. I'm not sure what happened to that but now would be a good time to raise the issue again because with the sub-apps structure and a dynamic get_classes method in oscar, we'll have a highly extensible api app.

Oscar Api Checkout

Hello , in terms of checkout process during the request, the current latest version of django-oscar api has a checkout method already implemented.But , i need to know how to use PayPal with django oscar api and Stripes as a payment gateway.I mean , when someone try to buy you most select a payment type as the demo site has show.

Can someone explain how can i do that ? from the Api side???

How to create a basket with more than one product?

Is it possible to POST more than one product to /basket/add-product/?
If so, how? If not, how can it be done?

Potential bug in `oscarapi_post_checkout` signal being sent

In oscarapi/views/checkout.py, the "response" argument of the oscarapi_post_checkout signal being sent is the entire rest_framework.response. I don't think that was the intent of the code.

from rest_framework import response


class CheckoutView(views.APIView):
    ...

    def post(self, request, format=None):
        ...
        oscarapi_post_checkout.send(
            sender=self, order=order, user=request.user,
            request=request, response=response)
        return response.Response(o_ser.data)

Probably should be something like this:

from rest_framework import response


class CheckoutView(views.APIView):
    ...

    def post(self, request, format=None):
        ...
        response = response.Response(o_ser.data)
        oscarapi_post_checkout.send(
            sender=self, order=order, user=request.user,
            request=request, response=response)
        return response

Compatibility with Django REST Framework 3

I have an existing oscar project that has some non-oscar parts using Django REST Framework 3. If I start using django-oscar-api for the oscar parts, will this cause an issue knowing that django-oscar-api requires DRF version less than 3?

Error in tests

"settings.OSCAR_MAX_BASKET_QUANTITY_THRESHOLD = None" in testoffer.py and testbasket.py is an error.

Update middleware to use the MiddlewareMixin

See https://docs.djangoproject.com/en/2.0/topics/http/middleware/#upgrading-pre-django-1-10-style-middleware and https://github.com/django-oscar/django-oscar/blob/1.5.2/src/oscar/core/compat.py#L74

Api Gateway and Authorizations

Hello , i am new using Django Oscar Api .I am using the latest stable version :1.0.10 (2016-12-08)

I just installed and need to use Api Key resource protection.I just create an Api Key Object in the Admin Panel, add to settings.py oscarapi.middleware.ApiGatewayMiddleWare and every time i send a request to : GET localhost:8000/api/ with the Header HTTP_AUTHORIZATION : Authorization:2W1bqko79ZF3Vit038e610R6DXIvkkyB it says that i dont have a permission.So do i need to add some class permission or is just bad configuration?

Should the JSON returned by a GET to /products/{id}/ of a child product include the images of its parent?

As it is right now, the json returned from a request to /products/{id}/ of a child product doesn't include images set on the parent. However, the Oscar dashboard doesn't let you set images on child products.

To me the expected behavior is that if I am requesting a child product, and there are images set on the parent, that I would be returned those.

As it is written, how should a client get the images of a child product?

Or is that a feature request? :)

ApiBasketMiddleWare: 'super' object has no attribute 'process_request'

When using the ApiBasketMiddleWare class, it throws an AttributeError exception on every page load. This is due to incorrect usage of the super function.

Oscar api for basket does not show **Shipping Discount** in Offer Discounts:

I have been using oscar api for mobile app. I need to show some shipping discounts in the basket api. Like If I apply conditional offer (free shipping above 250 USD). How can I show it to mobile user.

I have made /api/basket/shipping-methods/ api which loads shipping cost and discount for the current user basket. It shows the discounts on matching condition but how will I show the user that what condition we have applied for free shipping cost. Free shipping above what amount in the basket? So this condition value will be dynamic so I need to show it to the user.

For now it does not show that shipping discounts, I need to show the title of the shipping discount. Kindly suggest me some solution to figure it out.

i get this issue builtins.DeprecationWarning

i try to use django oscar, i install based on documentation, everything iis fine, but when i go to basket url
i get this issue:

DeprecationWarning: Setting BasketView.extraat the class level is now deprecated. SetBasketView.factory_kwargs instead.

Update checkout view (and docs) with billing address

checkout help

POST(basket, shipping_address,
[total, shipping_method_code, shipping_charge, billing_address])

its not entirely clear how each parameter should be represented. can someone please give an example how this is used?

Ajax PUT request to update line quantity

When trying to update the quantity of a line in my basket I am getting this AssertionError:

AssertionError: The .update() method does not support writable nested fields by default.
Write an explicit .update() method for serializer oscarapi.serializers.basket.BasketLineSerializer, or set read_only=True on nested serialiser fields.

Am I doing anything wrong here? I am basically executing the exact same code as explained in the Example Usage section of the docs.

Thank you!

Allow overriding the default serializers

We might want to make the Serializers overridable by the project using the app. By creating abstract serializers users can implement their own just like currently possible with the oscar models/classes.

This would mean that we would use e.g. get_class('ProductSerializer') in the views

How to show price excluding and including offer or discount in product list api

I am facing such scenario in which I want to show the price of a product which has if any offer is active then show price with the offer and without an offer in product list API.

Why not using oscar.loading?

Going through the api's you might need to change a class or more, using the "loading.py" from oscar will allow more functionalities and easier access and modifications.

Send ajax request to API

var basketForm = $(element).parent('form');
            var origin = window.location.origin;
            var endpoint =  origin + '/api/basket/add-product/';
            var add_prod_url = origin+"/api/products/"+2111;
            var csrf = o.cart.getCsrfToken();

            var data ={
                "url": add_prod_url,
                "quantity": 1
            };
            // $.post(endpoint, data,function (res) {
            //     alert(res);
            // });
            $.ajax({
                    type: 'POST',
                    data: data,
                    dataType: "json",
                    url: endpoint,
                    beforeSend: function(xhr, settings) {
                        xhr.setRequestHeader("X-CSRFToken", csrf);
                    }
                });

I am sending this request, however, it is producing 406 Error,
How I can sync user session with API session ?

Customizing LineAttributeSerializer

Hi,

Thank you for this great project.

I have a question on customizing LineAttributeSerializer. When getting basket lines (basket-line-detail) I'd like to return option's code with attributes. Meta model for LineAttributeSerializer is LineAttribute (AbstractLineAttribute) which has a fk relationship to catalogue.Option. I tried few things but I'm not quite sure how to go about returning option.code from it.

Any help would be greatly appreciated.

Question about implementing an express checkout api

Hi There,

I need an api that is essentially a single product express checkout, so to speak. I've developed a view that is a combination of the basket.addproductview and checkoutview. I'm new to Django/oscar (recovering C# developer) and I'd like to know if this is the right approach for such a feature. Thanks in advance.

    def post(self, request, format=None):
        # deserialize the product from json
        p_ser = self.add_product_serializer_class(
            data=request.data['addproduct'], context={'request': request})
        if p_ser.is_valid():
            # create a basket
            basket = operations.get_basket(request)
            # load the validate the product
            product = p_ser.validated_data['url']
            # load the validated quantity
            quantity = p_ser.validated_data['quantity']
            # load any options
            options = p_ser.validated_data.get('options', [])
            #validate the basket
            basket_valid, message = self.validate(
                basket, product, quantity, options)
            if not basket_valid:
                return Response(
                    {'reason': message},
                    status=status.HTTP_406_NOT_ACCEPTABLE)

            # add the product to the validated basket
            basket.add_product(product, quantity=quantity, options=options)

            # apply offers
            operations.apply_offers(request, basket)
            ###### from oscarapi.views.checkout
            # deserialize the checkout object and complete the order
            co_data = request.data['checkout']
            co_data['basket'] = "http://127.0.0.1:8000/oscar-api/baskets/"+str(basket.pk)+"/"
            c_ser = self.checkout_serializer(
                data=co_data, context={'request': request})
            if c_ser.is_valid():
                order = c_ser.save()
                basket.freeze()
                o_ser = self.order_serializer_class(
                    order, context={'request': request})
                oscarapi_post_checkout.send(
                    sender=self, order=order, user=request.user,
                    request=request, response=response)
                return response.Response(o_ser.data)

            return response.Response(c_ser.errors, status.HTTP_406_NOT_ACCEPTABLE)

The json request payload:

{
  "addproduct": {
    "url": "http://127.0.0.1:8000/oscar-api/products/1553/",
    "quantity": 1
  },
  "checkout": {
    "guest_email": "[email protected]",
    "total": "60.00",
    "shipping_method_code": "no-shipping-required",
    "first_name": "M",
    "last_name": "T",
    "phone_number": "12343455",
    "shipping_charge": {
      "currency": "USD",
      "incl_tax": "0.00",
      "excl_tax": "0.00",
      "tax": "0.0"
    },
    "shipping_address": {
      "country": "http://127.0.0.1:8000/oscar-api/countries/US/",
      "line1": "123 B St",
      "line2": "A",
      "line3": "B",
      "line4": "C",
      "notes": "Hello",
      "postcode": "94704",
      "state": "TX",
      "title": "Mr"
    }
  }
}

And response:

HTTP 200 OK
Allow: POST, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "number": "100035",
    "basket": "http://127.0.0.1:8000/oscar-api/baskets/35/",
    "url": "http://127.0.0.1:8000/oscar-api/orders/1/",
    "lines": "http://127.0.0.1:8000/oscar-api/orders/1/lines/",
    "owner": null,
    "billing_address": null,
    "currency": "USD",
    "total_incl_tax": "60.00",
    "total_excl_tax": "60.00",
    "shipping_incl_tax": "0.00",
    "shipping_excl_tax": "0.00",
    "shipping_address": {
        "id": 1,
        "country": "http://127.0.0.1:8000/oscar-api/countries/US/",
        "title": "Mr",
        "first_name": "",
        "last_name": "",
        "line1": "123 B St",
        "line2": "A",
        "line3": "B",
        "line4": "C",
        "state": "TX",
        "postcode": "94704",
        "search_text": "123 B St A B C TX 94704 United States of America",
        "phone_number": null,
        "notes": "Hello"
    },
    "shipping_method": "Free shipping",
    "shipping_code": "free-shipping",
    "status": "new",
    "guest_email": "[email protected]",
    "date_placed": "2017-03-23T07:01:03.672889Z",
    "payment_url": "You need to implement a view named 'api-payment' which redirects to the payment provider and sets up the callbacks.",
    "offer_discounts": [],
    "voucher_discounts": []
}

any idea on jwt authentication ?

Hi guys, you rock. I would like to know jwt authentication for api as rest-framework already supports that.

Checkout validation

I'm not sure if i'm doing it right. It seems that checkout validation in the CheckoutSerializer doesn't add the shipping charge to the total amount and if i do it myself via the OrderPlacementMixin validation fails because the total amount is validated against basket.total_incl_tax which does not include shipping. If i ignore this i end up with an order with a wrong total like this
#10 €48.00 €48.00

Discount €0.00 €0.00
Basket total €38.00 €38.00
Shipping total €10.00 €10.00
Order total €48.00 €48.00

A fix could be to use the OrderTotalCalculator to calculate the total after validation before create is called

Updating line item quantity doesn't recalculate discounts

This issue might be related to #78.

Essentially, I am just sending a PUT request to update the quantity of a line item as explained in the example usage. However, after updating the line item quantity, discounts are not recalculated and in the response price_excl_tax and price_excl_tax_excl_discounts are equal. I would expect that count based offers are applied after updating the quantity.

Only when I request the whole basket again, the line items are updated.

Module 'itertools' has no attribute 'imap'

The function itertools.imap was changed to just be map in Python 3 (stackoverflow.com). This breaks the basket list endpoint in Python 3.x.

oscarapi/views/basic.py#L58

    def get_queryset(self):
        qs = super(BasketList, self).get_queryset()
        return itertools.imap(
            functools.partial(assign_basket_strategy, request=self.request),
            qs)

Doc improvement proposal - what happens after place an order.

Hello - When implementing the Place an order api I noticed a confirmation email is never sent. I presume this is because I am expected to create the payment logic myself and only send the email once payment is confirmed.

For reference Oscar sends the email in a view after running place_order. See here. The order api calls place_order but not the handle_successful_order method that involves sending the order.

My proposal is just to note this in the "place an order" section of the docs that it is expected the developer will call send_confirmation_message themselves once the order is final if they want the email sent. Unless there is a better way. I'm happy to send a pull request doc change if this my understanding is correct.

billing_address field in checkout api causes exception

Am I missing something here or am I not supposed to be passing billing_address as a dict like shipping_address? The serializer doesn't create a BillingAddress object and so the call to save throws an exception...

ProductPrice & ProductAvailability views result in server error if the matching product is not found

ProductPrice and ProductAvailability views are using product = Product.objects.get(id=pk).

The exception Product.DoesNotExist is not handled correctly.

Implement `get_serializer_class` for read and write serializers

That's why all the HTML forms in the Browsable API are all not working. We should fix this according to https://www.django-rest-framework.org/api-guide/generic-views/#get_serializer_classself

Would also be needed for generating a correct OpenAPI specification for it.

New Release

Are you willing to upload the new release to PyPi anytime soon?

[Feature RE] Could we create an API for the dashboard?

Would creating an API for the dashboard be useful to have out of the the box? Or it outside the scope of the project? I'd be willing to contribute to that.

Partly using API in an oscar website

In a scenario where an already existing website tries to use some part of the API (eg. implement ajax cart), basket managment is broken.
oscarapi uses session to manage basket_id whereas oscar uses cookies.
If the basket addition is done using API and a redirect happens for checkout or any other functionalty, request.basket is empty.
I solved this problem by overwriting basket APIs to use request.basket instead of operations.get_basket.
But, then the clients not using cookies wont be able to use the api.
So, had to override oscar.apps.basket.middleware to use session to manage basket.id.

Question is "Is having such a hybrid approach a bad idea altogether? If not then shoudn't we have a common approach to managing basket?"

Adding price to product list view

Do you have a working example of Adding price to product list serializer?

Oscar price API

Hi,

I am using django oscar api and extending its functionality. Fetching a product price has a separate API. If I am displaying 20 products on a page, I need to call 20 extra APIs to fetch price. Product prices, i think, should be part of response returned by ProductList API.
My product will have multiple stock records but price will be same for all variants. Looking for a solution where I can make price as a part of productList API. Thanks in advance

logging in

how do i use the the api to login using something like curl?

Overriding serializer

Able to override views as per manual, but unable to do same with serializer.

Django Rest Framework v3 support?

Has anyone looked in to getting DRF v3 supported? @specialunderwear, I'd think you'd have good insight on this.

Thanks!