Developer Support
Guide for Invoicing Apps
7 min read
·
Last updated on Jul 27, 2023
Got an app that'll help Wix business owners provide invoices? Great! Here's a quick guide on how to get your app ready for the Wix App Market.
Important:
These types of apps require a special Partner Agreement. Contact us for more details before you begin developing your app.
Step 1: Set up your app in the Wix Developers Center
- Go to the Wix Developers Center and click Get Started.
- Click Create New App.
- Go through each tab under Build Your App in the side nav and fill out the required info:
Components
There are two main types of component: website and dashboard. All apps must have at least one component, but you can have two or more. You'll most likely need at least a dashboard component.
OAuth
To get access to user data – like a purchase made on the user's site – users must first grant your app permission to do so. If you need help setting this up, read this article.
Permissions
The following permissions are relevant to most invoicing apps:
- Wix Stores > Read Orders
- Wix Bookings > Read Bookings (Including Participants)
- Wix Payments > Read Transactions
Webhooks
The following webhooks are relevant to most invoicing apps:
App Management:
Note:
There are also several Paid Plan webhooks available, if your app will have paid plans.
Wix Stores:
Wix Bookings:
Wix Payments:
Step 2: Set up a free Premium Wix test site
It's essential that you test your app thoroughly before submitting it for review. To make this easier we provide a pre-made Premium development site that's free to use.
- Log in to the Wix Developers Center.
- Click Test Your App in the top right corner of your dashboard (if you already have one or more test sites, hover over Test Your App and click Create Development Site instead).
3. Select Wix Stores, Wix Bookings and Wix Events. You can always add more later in the site Editor.
4. Click Create Site. It takes around 20-30 seconds to create the site, so please don't refresh the page. You'll receive an email inviting you to join the site, but you should ignore this.
5. Hover over Test Your App again to select a starting point for your app: App Market, Editor, or Dashboard. A starting point is the location from which a user first installs / interacts with your app.
6. You'll be prompted to select the development site from your list of sites which will be named 'Dev Site'.
7. You can create multiple development sites. To do this, hover over Test Your App and click Create another development site.
- Go to the Accept Payments tab and set up Manual payments.
Step 3: Set up APIs relevant to your app
Now you'll be able to start adding the APIs you'll need for your app. Here's how the process works:
- A site visitor purchases a product/service/session/ticket.
Note:
In cases of asynchronous payment method (e.g. PayPal), a payment transaction will be triggered before the product/service/session/ticket order is triggered. When the order is abandoned, there won't be any reference to the order other than the transaction in Wix Payments.
- A transaction is created in Wix Payments, and a Payment Event Webhook is triggered.
Note:
The event type = TRANSACTION_STATUS_CHANGED carries the relevant data for your purposes.
- Collect the Payment ID and Wix App ID.
- Call the relevant API for more information, when relevant (e.g., Get Order endpoint in Wix Stores).
Product example
Let’s say you use a template like this for your customers:
To fill your template, you’ll need to collect the following data from our APIs:
- Customer name, address and phone number: Payment Event Webhook > order > shippingAddress
- Date of purchase: Payment Event Webhook > transaction
- Purchase line items: Payment Event Webhook > order > items Additional info per Wix App:
- Wix Stores purchase: Order Created Webhook / Get Order endpoint
- Wix Bookings purchase: Booking Notification Webhook / Query Bookings endpoint Note: The Booking ID is passed in the Payment Event Webhook as the Wix App Order ID.
- Wix Events purchase: List Order endpoint Note: Filter for the order number – it's passed in the Payment Event Webhook as the Wix App Order ID.
- Wix Invoices: Not available yet
- Payment transaction details: Payment Event Webhook > transaction
Things to note:
- Tax per line item: Not available yet
- Last 4 digits of CC: Not available yet
- ID (TZ): Not available yet
- Payments in instalments: Payment Event Webhook > transaction
Step 4: Test your app
Install the app on your test site and confirm that you get the App Installed Webhook.
Trigger a store order on your site
- Visit your test site as a site visitor, and add a product in the store to your cart.
- During checkout, enter test shipping details and select a delivery method. For payment, select Manual Payment (unless you've enabled other payment options).
- Place the order.
- Confirm that you get the Order Created Webhook and Payment Event Webhook.
Trigger the return of a product for a refund
- Enter your test site's dashboard and go to Store Orders.
- Select the order you placed above and under More Actions, mark it as Paid.
- Once the order is marked as Paid, under More Actions, select Issue Refund and confirm the refund.
- Confirm that you get the Payment Event Webhook with refund data.
Test orders with different shipping and payment options
To test payment options other than the basic Manual Payment, contact us about a coupon for a Premium website.
Note:
If you need more info, call the Stores Get Order endpoint, with the order ID from the webhook payload.
Trigger a booking for a class / session on your site
- Visit your test site as a site visitor, and book a class/session.
- During checkout, if you've required payment, select Manual Payment (unless you've enabled other payment options).
- Make the booking.
- Confirm that you get the Booking Notification Webhook.
Note: If payment was made, you should get the Payment Event Webhook now, and you can skip to the next step.
- Enter your test site's dashboard and go to Bookings Calendar.
- Select the booking you made above and mark it as Paid.
- Confirm you get the Payment Event Webhook.
- Call the List Bookings endpoint and filter for the relevant Booking ID.
Note: The Booking ID is passed in the Payment Event webhook as the Order Item ID.
Trigger an event purchase on your site
- Visit your test site as a site visitor, and purchase a ticket to an event.
- During checkout, if you've required payment, select Manual Payment (unless you've enabled other payment options).
- Place the order.
- Enter your test site's dashboard and go to Events > Orders.
- Select the purchase you made above and mark it as Paid.
- Confirm you get the Payment Event Webhook.
Trigger a pricing plan purchase on your site
- Visit your test site as a site visitor, and purchase a pricing plan.
- Confirm you get the Payment Event Webhook.
Remove the app from your test site
Once you've removed the app, confirm that you get the App Removed Webhook.
Step 5: Set up your app's market listing
In the Wix Developers' Center, open your app and complete all the info required under Publish Your App > Market Listing. If you need help with this, follow our market listing guidelines.
Step 6: Submit your app for review
When you're ready, you can submit your app for review. If you haven't already done so, here are some important guidelines and tutorials to check out before you submit your app:
- Read through our guidelines and our partner agreement.
- Review our app component types and how they work.
- Make sure you're using the instanceId parameter to identify users.
- Look through our API documentation.
- Test your app thoroughly.
Was this article helpful?
