Skip to content

Invoice: Add support for Create Preview Invoice API #249

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bravier merged 1 commit into from
Sep 2, 2025
Merged

Invoice: Add support for Create Preview Invoice API #249

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions localstripe/resources.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1602,6 +1602,40 @@ def _api_upcoming_invoice(cls, customer=None, subscription=None,

return invoice

@classmethod
def _api_create_preview_invoice(cls, customer=None, subscription=None,
subscription_details=None):
try:
if subscription_details is not None:
assert type(subscription_details) is dict
except AssertionError:
raise UserError(400, 'Bad request')

details = subscription_details or {}
default_tax_rates = details.get('default_tax_rates')
items = details.get('items')
proration_date = details.get('proration_date')
trial_end = details.get('trial_end')

invoice = cls._get_next_invoice(
customer=customer,
subscription=subscription,
upcoming=True,
subscription_default_tax_rates=default_tax_rates,
subscription_items=items,
subscription_proration_date=proration_date,
subscription_trial_end=trial_end)

# Do not store this invoice but real Stripe server do for a limited
# amount of time (72 hours) which make it possible to retrieve it
# on route /v1/invoices/:id:
# https://docs.stripe.com/invoicing/preview
del store[cls.object + ':' + invoice.id]
Copy link
Collaborator

@feliixx feliixx Aug 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Stripe docs says that an upcoming invoice can be retrieved via the /v1/invoices/id for 72 hours (cf https://docs.stripe.com/invoicing/preview), so maybe it would make more sense to keep these upcoming invoice in the store ?

Copy link
Collaborator Author

@bravier bravier Sep 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right, thanks for pointing this out.

I was misguided by the API doc that says:

Note that when you are viewing an upcoming invoice, you are simply viewing a preview – the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice.

https://docs.stripe.com/api/invoices/create_preview

I don't want to implement such "temporary" store in localstripe that would complicate things.
Also, please note that the /v1/invoices/:id route is not supported in localstripe right now so storing the invoice would not be useful.

Maybe I can change the comment to says that real Stripe servers keep these invoices for a limited amount of time? What do you think?

Copy link
Owner

@adrienverge adrienverge Sep 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would work for me. I'm curious about what @feliixx thinks!

Copy link
Collaborator

@feliixx feliixx Sep 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't want to implement such "temporary" store in localstripe that would complicate things.

+1 not to implement a "temporary" store: we don't need to access the preview invoices via the /v1/invoices/:id route right now so it's not worth the extra complexity

Also, please note that the /v1/invoices/:id route is not supported in localstripe right now so storing the invoice would not be useful.

Ok interesting, I wasn't aware of that !

Maybe I can change the comment to says that real Stripe servers keep these invoices for a limited amount of time? What do you think?

Seems like the best solution 👍

Copy link
Collaborator Author

@bravier bravier Sep 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment updated: diff


invoice.id = f'upcoming_{invoice.id}'
Copy link
Collaborator Author

@bravier bravier Aug 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Create Preview Invoice API adds an ID to the returned invoice whereas the Upcoming Invoice API didn't do that.


return invoice

@classmethod
def _api_pay_invoice(cls, id):
obj = Invoice._api_retrieve(id)
Expand Down Expand Up @@ -1664,6 +1698,8 @@ def _api_list_lines(cls, id, limit=None, **kwargs):

extra_apis.extend((
('GET', '/v1/invoices/upcoming', Invoice._api_upcoming_invoice),
('POST', '/v1/invoices/create_preview',
Invoice._api_create_preview_invoice),
('POST', '/v1/invoices/{id}/pay', Invoice._api_pay_invoice),
('POST', '/v1/invoices/{id}/void', Invoice._api_void_invoice),
('GET', '/v1/invoices/{id}/lines', Invoice._api_list_lines)))
Expand Down
16 changes: 16 additions & 0 deletions test.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -472,6 +472,11 @@ code=$(curl -sg -o /dev/null -w "%{http_code}" -u $SK: \
$HOST/v1/invoices/upcoming?customer=$cus)
[ "$code" = 404 ]

code=$(curl -sg -o /dev/null -w "%{http_code}" -u $SK: \
$HOST/v1/invoices/create_preview \
-d customer=$cus)
[ "$code" = 404 ]

curl -sSfg -u $SK: $HOST/v1/subscriptions \
-d customer=$cus \
-d items[0][plan]=basique-mensuel \
Expand All @@ -492,6 +497,17 @@ curl -sSfg -u $SK: $HOST/v1/invoices/upcoming?customer=$cus\&subscription_items[

curl -sSfg -u $SK: $HOST/v1/invoices/upcoming?customer=$cus\&subscription=$sub\&subscription_items[0][id]=si_RBrVStcKDimMnp\&subscription_items[0][plan]=basique-annuel\&subscription_proration_date=1504182686\&subscription_tax_percent=20

curl -sSfg -u $SK: $HOST/v1/invoices/create_preview \
-d customer=$cus

curl -sSfg -u $SK: $HOST/v1/invoices/create_preview \
-d customer=$cus \
-d subscription=$sub \
-d subscription_details[default_tax_rates][0]=$txr1 \
-d subscription_details[items][0][id]=si_RBrVStcKDimMnp \
-d subscription_details[items][0][plan]=basique-annuel \
-d subscription_details[proration_date]=1504182686
Copy link
Owner

@adrienverge adrienverge Sep 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I read that this is an old timestamp (from 2017), so I guess that if it works today, it will keep working in a month or a year 👍


curl -sSfg -u $SK: $HOST/v1/invoices/$in/lines

cus=$(curl -sSfg -u $SK: $HOST/v1/customers \
Expand Down
Loading