The API version used to communicate with the Stripe API is configurable, and defaults to the latest version that has been tested as working. Using a value other than the default is allowed, as a string in the format of YYYY-MM-DD.
For example, you can specify
"2020-03-02" to use that API version:
STRIPE_API_VERSION = "2020-03-02"
However you do so at your own risk, as using a value other than the default might result in incompatibilities between Stripe and this library, especially if Stripe has labelled the differences between API versions as "Major". Even small differences such as a new enumeration value might cause issues.
For this reason it is best to assume that only the default version is supported.
For more information on API versioning, see the stripe documentation.
See also API Versions.
(Introduced in 2.4.0)
DJSTRIPE_FOREIGN_KEY_TO_FIELD is a setting introduced in dj-stripe version 2.4.0. You
are required to set it in 2.4.0: It does not have a default value. In 3.0.0, the default
will be "id", and we recommend setting it to "id" for new installations. Older
installations should set it to "djstripe_id". Explanation below.
In dj-stripe 2.3 and before, foreign keys for Stripe models were set to point to the foreign model's djstripe_id field, a numeric integer generated by the local database. This new setting allows dj-stripe users to change it to use the "id" field, which is the upstream, non-numeric Stripe identifier.
When using the Stripe identifier as a foreign key, synchronization between Stripe and dj-stripe can be made far more efficient and robust. Furthermore, it removes the per-installation instability of a critical value. The plan is to get rid of djstripe_id altogether for the 3.0 release (we may retain the field itself until 4.0, but it will no longer be a primary key).
How to migrate older installations from "djstripe_id" to "id"?
Such a migration path has not been designed at the moment. Currently if you want to switch an older installation to "id", the easiest way is to wipe the djstripe db and sync again from scratch. This is obviously not ideal, and we will design a proper migration path before 3.0.
A function which will return an idempotency key for a particular object_type and action
pair. By default, this is set to a function which will create a
djstripe.IdempotencyKey object and return its
uuid. You may want to customize this
if you want to give your idempotency keys a different lifecycle than they normally would
The function takes the following signature:
def get_idempotency_key(object_type: str, action: str, livemode: bool): return "<idempotency key>"
The function MUST return a string suitably random for the object_type/action pair, and
usable in the Stripe
Idempotency-Key HTTP header. For more information, see the
By default, plans are not prorated in dj-stripe. Concretely, this is how this translates:
- If a customer cancels their plan during a trial, the cancellation is effective right away.
- If a customer cancels their plan outside of a trial, their subscription remains active until the subscription's period end, and they do not receive a refund.
- If a customer switches from one plan to another, the new plan becomes effective right away, and the customer is billed for the new plan's amount.
DJSTRIPE_PRORATION_POLICY reverses the functioning of item 2 (plan
cancellation) by making a cancellation effective right away and refunding the unused
balance to the customer, and affects the functioning of item 3 (plan change) by
prorating the previous customer's plan towards their new plan's amount.
This functionality is deprecated.
- "(app_name)" means everything from this app is exempt
- "[namespace]" means everything with this name is exempt
- "namespace:name" means this namespaced URL is exempt
- "name" means this URL is exempt
- The entire djstripe namespace is exempt
- If settings.DEBUG is True, then django-debug-toolbar is exempt
DJSTRIPE_SUBSCRIPTION_REQUIRED_EXCEPTION_URLS = ( "(allauth)", # anything in the django-allauth URLConf "[blogs]", # Anything in the blogs namespace "products:detail", # A ProductDetail view you want shown to non-payers "home", # Site homepage )
Adding app_names to applications.
To make the
(allauth) work, you may need to define an app_name in the
include() function in the URLConf. For example:
# in urls.py
url(r'^accounts/', include('allauth.urls', app_name="allauth")),
Every Customer object created in Stripe is tagged with metadata This setting controls what the name of the key in Stripe should be. The key name must be a string no more than 40 characters long.
You may set this to
"" to disable that behaviour altogether. This is
probably not something you want to do, though.
If the AUTH_USER_MODEL doesn't represent the object your application's subscription holder, you may define a subscriber model to use here. It should be a string in the form of 'app.model'.
DJSTRIPE_SUBSCRIBER_MODEL must have an
class Organization(models.Model): name = CharField(max_length=200, unique=True) admin = ForeignKey(settings.AUTH_USER_MODEL, on_delete=CASCADE) @property def email(self): return self.admin.email
If the model referenced in DJSTRIPE_SUBSCRIBER_MODEL is not created in the
migration of an app you can specify the migration name to depend on here. For example:
Setting this to
True will make the various dj-stripe JSON fields use the native Django
JSONField model instead of the
On Django 3.0 and older: The
django.contrib.postgres.fields.JSONField field will
always be used. A Postgres backend is required (uses
On Django 3.1 and newer:
django.models.JSONField will always be used. This field
type is compatible with all database backends.
Setting this to True is highly recommended. However, if you have already migrated with the old fields, migrating to the native JSONField has to be done manually and is not currently supported by dj-stripe. We will eventaully move to exclusively using the native JSONField.
The native Django JSONField uses the postgres
jsonb column type, which efficiently
stores JSON and can be queried far moreconveniently. Django also supports querying
with the ORM.
This is where you can tell Stripe to send webhook responses. You can set this to what you want to prevent unnecessary hijinks from unfriendly people.
As this is embedded in the URLConf, this must be a resolvable regular expression.
If this is set to a non-empty value, webhook signatures will be verified.
This setting controls which type of validation is done on webhooks. Value can be
"verify_signature" for signature verification (recommended default),
"retrieve_event" for event retrieval (makes an extra HTTP request), or
None for no
validation at all.
Controls the milliseconds tolerance which wards against replay attacks. Leave this to its default value unless you know what you're doing.
Webhook event callbacks allow an application to take control of what happens when an event from Stripe is received. It must be a callable or importable string to a callable that takes an event object.
One suggestion is to put the event onto a task queue (such as celery) for asynchronous processing.
# callbacks.py def webhook_event_callback(event): """ Dispatches the event to celery for processing. """ from . import tasks # Ansychronous hand-off to celery so that we can continue immediately tasks.process_webhook_event.s(event).apply_async()
# tasks.py from stripe.error import StripeError @shared_task(bind=True) def process_webhook_event(self, event): """ Processes events from Stripe asynchronously. """ logger.info("Processing Stripe event: %s", str(event)) try: event.process(raise_exception=True) except StripeError as exc: logger.error("Failed to process Stripe event: %s", str(event)) raise self.retry(exc=exc, countdown=60) # retry after 60 seconds
# settings.py DJSTRIPE_WEBHOOK_EVENT_CALLBACK = 'callbacks.webhook_event_callback'
STRIPE_API_HOST (= unset)
If set, this sets the base API host for Stripe. You may want to set this to, for
"http://localhost:12111" if you are running
If this is set in production (DEBUG=False), a warning will be raised on